Add support for custom hash functions

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

1 files changed, 137 insertions, 0 deletions

diff --git a/librecrypt_set_pepper.3 b/librecrypt_set_pepper.3
new file mode 100644
index 0000000..2d0c86b
--- /dev/null
+++ b/librecrypt_set_pepper.3
@@ -0,0 +1,137 @@
+.TH LIBRECRYPT_SET_PEPPER 3 LIBRECRYPT
+.SH NAME
+librecrypt_set_pepper - Set the pepper to use for a hash algorithm
+
+.SH SYNOPSIS
+.nf
+#include <librecrypt.h>
+
+enum librecrypt_hash_algorithm {
+	LIBRECRYPT_ARGON2I_V1_0,
+	LIBRECRYPT_ARGON2I_V1_3,
+	LIBRECRYPT_ARGON2D_V1_0,
+	LIBRECRYPT_ARGON2D_V1_3,
+	LIBRECRYPT_ARGON2ID_V1_0,
+	LIBRECRYPT_ARGON2ID_V1_3,
+	LIBRECRYPT_ARGON2DS_V1_0,
+	LIBRECRYPT_ARGON2DS_V1_3,
+	LIBRECRYPT_HASH_ALGORITHM_END /* end of enum marker (always last) */
+};
+
+void \fBlibrecrypt_set_pepper\fP(LIBRECRYPT_CONTEXT *\fIctx\fP, enum librecrypt_hash_algorithm \fIalgo\fP,
+                           const void *\fIdata\fP, size_t \fIlen\fP);
+.fi
+.PP
+Link with
+.IR -lrecrypt .
+
+.SH DESCRIPTION
+The
+.BR librecrypt_set_pepper ()
+function sets the pepper for a library-provided
+hash algorithm selected by the
+.I algo
+argument, when the
+.I ctx
+object is specified when performing the has.
+.PP
+The
+.I data
+argument shall be the pepper in raw binary,
+and the
+.I len
+argument shall be the number of bytes in
+.IR data .
+.PP
+The caller is responsible for the lifetime of
+.IR data :
+deallocating it will deallocate it for
+.I *ctx
+as it only holds a reference to
+.IR data ,
+not a copy of it.
+
+.SH RETURN VALUES
+The
+.BR librecrypt_set_pepper ()
+function returns 0 upon successful completion.
+On failure, -1 is returned and
+.I errno
+is set to describe the error.
+
+.SH ERRORS
+The
+.BR librecrypt_set_pepper ()
+function will fail if:
+.TP
+.B EINVAL
+The value of
+.I len
+is not supported for the selected algorithm.
+(This implies that the selected algorithm
+was enabled at compile time and that it
+supports pepper.)
+.TP
+.B ENOSUP
+The algorithm selected by the
+.I algo
+argument does not support peppers.
+(This implies that the selected algorithm
+was enabled at compile time.)
+.TP
+.B ENOSYS
+The algorithm selected by the
+.I algo
+argument is either not recognised by the
+library or was disabled at compile-time.
+
+.SH EXTENDED DESCRIPTION
+The following values for
+.I algo
+are supported and may cause the
+.BR librecrypt_is_enabled ()
+function to return either 0 or 1
+(all other cause the function to return 0):
+.TP
+.B LIBRECRYPT_ARGON2I_V1_0
+Argon2i, version 1.0, which is presented by
+\(dq$argon2i$v=13$\(dq, optionally without \(dq$v=13\(dq.
+.TP
+.B LIBRECRYPT_ARGON2I_V1_3
+Argon2i, version 1.3, which is presented by
+\(dq$argon2i$v=19$\(dq.
+.TP
+.B LIBRECRYPT_ARGON2D_V1_0
+Argon2d, version 1.0, which is presented by
+\(dq$argon2d$v=13$\(dq, optionally without \(dq$v=13\(dq.
+.TP
+.B LIBRECRYPT_ARGON2D_V1_3
+Argon2d, version 1.3, which is presented by
+\(dq$argon2d$v=19$\(dq.
+.TP
+.B LIBRECRYPT_ARGON2ID_V1_0
+Argon2id, version 1.0, which is presented by
+\(dq$argon2id$v=13$\(dq, optionally without \(dq$v=13\(dq.
+.TP
+.B LIBRECRYPT_ARGON2ID_V1_3
+Argon2id, version 1.3, which is presented by
+\(dq$argon2id$v=19$\(dq.
+.TP
+.B LIBRECRYPT_ARGON2DS_V1_0
+Argon2ds, version 1.0, which is presented by
+\(dq$argon2ds$v=13$\(dq, optionally without \(dq$v=13\(dq.
+.TP
+.B LIBRECRYPT_ARGON2DS_V1_3
+Argon2ds, version 1.3, which is presented by
+\(dq$argon2ds$v=19$\(dq.
+
+.SH HISTORY
+The
+.BR librecrypt_set_pepper ()
+function was introduced in version 1.1 of
+.BR librecrypt .
+
+.SH SEE ALSO
+.BR librecrypt (7),
+.BR librecrypt_create_context (3),
+.BR librecrypt_hash_algorithm_end (3)