Add readme and man pages

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

8 files changed, 582 insertions, 0 deletions

diff --git a/Makefile b/Makefile
index bed6999..92cdb58 100644
--- a/Makefile
+++ b/Makefile
@@ -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
diff --git a/README b/README
new file mode 100644
index 0000000..647e9ad
--- /dev/null
+++ b/README
@@ -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)