aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Makefile1
-rw-r--r--libar2.71
-rw-r--r--libar2.h23
-rw-r--r--libar2_hash.35
-rw-r--r--libar2_hash_buf_size.345
-rw-r--r--libar2_hash_buf_size.c9
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;
+}