diff options
| -rw-r--r-- | Makefile | 8 | ||||
| -rw-r--r-- | README | 15 | ||||
| -rw-r--r-- | libar2simplified.7 | 48 | ||||
| -rw-r--r-- | libar2simplified_crypt.3 | 132 | ||||
| -rw-r--r-- | libar2simplified_decode.3 | 141 | ||||
| -rw-r--r-- | libar2simplified_encode.3 | 89 | ||||
| -rw-r--r-- | libar2simplified_encode_hash.3 | 60 | ||||
| -rw-r--r-- | libar2simplified_hash.3 | 89 |
8 files changed, 582 insertions, 0 deletions
@@ -28,6 +28,8 @@ HDR =\ common.h LOBJ = $(OBJ:.o=.lo) +MAN3 = $(OBJ:.o=.3) +MAN7 = libar2simplified.7 all: libar2simplified.a libar2simplified.$(LIBEXT) test @@ -57,11 +59,15 @@ check: test install: libar2simplified.a libar2simplified.$(LIBEXT) mkdir -p -- "$(DESTDIR)$(PREFIX)/lib" mkdir -p -- "$(DESTDIR)$(PREFIX)/include" + mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3" + mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7" cp -- libar2simplified.a "$(DESTDIR)$(PREFIX)/lib/" cp -- libar2simplified.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libar2simplified.$(LIBMINOREXT)" ln -sf -- libar2simplified.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/libar2simplified.$(LIBMAJOREXT)" ln -sf -- libar2simplified.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/libar2simplified.$(LIBEXT)" cp -- libar2simplified.h "$(DESTDIR)$(PREFIX)/include/" + cp -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3/" + cp -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7/" uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libar2simplified.a" @@ -69,6 +75,8 @@ uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libar2simplified.$(LIBMINOREXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libar2simplified.$(LIBEXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/include/libar2simplified.h" + -cd -- "$(DESTDIR)$(MANPREFIX)/man3/" && rm -f -- $(MAN3) + -cd -- "$(DESTDIR)$(MANPREFIX)/man7/" && rm -f -- $(MAN7) clean: -rm -f -- *.o *.a *.lo *.su *.so *.so.* *.dll *.dylib @@ -0,0 +1,15 @@ +NAME + libar2simplified - Simplified interface for libar2 + +DESCRIPTION + libar2simplified is façade for the libar2 C library that + implements the family of Argon2 key derivation function, + including Argon2d, Argon2i, and Argon2id, as well as + Argon2ds which was not part of the submission to the + Password Hashing Competition of 2013, which Argon2 won in + 2015. As a key derivation function, Argon2 is well-suited + for cryptographically hashing (one-way encrypting) + passwords. + +SEE ALSO + libar2(7), crypt(3) diff --git a/libar2simplified.7 b/libar2simplified.7 new file mode 100644 index 0000000..bc03fff --- /dev/null +++ b/libar2simplified.7 @@ -0,0 +1,48 @@ +.TH LIBAR2SIMPLIFIED 7 LIBAR2 +.SH NAME +libar2simplified - Simplified interface for libar2 + +.SH DESCRIPTION +.B libar2simplified +is façade for the +.BR libar2 (7) +C library that implements the family of Argon2 key +derivation function, including Argon2d, Argon2i, and +Argon2id, as well as Argon2ds which was not part of +the submission to the Password Hashing Competition +of 2013, which Argon2 won in 2015. As a key derivation +function, Argon2 is well-suited for cryptographically +hashing (one-way encrypting) passwords. Where as the +.BR libar2 (7) +library is suitable in any code-base, as long as it +some standard C functions are avaible, since it does +not interact with the operating system, +.B libar2simplified +can only be used in fully hosted environments, since +it uses dynamic memory allocation, multi-threading, +and interacts with the operating system to generate +random salt or a seed used to generate the random +data used for the salt. +.PP +.B libar2simplified +provides two functions for calculating a hash: +.BR libar2simplified_crypt (3) +and +.BR libar2simplified_hash (3). +.BR libar2simplified_crypt (3) +provides a +.BR crypt (3)-style +interface, whereas +.BR libar2simplified_hash (3) +provides a flexible interface that supports pepper, +associated data, and NUL bytes in the message, and +output the password hash in binary without prepending +the parameters. + +.SH SEE ALSO +.BR libar2simplified (7), +.BR libar2simplified_crypt (3), +.BR libar2simplified_decode (3), +.BR libar2simplified_encode (3), +.BR libar2simplified_encode_hash (3), +.BR libar2simplified_hash (3) diff --git a/libar2simplified_crypt.3 b/libar2simplified_crypt.3 new file mode 100644 index 0000000..6b6a0e4 --- /dev/null +++ b/libar2simplified_crypt.3 @@ -0,0 +1,132 @@ +.TH LIBAR2SIMPLIFIED_CRYPT 3 LIBAR2SIMPLIFIED +.SH NAME +libar2simplified_crypt - Hash a password with Argon2 + +.SH SYNOPSIS +.nf +#include <libar2simplified.h> + +char *libar2simplified_crypt(char *\fImsg\fP, const char *\fIparams\fP, char *\fIrv\fP); +.fi +.PP +Link with +.IR "-lar2simplified -lar2 -lblake -lrt -pthread" . + +.SH DESCRIPTION +The +.BR libar2simplified_crypt () +function calculates an Argon2 if the message +provided in the +.I msg +parameter, which must be a NUL-terminated string, +according to the hashing parameters specified in the +.I params +parameter, which must not contain any excess data +(the tag (expected hash result) is not considered +excess data). See +.BR libar2_hash (3) +for more information about +.IR params . +The hash (tag) is stored, in raw binary format +(does not include the hashing parameters) in +the buffer provided via the +.I hash +parameter. This buffer must be at least +.I libar2_hash_buf_size(params) +bytes large. +.PP +.I params +may use the extended format specified in +.BR libar2simplified_encode (3). +.PP +The +.BR libar2simplified_hash (3) +function will erase (not deallocate) the contents of +.I msg +before returning. +.PP +If +.I rv +is +.IR NULL , +the returned pointer will shall be deallocated +using the +.BR free (3) +function, otherwise the function will return +.I rv +and +.I rv +must have an allocation size of at least +.I libar2_hash_buf_size(libar2simplified_decode(params, NULL, NULL, NULL)) +bytes (note however that the pointer returned by +.BR libar2simplified_decode (3) +shall be deallocated by the application). +.PP +If +.I params +specifies an exact hash and salt (and not just +their lengths), the returned string will be +equal to +.I params +if +.I msg +specifies the password that was used to create it, +and only with extreme unlikelyhood be equal to +.I params +otherwise. +.PP +Only +.I rv +may be +.IR NULL . + +.SH RETURN VALUES +The +.BR libar2simplified_crypt () +function returns +.I rv +upon successful completion, or if +.I rv +is +.IR NULL , +a +.RI non- NULL +pointer to dynamically allocated memory; +the content will contain a hashing parameter +string with the hashing result and the salt +that was generated or provided. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. + +.SH ERRORS +The +.BR libar2simplified_crypt () +function will fail if: +.TP +.B EINVAL +The contents of +.I str +is invalid or unsupported. +.TP +.B ENOMEM +Insufficient storage space is available. +.TP +.BR ENOSPC " or " EAGAIN +A resource required to initialise some item +needed for threading-support has been exhausted +or the number of instances of such items have +been reached. +.TP +.B EOWNERDEAD +A thread terminated unexpectedly. + +.SH SEE ALSO +.BR libar2simplified (7), +.BR libar2simplified_encode (3), +.BR libar2simplified_hash (3), +.BR libar2_hash (3), +.BR libar2_hash_buf_size (3), +.BR crypt (3), diff --git a/libar2simplified_decode.3 b/libar2simplified_decode.3 new file mode 100644 index 0000000..eaf8388 --- /dev/null +++ b/libar2simplified_decode.3 @@ -0,0 +1,141 @@ +.TH LIBAR2SIMPLIFIED_DECODE 3 LIBAR2SIMPLIFIED +.SH NAME +libar2simplified_decode - Decode hashing parameters + +.SH SYNOPSIS +.nf +#include <libar2simplified.h> + +struct libar2_argon2_parameters * +libar2simplified_decode(const char *\fIstr\fP, char **\fItagp\fP, char **\fIendp\fP, + int (*\fIrandom_byte_generator\fP)(char *\fIout\fP, size_t \fIn\fP)); +.fi +.PP +Link with +.IR "-lar2simplified -lar2" . + +.SH DESCRIPTION +The +.BR libar2simplified_decode () +function a decode hashing parameter string provided +in the +.I str +parameter. +.PP +This function supports the extended format described in +.BR libar2simplified_encode (3). +If the parameter string only specifies a salt length, and +not an actual salt, one is generate using the function +provided via the +.I random_byte_generator +parameter; or if +.I random_byte_generator +is +.IR NULL , +a function built into the libary itself. If the parameter +string specifies a tag (hash result), a pointer to it +is stored in +.IR *tagp , +otherwise +.I *tagp +is set to +.IR NULL . +.RI ( *tagp +is only set unless +.I tagp +is +.IR NULL ) +.PP +Unless +.I endp +is +.IR NULL , +.I *endp +will be set to the end of the parameter string, which +terminates the tag. The application shall make sure +that +.I *endp +is a proper termination of the parameter string, +typically this would be a colon +.RB ( : ), +if read from +.I /etc/shadow +or a similar file, or a NUL byte. The +.BR libar2simplified_decode () +function will +.B not +make this check even if +.I endp +is +.IR NULL . +.PP +Unless +.I random_byte_generator +is +.IR NULL , +it shall generate +.I n +random bytes and store them in +.I out +and return 0, or on failure -1. Each byte need +only have its 6 lower bits set randomly. +.PP +The hashing string does not encode information +about the secret (pepper) or associated data, +which will therefore be set to zero-length. +.PP +.I params +may not be +.IR NULL . + +.SH RETURN VALUES +The +.BR libar2simplified_decode () +function returns a dynamically allocated +structure detailing the contents of +.IR str , +which can be deallocated using the +.BR free (3) +function, upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. + +.SH ERRORS +The +.BR libar2simplified_decode () +function will fail if: +.TP +.B EINVAL +The contents of +.I str +is invalid or unsupported. +.TP +.B ENOMEM +Insufficient storage space is available. +.PP +The +.BR libar2simplified_decode () +function will fail if the +.I random_byte_generator +fails, in which case it will not modify +the value of +.IR errno . + +.SH NOTES +The returned objects allocation size will +exceed the size of its type, so that the +salt can be stored in it, and automatically +deallocated when the returned pointer is +deallocated. + +.SH SEE ALSO +.BR libar2simplified (7), +.BR libar2simplified_encode (3), +.BR libar2simplified_encode_hash (3), +.BR libar2simplified_hash (3), +.BR libar2_decode_params (3), +.BR libar2_validate_params (3), +.BR libar2_hash (3) diff --git a/libar2simplified_encode.3 b/libar2simplified_encode.3 new file mode 100644 index 0000000..1329e28 --- /dev/null +++ b/libar2simplified_encode.3 @@ -0,0 +1,89 @@ +.TH LIBAR2SIMPLIFIED_ENCODE 3 LIBAR2SIMPLIFIED +.SH NAME +libar2simplified_encode - Encode hashing parameters, with or without hashing result + +.SH SYNOPSIS +.nf +#include <libar2simplified.h> + +char *libar2simplified_encode(const struct libar2_argon2_parameters *\fIparams\fP, void *\fIhash\fP); +.fi +.PP +Link with +.IR "-lar2simplified -lar2" . + +.SH DESCRIPTION +The +.BR libar2simplified_encode () +function encode hashing parameters provided via the +.I params +parameter, with or without the tag (hashing result) +provided in the +.I hash +parameter. +.PP +This function extends the standard format for Argon2 +by letting the exact salt or tag (hash) be unspecified, +but the length specified using an asterisk-prefixed, +decimal integer. See +.BR libar2_encode_params (3) +for details about the standard format. To set the salt +to unspecified, set +.I params->salt +to +.IR NULL . +To set the tag to unspecified, set +.I hash +to +.IR NULL . +See +.BR libar2_hash (3) +for details about +.IR params . +.PP +The secret (pepper) and associated data, which may be +set in +.I params +will not be included in the returned string. +.PP +.I params +may not be +.IR NULL . + +.SH RETURN VALUES +The +.BR libar2simplified_encode () +function returns a dynamically allocated string +detailing the contents of +.I params +and +.IR hash , +which can be deallocated using the +.BR free (3) +function, upon successful completion. On error, +.I NULL +is returned and +.I errno +is set to describe the error. + +.SH ERRORS +The +.BR libar2simplified_encode () +function will fail if: +.TP +.B EINVAL +The contents of +.I params +is invalid or unsupported. +.TP +.B ENOMEM +Insufficient storage space is available. + +.SH SEE ALSO +.BR libar2simplified (7), +.BR libar2simplified_encode_hash (3), +.BR libar2simplified_decode (3), +.BR libar2simplified_hash (3), +.BR libar2_encode_params (3), +.BR libar2_validate_params (3), +.BR libar2_hash (3) diff --git a/libar2simplified_encode_hash.3 b/libar2simplified_encode_hash.3 new file mode 100644 index 0000000..e03827e --- /dev/null +++ b/libar2simplified_encode_hash.3 @@ -0,0 +1,60 @@ +.TH LIBAR2SIMPLIFIED_ENCODE_HASH 3 LIBAR2SIMPLIFIED +.SH NAME +libar2simplified_encode_hash - Encode hashing result without parameters + +.SH SYNOPSIS +.nf +#include <libar2simplified.h> + +char *libar2simplified_encode_hash(const struct libar2_argon2_parameters *\fIparams\fP, void *\fIhash\fP); +.fi +.PP +Link with +.IR "-lar2simplified -lar2" . + +.SH DESCRIPTION +The +.BR libar2simplified_encode_hash () +function encodes the contents of the +.I hash +parameter in base64, which is the encoding used +for Argon2. The length of the contents must be +set in +.IR params->hashlen . +The +.I params +parameter is otherwise unused. +.PP +Neither argument may be +.IR NULL . + +.SH RETURN VALUES +The +.BR libar2simplified_encode_hash () +function returns a dynamically allocated string +containing the contents of the +.I hash +parameter encoded in base64, which may be +deallocated using the +.BR free (3) +function, upon successful +completion. On error, +.I NULL +is returned and +.I errno +is set to describe the error. + +.SH ERRORS +The +.BR libar2simplified_encode_hash () +function will fail if: +.TP +.B ENOMEM +Insufficient storage space is available. + +.SH SEE ALSO +.BR libar2simplified (7), +.BR libar2simplified_encode (3), +.BR libar2simplified_decode (3), +.BR libar2simplified_hash (3), +.BR libar2_encode_base64 (3) diff --git a/libar2simplified_hash.3 b/libar2simplified_hash.3 new file mode 100644 index 0000000..71f0bd0 --- /dev/null +++ b/libar2simplified_hash.3 @@ -0,0 +1,89 @@ +.TH LIBAR2SIMPLIFIED_HASH 3 LIBAR2SIMPLIFIED +.SH NAME +libar2simplified_hash - Hash a password with Argon2 + +.SH SYNOPSIS +.nf +#include <libar2simplified.h> + +int libar2simplified_hash(void *\fIhash\fP, void *\fImsg\fP, size_t \fImsglen\fP, struct libar2_argon2_parameters *\fIparams\fP); +.fi +.PP +Link with +.IR "-lar2simplified -lar2 -lblake -lrt -pthread" . + +.SH DESCRIPTION +The +.BR libar2simplified_hash () +function calculates an Argon2 if the message +provided in the +.I msg +parameter, whose length (in bytes) is provided in the +.I msglen +parameter, according to the hashing parameters +specified in the +.I params +parameter. See +.BR libar2_hash (3) +for more information about +.IR params . +The hash (tag) is stored, in raw binary format +(does not include the hashing parameters) in +the buffer provided via the +.I hash +parameter. This buffer must be at least +.I libar2_hash_buf_size(params) +bytes large. +.PP +The +.BR libar2simplified_hash () +function will erase (not deallocate) the contents of +.I msg +before returning. +.PP +Only +.I msg +may be +.IR NULL , +but only if +.I msglen +is 0. + +.SH RETURN VALUES +The +.BR libar2simplified_hash () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. + +.SH ERRORS +The +.BR libar2simplified_hash () +function will fail if: +.TP +.B EINVAL +The contents of +.I str +is invalid or unsupported. +.TP +.B ENOMEM +Insufficient storage space is available. +.TP +.BR ENOSPC " or " EAGAIN +A resource required to initialise some item +needed for threading-support has been exhausted +or the number of instances of such items have +been reached. +.TP +.B EOWNERDEAD +A thread terminated unexpectedly. + +.SH SEE ALSO +.BR libar2simplified (7), +.BR libar2simplified_decode (3), +.BR libar2simplified_encode (3), +.BR libar2simplified_encode_hash (3), +.BR libar2simplified_crypt (3), +.BR libar2_hash (3), +.BR libar2_hash_buf_size (3) |