Minor improvement and man pages for HMAC

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

16 files changed, 358 insertions, 41 deletions

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
@@ -330,18 +330,28 @@ __attribute__((__leaf__, __nonnull__, __nothrow__))
 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 <libsha2.h>
+
+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 <libsha2.h>
+
+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 <libsha2.h>
+
+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 <libsha2.h>
+
+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 <libsha2.h>
+
+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