Pbkdf2.Base (pbkdf2_elixir v2.0.0) View Source

Base module for the Pbkdf2 password hashing library.

Link to this section Summary

Functions

Generates a random salt.

Hash a password using Pbkdf2.

Verify a password by comparing it with the stored Pbkdf2 hash.

Link to this section Functions

Specs

gen_salt(keyword() | integer()) :: binary()

Generates a random salt.

This function takes one optional argument - a keyword list (see below for more details).

Options

The following options are available:

  • :salt_len - the length of the random salt
    • the default is 16 bytes
    • for more information, see the 'Salt length recommendations' section below
  • :format - the length of the random salt
    • the default is :modular (modular crypt format)
    • the other available options are :django and :hex

Examples

Here is an example of generating a salt with the default salt length and format:

Pbkdf2.Base.gen_salt()

To generate a different length salt:

Pbkdf2.Base.gen_salt(salt_len: 32)

And to generate a salt in Django output format:

Pbkdf2.Base.gen_salt(format: :django)

Salt length recommendations

In most cases, 16 bytes is a suitable length for the salt. It is not recommended to use a salt that is shorter than this (see below for details and references).

According to the Pbkdf2 standard, the salt should be at least 8 bytes long, but according to NIST recommendations, the minimum salt length should be 16 bytes.

Link to this function

hash_password(password, salt, opts \\ [])

View Source

Specs

hash_password(binary(), binary(), keyword()) :: binary()

Hash a password using Pbkdf2.

Options

There are four options (rounds can be used to override the value in the config):

  • :rounds - the number of rounds
    • the amount of computation, given in number of iterations
    • the default is 160_000
    • this can also be set in the config file
  • :format - the output format of the hash
    • the default is :modular - modular crypt format
    • the other available formats are:
      • :django - the format used in django applications
      • :hex - the hash is encoded in hexadecimal
  • :digest - the sha algorithm that pbkdf2 will use
    • the default is sha512
  • :length - the length, in bytes, of the hash
    • the default is 64 for sha512 and 32 for sha256
Link to this function

verify_pass(password, hash, salt, digest, rounds, output_fmt)

View Source

Specs

verify_pass(binary(), binary(), binary(), atom(), binary(), atom()) :: boolean()

Verify a password by comparing it with the stored Pbkdf2 hash.