Crypto.Scrypt

Scrypt is a sequential memory-hard key derivation function. This module provides low-level bindings to the scrypt key derivation function as well as a higher-level password-storage API. It is based on a fast C implementation of scrypt, written by Colin Percival. For further information see http://www.tarsnap.com/scrypt.html.

Parameters to the scrypt function

Scrypt takes three tuning parameters: N, r and p. They affect running time and memory usage:

Memory usage is approximately 128*r*N bytes. Note that the scryptParams function takes log_2(N) as a parameter. As an example, the defaultParams

   log_2(N) = 14, r = 8 and p = 1

lead to scrypt using 128 * 8 * 2^14 = 16M bytes of memory.

Running time is proportional to all of N, r and p. Since it's influence on memory usage is small, p can be used to independently tune the running time.

data ScryptParams

Encapsulates the three tuning parameters to the scrypt function: N, r and p (see above) as well es the length of the derived key.

Instances

Eq ScryptParams

Show ScryptParams

scryptParams

Arguments

:: Integer

log_2(N). Scrypt's N parameter must be a power of two greater than one, thus it's logarithm to base two must be greater than zero. 128*r*N must be smaller than the available memory address space.

-> Integer

r, must be greater than zero.

-> Integer

p, must be greater than zero. r and p must satisfy r*p < 2^30.

-> Maybe ScryptParams

Returns Just the parameter object for valid arguments, otherwise Nothing.

Constructor function for ScryptParams with default derived-key-length of 64 bytes.

scryptParamsLen

Arguments

:: Integer

log_2(N),

-> Integer

r,

-> Integer

p,

-> Integer

Length of the derived key (the output of scrypt) in bytes. Must be greater than zero and less than or equal to (2^32-1)*32.

-> Maybe ScryptParams

Constructor function for ScryptParams with an additional parameter to control the length of the derived key. Only use this function if you are sure you need control over the length of the derived key. Use scryptParams instead.

defaultParams :: ScryptParams

Default parameters as recommended in the scrypt paper:

   N = 2^14, r = 8, p = 1

Equivalent to fromJust (scryptParams 14 8 1).

Password Storage

To allow storing encrypted passwords conveniently in a single database column, the password storage API provides the data type EncryptedPass. It combines a Pass as well as the Salt and ScryptParams used to compute it into a single ByteString, separated by pipe ("|") characters. The Salt and PassHash are base64-encoded. Storing the ScryptParams with the password allows to gradually strengthen password encryption in case of changing security requirements.

A usage example is given below, showing encryption, verification and changing ScryptParams:

 >>> encrypted <- encryptPassIO defaultParams (Pass "secret")
 >>> print encrypted
 EncryptedPass {getEncryptedPass = "14|8|1|Wn5x[SNIP]nM=|Zl+p[SNIP]g=="}
 >>> print $ verifyPass defaultParams (Pass "secret") encrypted
 (True,Nothing)
 >>> print $ verifyPass defaultParams (Pass "wrong") encrypted
 (False,Nothing)
 >>> let newParams = fromJust $ scryptParams 16 8 1
 >>> print $ verifyPass newParams (Pass "secret") encrypted
 (True,Just (EncryptedPass {getEncryptedPass = "16|8|1|Wn5x[SNIP]nM=|ZmWw[SNIP]Q=="}))

newtype EncryptedPass

Constructors

EncryptedPass

Fields

getEncryptedPass :: ByteString

Instances

Eq EncryptedPass

Show EncryptedPass

encryptPassIO :: ScryptParams -> Pass -> IO EncryptedPass

Encrypt the password with the given parameters and a random 32-byte salt. The salt is read from /dev/urandom on Unix systems or CryptoAPI on Windows.

encryptPassIO' :: Pass -> IO EncryptedPass

Equivalent to encryptPassIO defaultParams.

newSalt :: IO Salt

Generate a random 32-byte salt.

encryptPass :: ScryptParams -> Salt -> Pass -> EncryptedPass

Encrypt the password with the given parameters and salt.

encryptPass' :: Salt -> Pass -> EncryptedPass

Equivalent to encryptPass defaultParams.

verifyPass

Arguments

:: ScryptParams

Parameters to use for updating the EncryptedPass.

-> Pass

The candidate Pass.

-> EncryptedPass

The EncryptedPass to check against.

-> (Bool, Maybe EncryptedPass)

Returns a pair of

• Bool indicating verification success or failure.
• Just a new EncryptedPass if the given ScryptParams are different from those encapsulated in the given EncryptedPass, otherwise Nothing.

Verify a Pass against an EncryptedPass. The function also takes ScryptParams meeting your current security requirements. In case the EncryptedPass was generated with different parameters, the function returns an updated EncryptedPass, generated with the given ScryptParams. The Salt is kept from the given EncryptedPass.

verifyPass' :: Pass -> EncryptedPass -> Bool

Check the Pass against the EncryptedPass, using the ScryptParams encapsulated in the EncryptedPass.

Low-level bindings to the scrypt key derivation function

Bindings to a fast C implementation of scrypt. For password storage, consider using the more convenient higher-level API above.

newtype Pass

Constructors

Pass

Fields

getPass :: ByteString

Instances

Eq Pass

Show Pass

newtype Salt

Constructors

Salt

Fields

getSalt :: ByteString

Instances

Eq Salt

Show Salt

newtype PassHash

Constructors

PassHash

Fields

getHash :: ByteString

Instances

Eq PassHash

Show PassHash

scrypt :: ScryptParams -> Salt -> Pass -> PassHash

Calculates a hash from the given password, salt and parameters.

scrypt' :: Salt -> Pass -> PassHash

Note the prime symbol ('). Calls scrypt with defaultParams.