Update README

1 files changed, 218 insertions, 0 deletions

diff --git a/README b/README
index d805f27..9dcc6de 100644
--- a/README
+++ b/README
@@ -288,3 +288,221 @@ at the target directory.
 
 -- 
 Hiroyuki Yamamoto <hiro-y@kcn.ne.jp>
+
+
+Master password (by sgs)
+========================
+
+The master password feature is developed by
+Simeon Simeonov (sgs - sgs@pichove.org) and is currently in an experimental
+state.
+
+
+Motivation
+----------
+
+Currently Sylpheed is storing passwords in palin-text. One can always refrain
+from storing passwords and let Sylpheed prompt for them, but the more accounts
+one has, the more annoying this becomes.
+
+The goal is to have the passwords stored in a secure way and let Sylpheed only
+prompt for the master password.
+
+
+Security goals
+--------------
+
+- attacker (A) should not be able to derive the password from the digest
+
+- A should not be able to derive the master password even if she has
+  read and write access to the storage
+
+- A should not be able to determine the length of the encrypted password
+  even if she has read and write access to the storage
+
+- A should not be able to craft an edited password without obtaining the
+  master password
+
+- a warning / prompt should be given if a user accidently types in a "wrong"
+  master password before decryption is initiated
+
+
+Usage in Sylpheed
+-----------------
+
+- backup your Sylpheed profile (often $HOME/.sylpheed-2.0)!
+
+- start Sylpheed and open Configuration -> Common preferences...!
+
+- select the "Master password" tab, enable "Use master password" and
+  apply the changes!
+
+- restart Sylpheed (exit and then start Sylpheed again)!
+
+- you will be asked to type and verify a new master password.
+
+Note:
+Sylpheed will automatically convert existing stored passwords, but it will not
+touch your backups. You will have to remove all remnants of plain-text
+passwords manually.
+
+
+Choice of cryptographic primitives
+----------------------------------
+
+The primary concern when selecting cryptographic primitives was portability.
+The desire was to go for primitives that are both strong and available in all
+supported production distributions of OpenSSL and LibreSSL.
+
+
+Cipher
+......
+
+When it comes to implementation, there are several advantages in using stream
+cipher or a block cipher that behaves like a stream cipher when used in a
+certain mode of operation. One is avoiding to deal with padding.
+
+AES-256 operating in CFB was selected for these reasons.
+ChaCha20 should be considered as a replacement in the future.
+
+
+Hash-function
+.............
+
+Hash-functions are used for:
+- key derivation
+- plain-text digest
+
+Those operations do not have to use the same hash-function.
+(See the "Encryption & decryption scheme" section for more details!)
+
+Key-derivation:
+Since AES-256 uses a 256 bits key, we need a hash-function with at least
+the same digest size or bigger.
+Since the digest (which is the key itself) is considered confidential and is
+stored only in memory for only a limited amount of time, SHA-256 is considered
+sufficiently strong for that purpose.
+
+Size + plain-text + padding digest:
+Since the digest is created of both the plain-text and the plain-text size,
+as well as being encrypted, SHA-256 is considered sufficiently strong.
+SHA-512 may increase security at the price of adding additional 32 bytes
+to the encrypted password digest.
+
+Stronger hash-functions like SHA-3 or BLAKE2b can be considered as a
+replacement in the future.
+
+
+Master password digest
+......................
+
+In order to be able to decide whether the user typed a "wrong" master password,
+before attempting to decrypt, Sylpheed stores a digest of the master password
+in 'master_password_hash' in sylpheedrc.
+100000 iterations of PBKDF2_HMAC with SHA-512 and 16 bytes salt is used.
+Note that this digest is useless as a key and even if a plain-text that
+produces the same digest is found, it will most probably be useless as a
+master-password.
+
+
+Encryption & decryption scheme
+------------------------------
+
+
+Encryption
+..........
+
+
+Input:
+
+- palin-text password to be encrypted (P)
+
+- plain-text master-password used for key derivation (M)
+
+- integer minimum password length (0 < L < 100)
+
+
+Output:
+
+- an encrypted password digest (base64) (B)
+
+
+Operation:
+
+- generate 16 bytes of random data to be used as a salt (S)
+
+- derive the key (K): K = SHA_256(S + M)
+
+- produce a 2 byte string (N) indicating the length of P
+
+- if the length of P < L, produce L - P bytes of random data (R), N = "%02d"
+  if the length of P >= L, N = "-1"
+
+- produce a hash digest (H): H = SHA_256(N + P + R (if the length of P < L))
+
+- encrypt (E): E = AES_256_CFB_ENCRYPT(H + N + P + R (if the length of P < L), K)
+
+- B = mpes1:BASE64_ENCODE(S + E)
+  example:
+  mpes1:vo7lsIpD7i6byBA6+vlUoF4OVDfEe+aYRRk4FRtfJ2gMY8M43Kj6WfdfgbViIOl83bI4XEc96okhPW5Mla813aAR1gbPjDg0xmCyIbWOiUv/dg==
+
+
+Decryption
+..........
+
+
+Input:
+
+- encrypted password digest (base64) (B)
+
+- plain-text master-password used for key derivation (M)
+
+
+Output:
+
+- palin-text password (P)
+
+
+Operation:
+
+- remove the prefix (mpes1:) and base64-decode the rest of the digest: B = BASE64_DECODE(B)
+
+- fetch the first 16 bytes for the salt: S = B[0 : 15]
+
+- derive the key (K): K = SHA_256(S + M)
+
+- decrypt the rest of B (D): D = AES_256_CFB_DECRYPT(B[16 :], K)
+
+- extract the first 16 bytes for the hash digest (H): H = D[0 : 15]
+
+- in order to detect data-inconsistency, assert H == SHA_256(D[16 :])
+
+- extract the next 2 bytes for the length of P (N): N = D[16 : 17]
+
+- if N == "-1" the password is the remaining bytes of D: P = D[18 :]
+  if N != "-1", extract the next N-bytes from D: P = D[18 : (18 + N)]
+
+
+Limitations
+-----------
+
+- when Sylpheed starts, the master-password is loaded into memory and remains
+  there as long as Sylpheed is running. Currently no strong mechanisms,
+  preventing someone with access to the memory from snatching it,
+  are implemented.
+  "Unloading" the master-password immediately after
+  account-processing (decryption) should be considered in the future.
+
+- currently only the 'password' and 'smtp_password' keys in accountrc
+  are encrypted.
+  A machanism that allows for any key and even folders to be encrypted
+  should be considered in the future.
+
+- currently it is not possible to select alternative ciphers, hash-functions
+  and modes of operation (without editing the source code).
+
+- currently it is not possible to change your master password without having to
+  set your passwords manually.
+
+-- 
+Simeon Simeonov <sgs [ATTT] pichove (DOT) org>