CRYPTO.md

Crypto Specification

This document serves as a high level design document for the block cipher functions of dcrypt.

Definitions

• SALT initialization vector generated with random_bytes.
• CIPHER the chosen cipher method as a string
• ALGO the chosen hmac algorithm as a string
• KEY high entropy key selected for symmetric encryption
• ENCRINFO is the string encryptionKey + | + CIPHER
• AUTHINFO is the string authenticationKey + | + CIPHER
• MTEXT the plaintext message to be encrypted
• HKDF is the key derivation function supported by PHP (hash_hkdf) and defined as (RFC-5869). The parameters are:
  • hashing algo to use
  • key to hash with
  • info string parameter
• HMAC is a HMAC checksum function supported by PHP (hash_hmac). The parameters are:
  • input data to hash
  • hashing algo to use
  • key to hash with
• OPENSSL_ENCRYPT. The parameters are:
  • input data to encrypt
  • key to hash with
  • iv
• OPENSSL_DECRYPT. The parameters are:
  • input data to decrypt
  • key to hash with
  • iv
  • tag

Providing a high quality key is essential to the security level it provides.

Steps for encryption

1. Obtain a new SALT of appropriate size for given CIPHER
2. Test key for validity
3. Derive authentication key AKEY = HKDF(ALGO, KEY, AUTHINFO)
4. Derive encryption key EKEY = HKDF(ALGO, KEY, ENCRINFO)
5. Encrypt the data as CTEXT = OPENSSL_ENCRYPT(MTEXT, EKEY, SALT)
6. Generate a checksum where CHECKSUM = HMAC(CTEXT, ALGO, AKEY)
7. Concatenate and return the following values
   1. SALT
   2. CHECKSUM
   3. TAG (if required by CIPHER, otherwise skip)
   4. CTEXT

Steps for decryption

1. Pop SALT off front of CTEXT
2. Same as step 3 from above
3. Same as step 4 from above
4. Pop CHECKSUM from front of CTEXT
5. Pop TAG from front of CTEXT
6. Generate a checksum where COMPUTED = HMAC(CTEXT, ALGO, AKEY)
7. If COMPUTED != CHECKSUM throw an exception
8. Decrypt data as MTEXT = OPENSSL_DECRYPT(CTEXT, EKEY, SALT, TAG)
9. Return MTEXT