This module gives different ways of obtaining secret keys.

Key derivation (from a password)

Sometimes, instead of generating fresh random transient encryption keys, you want an encryption key to be persistent and you don’t want to store it anywhere – instead you ask the user to provide it. Such a secret value known and entered by the user is usually called a “password”.

However, passwords make terrible encryption keys because encryption keys:

1. often need to have a specific exact length and
2. need to be hard to guess (or brute-force).

Item 1 above can be easily ticked off by deriving the encryption key from the password by applying a hash-function to it, however in order to achieve 2 we need our “hash-function” to:

• be slow to compute (to make brute-forcing less feasible) and
• mix extra “noise” into the derivation process to make it harder to pre-compute derived values in advance.

A construction that satisfies both requirements is called a key derivation function (KDF). This module provides a convenient interface for deriving secure keys from passwords by the way of one such KDF.

Use

This module provides two functions: derive and rederive. You can think of the entire process similar to how you set the password on your account at some website once, and then use this password to log in.

When you derive a key for the first time (e.g. you ask the user to enter their password twice, and then encrypt something), you use the derive function, which gives you the derived key and a derivation slip. The slip is not secret, you can store it in plain text and, in fact, you have to store it in plaintext somewhere next to the encrypted data.

When you need to derive the key in the future (e.g. to decrypt some previously encrypted data), you will need the user’s password (ask them) and you will need the original derivation slip, which you should have stored. You pass these to rederive and it will give you the same key.

import qualified Crypto.Key as Key

encrypt = do
  password <- {- ask the user to enter their password -}
  password2 <- {- ask the user to confirm their password -}
  when (password /= password2 then) $ throwIO {- passwords do not match -}

  let params = {- choose key derivation parameters -}
  (key, slip) <- Key.derive params password

  {- store slip (it is not secret) -}
  {- encrypt data with key -}

decrypt = do
  password <- {- ask the user to enter their password -}
  slip <- {- get the stored slip -}

  key <- Key.rederive slip password

  {- decrypt data with key -}

Random key generation

The generate function is great at generating new secure secret keys.