Added password_encryption.txt to docs/src.
[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 either PASSCRYPT_KEY, or user-selected master password.
6
7 We take the digest of the key using SHA-512, which gives us a 64 bytes
8 long hash.
9
10 The first half of the hash is XORed with the second (1st byte with
11 33rd, 2nd with 34th, etc.). This is gives us 32 bytes, which is
12 ey length required for AES-256-CBC.
13
14 IV for the cipher is filled with random bytes.
15
16
17 Encryption
18 ----------
19
20 We prepare a buffer 128+blocksize bytes long, with one block of random
21 data at the beginning, followed by the password we want to encrypt,
22 rest is padded with zero bytes.
23
24 We encrypt the buffer.
25
26 We base64-encode the ciphertext, and store it as:
27 "{algorithm}encodedciphertext"
28
29
30 Decryption
31 ----------
32 We strip the "{algorithm}" (after verifying that it matches what we
33 expect) and base64-decode the remaining ciphertext.
34
35 We decrypt the ciphertext.
36
37 We discard the first block, and the rest is a zero-terminated string
38 with our password.
39
40
41 Why the random block at the beginning?
42 --------------------------------------
43
44 We are taking advantage of property of CBC mode where decryption with
45 a wrong IV results in only first block being garbled. Therefore we
46 prepend a random block to our plaintext before encryption, and discard
47 first block from plaintext after decryption.