.TH LIBAR2SIMPLIFIED_CRYPT 3 LIBAR2SIMPLIFIED
.SH NAME
libar2simplified_crypt - Hash a password with Argon2
.SH SYNOPSIS
.nf
#include <libar2simplified.h>
char *libar2simplified_crypt(char *\fImsg\fP, const char *\fIparams\fP, char *\fIrv\fP);
.fi
.PP
Link with
.IR "-lar2simplified -lar2 -lblake -pthread" .
.SH DESCRIPTION
The
.BR libar2simplified_crypt ()
function calculates an Argon2 if the message
provided in the
.I msg
parameter, which must be a NUL-terminated string,
according to the hashing parameters specified in the
.I params
parameter, which must not contain any excess data
(the tag (expected hash result) is not considered
excess data). See
.BR libar2_hash (3)
for more information about
.IR params .
The hash (tag) is stored, in raw binary format
(does not include the hashing parameters) in
the buffer provided via the
.I hash
parameter. This buffer must be at least
.I libar2_hash_buf_size(params)
bytes large.
.PP
.I params
may use the extended format specified in
.BR libar2simplified_encode (3).
.PP
The
.BR libar2simplified_crypt (3)
function will erase (not deallocate) the contents of
.I msg
before returning.
.PP
If
.I rv
is
.IR NULL ,
the returned pointer will shall be deallocated
using the
.BR free (3)
function, otherwise the function will return
.I rv
and
.I rv
must have an allocation size of at least
.I libar2_hash_buf_size(libar2simplified_decode(params, NULL, NULL, NULL))
bytes (note however that the pointer returned by
.BR libar2simplified_decode (3)
shall be deallocated by the application).
.PP
If
.I params
specifies an exact hash and salt (and not just
their lengths), the returned string will be
equal to
.I params
if
.I msg
specifies the password that was used to create it,
and only with extreme unlikelyhood be equal to
.I params
otherwise.
.PP
Only
.I rv
may be
.IR NULL .
.SH RETURN VALUES
The
.BR libar2simplified_crypt ()
function returns
.I rv
upon successful completion, or if
.I rv
is
.IR NULL ,
a
.RI non- NULL
pointer to dynamically allocated memory;
the content will contain a hashing parameter
string with the hashing result and the salt
that was generated or provided.
On error,
.I NULL
is returned and
.I errno
is set to describe the error.
.SH ERRORS
The
.BR libar2simplified_crypt ()
function will fail if:
.TP
.B EINVAL
The contents of
.I params
is invalid or unsupported.
.TP
.B ENOMEM
Insufficient storage space is available.
.TP
.BR ENOSPC " or " EAGAIN
A resource required to initialise some item
needed for threading-support has been exhausted
or the number of instances of such items have
been reached.
.TP
.B EOWNERDEAD
A thread terminated unexpectedly.
.SH SEE ALSO
.BR libar2simplified (7),
.BR libar2simplified_recommendation (3),
.BR libar2simplified_encode (3),
.BR libar2simplified_hash (3),
.BR libar2_hash (3),
.BR libar2_hash_buf_size (3),
.BR crypt (3),
