Module libreauth::pass

source ·
Expand description

Password authentication module.

It allows you to:

  • generate a fingerprint of the password that could be stored;
  • check a password against the stored fingerprint.

Standards

By default, LibreAuth has security in mind and therefore provides a decent level of security.

Sometimes, you may be required to comply with industry or government standards. To ease such requirements, LibreAuth is able to adapt itself to some standards. Please note such modes does not automatically guaranty you compliance, you may have other items to check.

Storage format

The password fingerprint is stored in the PHC format which is very close to the modular crypt format (cf. [1] and [2]).

Supported identifiers and parameters

Algorithm Parameter name Parameter type Parameter description Default value
Global parameters len-calc string: bytes | chars Unicode string length calculation method. chars
norm string: nfd | nfkd | nfc | nfkc | none Unicode normalization. nfkc
pmax integer Password maximal length. 128
pmin integer Password minimal length. 8
ver integer The password hashing version. Sum of the user-defined and internal version numbers.
xhmac string: none | before | after If not none, apply an additional HMAC with an external pepper before or after hashing the password. none
xhmac-alg string: sha1 | sha224 | sha256 | sha384 | sha512 | sha512t224 | sha512t256 | keccak224 | keccak256 | keccak384 | keccak512 | sha3-224 | sha3-256 | sha3-384 | sha3-512 The underlying hash function to use for the HMAC. sha512
argon2 lanes integer The degree of parallelism by which memory is filled during hash computation. 4
len integer Output length, in bytes. 128
mem integer Memmory cost (2^mem kibbibytes). 12 (4096 KiB)
passes integer The number of block matrix iterations to perform. 3
pbkdf2 hmac string: sha1 | sha224 | sha256 | sha384 | sha512 | sha512t224 | sha512t256 | keccak224 | keccak256 | keccak384 | keccak512 | sha3-224 | sha3-256 | sha3-384 | sha3-512 The underlying hash function to use for the HMAC. sha512
iter integer Number of iterations. 45000

Examples

use libreauth::pass::HashBuilder;

const PWD_SCHEME_VERSION: usize = 1;

// Hashing a password.
let password = "correct horse battery staple";
let hasher = HashBuilder::new().version(PWD_SCHEME_VERSION).finalize().unwrap();
let stored_password = hasher.hash(password).unwrap();
// Store the result in the database.

// Checking a password against a previously hashed one.
let checker = HashBuilder::from_phc(stored_password.as_str()).unwrap();
assert!(!checker.is_valid("bad password"));
assert!(checker.is_valid(password));
if checker.is_valid(password) && checker.needs_update(Some(PWD_SCHEME_VERSION)) {
  // The password hashing scheme has been updated since we stored this
  // password. Hence, We should hash it again and update the database.
}

Structs

  • HashBuilder
    Builds a Hasher object.
  • Hasher
    Hash a password and check a password against a previously hashed one.
  • PassCfg
    [C binding] Password hasher configuration storage

Enums

Constants

Functions