First commit

Signed-off-by: Mattias Andrée <m@maandree.se>

1 files changed, 131 insertions, 0 deletions

diff --git a/librecrypt_crypt.3 b/librecrypt_crypt.3
new file mode 100644
index 0000000..0237862
--- /dev/null
+++ b/librecrypt_crypt.3
@@ -0,0 +1,131 @@
+.TH LIBRECRYPT_CRYPT 3 LIBRECRYPT
+.SH NAME
+librecrypt_crypt - Compute password hash encoded in ASCII with settings prefix
+
+.SH SYNOPSIS
+.nf
+#include <librecrypt.h>
+
+ssize_t \fBlibrecrypt_crypt\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_crypt ()
+function computes the hash of a password.
+The resulting hash is encoded with
+.BR librecrypt_encode (3)
+and the settings string is included in the front
+of the output.
+.PP
+The password is provided in
+.IR phrase
+and can contain null bytes; its length is
+specified, in bytes, by
+.IR len .
+.PP
+The password hash configuration string is
+provided in
+.IR settings .
+If
+.I settings
+contains a resulting hash, it is ignored.
+.PP
+The
+.I reserved
+parameter is reserved for future use and
+should be
+.IR NULL .
+.PP
+On successful completion, if
+.I size
+is positive, the output is
+null byte-terminated even if truncated.
+.PP
+Any encountered
+.BR EINTR
+is ignored.
+.PP
+On failure,
+.I out_buffer
+may be partially written.
+.PP
+.I settings
+must not be
+.IR NULL .
+
+.SH RETURN VALUES
+The
+.BR librecrypt_crypt ()
+function returns the number of bytes that would
+have been written to
+.IR out_buffer
+if
+.I size
+was sufficiently large, excluding the terminating
+null byte. On failure, -1 is returned and
+.I errno
+is set to describe the error.
+
+.SH ERRORS
+The
+.BR librecrypt_crypt ()
+function will fail if:
+.TP
+.B EINVAL
+.I reserved
+is not
+.IR NULL .
+.TP
+.B EINVAL
+.I settings
+is invalid.
+.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_crypt ()
+T}	Thread safety	MT-Safe
+T{
+.BR librecrypt_crypt ()
+T}	Async-signal safety	AS-Unsafe
+.TE
+.sp
+
+.SH HISTORY
+The
+.BR librecrypt_crypt ()
+function was introduced in version 1.0 of
+.BR librecrypt .
+
+.SH SEE ALSO
+.BR librecrypt (7),
+.BR librecrypt_hash_binary (3),
+.BR librecrypt_hash (3),
+.BR librecrypt_test_supported (3)