.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)