1 files changed, 138 insertions, 0 deletions
diff --git a/librecrypt_hash_binary.3 b/librecrypt_hash_binary.3
new file mode 100644
index 0000000..720b82d
--- /dev/null
+++ b/librecrypt_hash_binary.3
@@ -0,0 +1,138 @@
+.TH LIBRECRYPT_HASH_BINARY 3 LIBRECRYPT
+.SH NAME
+librecrypt_hash_binary - Compute password hash in raw binary form
+
+.SH SYNOPSIS
+.nf
+#include <librecrypt.h>
+
+ssize_t \fBlibrecrypt_hash_binary\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_binary ()
+function computes the hash of a password.
+The hash is stored in raw binary format 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, up to
+.I size
+bytes are written to
+.IR out_buffer ;
+the return value describes how many bytes would have
+been written if
+.I size
+was sufficiently large.
+.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_binary ()
+function returns the number of bytes that would
+have been written to
+.IR out_buffer
+if
+.I size
+was sufficiently large.
+On failure, -1 is returned and
+.I errno
+is set to describe the error.
+
+.SH ERRORS
+The
+.BR librecrypt_hash_binary ()
+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_binary ()
+T}	Thread safety	MT-Safe
+T{
+.BR librecrypt_hash_binary ()
+T}	Async-signal safety	AS-Unsafe
+.TE
+.sp
+
+.SH HISTORY
+The
+.BR librecrypt_hash_binary ()
+function was introduced in version 1.0 of
+.BR librecrypt .
+
+.SH SEE ALSO
+.BR librecrypt (7),
+.BR librecrypt_hash (3),
+.BR librecrypt_crypt (3),
+.BR librecrypt_test_supported (3)