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