Deprecate libkeccak_{state,hmac}_{unmarshal_skip,marshal_size} and replace with the functions without the _skip or _size suffix

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

20 files changed, 152 insertions, 302 deletions

diff --git a/Makefile b/Makefile
index c696010..1712539 100644
--- a/Makefile
+++ b/Makefile
@@ -35,7 +35,6 @@ OBJ =\
 	libkeccak_state_initialise.o\
 	libkeccak_state_marshal.o\
 	libkeccak_state_unmarshal.o\
-	libkeccak_state_unmarshal_skip.o\
 	libkeccak_state_wipe.o\
 	libkeccak_state_wipe_message.o\
 	libkeccak_state_wipe_sponge.o\
@@ -68,11 +67,9 @@ MAN3 =\
 	libkeccak_hmac_free.3\
 	libkeccak_hmac_initialise.3\
 	libkeccak_hmac_marshal.3\
-	libkeccak_hmac_marshal_size.3\
 	libkeccak_hmac_reset.3\
 	libkeccak_hmac_set_key.3\
 	libkeccak_hmac_unmarshal.3\
-	libkeccak_hmac_unmarshal_skip.3\
 	libkeccak_hmac_update.3\
 	libkeccak_hmac_wipe.3\
 	libkeccak_keccaksum_fd.3\
@@ -94,10 +91,8 @@ MAN3 =\
 	libkeccak_state_free.3\
 	libkeccak_state_initialise.3\
 	libkeccak_state_marshal.3\
-	libkeccak_state_marshal_size.3\
 	libkeccak_state_reset.3\
 	libkeccak_state_unmarshal.3\
-	libkeccak_state_unmarshal_skip.3\
 	libkeccak_state_wipe.3\
 	libkeccak_state_wipe_message.3\
 	libkeccak_state_wipe_sponge.3\
diff --git a/TODO b/TODO
index fa32b26..c41fded 100644
--- a/TODO
+++ b/TODO
@@ -9,3 +9,5 @@ Just for fun:
 Test parallelisation and acceleration.
 
 Measure cycles per byte.
+
+Add tests for HMAC.
diff --git a/libkeccak-legacy.h b/libkeccak-legacy.h
index 7641711..3579b5e 100644
--- a/libkeccak-legacy.h
+++ b/libkeccak-legacy.h
@@ -12,3 +12,31 @@ typedef struct libkeccak_state libkeccak_state_t;
 
 LIBKECCAK_GCC_ONLY(__attribute__((__deprecated__("Use struct libkeccak_hmac_state instead of libkeccak_hmac_state_t"))))
 typedef struct libkeccak_hmac_state libkeccak_hmac_state_t;
+
+LIBKECCAK_GCC_ONLY(__attribute__((__deprecated__("Use libkeccak_hmac_unmarshal(NULL, data) instead of libkeccak_hmac_unmarshal_skip(data)"))))
+static inline size_t
+libkeccak_hmac_unmarshal_skip(const void *restrict data)
+{
+	return libkeccak_hmac_unmarshal(NULL, data);
+}
+
+LIBKECCAK_GCC_ONLY(__attribute__((__deprecated__("Use libkeccak_state_unmarshal(NULL, data) instead of libkeccak_state_unmarshal_skip(data)"))))
+static inline size_t
+libkeccak_state_unmarshal_skip(const void *restrict data)
+{
+	return libkeccak_state_unmarshal(NULL, data);
+}
+
+LIBKECCAK_GCC_ONLY(__attribute__((__deprecated__("Use libkeccak_hmac_marshal(state, NULL) instead of libkeccak_hmac_marshal_size(state)"))))
+static inline size_t
+libkeccak_hmac_marshal_size(const struct libkeccak_hmac_state *restrict state)
+{
+	return libkeccak_hmac_marshal(state, NULL);
+}
+
+LIBKECCAK_GCC_ONLY(__attribute__((__deprecated__("Use libkeccak_state_marshal(state, NULL) instead of libkeccak_state_marshal_size(state)"))))
+static inline size_t
+libkeccak_state_marshal_size(const struct libkeccak_state *restrict state)
+{
+	return libkeccak_state_marshal(state, NULL);
+}
diff --git a/libkeccak.7 b/libkeccak.7
index 0a6ef04..8aba9e7 100644
--- a/libkeccak.7
+++ b/libkeccak.7
@@ -27,10 +27,8 @@ Keccak-3200 may be implemented in the future.
 .BR libkeccak_state_free (3),
 .BR libkeccak_state_copy (3),
 .BR libkeccak_state_duplicate (3),
