.TH LIBRECRYPT_REALISE_SALTS 3 LIBRECRYPT
.SH NAME
librecrypt_realise_salts - Realise asterisk-encoded random salts in a settings string

.SH SYNOPSIS
.nf
#include <librecrypt.h>

ssize_t \fBlibrecrypt_realise_salts\fP(char *restrict \fIout_buffer\fP, size_t \fIsize\fP, const char *\fIsettings\fP,
                                ssize_t (*\fIrng\fP)(void *\fIout\fP, size_t \fIn\fP, void *\fIuser\fP), void *\fIuser\fP);
.fi
.PP
Link with
.IR -lrecrypt .
Static linking may require additional flags
depending on enabled hash algorithms.

.SH DESCRIPTION
The
.BR librecrypt_realise_salts ()
function locates all asterisks followed by a
non-negative decimal number in
.IR settings
and replaces each with ASCII-encoded random
bytes (as many bytes as the number specifies),
writing the result to
.IR out_buffer .
.PP
.IR *rng ,
or a default implementation (which tries to use
cryptographic random number generation but has
a non-cryptographic random number generation as
a last resort) if
.I rng
is
.IR NULL ,
used to generate random bytes.
.I *rng
shall fill out with at least 1, and up to
.IR n ,
random bytes, and return the number of bytes
written, or return -1 on failure.
.PP
The
.I data
argument is passed into the
.IR *rng -parameter
with the same name, as is and may be used by
.I *rng
for user-defined purposes.
.PP
If
.I rng
is
.IR NULL ,
a default cryptographic random number generator
is used. The
.I *rng
function shall generate between 1 and
.I n
bytes (inclusively), write them to the front of
.IR out ,
and return the number of generated bytes, or
-1 on failure.
.PP
On successful completion, if
.I size
is positive, the output is
null byte-terminated even if truncated.
.PP
If
.I rng
is
.IR NULL ,
any encountered
.BR EINTR
is ignored; if it is encountered,
.I errno
will be set to
.BR EINTR ,
but is otherwise left unmodified unless the
function fails due to one of the
errors listed in the
.B ERRORS
section.
.PP
.I settings
must not be
.IR NULL .

.SH RETURN VALUES
The
.BR librecrypt_realise_salts ()
function returns the number of bytes that
would have been written to
.IR out_buffer
if
.I size
was sufficiently large, or -1 on failure.

.SH ERRORS
The
.BR librecrypt_realise_salts ()
function will fail if:
.TP
.B ERANGE
The expected return value is greater than {SSIZE_MAX}.
.TP
.B EINVAL
Asterisk-encoding was used in an invalid context.
.TP
.B ENOSYS
.I settings
contain an algorithm that is not recognised or was
disabled at compile-time.
.PP
Additionally, unless
.I rng
is
.IR NULL ,
.I *rng
may set
.IR errno .

.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_realise_salts ()
T}	Thread safety	MT-Safe
T{
.BR librecrypt_realise_salts ()
T}	Async-signal safety	T{
AS-Safe /\fIrng\fP
.br
AS-Unsafe /\fI!rng\fP
T}
.TE
.sp
.PP
.I rng
is
.RI non- NULL ,
.I *rng
may weaken the safety attributes.

.SH HISTORY
The
.BR librecrypt_realise_salts ()
function was introduced in version 1.0 of
.BR librecrypt .

.SH SEE ALSO
.BR librecrypt (7),
.BR librecrypt_make_settings (3)