62.2.5 Symmetric Cryptography

Symmetric-key algorithms can be divided into stream ciphers and block ciphers. Stream ciphers encrypt the bits of the message one at a time, and block ciphers take a number of bits and encrypt them as a single unit.

In order to use symmetric-key cryptography some preparations have to be done, mostly due to the block-oriented operation of the algorithms. The following function, given a cipher and digest algorithm, computes a valid key suitable for the given cipher algorithm.

Function: ossl-bytes-to-key cipher digest salt password count

Derive a key and initialisation vector (iv) suitable for a cipher. Return a string key being the key. The initialisation vector is put into key’s property list as 'iv.

cipher (a symbol) is the cipher to derive the key and IV for. Valid ciphers can be obtained by ossl-available-ciphers.

digest (a symbol) is the message digest to use. Valid digests can be obtained by ossl-available-digests.

salt (string or nil) is used as a salt in the derivation. Use nil here to indicate that no salt is used.

password is an arbitrary string which is processed to derive a unique key and IV.

count (a positive integer) is the iteration count to use. This indicates how often the hash algorithm is called recursively.

Note: You probably want to put a wrapping encoder function (like base16-encode-string) around it, since this returns binary string data.

Note: It is disregarded to use the key/iv pair of, say, AES-128 cipher for e.g. a blowfish (BF) cipher, although it seems possible and is not explicitly forbidden. Such malpractices may result in severe crashes.

(base16-encode-string
 (ossl-bytes-to-key 'AES-256-OFB 'SHA512 "somesalt" "secret" 1))
  ⇒ "bd2b1aaf7ef4f09be9f52ce2d8d599674d81aa9d6a4421696dc4d93dd0619d68"

(base16-encode-string
 (ossl-bytes-to-key 'AES-256-OFB 'SHA512 "diffsalt" "secret" 1))
  ⇒ "bd2b1aaf7ef4f09be9f52ce2d8d599674d81aa9d6a4421696dc4d93dd0619d68"

(base16-encode-string
 (ossl-bytes-to-key 'AES-256-OFB 'SHA512 "diffsalt" "retsec" 1))
  ⇒ "38515c1868bcab470075ec32bc79b0ed1aa945de95d2261991ea840921e7747b"

These examples show how different passwords yield different keys, and that different salts do not affect the result. As mentioned in the doc string the result carries an object-plist with the initialisation vector inside:

(object-plist
 (ossl-bytes-to-key 'AES-256-OFB 'SHA512 "somesalt" "secret" 1))
  ⇒ (iv "????????????????")

(base16-encode-string
 (get
  (ossl-bytes-to-key 'AES-256-OFB 'SHA512 "somesalt" "secret" 1)
  'iv))
  ⇒ "2ce56b4d64a9ef097761ced99e0f6726"

Function: ossl-encrypt cipher string key &optional iv

Return the cipher of string computed by cipher under key.

cipher (a symbol) may be one of the OpenSSL cipher algorithms you have compiled. See ossl-available-ciphers.

string is the text to be encrypted.

key should be a key generated suitably for this cipher, for example by ossl-bytes-to-key.

Optional fourth argument iv should be an initialisation vector suitable for this cipher. Normally the initialisation vector from key’s property list is used. However, if iv is non-nil, use this IV instead.

Note: You probably want to put a wrapping encoder function (like base16-encode-string) around it, since this returns binary string data.

Function: ossl-decrypt cipher string key &optional iv

Return the deciphered version of string computed by cipher under key.

cipher (a symbol) may be one of the OpenSSL cipher algorithms you have compiled. See ossl-available-ciphers.

string is the text to be decrypted.

key should be a key generated suitably for this cipher, for example by ossl-bytes-to-key.

Optional fourth argument iv should be an initialisation vector suitable for this cipher. Normally the initialisation vector from key’s property list is used. However, if iv is non-nil, use this IV instead.

(base16-encode-string
 (let ((key
        (ossl-bytes-to-key 'AES-256-OFB 'SHA512 "salt" "secret" 10)))
   (ossl-encrypt 'AES-256-OFB "Very secret text." key)))
  ⇒ "bbedc78c88eddea29c8653f551da391091"

(let ((key
       (ossl-bytes-to-key 'AES-256-OFB 'SHA512 "salt" "secret" 10))
      (s (base16-decode-string "bbedc78c88eddea29c8653f551da391091")))
  (ossl-decrypt 'AES-256-OFB s key))
  ⇒ "Very secret text."

(let ((key
       (ossl-bytes-to-key 'AES-256-OFB 'SHA512 "salt" "dontknow" 1))
      (s (base16-decode-string "bbedc78c88eddea29c8653f551da391091")))
  (ossl-decrypt 'AES-256-OFB s key))
  ⇒ "?????????????????"

The above example shows a complete cycle of encryption and decryption, as well as an attempt to decrypt a string using a wrong password.

As for message digests, there are two companion functions which directly work on files.

Function: ossl-encrypt-file cipher file key &optional iv outfile

Return the encrypted contents of file computed by cipher under key.

cipher (a symbol) may be one of the OpenSSL cipher algorithms you have compiled. See ossl-available-ciphers.

file is the file to be encrypted.

key should be a key generated suitably for this cipher, for example by ossl-bytes-to-key.

Optional fourth argument iv should be an initialisation vector suitable for this cipher. Normally the initialisation vector from key’s property list is used. However, if iv is non-nil, use this IV instead.

Optional fifth argument outfile may specify a file to have the encrypted data redirected.

Note: You probably want to put a wrapping encoder function (like base16-encode-string) around it, since this returns binary string data.

Function: ossl-decrypt-file cipher file key &optional iv outfile

Return the deciphered version of file computed by cipher under key.

cipher (a symbol) may be one of the OpenSSL cipher algorithms you have compiled. See ossl-available-ciphers.

file is the file to be decrypted.

key should be a key generated suitably for this cipher, for example by ossl-bytes-to-key.

Optional fourth argument iv should be an initialisation vector suitable for this cipher. Normally the initialisation vector from key’s property list is used. However, if iv is non-nil, use this IV instead.

Optional fifth argument outfile may specify a file to have the decrypted data redirected.