Add librecrypt.7 and READMEHEADmaster

Signed-off-by: Mattias Andrée <m@maandree.se>

1 files changed, 128 insertions, 0 deletions

diff --git a/librecrypt.7 b/librecrypt.7
new file mode 100644
index 0000000..7c577a4
--- /dev/null
+++ b/librecrypt.7
@@ -0,0 +1,128 @@
+.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)