First commit

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

1 files changed, 135 insertions, 0 deletions

diff --git a/librecrypt_hash.3 b/librecrypt_hash.3
new file mode 100644
index 0000000..5bf32ea
--- /dev/null
+++ b/librecrypt_hash.3
@@ -0,0 +1,135 @@
+.TH LIBRECRYPT_HASH 3 LIBRECRYPT
+.SH NAME
+librecrypt_hash - Compute password hash encoded in ASCII without settings prefix
+
+.SH SYNOPSIS
+.nf
+#include <librecrypt.h>
+
+ssize_t \fBlibrecrypt_hash\fP(char *restrict \fIout_buffer\fP, size_t \fIsize\fP,
+                       const char *\fIphrase\fP, size_t \fIlen\fP,
+                       const char *\fIsettings\fP, void *\fIreserved\fP);
+.fi
+.PP
+Link with
+.IR -lrecrypt .
+Static linking may require additional flags
+depending on enabled hash algorithms.
+
+.SH DESCRIPTION
+The
+.BR librecrypt_hash ()
+function computes the hash of a password.
+The resulting hash is encoded with
+.BR librecrypt_encode (3)
+but stored without any settings prefix.
+.PP
+The password is provided in
+.IR phrase
+and can contain null bytes; its length is specified by
+.IR len .
+.PP
+The password hash configuration string is provided in
+.IR settings .
+If
+.I settings
+contains a resulting hash, it is ignored.
+If
+.I settings
+uses asterisk-encoding to specify random salts,
+the function fails.
+.PP
+The
+.I reserved
+parameter is reserved for future use and should be
+.IR NULL .
+.PP
+On successful completion, if
+.I size
+is positive, the output is
+null byte-terminated even if truncated.
+.PP
+Any encountered
+.BR EINTR
+is ignored.
+.PP
+On failure,
+.I out_buffer
+remains unmodified.
+.PP
+.I settings
+must not be
+.IR NULL .
+
+.SH RETURN VALUES
+The
+.BR librecrypt_hash ()
+function returns the number of bytes that would
+have been written to
+.IR out_buffer
+if
+.I size
+was sufficiently large, excluding the terminating
+null byte. On failure, -1 is returned and
+.I errno
+is set to describe the error.
+
+.SH ERRORS
+The
+.BR librecrypt_hash ()
+function will fail if:
+.TP
+.B EINVAL
+.I reserved
+is not
+.IR NULL .
+.TP
+.B EINVAL
+.I settings
+is invalid.
+.TP
+.B EINVAL
+.I settings
+uses asterisk-encoding to specify random salts.
+.TP
+.B ERANGE
+.I len
+is too large or too small for the selected
+initial algorithm.
+.TP
+.B ENOMEM
+Failed to allocate internal scratch memory.
+.TP
+.B ENOSYS
+A selected hash algorithm is not recognised or
+was disabled at compile-time.
+
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.PP
+.TS
+allbox;
+lb lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.BR librecrypt_hash ()
+T}	Thread safety	MT-Safe
+T{
+.BR librecrypt_hash ()
+T}	Async-signal safety	AS-Unsafe
+.TE
+.sp
+
+.SH HISTORY
+The
+.BR librecrypt_hash ()
+function was introduced in version 1.0 of
+.BR librecrypt .
+
+.SH SEE ALSO
+.BR librecrypt (7),
+.BR librecrypt_hash_binary (3),
+.BR librecrypt_crypt (3),
+.BR librecrypt_test_supported (3)