.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)