for release 3.17.5
[claws.git] / doc / src / password_encryption.txt
1 Unless --with-password-encryption=old is active, account passwords are
2 stored encrypted using AES-256-CBC, using following scheme:
3 ----------------------------------------------------------------------
4
5 Encryption/decryption key is derived from either PASSCRYPT_KEY, or
6 user-selected master passphrase, using PBKDF2, using salt from
7 'master_passphrase_salt', and number of rounds (iterations) from
8 'master_passphrase_pbkdf2_rounds'.
9
10 IV (initialization vector) for the cipher is filled with random bytes.
11
12
13 Encryption
14 ----------
15 We prepare a buffer long enough to fit the NULL-terminated password string
16 plus one cipher block in it, with one block of random data at the beginning,
17 followed by the password we want to encrypt (in UTF-8), rest is padded
18 with zero bytes.
19
20 The minimal buffer size is 128+blocksize, and if the password (including
21 the trailing NULL byte) is longer than 128 bytes, the size is increased by
22 another 128 bytes until it is long enough to fit the password plus one
23 cipher block. This is to make it harder to guess the password length from
24 length of the encrypted string. So for example, if the password (again,
25 including the trailing NULL byte) is 129 characters long, our buffer will
26 be 256+blocksize bytes long.
27
28 We encrypt the buffer using the encryption key and IV mentioned above,
29 resulting in ciphertext of the same length as the buffer.
30
31 We base64-encode the ciphertext, and store it as:
32 "{algorithm,rounds}encodedciphertext"
33
34 "rounds" is an integer value set to number of PBKDF2 rounds used to
35 generate the key derivation used as encryption key.
36
37
38 Decryption
39 ----------
40 We strip the "{algorithm}" (after verifying that it matches what we
41 expect) and base64-decode the remaining ciphertext.
42
43 We decrypt the ciphertext using decryption key and IV mentioned above,
44 resulting in plaintext of the same length as the ciphertext.
45
46 We discard the first block from plaintext, and the rest is a
47 zero-terminated string with our password in UTF-8.
48
49
50 Why the random block at the beginning?
51 --------------------------------------
52 We are taking advantage of property of CBC mode where decryption with
53 a wrong IV results in only first block being garbled. Therefore we
54 prepend a random block to our plaintext before encryption, and discard
55 first block from plaintext after decryption.
56
57
58 Master passphrase
59 -----------------
60 This can be any string user chooses. We store its 64 bytes long key
61 derivation (KD), using PBKDF2 with HMAC-SHA1, and later check correctness
62 of user-entered passphrase by making same KD from it and comparing it
63 to the stored one. Only if the two KDs match, the passphrase is accepted
64 and remembered for session, thus giving access to account or plugin
65 passwords.
66
67 Salt used for PBKDF2 is stored in 'master_passphrase_salt', encoded
68 as base64. It consists of 64 randomly generated bytes.
69
70 Number of rounds for PBKDF2 is stored in hidden preference
71 'master_passphrase_pbkdf2_rounds'.