Fix a possible leak
[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'.
8
9 IV for the cipher is filled with random bytes.
10
11
12 Encryption
13 ----------
14 We prepare a buffer 128+blocksize bytes long, with one block of random
15 data at the beginning, followed by the password we want to encrypt,
16 rest is padded with zero bytes.
17
18 We encrypt the buffer.
19
20 We base64-encode the ciphertext, and store it as:
21 "{algorithm}encodedciphertext"
22
23
24 Decryption
25 ----------
26 We strip the "{algorithm}" (after verifying that it matches what we
27 expect) and base64-decode the remaining ciphertext.
28
29 We decrypt the ciphertext.
30
31 We discard the first block, and the rest is a zero-terminated string
32 with our password.
33
34
35 Why the random block at the beginning?
36 --------------------------------------
37 We are taking advantage of property of CBC mode where decryption with
38 a wrong IV results in only first block being garbled. Therefore we
39 prepend a random block to our plaintext before encryption, and discard
40 first block from plaintext after decryption.
41
42
43 Master passphrase
44 -----------------
45 This can be any string user chooses. We store its 64 bytes long key
46 derivation (KD), using PBKDF2 with HMAC-SHA1, and later check correctness
47 of user-entered passphrase by making same KD from it and comparing it
48 to the stored one. Only if the two KDs match, the passphrase is accepted
49 and remembered for session, thus giving access to account or plugin
50 passwords.
51
52 Salt used for PBKDF2 is stored in 'master_passphrase_salt', encoded
53 as base64. It consists of 64 randomly generated bytes.
54
55 Number of rounds for PBKDF2 is stored in hidden preference
56 'master_passphrase_pbkdf2_rounds'.