Add threat model sketch to pgpainless-core/README

pgpainless-core/README.md

@@ -7,3 +7,39 @@ SPDX-License-Identifier: Apache-2.0
 # PGPainless-Core
 
 Wrapper around Bouncycastle's OpenPGP implementation.
+
+## Protection Against Attacks
+
+PGPainless aims to fulfil the primary goals of cryptography:
+* Confidentiality through message encryption
+* Authenticity through signatures
+* Integrity through the use of Modification Detection Code and again signatures
+
+In short: Communication protected using PGPainless is intended to be private,
+users can verify that messages they receive were really send by their communication peer
+and users can verify that messages have not been tampered with.
+
+This is being achieved by preventing a number of typical attacks on the users communication,
+like the attacker introducing an evil subkey to the victims public key, or the attacker creating
+counterfeit signatures to fool the victim.
+
+Due to its nature as a library however, it does not make sense to set up defences against all possible
+attack types (see below).
+So here is a threat model that best applies to PGPainless.
+
+### Threat Model
+A threat model that makes the most sense for PGPainless would be an evil attacker using PGPainless
+through a benign client application (like an email app) on a trustworthy device.
+
+The attacker can try to feed the application malicious input (like manipulated public key updates,
+specially crafted PGP message objects etc.) but they cannot access the victims decrypted secret key material as
+it is protected by the device (eg. stored in a secure key store).
+
+### What doesn't PGPainless Protect Against?
+
+#### Brute Force Attacks
+It was decided that protection against brute force attacks on passwords used in symmetric encryption
+(password encrypted messages/keys) are out of scope for PGPainless.
+PGPainless cannot limit access to the ciphertext that is being brute forced, as that is provided by
+the application that uses PGPainless.
+Therefore, protection against brute force attacks must be employed by the application itself.