.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 SEE ALSO
.BR crypt (3),
.BR crypt (5)