Module libreauth::pass

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	norm	string: nfd | nfkd | nfc | nfkc | none	Unicode normalization.	nfkc
	len-calc	string: bytes | chars	Unicode string length calculation method.	chars
	pmin	integer	Password minimal length.	8
	pmax	integer	Password maximal length.	128
	ver	integer	The password hashing version.	1
argon2	passes	integer	The number of block matrix iterations to perform.	3
	mem	integer	Memmory cost (2^mem kibbibytes).	12 (4096 KiB)
	lanes	integer	The degree of parallelism by which memory is filled during hash computation.	4
	len	integer	Output length, in bytes.	128
pbkdf2	iter	integer	Number of iterations.	45000
	hash	string: sha1 | sha224 | sha256 | sha384 | sha512 | sha512t224 | sha512t256 | keccak224 | keccak256 | keccak384 | keccak512 | sha3-224 | sha3-256 | sha3-384 | sha3-512	The hash function.	sha512

Examples

use libreauth::pass::HashBuilder;

const PWD_SCHEME_VERSION: usize = 1;

// Hashing a password.
let password = "correct horse battery staple".to_string();
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".to_string()));
assert!(checker.is_valid(&password));
if checker.is_valid(&password) && checker.needs_update(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.

Enums

Algorithm	Algorithms available to hash the password.
ErrorCode	Error codes used both in the rust and C interfaces.
LengthCalculationMethod	Available methods to calculate the length of a UTF-8 string.
Normalization	Available string normalization methods.
PasswordStorageStandard	Defines whether or not LibreAuth should comply with recommendations from a specific standard.

Constants

PASSWORD_STORAGE_LEN

The recommended length to reserve for password hash storage.

Functions

libreauth_pass_hash	[C binding] Hash a password according to the given configuration and stores it in the supplied buffer.
libreauth_pass_init	[C binding] Initialize a struct libreauth_pass_cfg with the default values.
libreauth_pass_init_from_phc	[C binding] Initialize a struct libreauth_pass_cfg from a PHC string.
libreauth_pass_init_std	[C binding] Initialize a struct libreauth_pass_cfg with the default values for a given standard.
libreauth_pass_is_valid	[C binding] Check whether or not the supplied password is valid.