Add readme and man pages

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

1 files changed, 132 insertions, 0 deletions

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