Add librecrypt_verify

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

1 files changed, 128 insertions, 0 deletions

diff --git a/librecrypt_verify.3 b/librecrypt_verify.3
new file mode 100644
index 0000000..8c6e421
--- /dev/null
+++ b/librecrypt_verify.3
@@ -0,0 +1,128 @@
+.TH LIBRECRYPT_VERIFY 3 LIBRECRYPT
+.SH NAME
+librecrypt_verify - Verify password against known password hash
+
+.SH SYNOPSIS
+.nf
+#include <librecrypt.h>
+
+int \fBlibrecrypt_verify\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_verify ()
+function computes the hash of a password and compares
+it against a provided hash.
+.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 ,
+and shall include the hash result, that is, it shall
+conform to the output of the
+.BR librecrypt_crypt (3)
+function. 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
+Any encountered
+.BR EINTR
+is ignored.
+.PP
+.I settings
+must not be
+.IR NULL .
+
+.SH RETURN VALUES
+The
+.BR librecrypt_hash ()
+function returns 1 if the hash of the input
+password matches the provided hash, 0 otherwise.
+On failure, -1 is returned and
+.I errno
+is set to describe the error.
+
+.SH ERRORS
+The
+.BR librecrypt_verify ()
+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 EINVAL
+.I settings
+uses asterisk-encoding in place of a hash result.
+.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_verify ()
+T}	Thread safety	MT-Safe
+T{
+.BR librecrypt_verify ()
+T}	Async-signal safety	AS-Unsafe
+.TE
+.sp
+
+.SH HISTORY
+The
+.BR librecrypt_verify ()
+function was introduced in version 1.1 of
+.BR librecrypt .
+
+.SH SEE ALSO
+.BR librecrypt (7),
+.BR librecrypt_hash_binary (3),
+.BR librecrypt_hash (3),
+.BR librecrypt_crypt (3),
+.BR librecrypt_equal (3),
+.BR librecrypt_equal_binary (3)