From 6e3af681aa5927d2ab2861e94c0cfea6fa42c0ab Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 10 Feb 2019 17:54:09 +0100 Subject: Minor improvement and man pages for HMAC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- Makefile | 9 +++++- algorithm_output_size.c | 2 +- hmac_digest.c | 20 +++++------- hmac_init.c | 4 +++ hmac_state_output_size.c | 15 +++++++++ hmac_update.c | 15 ++++----- init.c | 4 +-- libsha2.h | 35 ++++++++++++-------- libsha2.h.0 | 29 ++++++++++++++++- libsha2_hmac_init.3 | 70 ++++++++++++++++++++++++++++++++++++++++ libsha2_hmac_marshal.3 | 56 ++++++++++++++++++++++++++++++++ libsha2_hmac_state_output_size.3 | 40 +++++++++++++++++++++++ libsha2_hmac_unmarshal.3 | 54 +++++++++++++++++++++++++++++++ libsha2_hmac_update.3 | 42 ++++++++++++++++++++++++ libsha2_marshal.3 | 2 +- state_output_size.c | 2 +- 16 files changed, 358 insertions(+), 41 deletions(-) create mode 100644 hmac_state_output_size.c create mode 100644 libsha2_hmac_init.3 create mode 100644 libsha2_hmac_marshal.3 create mode 100644 libsha2_hmac_state_output_size.3 create mode 100644 libsha2_hmac_unmarshal.3 create mode 100644 libsha2_hmac_update.3 diff --git a/Makefile b/Makefile index dc7060e..14be91d 100644 --- a/Makefile +++ b/Makefile @@ -21,6 +21,7 @@ OBJ =\ hmac_digest.o\ hmac_init.o\ hmac_marshal.o\ + hmac_state_output_size.o\ hmac_unmarshal.o\ hmac_update.o\ init.o\ @@ -40,8 +41,14 @@ MAN3 =\ libsha2_behex_lower.3\ libsha2_behex_upper.3\ libsha2_digest.3\ - libsha2_marshal.3\ + libsha2_hmac_digest.3\ + libsha2_hmac_init.3\ + libsha2_hmac_marshal.3\ + libsha2_hmac_state_output_size.3\ + libsha2_hmac_unmarshal.3\ + libsha2_hmac_update.3\ libsha2_init.3\ + libsha2_marshal.3\ libsha2_state_output_size.3\ libsha2_sum_fd.3\ libsha2_unhex.3\ diff --git a/algorithm_output_size.c b/algorithm_output_size.c index 2593a15..4b287b2 100644 --- a/algorithm_output_size.c +++ b/algorithm_output_size.c @@ -6,7 +6,7 @@ /** * Get the output size of an algorithm * - * @parma algorithm The hashing algorithm + * @param algorithm The hashing algorithm * @return The number of bytes in the output, zero on error */ size_t diff --git a/hmac_digest.c b/hmac_digest.c index caee756..9cc4271 100644 --- a/hmac_digest.c +++ b/hmac_digest.c @@ -10,28 +10,24 @@ * `libsha2_hmac_update` and `libsha2_hmac_update` * can be called again * - * @param state The state of the algorithm - * @param data Data to feed into the algorithm - * @param n The number of bytes to feed into the algorithm - * @param output The output buffer for the hash, it will be as - * large as for the underlaying hash algorithm - * @return Zero on success, -1 on error + * @param state The state of the algorithm + * @param data Data to feed into the algorithm + * @param n The number of bytes to feed into the algorithm + * @param output The output buffer for the hash, it will be as + * large as for the underlaying hash algorithm */ -int +void libsha2_hmac_digest(struct libsha2_hmac_state *restrict state, const void *data, size_t n, void *output) { if (!state->inited) { - if (libsha2_init(&state->sha2_state, state->sha2_state.algorithm)) - return -1; + libsha2_init(&state->sha2_state, state->sha2_state.algorithm); libsha2_update(&state->sha2_state, state->ipad, state->sha2_state.chunk_size * 8); } libsha2_digest(&state->sha2_state, data, n, output); - if (libsha2_init(&state->sha2_state, state->sha2_state.algorithm)) - return -1; + libsha2_init(&state->sha2_state, state->sha2_state.algorithm); libsha2_update(&state->sha2_state, state->opad, state->sha2_state.chunk_size * 8); libsha2_digest(&state->sha2_state, output, state->outsize, output); state->inited = 0; - return 0; } diff --git a/hmac_init.c b/hmac_init.c index 4aee2c2..17b31ce 100644 --- a/hmac_init.c +++ b/hmac_init.c @@ -20,6 +20,10 @@ libsha2_hmac_init(struct libsha2_hmac_state *restrict state, enum libsha2_algori state->sha2_state.algorithm = algorithm; state->outsize = libsha2_algorithm_output_size(algorithm) * 8; + if (!state->outsize) { + errno = EINVAL; + return -1; + } state->inited = 0; if (keylen <= state->sha2_state.chunk_size * 8) { diff --git a/hmac_state_output_size.c b/hmac_state_output_size.c new file mode 100644 index 0000000..d1a94dd --- /dev/null +++ b/hmac_state_output_size.c @@ -0,0 +1,15 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Get the output size of the algorithm specified for a HMAC state + * + * @param state The state + * @return The number of bytes in the output, zero on error + */ +size_t +libsha2_hmac_state_output_size(const struct libsha2_hmac_state *restrict state) +{ + return libsha2_algorithm_output_size(state->sha2_state.algorithm); +} diff --git a/hmac_update.c b/hmac_update.c index 7f4cef3..245c7b1 100644 --- a/hmac_update.c +++ b/hmac_update.c @@ -5,22 +5,19 @@ /** * Feed data into the HMAC algorithm * - * @param state The state of the algorithm - * @param data Data to feed into the algorithm - * @param n The number of bytes to feed into the - * algorithm, this must be a multiple of 8 - * @return Zero on success, -1 on error + * @param state The state of the algorithm + * @param data Data to feed into the algorithm + * @param n The number of bytes to feed into the + * algorithm, this must be a multiple of 8 */ -int +void libsha2_hmac_update(struct libsha2_hmac_state *restrict state, const void *restrict data, size_t n) { if (!state->inited) { - if (libsha2_init(&state->sha2_state, state->sha2_state.algorithm)) - return -1; + libsha2_init(&state->sha2_state, state->sha2_state.algorithm); libsha2_update(&state->sha2_state, state->ipad, state->sha2_state.chunk_size * 8); state->inited = 1; } libsha2_update(&state->sha2_state, data, n); - return 0; } diff --git a/init.c b/init.c index 1d7f80b..41c8473 100644 --- a/init.c +++ b/init.c @@ -81,8 +81,8 @@ static const uint64_t H_512_256[] = { /** * Initialise a state * - * @parma state The state that should be initialised - * @parma algorithm The hashing algorithm + * @param state The state that should be initialised + * @param algorithm The hashing algorithm * @return Zero on success, -1 on error */ int diff --git a/libsha2.h b/libsha2.h index 21e0b98..c2112aa 100644 --- a/libsha2.h +++ b/libsha2.h @@ -329,19 +329,29 @@ __attribute__((__leaf__, __nonnull__, __nothrow__)) #endif int libsha2_hmac_init(struct libsha2_hmac_state *restrict, enum libsha2_algorithm, const void *restrict, size_t); +/** + * Get the output size of the algorithm specified for an HMAC state + * + * @param state The state + * @return The number of bytes in the output, zero on error + */ +#if defined(__GNUC__) +__attribute__((__nothrow__, __nonnull__, __pure__)) +#endif +size_t libsha2_hmac_state_output_size(const struct libsha2_hmac_state *restrict); + /** * Feed data into the HMAC algorithm * - * @param state The state of the algorithm - * @param data Data to feed into the algorithm - * @param n The number of bytes to feed into the - * algorithm, this must be a multiple of 8 - * @return Zero on success, -1 on error + * @param state The state of the algorithm + * @param data Data to feed into the algorithm + * @param n The number of bytes to feed into the + * algorithm, this must be a multiple of 8 */ #if defined(__GNUC__) __attribute__((__leaf__, __nonnull__, __nothrow__)) #endif -int libsha2_hmac_update(struct libsha2_hmac_state *restrict, const void *restrict, size_t); +void libsha2_hmac_update(struct libsha2_hmac_state *restrict, const void *restrict, size_t); /** * Feed data into the HMAC algorithm and @@ -351,17 +361,16 @@ int libsha2_hmac_update(struct libsha2_hmac_state *restrict, const void *restric * `libsha2_hmac_update` and `libsha2_hmac_update` * can be called again * - * @param state The state of the algorithm - * @param data Data to feed into the algorithm - * @param n The number of bytes to feed into the algorithm - * @param output The output buffer for the hash, it will be as - * large as for the underlaying hash algorithm - * @return Zero on success, -1 on error + * @param state The state of the algorithm + * @param data Data to feed into the algorithm + * @param n The number of bytes to feed into the algorithm + * @param output The output buffer for the hash, it will be as + * large as for the underlaying hash algorithm */ #if defined(__GNUC__) __attribute__((__leaf__, __nonnull__, __nothrow__)) #endif -int libsha2_hmac_digest(struct libsha2_hmac_state *restrict, const void *, size_t, void *); +void libsha2_hmac_digest(struct libsha2_hmac_state *restrict, const void *, size_t, void *); /** * Marshal an HMAC state into a buffer diff --git a/libsha2.h.0 b/libsha2.h.0 index e1a0060..237e406 100644 --- a/libsha2.h.0 +++ b/libsha2.h.0 @@ -1,4 +1,4 @@ -.TH LIBSHA2.H 0 2019-02-09 libjson +.TH LIBSHA2.H 0 2019-02-10 libjson .SH NAME libsha2.h \- SHA 2 library header .SH SYNOPSIS @@ -29,6 +29,13 @@ void libsha2_behex_upper(char *restrict \fIoutput\fP, const void *restrict \fIha void libsha2_unhex(void *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP); size_t libsha2_marshal(const struct libsha2_state *restrict \fIstate\fP, void *restrict \fIbuf\fP); size_t libsha2_unmarshal(struct libsha2_state *restrict \fIstate\fP, const void *restrict \fIbuf\fP, size_t \fIbufsize\fP); +int libsha2_hmac_init(struct libsha2_hmac_state *restrict \fIstate\fP, enum libsha2_algorithm \fIalgorithm\fP, + const void *restrict \fIkey\fP, size_t \fIkeylen\fP); +size_t libsha2_hmac_state_output_size(const struct libsha2_hmac_state *restrict \fIstate\fP); +void libsha2_hmac_update(struct libsha2_hmac_state *restrict \fIstate\fP, const void *restrict \fIdata\fP, size_t \fIn\fP); +void libsha2_hmac_digest(struct libsha2_hmac_state *restrict \fIstate\fP, const void *\fIdata\fP, size_t \fIn\fP, void *\fIoutput\fP); +size_t libsha2_hmac_marshal(const struct libsha2_hmac_state *restrict \fIstate\fP, void *restrict \fIbuf\fP); +size_t libsha2_hmac_unmarshal(struct libsha2_hmac_state *restrict \fIstate\fP, const void *restrict \fIbuf\fP, size_t \fIbufsize\fP); .fi .PP Link with @@ -97,6 +104,21 @@ Marshal a hashing state. .TP .BR libsha2_unmarshal (3) Unmarshal a hashing state. +.TP +.BR libsha2_hmac_init (3) +Initialise HMAC hashing state. +.TP +.BR libsha2_hmac_update (3) +Feed data into the HMAC hashing state. +.TP +.BR libsha2_hmac_digest (3) +Get the result of an HMAC hashing. +.TP +.BR libsha2_hmac_marshal (3) +Marshal an HMAC hashing state. +.TP +.BR libsha2_hmac_unmarshal (3) +Unmarshal an HMAC hashing state. .SH EXAMPLES None. .SH APPLICATION USAGE @@ -114,6 +136,11 @@ None. .BR libsha2_behex_lower (3), .BR libsha2_behex_upper (3), .BR libsha2_digest (3), +.BR libsha2_hmac_digest (3), +.BR libsha2_hmac_init (3), +.BR libsha2_hmac_marshal (3), +.BR libsha2_hmac_unmarshal (3), +.BR libsha2_hmac_update (3), .BR libsha2_init (3), .BR libsha2_marshal (3), .BR libsha2_state_output_size (3), diff --git a/libsha2_hmac_init.3 b/libsha2_hmac_init.3 new file mode 100644 index 0000000..e26bbe5 --- /dev/null +++ b/libsha2_hmac_init.3 @@ -0,0 +1,70 @@ +.TH LIBSHA2_HMAC_INIT 3 2019-02-10 libjson +.SH NAME +libsha2_hmac_init \- Initialises hashing with an HMAC-SHA 2 algorithm +.SH SYNOPSIS +.nf +#include + +enum libsha2_algorithm { + LIBSHA2_224, /* SHA-224 */ + LIBSHA2_256, /* SHA-256 */ + LIBSHA2_384, /* SHA-384 */ + LIBSHA2_512, /* SHA-512 */ + LIBSHA2_512_224, /* SHA-512/224 */ + LIBSHA2_512_256 /* SHA-512/256 */ +}; + +int libsha2_hmac_init(struct libsha2_hmac_state *restrict \fIstate\fP, enum libsha2_algorithm \fIalgorithm\fP, + const void *restrict \fIkey\fP, size_t \fIkeylen\fP); +.fi +.PP +Link with +.IR \-lsha2 . +.SH DESCRIPTION +The +.BR libsha2_hmac_init () +function stores the selected +.I algorithm +in +.I state +and initialises +.I state +with the first +.I keylen +bits of +.I key +as the key. +.SH RETURN VALUE +The +.BR libsha2_hmac_init () +function returns 0 upon successful completion, +otherwise -1 is returned and +.I errno +is set appropriately. +.SH ERRORS +The +.BR libsha2_hmac_init () +function will fail if: +.TP +.B EINVAL +.I algorithm +is not a valid +.B enum libsha2_algorithm +value. +.SH EXAMPLES +None. +.SH APPLICATION USAGE +None. +.SH RATIONALE +None. +.SH FUTURE DIRECTIONS +None. +.SH NOTES +None. +.SH BUGS +None. +.SH SEE ALSO +.BR libsha2_hmac_digest (3), +.BR libsha2_hmac_marshal (3), +.BR libsha2_hmac_unmarshal (3), +.BR libsha2_hmac_update (3) diff --git a/libsha2_hmac_marshal.3 b/libsha2_hmac_marshal.3 new file mode 100644 index 0000000..1808dae --- /dev/null +++ b/libsha2_hmac_marshal.3 @@ -0,0 +1,56 @@ +.TH LIBSHA2_HMAC_MARSHAL 3 2019-02-10 libjson +.SH NAME +libsha2_hmac_marshal \- Marshal an HMAC-SHA 2 hashing state +.SH SYNOPSIS +.nf +#include + +size_t libsha2_hmac_marshal(const struct libsha2_hmac_state *restrict \fIstate\fP, void *restrict \fIbuf\fP); +.fi +.PP +Link with +.IR \-lsha2 . +.SH DESCRIPTION +The +.BR libsha2_marshal () +function marshal +.I state +into the buffer +.IR buf . +If the function is called with +.I NULL +as +.IR buf , +the required size for +.I buf +is returned. +.PP +A version number is marshalled into +.IR buf , +this allows new versions of the library to +unmarshal states marshalled by older versions. +.SH RETURN VALUE +The +.BR libsha2_hmac_marshal () +function returns the number of marshalled +bytes (or if +.I buf +is +.IR NULL , +the number of bytes that would have been marshalled). +.SH ERRORS +None. +.SH EXAMPLES +None. +.SH APPLICATION USAGE +None. +.SH RATIONALE +None. +.SH FUTURE DIRECTIONS +None. +.SH NOTES +None. +.SH BUGS +None. +.SH SEE ALSO +.BR libsha2_hmac_unmarshal (3) diff --git a/libsha2_hmac_state_output_size.3 b/libsha2_hmac_state_output_size.3 new file mode 100644 index 0000000..77a1023 --- /dev/null +++ b/libsha2_hmac_state_output_size.3 @@ -0,0 +1,40 @@ +.TH LIBSHA2_HMAC_STATE_OUTPUT_SIZE 3 2019-02-10 libjson +.SH NAME +libsha2_hmac_state_output_size \- Get the size of the output for a HMAC-SHA 2 algorithm +.SH SYNOPSIS +.nf +#include + +size_t libsha2_hmac_state_output_size(const struct libsha2_hmac_state *restrict \fIstate\fP); +.fi +.PP +Link with +.IR \-lsha2 . +.SH DESCRIPTION +The +.BR libsha2_hmac_state_output_size () +function get the output size for the +binary output of the hash algorithm +selected for +.IR state . +.SH RETURN VALUE +The +.BR libsha2_hmac_state_output_size () +function returns the output size in bytes, +a positive number. +.SH ERRORS +None. +.SH EXAMPLES +None. +.SH APPLICATION USAGE +None. +.SH RATIONALE +None. +.SH FUTURE DIRECTIONS +None. +.SH NOTES +None. +.SH BUGS +None. +.SH SEE ALSO +None. diff --git a/libsha2_hmac_unmarshal.3 b/libsha2_hmac_unmarshal.3 new file mode 100644 index 0000000..e856146 --- /dev/null +++ b/libsha2_hmac_unmarshal.3 @@ -0,0 +1,54 @@ +.TH LIBSHA2_HMAC_UNMARSHAL 3 2019-02-10 libjson +.SH NAME +libsha2_hmac_unmarshal \- Unmarshal an HMAC-SHA 2 hashing state +.SH SYNOPSIS +.nf +#include + +size_t libsha2_hmac_unmarshal(struct libsha2_hmac_state *restrict \fIstate\fP, const void *restrict \fIbuf\fP, size_t \fIbufsize\fP); +.fi +.PP +Link with +.IR \-lsha2 . +.SH DESCRIPTION +The +.BR libsha2_hmac_unmarshal () +function unmarshal +.I state +from the buffer +.IR buf . +.I bufsize +shall be the maximum number of bytes the +function may read from +.IR buf . +.SH RETURN VALUE +The +.BR libsha2_hmac_unmarshal () +function returns the number of unmarshalled +bytes (this number is always positive) upon +successful completion, otherwise 0 is returned. +.SH ERRORS +The +.BR libsha2_hmac_unmarshal () +function will fail if: +.TP +.B EINVAL +.I bufsize +is too small or the contents of +.I buf +is invalid or created with an incompatible +version of the library. +.SH EXAMPLES +None. +.SH APPLICATION USAGE +None. +.SH RATIONALE +None. +.SH FUTURE DIRECTIONS +None. +.SH NOTES +None. +.SH BUGS +None. +.SH SEE ALSO +.BR libsha2_hmac_marshal (3) diff --git a/libsha2_hmac_update.3 b/libsha2_hmac_update.3 new file mode 100644 index 0000000..0310a21 --- /dev/null +++ b/libsha2_hmac_update.3 @@ -0,0 +1,42 @@ +.TH LIBSHA2_HMAC_UPDATE 3 2019-02-10 libjson +.SH NAME +libsha2_hmac_update \- Feed data into a HMAC-SHA 2 algorithm +.SH SYNOPSIS +.nf +#include + +void libsha2_hmac_update(struct libsha2_hmac_state *restrict \fIstate\fP, const void *restrict \fImessage\fP, size_t \fImsglen\fP); +.fi +.PP +Link with +.IR \-lsha2 . +.SH DESCRIPTION +The +.BR libsha2_hmac_update () +function feeds the first +.I msglen +.B bits +(must equivalent to 0 modulus 8) of +.I message +into the hashing state of the +.I state +parameter. +.SH RETURN VALUE +None. +.SH ERRORS +None. +.SH EXAMPLES +None. +.SH APPLICATION USAGE +None. +.SH RATIONALE +None. +.SH FUTURE DIRECTIONS +None. +.SH NOTES +None. +.SH BUGS +None. +.SH SEE ALSO +.BR libsha2_hmac_digest (3), +.BR libsha2_hmac_init (3) diff --git a/libsha2_marshal.3 b/libsha2_marshal.3 index f6d1e4d..eb36dfc 100644 --- a/libsha2_marshal.3 +++ b/libsha2_marshal.3 @@ -31,7 +31,7 @@ this allows new versions of the library to unmarshal states marshalled by older versions. .SH RETURN VALUE The -.BR libsha2_init () +.BR libsha2_marshal () function returns the number of marshalled bytes (or if .I buf diff --git a/state_output_size.c b/state_output_size.c index d2cc5c1..85da7c2 100644 --- a/state_output_size.c +++ b/state_output_size.c @@ -5,7 +5,7 @@ /** * Get the output size of the algorithm specified for a state * - * @parma state The state + * @param state The state * @return The number of bytes in the output, zero on error */ size_t -- cgit v1.2.3-70-g09d2