scrypt-0.3.1: Stronger password hashing via sequential memory-hard functions.

Crypto.Scrypt

Contents

Description

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.

Synopsis

Parameters to the scrypt function

Scrypt takes three tuning parameters: N, r and p. The parameters 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. However p only has an insignificant influence on memory usage an can thus be used to independently tune the running time of scrypt.

data ScryptParams Source

Encapsulates the three tuning parameters to the scrypt function: N, r and p (see above).

scryptParamsSource

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

The parameter r, must be greater than zero.

-> Integer

The parameter 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 the ScryptParams data type

defaultParams :: ScryptParamsSource

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 <- encryptPass defaultParams (Pass "secret")
 >>> print encrypted
 EncryptedPass {unEncryptedPass = "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 {unEncryptedPass = "16|8|1|Wn5x[SNIP]nM=|ZmWw[SNIP]Q=="}))

encryptPass :: ScryptParams -> Pass -> IO EncryptedPassSource

Encrypt the password with the given parameters and a random 32-byte salt. The salt is read from /dev/urandom.

encryptPass' :: Pass -> IO EncryptedPassSource

Equivalent to encryptPass defaultParams.

verifyPassSource

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

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 -> BoolSource

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 Source

Constructors

Pass 

Fields

unPass :: ByteString
 

Instances

newtype Salt Source

Constructors

Salt 

Fields

unSalt :: ByteString
 

Instances

newtype PassHash Source

Constructors

PassHash 

Fields

unHash :: ByteString
 

Instances

scrypt :: ScryptParams -> Salt -> Pass -> PassHashSource

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

scrypt' :: Salt -> Pass -> PassHashSource

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