.TH LIBRECRYPT 7 LIBRECRYPT
.SH NAME
librecrypt - Offline-hardenable password hashing

.SH SYNOPSIS
.ni
#include <librecrypt.h>
.fi
.PP
Link with
.IR -lrecrypt .
Static linking may require additional
flags depending on enabled hash algorithms.

.SH DESCRIPTION
The
.B librecrypt
library provides a unified interface for
several password hash functions and the ability to chain
password hash functions so that a weaking hashed password
can be hardend, without knowing the plain-text password,
by hashing the hash with a stronger function.
.PP
.B librecrypt
extends
.BR crypt (3)\(aqs
password hash string syntax
by introducing the
.RB \(aq > \(aq
character to specifying chaining.
The left-most hash function is used on the plain-text
password, and the next to the right, is used on the binary
hash result, and so on, and only the final hash is stored
in the string: as part of the last
.RB \(aq > \(aq-delimited
section.
.PP
It also supports specifying a password hashing configuration
without specifying actual salt values, but instead how many
bytes of salt to generate. This done using asterisk-encoding:
an ASCII asterisk character
.RB (\(aq * \(aq)
followed by the number of
bytes encoded as a non-negative decimal number in ASCII.
.PP
The
.B librecrypt
library implements the following functions:
.sp
.SS Password hashing functions:
.TP
.BR librecrypt_crypt (3)
Compute password hash encoded in ASCII with settings
prefix.
.TP
.BR librecrypt_hash (3)
Compute password hash encoded in ASCII without
settings prefix.
.TP
.BR librecrypt_hash_binary (3)
Compute password hash in raw binary form.
.TP
.BR librecrypt_add_algorithm (3)
Append an algorithm chain to a password hash string.
.sp
.SS Password hashing configuration generation functions:
.TP
.BR librecrypt_test_supported (3)
Check whether an algorithm chain is supported.
.TP
.BR librecrypt_make_settings (3)
Generate a password hash settings string.
.TP
.BR librecrypt_realise_salts (3)
Realise asterisk-encoded random salts in a settings
string.
.sp
.SS Secure application helper functions:
.TP
.BR librecrypt_equal (3)
Compare strings in constant time.
.TP
.BR librecrypt_equal_binary (3)
Compare memory segments in constant time.
.TP
.BR librecrypt_wipe (3)
Securely erase a memory buffer.
.TP
.BR librecrypt_wipe_str (3)
Securely erase a string.
.sp
.SS Password hash string decomposition functions (ADVANCED):
.TP
.BR librecrypt_settings_prefix (3)
Get length of settings prefix in a password hash
string.
.TP
.BR librecrypt_chain_length (3)
Get number of algorithms in a chained password hash
string.
.TP
.BR librecrypt_decompose_chain (3)
Split a chained password hash string into algorithm
components.
.TP
.BR librecrypt_decompose_chain1 (3)
Replace algorithm link delimiters with null bytes.
.TP
.BR librecrypt_next_algorithm (3)
Iterate over algorithms in a chained password hash
string.
.sp
.SS Binary value encoding functions (ADVANCED):
.TP
.BR librecrypt_encode (3)
Encode binary salt or hash result into ASCII.
.TP
.BR librecrypt_decode (3)
Decode ASCII encoding of a salt or hash result into
binary.
.TP
.BR librecrypt_get_encoding (3)
Get encoding alphabet for the last algorithm in a
chain.

.SH NOTES
Using
.BR librecrypt_add_algorithm (3)
to hash existing password
hashes should be used as a transitional mitigation strategy
when replaing an old password hash function. Once the password
is available in clear text, it should be hashed anew using
only the new password hash function: this will both increase
security and reducing login it, allowing for stronger hash
function configurations. This is especially important if the
password is actually a key and longer than the old hash. It
is also a good idea to force password reset, and lock any
account that hasn't reset its password, because it is
possibly that the old password hashes has been leaked and it
will force a fresh hashing even one counts that seldom log in.

.SH SEE ALSO
.BR crypt (3),
.BR crypt (5)