|
| 1 | +Cryptography Details |
| 2 | +===================== |
| 3 | + |
| 4 | +Here is a high-level description of how this library works. Any discrepancy |
| 5 | +between this documentation and the actual implementation will be considered |
| 6 | +a security bug. |
| 7 | + |
| 8 | +Let's start with the following definitions: |
| 9 | + |
| 10 | +- HKDF-SHA256(*k*, *n*, *info*, *s*) is the key derivation function specified in |
| 11 | + RFC 5869 (using the SHA256 hash function). The parameters are: |
| 12 | + - *k*: The initial keying material. |
| 13 | + - *n*: The number of output bytes. |
| 14 | + - *info*: The info string. |
| 15 | + - *s*: The salt. |
| 16 | +- AES-256-CTR(*m*, *k*, *iv*) is AES-256 encryption in CTR mode. The parameters |
| 17 | + are: |
| 18 | + - *m*: An arbitrary-length (possibly zero-length) message. |
| 19 | + - *k*: A 32-byte key. |
| 20 | + - *iv*: A 16-byte initialization vector (nonce). |
| 21 | +- PBKDF2-SHA256(*p*, *s*, *i*, *n*) is the password-based key derivation |
| 22 | + function defined in RFC 2898 (using the SHA256 hash function). The parameters |
| 23 | + are: |
| 24 | + - *p*: The password string. |
| 25 | + - *s*: The salt string. |
| 26 | + - *i*: The iteration count. |
| 27 | + - *n*: The output length in bytes. |
| 28 | +- VERSION is the string `"\xDE\xF5\x02\x00"`. |
| 29 | +- AUTHINFO is the string `"Ecotone|V2|KeyForAuthentication"`. |
| 30 | +- ENCRINFO is the string `"Ecotone|V2|KeyForEncryption"`. |
| 31 | + |
| 32 | +To encrypt a message *m* using a 32-byte key *k*, the following steps are taken: |
| 33 | + |
| 34 | +1. Generate a random 32-byte string *salt*. |
| 35 | +2. Derive the 32-byte authentication key *akey* = HKDF-SHA256(*k*, 32, AUTHINFO, *salt*). |
| 36 | +3. Derive the 32-byte encryption key *ekey* = HKDF-SHA256(*k*, 32, ENCRINFO, *salt*). |
| 37 | +4. Generate a random 16-byte initialization vector *iv*. |
| 38 | +5. Compute *c* = AES-256-CTR(*m*, *ekey*, *iv*). |
| 39 | +6. Combine *ctxt* = VERSION || *salt* || *iv* || *c*. |
| 40 | +7. Compute *h* = HMAC-SHA256(*ctxt*, *akey*). |
| 41 | +8. Output *ctxt* || *h*. |
| 42 | + |
| 43 | +Decryption is roughly the reverse process (see the code for details, since the |
| 44 | +security of the decryption routine is highly implementation-dependent). |
| 45 | + |
| 46 | +For encryption using a password *p*, steps 1-3 above are replaced by: |
| 47 | + |
| 48 | +1. Generate a random 32-byte string *salt*. |
| 49 | +2. Compute *k* = PBKDF2-SHA256(SHA256(*p*), *salt*, 100000, 32). |
| 50 | +3. Derive the 32-byte authentication key *akey* = HKDF-SHA256(*k*, 32, AUTHINFO, *salt*) |
| 51 | +4. Derive the 32-byte encryption key *ekey* = HKDF-SHA256(*k*, 32, ENCRINFO, *salt*) |
| 52 | + |
| 53 | +The remainder of the process is the same. Notice the reuse of the same *salt* |
| 54 | +for PBKDF2-SHA256 and HKDF-SHA256. The prehashing of the password in step 2 is |
| 55 | +done to prevent a DoS attack using long passwords. |
| 56 | + |
| 57 | +For `KeyProtectedByPassword`, the serialized key is encrypted according to the |
| 58 | +password encryption defined above. However, the actual password used for |
| 59 | +encryption is the SHA256 hash of the password the user provided. This is done in |
| 60 | +order to provide domain separation between the message encryption in the user's |
| 61 | +application and the internal key encryption done by this library. |
0 commit comments