-.BR libkeccak_state_marshal_size (3),
 .BR libkeccak_state_marshal (3),
 .BR libkeccak_state_unmarshal (3),
-.BR libkeccak_state_unmarshal_skip (3),
 .BR libkeccak_fast_update (3),
 .BR libkeccak_update (3),
 .BR libkeccak_fast_digest (3),
@@ -57,14 +55,9 @@ Keccak-3200 may be implemented in the future.
 .BR libkeccak_hmac_free (3),
 .BR libkeccak_hmac_copy (3),
 .BR libkeccak_hmac_duplicate (3),
-.BR libkeccak_hmac_marshal_size (3),
 .BR libkeccak_hmac_marshal (3),
 .BR libkeccak_hmac_unmarshal (3),
-.BR libkeccak_hmac_unmarshal_skip (3),
 .BR libkeccak_hmac_fast_update (3),
 .BR libkeccak_hmac_update (3),
 .BR libkeccak_hmac_fast_digest (3),
 .BR libkeccak_hmac_digest (3)
-.SH BUGS
-Please report bugs to https://github.com/maandree/libkeccak/issues or to
-maandree@kth.se
diff --git a/libkeccak.h b/libkeccak.h
index 8f1193c..d830ed8 100644
--- a/libkeccak.h
+++ b/libkeccak.h
@@ -528,50 +528,27 @@ libkeccak_state_duplicate(const struct libkeccak_state *restrict src)
 }
 
 /**
- * Calculates the allocation size required for the second argument
- * of `libkeccak_state_marshal` (`char* restrict data)`)
- * 
- * @param   state  The state as it will be marshalled by a subsequent call to `libkeccak_state_marshal`
- * @return         The allocation size needed for the buffer to which the state will be marshalled
- */
-LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __unused__, __warn_unused_result__, __pure__)))
-static inline size_t
-libkeccak_state_marshal_size(const struct libkeccak_state *restrict state)
-{
-	return sizeof(struct libkeccak_state) - sizeof(char *) + state->mptr * sizeof(char);
-}
-
-/**
  * Marshal a `struct libkeccak_state` into a buffer
  * 
  * @param   state  The state to marshal
- * @param   data   The output buffer
+ * @param   data   The output buffer, can be `NULL`
  * @return         The number of bytes stored to `data`
  */
-LIBKECCAK_GCC_ONLY(__attribute__((__leaf__, __nonnull__, __nothrow__)))
+LIBKECCAK_GCC_ONLY(__attribute__((__leaf__, __nonnull__(1), __nothrow__)))
 size_t libkeccak_state_marshal(const struct libkeccak_state *restrict, void *restrict);
 
 /**
  * Unmarshal a `struct libkeccak_state` from a buffer
  * 
- * @param   state  The slot for the unmarshalled state, must not be initialised (memory leak otherwise)
+ * @param   state  The slot for the unmarshalled state, must not be
+ *                 initialised (memory leak otherwise), can be `NULL`
  * @param   data   The input buffer
  * @return         The number of bytes read from `data`, 0 on error
  */
