Add libar2_hash_buf_size and fix related documentation for libar2_hash

6 files changed, 80 insertions, 4 deletions

diff --git a/Makefile b/Makefile
index 3eee9e5..c9364dc 100644
--- a/Makefile
+++ b/Makefile
@@ -23,6 +23,7 @@ OBJ =\
 	libar2_encode_params.o\
 	libar2_erase.o\
 	libar2_hash.o\
+	libar2_hash_buf_size.o\
 	libar2_latest_argon2_version.o\
 	libar2_string_to_type.o\
 	libar2_string_to_version.o\
diff --git a/libar2.7 b/libar2.7
index 7b772be..60aaca4 100644
--- a/libar2.7
+++ b/libar2.7
@@ -19,6 +19,7 @@ hashing (one-way encrypting) passwords.
 .BR libar2_encode_params (3),
 .BR libar2_erase (3),
 .BR libar2_hash (3),
+.BR libar2_hash_buf_size (3),
 .BR libar2_latest_argon2_version (3),
 .BR libar2_string_to_type (3),
 .BR libar2_string_to_version (3),
diff --git a/libar2.h b/libar2.h
index 8915a1a..f121bc7 100644
--- a/libar2.h
+++ b/libar2.h
@@ -14,8 +14,10 @@
 
 #if defined(__GNUC__)
 # define LIBAR2_NONNULL__(...) __attribute__((nonnull(__VA_ARGS__)))
+# define LIBAR2_PURE__ __attribute__((pure))
 #else
 # define LIBAR2_NONNULL__(...)
+# define LIBAR2_PURE__
 #endif
 
 #ifndef LIBAR2_PUBLIC__
@@ -644,8 +646,8 @@ void libar2_erase(volatile void *mem, size_t size);
  * have erased data configured in `ctx` to be automatically
  * erased
  * 
- * @param   hash    Binary hash ("tag") output buffer, shall
- *                  be at least `params->hashlen` bytes large
+ * @param   hash    Binary hash ("tag") output buffer, shall be at
+ *                  least `libar2_hash_buf_size(params)` bytes large
  * @param   msg     Message (password) to hash; only modified if
  *                  `ctx->autoerase_message` is non-zero
  * @param   msglen  The length of `msg`; at least 0, at most 2³²−1
@@ -656,6 +658,23 @@ void libar2_erase(volatile void *mem, size_t size);
 LIBAR2_PUBLIC__ LIBAR2_NONNULL__(1, 4, 5)
 int libar2_hash(void *hash, void *msg, size_t msglen, struct libar2_argon2_parameters *params, struct libar2_context *ctx);
 
+/**
+ * Return the number of bytes that is required for
+ * the first parameter, the output parmeter, of
+ * `libar2_hash`
+ * 
+ * If `params->hashlen <= 64`, this function will
+ * return `params->hashlen` as is, otherwise it
+ * will return a value that is no greater than
+ * `params->hashlen + 127`
+ * 
+ * @param   params  Hashing parameters
+ * @return          The required allocation size of the
+ *                  output parameter of `libar2_hash`
+ */
+LIBAR2_PUBLIC__ LIBAR2_NONNULL__(1) LIBAR2_PURE__
+size_t libar2_hash_buf_size(struct libar2_argon2_parameters *params);
+
 #if defined(__clang__)
 # pragma clang diagnostic pop
 #endif
diff --git a/libar2_hash.3 b/libar2_hash.3
index 3240508..1dcabb6 100644
--- a/libar2_hash.3
+++ b/libar2_hash.3
@@ -70,8 +70,8 @@ parameter. The resulting hash is stored,
 in raw, binary format, in
 .IR hash ,
 which must have an allocation size of at least
-the number of bytes specified by
-.IR params->hashlen .
+the number of bytes returned by
+.IR "libar2_hash_buf_size(params)" .
 The
 .I ctx
 parameter is used to provide memory and thread
@@ -477,6 +477,7 @@ fails, and will, in that case, not modify
 
 .SH SEE ALSO
 .BR libar2 (7),
+.BR libar2_hash_buf_size (3),
 .BR libar2_encode_base64 (3),
 .BR libar2_encode_params (3),
 .BR libar2_decode_params (3),
diff --git a/libar2_hash_buf_size.3 b/libar2_hash_buf_size.3
new file mode 100644
index 0000000..f538cfc
--- /dev/null
+++ b/libar2_hash_buf_size.3
@@ -0,0 +1,45 @@
+.TH LIBAR2_HASH_BUF_SIZE 7 LIBAR2
+.SH NAME
+libar2_hash_buf_size - Determine require output buffer size
+
+.SH SYNOPSIS
+.nf
+#include <libar2.h>
+
+size_t libar2_hash_buf_size(struct libar2_argon2_parameters *\fIparams\fP);
+.fi
+.PP
+Link with
+.IR -lar2 .
+
+.SH DESCRIPTION
+The
+.BR libar2_hash_buf_size ()
+function returns the number of bytes that the
+output buffer for the
+.BR libar2_hash (3)
+function must fit (that it, it's first parameter).
+.PP
+.I params
+may not be
+.IR NULL .
+.PP
+The return value is
+.I params->hashlen
+if this number is 64 or less, otherwise it is
+.I params->hashlen
+rounded up to the next multiple of 128.
+
+.SH RETURN VALUES
+See
+.BR DESCRIPTION .
+
+.SH ERRORS
+The
+.BR libar2_hash_buf_size ()
+function cannot fail; however, if the
+return value is 0, the value has overflown.
+
+.SH SEE ALSO
+.BR libar2 (7),
+.BR libar2_hash (3)
diff --git a/libar2_hash_buf_size.c b/libar2_hash_buf_size.c
new file mode 100644
index 0000000..b165d4b
--- /dev/null
+++ b/libar2_hash_buf_size.c
@@ -0,0 +1,9 @@
+/* See LICENSE file for copyright and license details. */
+#include "common.h"
+
+
+size_t
+libar2_hash_buf_size(struct libar2_argon2_parameters *params)
+{
+	return (params->hashlen > 64 && (params->hashlen & 127)) ? (params->hashlen | 127) + 1 : params->hashlen;
+}