Added password_encryption.txt to docs/src.

[claws.git] / doc / src / password_encryption.txt

diff --git a/doc/src/password_encryption.txt b/doc/src/password_encryption.txt
new file mode 100644 (file)
index 0000000..aed0cb0
--- /dev/null
+++ b/doc/src/password_encryption.txt
@@ -0,0 +1,47 @@
+Unless --with-password-encryption=old is active, account passwords are
+stored encrypted using AES-256-CBC, using following scheme:
+----------------------------------------------------------------------
+
+Encryption/decryption key is either PASSCRYPT_KEY, or user-selected master password.
+
+We take the digest of the key using SHA-512, which gives us a 64 bytes
+long hash.
+
+The first half of the hash is XORed with the second (1st byte with
+33rd, 2nd with 34th, etc.). This is gives us 32 bytes, which is
+ey length required for AES-256-CBC.
+
+IV for the cipher is filled with random bytes.
+
+
+Encryption
+----------
+
+We prepare a buffer 128+blocksize bytes long, with one block of random
+data at the beginning, followed by the password we want to encrypt,
+rest is padded with zero bytes.
+
+We encrypt the buffer.
+
+We base64-encode the ciphertext, and store it as:
+"{algorithm}encodedciphertext"
+
+
+Decryption
+----------
+We strip the "{algorithm}" (after verifying that it matches what we
+expect) and base64-decode the remaining ciphertext.
+
+We decrypt the ciphertext.
+
+We discard the first block, and the rest is a zero-terminated string
+with our password.
+
+
+Why the random block at the beginning?
+--------------------------------------
+
+We are taking advantage of property of CBC mode where decryption with
+a wrong IV results in only first block being garbled. Therefore we
+prepend a random block to our plaintext before encryption, and discard
+first block from plaintext after decryption.