-LIBKECCAK_GCC_ONLY(__attribute__((__leaf__, __nonnull__)))
+LIBKECCAK_GCC_ONLY(__attribute__((__leaf__, __nonnull__(2))))
 size_t libkeccak_state_unmarshal(struct libkeccak_state *restrict, const void *restrict);
 
 /**
- * Gets the number of bytes the `struct libkeccak_state` stored
- * at the beginning of `data` occupies
- * 
- * @param   data  The data buffer
- * @return        The byte size of the stored state
- */
-LIBKECCAK_GCC_ONLY(__attribute__((__leaf__, __nonnull__, __nothrow__, __warn_unused_result__, __pure__)))
-size_t libkeccak_state_unmarshal_skip(const void *restrict);
-
-/**
  * Absorb more of the message to the Keccak sponge
  * without wiping sensitive data when possible
  * 
@@ -1018,71 +995,42 @@ libkeccak_hmac_duplicate(const struct libkeccak_hmac_state *restrict src)
 }
 
 /**
- * Calculates the allocation size required for the second argument
- * of `libkeccak_hmac_marshal` (`char* restrict data)`)
- * 
- * @param   state  The state as it will be marshalled by a subsequent call to `libkeccak_hamc_marshal`
- * @return         The allocation size needed for the buffer to which the state will be marshalled
- */
-LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __unused__, __warn_unused_result__, __pure__)))
-static inline size_t
-libkeccak_hmac_marshal_size(const struct libkeccak_hmac_state *restrict state)
-{
-	return libkeccak_state_marshal_size(&state->sponge) + sizeof(size_t) +
-	       ((state->key_length + 7) >> 3) + 2 * sizeof(char);
-}
-
-/**
  * Marshal a `struct libkeccak_hmac_state` into a buffer
  * 
  * @param   state  The state to marshal
- * @param   data   The output buffer
+ * @param   data   The output buffer, can be `NULL`
  * @return         The number of bytes stored to `data`
  */
-LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__)))
+LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__(1), __nothrow__)))
 static inline size_t
 libkeccak_hmac_marshal(const struct libkeccak_hmac_state *restrict state, void *restrict data_)
 {
 	unsigned char *restrict data = data_;
-	size_t written = libkeccak_state_marshal(&state->sponge, data);
-	data += written / sizeof(char);
-	*(size_t *)data = state->key_length;
-	data += sizeof(size_t) / sizeof(char);
-	memcpy(data, state->key_opad, (state->key_length + 7) >> 3);
-	data += ((state->key_length + 7) >> 3) / sizeof(char);
-	data[0] = (unsigned char)!!state->key_ipad;
-	data[1] = state->leftover;
+	size_t written = libkeccak_state_marshal(state ? &state->sponge : NULL, data);
+	if (data) {
+		data += written / sizeof(char);
+		*(size_t *)data = state->key_length;
+		data += sizeof(size_t) / sizeof(char);
+		memcpy(data, state->key_opad, (state->key_length + 7) >> 3);
+		data += ((state->key_length + 7) >> 3) / sizeof(char);
+		data[0] = (unsigned char)!!state->key_ipad;
+		data[1] = state->leftover;
+	}
 	return written + sizeof(size_t) + ((state->key_length + 7) >> 3) + 2 * sizeof(char);
 }
 
 /**
  * Unmarshal a `struct libkeccak_hmac_state` from a buffer
  * 
- * @param   state  The slot for the unmarshalled state, must not be initialised (memory leak otherwise)
+ * @param   state  The slot for the unmarshalled state, must not be
+ *                 initialised (memory leak otherwise), can be `NULL`
  * @param   data   The input buffer
  * @return         The number of bytes read from `data`, 0 on error
  */
-LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__)))
+LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__(2))))
 size_t libkeccak_hmac_unmarshal(struct libkeccak_hmac_state *restrict, const void *restrict);
 
 /**
- * Gets the number of bytes the `struct libkeccak_hmac_state` stored
- * at the beginning of `data` occupies
- * 
- * @param   data  The data buffer
- * @return        The byte size of the stored state
- */
-LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __warn_unused_result__, __pure__)))
-static inline size_t
-libkeccak_hmac_unmarshal_skip(const void *restrict data_)
-{
-	const char *restrict data = data_;
-	size_t skip = libkeccak_state_unmarshal_skip(data);
-	data += skip / sizeof(char);
-	return skip + sizeof(size_t) + *(const size_t *)data + 2 * sizeof(char);
-}
-
-/**
  * Absorb more, or the first part, of the message
  * without wiping sensitive data when possible
  * 
diff --git a/libkeccak_hmac_initialise.3 b/libkeccak_hmac_initialise.3
index 5d1b923..8570a86 100644
--- a/libkeccak_hmac_initialise.3
+++ b/libkeccak_hmac_initialise.3
@@ -42,7 +42,6 @@ and
 .BR libkeccak_hmac_destroy (3),
 .BR libkeccak_hmac_fast_destroy (3),
 .BR libkeccak_hmac_copy (3),
-.BR libkeccak_hmac_marshal_size (3),
 .BR libkeccak_spec_sha3 (3),
 .BR libkeccak_spec_shake (3),
 .BR libkeccak_spec_rawshake (3),
diff --git a/libkeccak_hmac_marshal.3 b/libkeccak_hmac_marshal.3
index 7693050..29ca9ea 100644
--- a/libkeccak_hmac_marshal.3
+++ b/libkeccak_hmac_marshal.3
@@ -18,10 +18,11 @@ function marshals
 into the beginning of
 .IR data .
 .PP
-Use the
-.BR libkeccak_hmac_marshal_size (3)
-function to get minimum usable allocation size
-for
+Specific
+.I NULL
+as
+.I data
+to get minimum usable allocation size for
 .IR data .
 .SH RETURN VALUES
 The
@@ -33,6 +34,4 @@ The
 .BR libkeccak_hmac_marshal ()
 function cannot fail.
 .SH SEE ALSO
-.BR libkeccak_hmac_marshal_size (3),
-.BR libkeccak_hmac_unmarshal (3),
-.BR libkeccak_hmac_unmarshal_skip (3)
+.BR libkeccak_hmac_unmarshal (3)
diff --git a/libkeccak_hmac_marshal_size.3 b/libkeccak_hmac_marshal_size.3
deleted file mode 100644
index b2b8595..0000000
--- a/libkeccak_hmac_marshal_size.3
+++ /dev/null
@@ -1,31 +0,0 @@
-.TH LIBKECCAK_HMAC_MARSHAL_SIZE 3 LIBKECCAK
-.SH NAME
-libkeccak_hmac_marshal_size - Calculates the marshal-size of an HMAC-hashing state
-.SH SYNOPSIS
-.nf
-#include <libkeccak.h>
-
-size_t libkeccak_hmac_marshal_size(const struct libkeccak_hmac_state *\fIstate\fP);
-.fi
-.PP
-Link with
-.IR -lkeccak .
-.SH DESCRIPTION
-The
-.BR libkeccak_hmac_marshal_size ()
-function calculates the number of bytes required
-to marshal
-.IR *state .
-.SH RETURN VALUES
-The
-.BR libkeccak_hmac_marshal_size ()
-returns a positive value: the number of
-bytes required to marshal the specified state.
-.SH ERRORS
-The
-.BR libkeccak_hmac_marshal_size ()
-function cannot fail.
-.SH SEE ALSO
-.BR libkeccak_hmac_marshal (3),
-.BR libkeccak_hmac_unmarshal (3),
-.BR libkeccak_hmac_unmarshal_skip (3)
diff --git a/libkeccak_hmac_unmarshal.3 b/libkeccak_hmac_unmarshal.3
index a0d98fd..7224282 100644
--- a/libkeccak_hmac_unmarshal.3
+++ b/libkeccak_hmac_unmarshal.3
@@ -17,17 +17,30 @@ function unmarshals an HMAC-hashing state from the beginning of
 .IR data .
 and stores it in
 .IR *state .
+.I state
+may be
+.IR NULL .
 .SH RETURN VALUES
 The
 .BR libkeccak_hmac_unmarshal ()
 returns the number of bytes reads from
-.IR data .
+.I data
+upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+If
+.I state
+is
+.IR NULL ,
+the number the function will always be
+successful and return a positive value,
+this value is the number of bytes that
+make un the marshalled state.
 .SH ERRORS
 The
 .BR libkeccak_hmac_unmarshal ()
 function may fail for any specified for the function
 .BR malloc (3).
 .SH SEE ALSO
-.BR libkeccak_hmac_marshal_size (3),
-.BR libkeccak_hmac_marshal (3),
-.BR libkeccak_hmac_unmarshal_skip (3)
+.BR libkeccak_hmac_marshal (3)
diff --git a/libkeccak_hmac_unmarshal.c b/libkeccak_hmac_unmarshal.c
index 9627f1e..452efa3 100644
--- a/libkeccak_hmac_unmarshal.c
+++ b/libkeccak_hmac_unmarshal.c
@@ -5,7 +5,8 @@
 /**
  * Unmarshal a `struct libkeccak_hmac_state` from a buffer
  * 
- * @param   state  The slot for the unmarshalled state, must not be initialised (memory leak otherwise)
+ * @param   state  The slot for the unmarshalled state, must not be
+ *                 initialised (memory leak otherwise), can be `NULL`
  * @param   data   The input buffer
  * @return         The number of bytes read from `data`, 0 on error
  */
