1 files changed, 161 insertions, 0 deletions
diff --git a/librecrypt_realise_salts.3 b/librecrypt_realise_salts.3
new file mode 100644
index 0000000..8a743cc
--- /dev/null
+++ b/librecrypt_realise_salts.3
@@ -0,0 +1,161 @@
+.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)