ExPassword.Algorithm behaviour (expassword v0.2.0) View Source

Defines an algorithm to be used by ExPassword as a behaviour to be implemented

Link to this section Summary

Callbacks

Callback to extract the options initially used to produce hash from the hash itself

Callback to compute the hash of password with the given options (algorithm specific)

This callback should return true if the options initially used to produce hash are somehow different to options. Its goal is to indicate if the password should be rehashed because these options have since changed, in particular if they are now too weak.

valid?(hash)

Callback to determine if a given hash is valid to the current algorithm.

verify?(password, stored_hash)

Callback to check if the provided password matches the reference hash stored_hash

Link to this section Types

hash()

Specs

hash() :: binary()

options()

Specs

options() :: %{optional(atom()) => any()}

password()

Specs

password() :: binary()

Link to this section Callbacks

get_options(hash)

Specs

get_options(hash :: hash()) :: {:ok, options()} | {:error, :invalid}

Callback to extract the options initially used to produce hash from the hash itself

Returns {:error, :invalid} if the hash is invalid to the current algorithm else {:ok, options} where options is a Map filled with the values of the options specific to the current hashing method.

hash(password, options)

Specs

hash(password :: password(), options :: options()) :: hash() | no_return()

Callback to compute the hash of password with the given options (algorithm specific)

May raise in case of internal failure or if an option is invalid

needs_rehash?(hash, options)

Specs

needs_rehash?(hash :: hash(), options :: options()) :: boolean() | no_return()

Raises if options is invalid

valid?(hash)

Specs

valid?(hash :: hash()) :: boolean()

Callback to determine if a given hash is valid to the current algorithm.

It might be used for validation but its primary purpose is to identify (find) the algorithm from which were generated the given hash.

verify?(password, stored_hash)

Specs

verify?(password :: password(), stored_hash :: hash()) ::
  boolean() | no_return()

Callback to check if the provided password matches the reference hash stored_hash

May raise in case of internal failure or if stored_hash is invalid