@@ -18,33 +19,37 @@ libkeccak_hmac_unmarshal(struct libkeccak_hmac_state *restrict state, const void
 	state->key_opad = NULL;
 	state->key_ipad = NULL;
 
-	parsed = libkeccak_state_unmarshal(&state->sponge, data);
-	if (parsed == 0)
+	parsed = libkeccak_state_unmarshal(state ? &state->sponge : NULL, data);
+	if (!parsed)
 		return 0;
-
 	data += parsed / sizeof(char);
-	state->key_length = *(const size_t *)data;
+
+	size = *(const size_t *)data;
 	data += sizeof(size_t) / sizeof(char);
+	if (state)
+		size = state->key_length;
 	size = (state->key_length + 7) >> 3;
 
-	state->key_opad = malloc(2 * size);
-	if (!state->key_opad) {
-		libkeccak_state_destroy(&state->sponge);
-		return 0;
+	if (state) {
+		state->key_opad = malloc(2 * size);
+		if (!state->key_opad) {
+			libkeccak_state_destroy(&state->sponge);
+			return 0;
+		}
+		memcpy(state->key_opad, data, size);
+		data += size / sizeof(char);
+
+		if (data[0]) {
+			state->key_ipad = state->key_opad + size / sizeof(char);
+			memcpy(state->key_ipad, state->key_opad, size);
+			for (i = 0; i < size / sizeof(char); i++)
+				state->key_ipad[i] ^= (char)(HMAC_OUTER_PAD ^ HMAC_INNER_PAD);
+		}
+
+		state->leftover = data[1];
+		state->buffer = NULL;
+		state->buffer_size = 0;
 	}
-	memcpy(state->key_opad, data, size);
-	data += size / sizeof(char);
-
-	if (data[0]) {
-		state->key_ipad = state->key_opad + size / sizeof(char);
-		memcpy(state->key_ipad, state->key_opad, size);
-		for (i = 0; i < size / sizeof(char); i++)
-			state->key_ipad[i] ^= (char)(HMAC_OUTER_PAD ^ HMAC_INNER_PAD);
-	}
-
-	state->leftover = data[1];
-	state->buffer = NULL;
-	state->buffer_size = 0;
 
 	return parsed + sizeof(size_t) + size + 2 * sizeof(char);
 }
diff --git a/libkeccak_hmac_unmarshal_skip.3 b/libkeccak_hmac_unmarshal_skip.3
deleted file mode 100644
index 25db1ba..0000000
--- a/libkeccak_hmac_unmarshal_skip.3
+++ /dev/null
@@ -1,35 +0,0 @@
-.TH LIBKECCAK_HMAC_UNMARSHAL_SKIP 3 LIBKECCAK
-.SH NAME
-libkeccak_hmac_unmarshal_skip - Calculates the marshal-size of a marshalled HMAC-hashing state
-.SH SYNOPSIS
-.nf
-#include <libkeccak.h>
-
-size_t libkeccak_hmac_unmarshal_skip(const void *\fIdata\fP);
-.fi
-.PP
-Link with
-.IR -lkeccak .
-.SH DESCRIPTION
-The
-.BR libkeccak_hmac_unmarshal_skip ()
-function gets the number of bytes with which
-the HMAC-hashing state in the beginning of
-.I data
-is store stored. This is useful if you do not
-want to unmarshal the state.
-.SH RETURN VALUES
-The
-.BR libkeccak_hmac_unmarshal_skip ()
-returns a positive value: the number of
-bytes to skip forward to skip pass the
-hash state stored at the beginning of
-the buffer.
-.SH ERRORS
-The
-.BR libkeccak_hmac_unmarshal_skip ()
-function cannot fail.
-.SH SEE ALSO
-.BR libkeccak_hmac_marshal_size (3),
-.BR libkeccak_hmac_marshal (3),
-.BR libkeccak_hmac_unmarshal (3)
diff --git a/libkeccak_state_initialise.3 b/libkeccak_state_initialise.3
index b08b924..84d6ae9 100644
--- a/libkeccak_state_initialise.3
+++ b/libkeccak_state_initialise.3
@@ -50,5 +50,5 @@ function may fail for any specified for the function
 .BR libkeccak_spec_rawshake (3),
 .BR libkeccak_spec_check (3),
 .BR libkeccak_generalised_spec_initialise (3),
-.BR libkeccak_state_marshal_size (3),
+.BR libkeccak_state_marshal (3),
 .BR libkeccak_hmac_initialise (3)
diff --git a/libkeccak_state_marshal.3 b/libkeccak_state_marshal.3
index 9e49c17..0599b5a 100644
--- a/libkeccak_state_marshal.3
+++ b/libkeccak_state_marshal.3
@@ -18,11 +18,11 @@ function marshals
 into the beginning of
 .IR data .
 .PP
-Use the
-.BR libkeccak_state_marshal_size (3)
-function to get minimum usable allocation size
-for
-.IR data .
+Specific
+.I NULL
+as
+.I data
+to get minimum usable allocation size for
 .SH RETURN VALUES
 The
 .BR libkeccak_state_marshal ()
@@ -33,6 +33,4 @@ The
 .BR libkeccak_state_marshal ()
 function cannot fail.
 .SH SEE ALSO
-.BR libkeccak_state_marshal_size (3),
-.BR libkeccak_state_unmarshal (3),
-.BR libkeccak_state_unmarshal_skip (3)
+.BR libkeccak_state_unmarshal (3)
diff --git a/libkeccak_state_marshal.c b/libkeccak_state_marshal.c
index 00b54cc..c4ce7f6 100644
--- a/libkeccak_state_marshal.c
+++ b/libkeccak_state_marshal.c
@@ -6,7 +6,7 @@
  * Marshal a `struct libkeccak_state` into a buffer
  * 
  * @param   state  The state to marshal
- * @param   data   The output buffer
+ * @param   data   The output buffer, can be `NULL`
  * @return         The number of bytes stored to `data`
  */
 size_t
@@ -14,20 +14,22 @@ libkeccak_state_marshal(const struct libkeccak_state *restrict state, void *rest
 {
 #define set(type, var) *((type *)data) = state->var, data += sizeof(type) / sizeof(char)
 	unsigned char *restrict data = data_;
-	set(long int, r);
-	set(long int, c);
-	set(long int, n);
-	set(long int, b);
-	set(long int, w);
-	set(int64_t, wmod);
-	set(long int, l);
-	set(long int, nr);
-	memcpy(data, state->S, sizeof(state->S));
-	data += sizeof(state->S) / sizeof(char);
-	set(size_t, mptr);
-	set(size_t, mlen);
-	memcpy(data, state->M, state->mptr * sizeof(char));
-	data += state->mptr;
+	if (data) {
+		set(long int, r);
+		set(long int, c);
+		set(long int, n);
+		set(long int, b);
+		set(long int, w);
+		set(int64_t, wmod);
+		set(long int, l);
+		set(long int, nr);
+		memcpy(data, state->S, sizeof(state->S));
+		data += sizeof(state->S) / sizeof(char);
+		set(size_t, mptr);
+		set(size_t, mlen);
+		memcpy(data, state->M, state->mptr * sizeof(char));
+		data += state->mptr;
+	}
 	return sizeof(struct libkeccak_state) - sizeof(char *) + state->mptr * sizeof(char);
 #undef set
 }
diff --git a/libkeccak_state_marshal_size.3 b/libkeccak_state_marshal_size.3
deleted file mode 100644
index 312c415..0000000
--- a/libkeccak_state_marshal_size.3
+++ /dev/null
@@ -1,31 +0,0 @@
-.TH LIBKECCAK_STATE_MARSHAL_SIZE 3 LIBKECCAK
-.SH NAME
-libkeccak_state_marshal_size - Calculates the marshal-size of a hash state
-.SH SYNOPSIS
-.nf
-#include <libkeccak.h>
-
-size_t libkeccak_state_marshal_size(const struct libkeccak_state *\fIstate\fP);
-.fi
-.PP
-Link with
-.IR -lkeccak .
-.SH DESCRIPTION
-The
-.BR libkeccak_state_marshal_size ()
-function calculates the number of bytes required
-to marshal
-.IR *state .
-.SH RETURN VALUES
-The
-.BR libkeccak_state_marshal_size ()
-returns a positive value: the number of
-bytes required to marshal the specified state.
-.SH ERRORS
-The
-.BR libkeccak_state_marshal_size ()
-function cannot fail.
-.SH SEE ALSO
-.BR libkeccak_state_marshal (3),
-.BR libkeccak_state_unmarshal (3),
-.BR libkeccak_state_unmarshal_skip (3)
diff --git a/libkeccak_state_unmarshal.3 b/libkeccak_state_unmarshal.3
index 3881550..6198e3a 100644
--- a/libkeccak_state_unmarshal.3
+++ b/libkeccak_state_unmarshal.3
@@ -18,17 +18,30 @@ of
 .IR data .
 and stores it in
 .IR *state .
+.I state
+may be
+.IR NULL .
 .SH RETURN VALUES
 The
 .BR libkeccak_state_unmarshal ()
 returns the number of bytes reads from
-.IR data .
+.I data
+upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+If
+.I state
+is
+.IR NULL ,
+the number the function will always be
+successful and return a positive value,
+this value is the number of bytes that
+make un the marshalled state.
 .SH ERRORS
 The
 .BR libkeccak_state_unmarshal ()
 function may fail for any specified for the function
 .BR malloc (3).
 .SH SEE ALSO
-.BR libkeccak_state_marshal_size (3),
-.BR libkeccak_state_marshal (3),
-.BR libkeccak_state_unmarshal_skip (3)
+.BR libkeccak_state_marshal (3)
diff --git a/libkeccak_state_unmarshal.c b/libkeccak_state_unmarshal.c
index af1f7de..e46db54 100644
--- a/libkeccak_state_unmarshal.c
+++ b/libkeccak_state_unmarshal.c
@@ -5,7 +5,8 @@
 /**
  * Unmarshal a `struct libkeccak_state` from a buffer
  * 
- * @param   state  The slot for the unmarshalled state, must not be initialised (memory leak otherwise)
+ * @param   state  The slot for the unmarshalled state, must not be
+ *                 initialised (memory leak otherwise), can be `NULL`
  * @param   data   The input buffer
  * @return         The number of bytes read from `data`, 0 on error
  */
@@ -14,6 +15,10 @@ libkeccak_state_unmarshal(struct libkeccak_state *restrict state, const void *re
 {
 #define get(type, var) state->var = *((const type *)data), data += sizeof(type) / sizeof(char)
 	const unsigned char *restrict data = data_;
+	if (!state) {
+		data += (7 * sizeof(long int) + 26 * sizeof(int64_t)) / sizeof(char);
+		return sizeof(struct libkeccak_state) - sizeof(char *) + *(const size_t *)data * sizeof(char);
+	}
 	get(long int, r);
 	get(long int, c);
 	get(long int, n);
diff --git a/libkeccak_state_unmarshal_skip.3 b/libkeccak_state_unmarshal_skip.3
deleted file mode 100644
index 9fb9336..0000000
--- a/libkeccak_state_unmarshal_skip.3
+++ /dev/null
@@ -1,35 +0,0 @@
-.TH LIBKECCAK_STATE_UNMARSHAL_SKIP 3 LIBKECCAK
-.SH NAME
-libkeccak_state_unmarshal_skip - Calculates the marshal-size of a marshalled hash state
-.SH SYNOPSIS
-.nf
-#include <libkeccak.h>
-
-size_t libkeccak_state_unmarshal_skip(const void *\fIdata\fP);
-.fi
-.PP
-Link with
-.IR -lkeccak .
-.SH DESCRIPTION
-The
-.BR libkeccak_state_unmarshal_skip ()
-function gets the number of bytes with which
-the hash state in the beginning of
-.I data
-is store stored. This is useful if you do not
-want to unmarshal the state.
-.SH RETURN VALUES
-The
-.BR libkeccak_state_unmarshal_skip ()
-returns a positive value: the number of
-bytes to skip forward to skip pass the
-hash state stored at the beginning of
-the buffer.
-.SH ERRORS
-The
-.BR libkeccak_state_unmarshal_skip ()
-function cannot fail.
-.SH SEE ALSO
-.BR libkeccak_state_marshal_size (3),
-.BR libkeccak_state_marshal (3),
-.BR libkeccak_state_unmarshal (3)
diff --git a/libkeccak_state_unmarshal_skip.c b/libkeccak_state_unmarshal_skip.c
deleted file mode 100644
index 34a898a..0000000
--- a/libkeccak_state_unmarshal_skip.c
+++ /dev/null
@@ -1,18 +0,0 @@
-/* See LICENSE file for copyright and license details. */
-#include "common.h"
-
-
-/**
- * Gets the number of bytes the `struct libkeccak_state` stored
- * at the beginning of `data` occupies
- * 
- * @param   data  The data buffer
- * @return        The byte size of the stored state
- */
-size_t
-libkeccak_state_unmarshal_skip(const void *restrict data_)
-{
-	const unsigned char *restrict data = data_;
-	data += (7 * sizeof(long int) + 26 * sizeof(int64_t)) / sizeof(char);
-	return sizeof(struct libkeccak_state) - sizeof(char *) + *(const size_t *)data * sizeof(char);
-}
diff --git a/test.c b/test.c
index 059a9eb..020e045 100644
--- a/test.c
+++ b/test.c
@@ -8,7 +8,7 @@
 
 
 /**
- * Test functions in <libkeccak/hex.h>
+ * Test hexdecimal-coding functions
  * 
  * @return  Zero on success, -1 on error
  */
@@ -62,7 +62,7 @@ test_hex(void)
 
 
 /**
- * Test functions in <libkeccak/state.h>
+ * Test state functions
  * 
  * @param   spec  The specifications for the state
  * @return        Zero on success, -1 on error
@@ -96,7 +96,7 @@ test_state(struct libkeccak_spec *restrict spec)
 		return -1;
 	}
 
-	marshal_size = libkeccak_state_marshal_size(state2);
+	marshal_size = libkeccak_state_marshal(state2, NULL);
 	marshalled_data = malloc(marshal_size);
 	if (!marshalled_data) {
 		perror("malloc");
@@ -126,8 +126,8 @@ test_state(struct libkeccak_spec *restrict spec)
 		return -1;
 	}
 
-	if (libkeccak_state_unmarshal_skip(marshalled_data) != marshal_size) {
-		printf("libkeccak_state_unmarshal_skip returned an unexpected value.\n");
+	if (libkeccak_state_unmarshal(NULL, marshalled_data) != marshal_size) {
+		printf("libkeccak_state_unmarshal(NULL, .) returned an unexpected value.\n");
 		return -1;
 	}