From 238d8b72069b80522066ac5edc3a4d2155e3382c Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 13 Feb 2022 23:22:53 +0100 Subject: Add libar2_hash_buf_size and fix related documentation for libar2_hash --- Makefile | 1 + libar2.7 | 1 + libar2.h | 23 +++++++++++++++++++++-- libar2_hash.3 | 5 +++-- libar2_hash_buf_size.3 | 45 +++++++++++++++++++++++++++++++++++++++++++++ libar2_hash_buf_size.c | 9 +++++++++ 6 files changed, 80 insertions(+), 4 deletions(-) create mode 100644 libar2_hash_buf_size.3 create mode 100644 libar2_hash_buf_size.c 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 + +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; +} -- cgit v1.2.3-70-g09d2