Document *everything*

18 files changed, 221 insertions, 27 deletions

diff --git a/src/crypto/cipher/aes128_ctr/aes128_ctr.c b/src/crypto/cipher/aes128_ctr/aes128_ctr.c
index 52122d9..4448dd0 100644
--- a/src/crypto/cipher/aes128_ctr/aes128_ctr.c
+++ b/src/crypto/cipher/aes128_ctr/aes128_ctr.c
@@ -23,10 +23,17 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The aes128-ctr stream cipher
+*/
+
 
 #include "../../../crypto.h"
 
 
+/** cipher info about aes128-ctr */
 const fastd_cipher_info_t fastd_cipher_info_aes128_ctr = {
 	.key_length = 16,
 	.iv_length = 16,
diff --git a/src/crypto/cipher/aes128_ctr/nacl/cipher_aes128_ctr_nacl.c b/src/crypto/cipher/aes128_ctr/nacl/cipher_aes128_ctr_nacl.c
index 793b724..797572c 100644
--- a/src/crypto/cipher/aes128_ctr/nacl/cipher_aes128_ctr_nacl.c
+++ b/src/crypto/cipher/aes128_ctr/nacl/cipher_aes128_ctr_nacl.c
@@ -23,17 +23,25 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The aes128-ctr implementation from NaCl
+*/
+
 
 #include "../../../../crypto.h"
 
 #include <crypto_stream_aes128ctr.h>
 
 
+/** The cipher state */
 struct __attribute__((aligned(16))) fastd_cipher_state {
-	uint8_t d[crypto_stream_aes128ctr_BEFORENMBYTES] __attribute__((aligned(16)));
+	uint8_t d[crypto_stream_aes128ctr_BEFORENMBYTES] __attribute__((aligned(16))); /**< The unpacked AES key */
 };
 
 
+/** Initializes the cipher state */
 static fastd_cipher_state_t* aes128_ctr_init(const uint8_t *key) {
 	fastd_block128_t k;
 	memcpy(k.b, key, sizeof(fastd_block128_t));
@@ -47,11 +55,13 @@ static fastd_cipher_state_t* aes128_ctr_init(const uint8_t *key) {
 	return state;
 }
 
+/** XORs data with the aes128-ctr cipher stream */
 static bool aes128_ctr_crypt(const fastd_cipher_state_t *state, fastd_block128_t *out, const fastd_block128_t *in, size_t len, const uint8_t *iv) {
 	crypto_stream_aes128ctr_xor_afternm(out->b, in->b, len, iv, state->d);
 	return true;
 }
 
+/** Frees the cipher state */
 static void aes128_ctr_free(fastd_cipher_state_t *state) {
 	if (state) {
 		secure_memzero(state, sizeof(*state));
@@ -59,6 +69,8 @@ static void aes128_ctr_free(fastd_cipher_state_t *state) {
 	}
 }
 
+
+/** The nacl aes128-ctr implementation */
 const fastd_cipher_t fastd_cipher_aes128_ctr_nacl = {
 	.init = aes128_ctr_init,
 	.crypt = aes128_ctr_crypt,
diff --git a/src/crypto/cipher/aes128_ctr/openssl/aes128_ctr_openssl.c b/src/crypto/cipher/aes128_ctr/openssl/aes128_ctr_openssl.c
index b47be57..2e06763 100644
--- a/src/crypto/cipher/aes128_ctr/openssl/aes128_ctr_openssl.c
+++ b/src/crypto/cipher/aes128_ctr/openssl/aes128_ctr_openssl.c
@@ -23,17 +23,25 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The aes128-ctr implementation from OpenSSL
+*/
+
 
 #include "../../../../crypto.h"
 
 #include <openssl/evp.h>
 
 
+/** The cipher state containing the OpenSSL cipher context */
 struct fastd_cipher_state {
-	EVP_CIPHER_CTX *aes;
+	EVP_CIPHER_CTX *aes;		/**< The OpenSSL cipher context */
 };
 
 
+/** Initializes the cipher state */
 static fastd_cipher_state_t* aes128_ctr_init(const uint8_t *key) {
 	fastd_cipher_state_t *state = malloc(sizeof(fastd_cipher_state_t));
 
@@ -43,6 +51,7 @@ static fastd_cipher_state_t* aes128_ctr_init(const uint8_t *key) {
 	return state;
 }
 
+/** XORs data with the aes128-ctr cipher stream */
 static bool aes128_ctr_crypt(const fastd_cipher_state_t *state, fastd_block128_t *out, const fastd_block128_t *in, size_t len, const uint8_t *iv) {
 	int clen, clen2;
 
@@ -61,6 +70,7 @@ static bool aes128_ctr_crypt(const fastd_cipher_state_t *state, fastd_block128_t
 	return true;
 }
 
+/** Frees the cipher state */
 static void aes128_ctr_free(fastd_cipher_state_t *state) {
 	if (state) {
 		EVP_CIPHER_CTX_free(state->aes);
@@ -68,6 +78,8 @@ static void aes128_ctr_free(fastd_cipher_state_t *state) {
 	}
 }
 
+
+/** The openssl aes128-ctr implementation */
 const fastd_cipher_t fastd_cipher_aes128_ctr_openssl = {
 	.available = fastd_true,
 
diff --git a/src/crypto/cipher/ciphers.c.in b/src/crypto/cipher/ciphers.c.in
index 01b5a35..7816bca 100644
--- a/src/crypto/cipher/ciphers.c.in
+++ b/src/crypto/cipher/ciphers.c.in
@@ -23,6 +23,12 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   Generated lists of ciphers and their implementations
+*/
+
 
 #include <src/crypto.h>
 #include <src/fastd.h>
@@ -30,30 +36,35 @@
 
 @CIPHER_DEFINITIONS@
 
+/** A cipher implementation */
 typedef struct fastd_cipher_impl {
-	const char *name;
-	const fastd_cipher_t *impl;
+	const char *name;			/**< The name of the cipher implementation */
+	const fastd_cipher_t *impl;		/**< The cipher implementation */
 } fastd_cipher_impl_t;
 
+/** A cipher */
 typedef struct cipher_entry {
-	const char *name;
-	const fastd_cipher_info_t *info;
-	const fastd_cipher_impl_t *impls;
+	const char *name;			/**< The name of the cipher */
+	const fastd_cipher_info_t *info;	/**< The associated cipher information */
+	const fastd_cipher_impl_t *impls;	/**< NULL-terminated array of cipher implementations */
 } cipher_entry_t;
 
 @CIPHER_IMPLS@
 
+/** The list of supported ciphers */
 static const cipher_entry_t ciphers[] = { @CIPHER_LIST@
 };
 
+/** The list of chosen cipher implementations */
 static const fastd_cipher_t *cipher_conf[array_size(ciphers)] = {};
 
 
+/** Checks if a cipher implementation is available on the runtime platform */
 static inline bool cipher_available(const fastd_cipher_t *cipher) {
 	return (!cipher->available) || cipher->available();
 }
 
-/** Initializes the list of ciphers */
+/** Initializes the list of cipher implementations */
 void fastd_cipher_init(void) {
 	size_t i, j;
 	for (i = 0; i < array_size(ciphers); i++) {
@@ -89,6 +100,7 @@ bool fastd_cipher_config(const char *name, const char *impl) {
 	return false;
 }
 
+/** Returns information about the cipher with the specified name if there is an implementation available */
 const fastd_cipher_info_t* fastd_cipher_info_get_by_name(const char *name) {
 	size_t i;
 	for (i = 0; i < array_size(ciphers); i++) {
@@ -104,6 +116,7 @@ const fastd_cipher_info_t* fastd_cipher_info_get_by_name(const char *name) {
 	return NULL;
 }
 
+/** Returns the chosen cipher implementation for a given cipher */
 const fastd_cipher_t* fastd_cipher_get(const fastd_cipher_info_t *info) {
 	size_t i;
 	for (i = 0; i < array_size(ciphers); i++) {
diff --git a/src/crypto/cipher/null/memcpy/null_memcpy.c b/src/crypto/cipher/null/memcpy/null_memcpy.c
index a2c0df9..089817f 100644
--- a/src/crypto/cipher/null/memcpy/null_memcpy.c
+++ b/src/crypto/cipher/null/memcpy/null_memcpy.c
@@ -23,22 +23,32 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The memcpy null implementation
+*/
+
 
 #include "../../../../crypto.h"
 
 
+/** Doesn't do anything as the null cipher doesn't use any state */
 static fastd_cipher_state_t* null_init(const uint8_t *key UNUSED) {
 	return NULL;
 }
 
+/** Just copies the input data to the output */
 static bool null_memcpy(const fastd_cipher_state_t *state UNUSED, fastd_block128_t *out, const fastd_block128_t *in, size_t len, const uint8_t *iv UNUSED) {
 	memcpy(out, in, len);
 	return true;
 }
 
+/** Doesn't do anything as the null cipher doesn't use any state */
 static void null_free(fastd_cipher_state_t *state UNUSED) {
 }
 
+/** The memcpy null implementation */
 const fastd_cipher_t fastd_cipher_null_memcpy = {
 	.init = null_init,
 	.crypt = null_memcpy,
diff --git a/src/crypto/cipher/null/null.c b/src/crypto/cipher/null/null.c
index d6e4cab..353090a 100644
--- a/src/crypto/cipher/null/null.c
+++ b/src/crypto/cipher/null/null.c
@@ -23,10 +23,17 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The null cipher not performing any encryption
+*/
+
 
 #include "../../../crypto.h"
 
 
+/** cipher info about the null cipher */
 const fastd_cipher_info_t fastd_cipher_info_null = {
 	.key_length = 0,
 	.iv_length = 0,
diff --git a/src/crypto/cipher/salsa20/nacl/salsa20_nacl.c b/src/crypto/cipher/salsa20/nacl/salsa20_nacl.c
index 03ab1d9..6179bc2 100644
--- a/src/crypto/cipher/salsa20/nacl/salsa20_nacl.c
+++ b/src/crypto/cipher/salsa20/nacl/salsa20_nacl.c
@@ -23,17 +23,25 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The Salsa20 implementation from NaCl
+*/
+
 
 #include "../../../../crypto.h"
 
 #include <crypto_stream_salsa20.h>
 
 
+/** The cipher state */
 struct fastd_cipher_state {
-	uint8_t key[crypto_stream_salsa20_KEYBYTES];
+	uint8_t key[crypto_stream_salsa20_KEYBYTES];	/**< The encryption key */
 };
 
 
+/** Initializes the cipher state */
 static fastd_cipher_state_t* salsa20_init(const uint8_t *key) {
 	fastd_cipher_state_t *state = malloc(sizeof(fastd_cipher_state_t));
 	memcpy(state->key, key, crypto_stream_salsa20_KEYBYTES);
@@ -41,11 +49,13 @@ static fastd_cipher_state_t* salsa20_init(const uint8_t *key) {
 	return state;
 }
 
+/** XORs data with the Salsa20 cipher stream */
 static bool salsa20_crypt(const fastd_cipher_state_t *state, fastd_block128_t *out, const fastd_block128_t *in, size_t len, const uint8_t *iv) {
 	crypto_stream_salsa20_xor(out->b, in->b, len, iv, state->key);
 	return true;
 }
 
+/** Frees the cipher state */
 static void salsa20_free(fastd_cipher_state_t *state) {
 	if (state) {
 		secure_memzero(state, sizeof(*state));
@@ -53,6 +63,8 @@ static void salsa20_free(fastd_cipher_state_t *state) {
 	}
 }
 
+
+/** The nacl salsa20 implementation */
 const fastd_cipher_t fastd_cipher_salsa20_nacl = {
 	.init = salsa20_init,
 	.crypt = salsa20_crypt,
diff --git a/src/crypto/cipher/salsa20/salsa20.c b/src/crypto/cipher/salsa20/salsa20.c
index f4f713f..dad6a6c 100644
--- a/src/crypto/cipher/salsa20/salsa20.c
+++ b/src/crypto/cipher/salsa20/salsa20.c
@@ -23,10 +23,17 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The Salsa20 stream cipher
+*/
+
 
 #include "../../../crypto.h"
 
 
+/** Cipher info about Salsa20 */
 const fastd_cipher_info_t fastd_cipher_info_salsa20 = {
 	.key_length = 32,
 	.iv_length = 8,
diff --git a/src/crypto/cipher/salsa20/xmm/salsa20_xmm.c b/src/crypto/cipher/salsa20/xmm/salsa20_xmm.c
index 52c4b6d..a85ed72 100644
--- a/src/crypto/cipher/salsa20/xmm/salsa20_xmm.c
+++ b/src/crypto/cipher/salsa20/xmm/salsa20_xmm.c
@@ -23,15 +23,21 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-/*
-  The assembly implementations were written by D. J. Bernstein and are
-  Public Domain. For more information see http://cr.yp.to/snuffle.html
+/**
+   \file
+
+   The XMM Salsa20 implementation for SSE2-capable x86 systems
+
+   The assembly implementations were written by D. J. Bernstein and are
+   Public Domain. For more information see http://cr.yp.to/snuffle.html
 */
 
+
 #include "../../../../crypto.h"
 #include "../../../../cpuid.h"
 
 
+/** The length of the key used by Salsa20 */
 #define KEYBYTES 32
 
 
@@ -44,18 +50,22 @@
 #endif
 
 
+/** The actual Salsa20 assembly implementation */
 int crypto_stream_salsa20_xor(unsigned char *c, const unsigned char *m, unsigned long long mlen, const unsigned char *n, const unsigned char *k);
 
 
+/** The cipher state */
 struct fastd_cipher_state {
-	uint8_t key[KEYBYTES];
+	uint8_t key[KEYBYTES];		/**< The encryption key */
 };
 
 
+/** Checks if the runtime platform supports SSE2 */
 static bool salsa20_available(void) {
 	return fastd_cpuid() & CPUID_SSE2;
 }
 
+/** Initializes the cipher state */
 static fastd_cipher_state_t* salsa20_init(const uint8_t *key) {
 	fastd_cipher_state_t *state = malloc(sizeof(fastd_cipher_state_t));
 	memcpy(state->key, key, KEYBYTES);
@@ -63,11 +73,13 @@ static fastd_cipher_state_t* salsa20_init(const uint8_t *key) {
 	return state;
 }
 
+/** XORs data with the Salsa20 cipher stream */
 static bool salsa20_crypt(const fastd_cipher_state_t *state, fastd_block128_t *out, const fastd_block128_t *in, size_t len, const uint8_t *iv) {
 	crypto_stream_salsa20_xor(out->b, in->b, len, iv, state->key);
 	return true;
 }
 
+/** Frees the cipher state */
 static void salsa20_free(fastd_cipher_state_t *state) {
 	if (state) {
 		secure_memzero(state, sizeof(*state));
@@ -75,6 +87,8 @@ static void salsa20_free(fastd_cipher_state_t *state) {
 	}
 }
 
+
+/** The xmm salsa20 implementation */
 const fastd_cipher_t fastd_cipher_salsa20_xmm = {
 	.available = salsa20_available,
 
diff --git a/src/crypto/cipher/salsa2012/nacl/salsa2012_nacl.c b/src/crypto/cipher/salsa2012/nacl/salsa2012_nacl.c
index efe7089..18ec502 100644
--- a/src/crypto/cipher/salsa2012/nacl/salsa2012_nacl.c
+++ b/src/crypto/cipher/salsa2012/nacl/salsa2012_nacl.c
@@ -23,17 +23,25 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The Salsa20/12 implementation from NaCl
+*/
+
 
 #include "../../../../crypto.h"
 
 #include <crypto_stream_salsa2012.h>
 
 
+/** The cipher state */
 struct fastd_cipher_state {
-	uint8_t key[crypto_stream_salsa2012_KEYBYTES];
+	uint8_t key[crypto_stream_salsa2012_KEYBYTES];	/**< The encryption key */
 };
 
 
+/** Initializes the cipher state */
 static fastd_cipher_state_t* salsa2012_init(const uint8_t *key) {
 	fastd_cipher_state_t *state = malloc(sizeof(fastd_cipher_state_t));
 	memcpy(state->key, key, crypto_stream_salsa2012_KEYBYTES);
@@ -41,11 +49,13 @@ static fastd_cipher_state_t* salsa2012_init(const uint8_t *key) {
 	return state;
 }
 
+/** XORs data with the Salsa20/12 cipher stream */
 static bool salsa2012_crypt(const fastd_cipher_state_t *state, fastd_block128_t *out, const fastd_block128_t *in, size_t len, const uint8_t *iv) {
 	crypto_stream_salsa2012_xor(out->b, in->b, len, iv, state->key);
 	return true;
 }
 
+/** Frees the cipher state */
 static void salsa2012_free(fastd_cipher_state_t *state) {
 	if (state) {
 		secure_memzero(state, sizeof(*state));
@@ -53,6 +63,8 @@ static void salsa2012_free(fastd_cipher_state_t *state) {
 	}
 }
 
+
+/** The nacl salsa2012 implementation */
 const fastd_cipher_t fastd_cipher_salsa2012_nacl = {
 	.init = salsa2012_init,
 	.crypt = salsa2012_crypt,
diff --git a/src/crypto/cipher/salsa2012/salsa2012.c b/src/crypto/cipher/salsa2012/salsa2012.c
index 8dcfc33..d10c4fb 100644
--- a/src/crypto/cipher/salsa2012/salsa2012.c
+++ b/src/crypto/cipher/salsa2012/salsa2012.c
@@ -23,10 +23,17 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   The Salsa20/12 stream cipher, a reduced-round version of Salsa20
+*/
+
 
 #include "../../../crypto.h"
 
 
+/** Cipher info about Salsa20/12 */
 const fastd_cipher_info_t fastd_cipher_info_salsa2012 = {
 	.key_length = 32,
 	.iv_length = 8,
diff --git a/src/crypto/cipher/salsa2012/xmm/salsa2012_xmm.c b/src/crypto/cipher/salsa2012/xmm/salsa2012_xmm.c
index 5e5862f..7e6fe80 100644
--- a/src/crypto/cipher/salsa2012/xmm/salsa2012_xmm.c
+++ b/src/crypto/cipher/salsa2012/xmm/salsa2012_xmm.c
@@ -23,15 +23,21 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
-/*
-  The assembly implementations were written by D. J. Bernstein and are
-  Public Domain. For more information see http://cr.yp.to/snuffle.html
+/**
+   \file
+
+   The XMM Salsa20/12 implementation for SSE2-capable x86 systems
+
+   The assembly implementations were written by D. J. Bernstein and are
+   Public Domain. For more information see http://cr.yp.to/snuffle.html
 */
 
+
 #include "../../../../crypto.h"
 #include "../../../../cpuid.h"
 
 
+/** The length of the key used by Salsa20/12 */
 #define KEYBYTES 32
 
 
@@ -44,18 +50,22 @@
 #endif
 
 
+/** The actual Salsa20/12 assembly implementation */
 int crypto_stream_salsa2012_xor(unsigned char *c, const unsigned char *m, unsigned long long mlen, const unsigned char *n, const unsigned char *k);
 
 
+/** The cipher state */
 struct fastd_cipher_state {
-	uint8_t key[KEYBYTES];
+	uint8_t key[KEYBYTES];		/**< The encryption key */
 };
 
 
+/** Checks if the runtime platform supports SSE2 */
 static bool salsa2012_available(void) {
 	return fastd_cpuid() & CPUID_SSE2;
 }
 
+/** Initializes the cipher state */
 static fastd_cipher_state_t* salsa2012_init(const uint8_t *key) {
 	fastd_cipher_state_t *state = malloc(sizeof(fastd_cipher_state_t));
 	memcpy(state->key, key, KEYBYTES);
@@ -63,11 +73,13 @@ static fastd_cipher_state_t* salsa2012_init(const uint8_t *key) {
 	return state;
 }
 
+/** XORs data with the Salsa20/12 cipher stream */
 static bool salsa2012_crypt(const fastd_cipher_state_t *state, fastd_block128_t *out, const fastd_block128_t *in, size_t len, const uint8_t *iv) {
 	crypto_stream_salsa2012_xor(out->b, in->b, len, iv, state->key);
 	return true;
 }
 
+/** Frees the cipher state */
 static void salsa2012_free(fastd_cipher_state_t *state) {
 	if (state) {
 		secure_memzero(state, sizeof(*state));
@@ -75,6 +87,8 @@ static void salsa2012_free(fastd_cipher_state_t *state) {
 	}
 }
 
+
+/** The xmm salsa2012 implementation */
 const fastd_cipher_t fastd_cipher_salsa2012_xmm = {
 	.available = salsa2012_available,
 
diff --git a/src/crypto/mac/ghash/builtin/ghash_builtin.c b/src/crypto/mac/ghash/builtin/ghash_builtin.c
index 28e9292..0b957a4 100644
--- a/src/crypto/mac/ghash/builtin/ghash_builtin.c
+++ b/src/crypto/mac/ghash/builtin/ghash_builtin.c
@@ -23,18 +23,27 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   Portable, table-based GHASH implementation
+*/
+
 
 #include "../../../../crypto.h"
 
 
+/** MAC state used by this GHASH implmentation */
 struct fastd_mac_state {
-	fastd_block128_t H[32][16];
+	fastd_block128_t H[32][16];		/**< Lookup table unpacked from the hash key */
 };
 
 
+/** Lower 128 bit of the modulus \f$ x^{128} + x^7 + x^2 + x + 1 \f$ */
 static const fastd_block128_t r = { .b = {0xe1} };
 
 
+/** Right shift of a 128bit integer by up to 8 bytes */
 static inline uint8_t shr(fastd_block128_t *out, const fastd_block128_t *in, int n) {
 	size_t i;
 	uint8_t c = 0;
@@ -48,6 +57,7 @@ static inline uint8_t shr(fastd_block128_t *out, const fastd_block128_t *in, int
 	return (c >> (8-n));
 }
 
+/** Galois field multiplication of a 128bit integer with H */
 static inline void mulH_a(fastd_block128_t *x, const fastd_mac_state_t *cstate) {
 	fastd_block128_t out = {};
 
@@ -61,6 +71,7 @@ static inline void mulH_a(fastd_block128_t *x, const fastd_mac_state_t *cstate)
 }
 
 
+/** Initializes the MAC state with the unpacked key data */
 static fastd_mac_state_t* ghash_init(const uint8_t *key) {
 	fastd_mac_state_t *state;
 	if (posix_memalign((void**)&state, 16, sizeof(fastd_mac_state_t)))
@@ -107,6 +118,7 @@ static fastd_mac_state_t* ghash_init(const uint8_t *key) {
 	return state;
 }
 
+/** Calculates the GHASH of the supplied blocks */
 static bool ghash_hash(const fastd_mac_state_t *state, fastd_block128_t *out, const fastd_block128_t *in, size_t n_blocks) {
 	memset(out, 0, sizeof(fastd_block128_t));
 
@@ -119,6 +131,7 @@ static bool ghash_hash(const fastd_mac_state_t *state, fastd_block128_t *out, co
 	return true;
 }
 
+/** Frees the MAC state */
 static void ghash_free(fastd_mac_state_t *state) {
 	if (state) {
 		secure_memzero(state, sizeof(*state));
@@ -126,6 +139,7 @@ static void ghash_free(fastd_mac_state_t *state) {
 	}
 }
 
+/** The builtin GHASH implementation */
 const fastd_mac_t fastd_mac_ghash_builtin = {
 	.init = ghash_init,
 	.hash = ghash_hash,
diff --git a/src/crypto/mac/ghash/ghash.c b/src/crypto/mac/ghash/ghash.c
index 5976131..0ba6440 100644
--- a/src/crypto/mac/ghash/ghash.c
+++ b/src/crypto/mac/ghash/ghash.c
@@ -23,10 +23,18 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   General information about the GHASH algorithm
+
+   \sa http://en.wikipedia.org/wiki/Galois/Counter_Mode
+*/
 
 #include "../../../crypto.h"
 
 
+/** MAC info about the GHASH algorithm */
 const fastd_mac_info_t fastd_mac_info_ghash = {
 	.key_length = 16,
 };
diff --git a/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.c b/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.c
index e335a82..5d5977a 100644
--- a/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.c
+++ b/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.c
@@ -23,17 +23,25 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   PCLMULQDQ-based GHASH implementation for newer x86 systems
+*/
+
 
 #include "ghash_pclmulqdq.h"
 #include "../../../../cpuid.h"
 
 
+/** Checks if the runtime platform can support the PCLMULQDQ implementation */
 static bool ghash_available(void) {
 	static const uint64_t REQ = CPUID_FXSR|CPUID_SSSE3|CPUID_PCLMULQDQ;
 
 	return ((fastd_cpuid()&REQ) == REQ);
 }
 
+/** The pclmulqdq ghash implementation */
 const fastd_mac_t fastd_mac_ghash_pclmulqdq = {
 	.available = ghash_available,
 
diff --git a/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.h b/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.h
index c2cf4e3..51ef5da 100644
--- a/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.h
+++ b/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.h
@@ -23,6 +23,12 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   PCLMULQDQ-based GHASH implementation for newer x86 systems
+*/
+
 
 #pragma once
 
diff --git a/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq_impl.c b/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq_impl.c
index 9dc0a32..49c036a 100644
--- a/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq_impl.c
+++ b/src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq_impl.c
@@ -23,6 +23,12 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   PCLMULQDQ-based GHASH implementation for newer x86 systems: implementation
+*/
+
 
 #include "ghash_pclmulqdq.h"
 #include <wmmintrin.h>
@@ -30,16 +36,19 @@
 #include <tmmintrin.h>
 
 
+/** An union allowing easy access to a block as a SIMD vector and a fastd_block128_t */
 typedef union vecblock {
-	__m128i v;
-	fastd_block128_t b;
+	__m128i v;			/**< __m128i access */
+	fastd_block128_t b;		/**< fastd_block128_t access */
 } vecblock_t;
 
+/** The MAC state used by this GHASH implementation */
 struct fastd_mac_state {
-	vecblock_t H;
+	vecblock_t H;			/**< The hash key used by GHASH */
 };
 
 
+/** Left shift on a 128bit integer */
 static inline __m128i shl(__m128i v, int a) {
 	__m128i tmpl = _mm_slli_epi64(v, a);
 	__m128i tmpr = _mm_srli_epi64(v, 64-a);
@@ -48,6 +57,7 @@ static inline __m128i shl(__m128i v, int a) {
 	return _mm_xor_si128(tmpl, tmpr);
 }
 
+/** Right shift on a 128bit integer */
 static inline __m128i shr(__m128i v, int a) {
 	__m128i tmpr = _mm_srli_epi64(v, a);
 	__m128i tmpl = _mm_slli_epi64(v, 64-a);
@@ -56,13 +66,16 @@ static inline __m128i shr(__m128i v, int a) {
 	return _mm_xor_si128(tmpr, tmpl);
 }
 
+/** _mm_shuffle_epi8 parameter to reverse the bytes of a __m128i */
 static const __v16qi BYTESWAP_SHUFFLE = {15, 14, 13, 12, 11, 10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0};
 
+/** Reverses the order of the bytes of a __m128i */
 static inline __m128i byteswap(__m128i v) {
 	return _mm_shuffle_epi8(v, (__m128i)BYTESWAP_SHUFFLE);
 }
 
 
+/** Initializes the state used by this GHASH implementation */
 fastd_mac_state_t* fastd_ghash_pclmulqdq_init(const uint8_t *key) {
 	fastd_mac_state_t *state;
 	if (posix_memalign((void**)&state, 16, sizeof(fastd_mac_state_t)))
@@ -74,6 +87,7 @@ fastd_mac_state_t* fastd_ghash_pclmulqdq_init(const uint8_t *key) {
 	return state;
 }
 
+/** Frees the state used by this GHASH implementation */
 void fastd_ghash_pclmulqdq_free(fastd_mac_state_t *state) {
 	if (state) {
 		secure_memzero(state, sizeof(*state));
@@ -81,6 +95,7 @@ void fastd_ghash_pclmulqdq_free(fastd_mac_state_t *state) {
 	}
 }
 
+/** Performs a carryless multiplication of two 128bit integers modulo \f$ x^{128} + x^7 + x^2 + x + 1 \f$ */
 static __m128i gmul(__m128i v, __m128i h) {
 	/* multiply */
 	__m128i z0, z1, z2, tmp;
@@ -134,6 +149,7 @@ static __m128i gmul(__m128i v, __m128i h) {
 }
 
 
+/** Calculates the GHASH of the supplied input blocks */
 bool fastd_ghash_pclmulqdq_hash(const fastd_mac_state_t *state, fastd_block128_t *out, const fastd_block128_t *in, size_t n_blocks) {
 	vecblock_t v = {.v = _mm_setzero_si128()};
 
diff --git a/src/crypto/mac/macs.c.in b/src/crypto/mac/macs.c.in
index 0db26d9..5f9a353 100644
--- a/src/crypto/mac/macs.c.in
+++ b/src/crypto/mac/macs.c.in
@@ -23,6 +23,12 @@
   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
 
+/**
+   \file
+
+   Generated lists of MACs and their implementations
+*/
+
 
 #include <src/crypto.h>
 #include <src/fastd.h>
@@ -30,29 +36,35 @@
 
 @MAC_DEFINITIONS@
 
+/** A MAC implementation */
 typedef struct fastd_mac_impl {
-	const char *name;
-	const fastd_mac_t *impl;
+	const char *name;			/**< The name of the MAC implementation */
+	const fastd_mac_t *impl;		/**< The MAC implementation */
 } fastd_mac_impl_t;
 
+/** A MAC */
 typedef struct mac_entry {
-	const char *name;
-	const fastd_mac_info_t *info;
-	const fastd_mac_impl_t *impls;
+	const char *name;			/**< The name of the MAC */
+	const fastd_mac_info_t *info;		/**< The associated MAC information */
+	const fastd_mac_impl_t *impls;		/**< NULL-terminated array of MAC implementations */
 } mac_entry_t;
 
 @MAC_IMPLS@
 
+/** The list of supported MACs */
 static const mac_entry_t macs[] = { @MAC_LIST@
 };
 
+/** The list of chosen MAC implementations */
 static const fastd_mac_t *mac_conf[array_size(macs)] = {};
 
 
+/** Checks if a MAC implementation is available on the runtime platform */
 static inline bool mac_available(const fastd_mac_t *mac) {
 	return (!mac->available) || mac->available();
 }
 
+/** Initializes the list of MAC implementations */
 void fastd_mac_init(void) {
 	size_t i, j;
 	for (i = 0; i < array_size(macs); i++) {
@@ -65,6 +77,7 @@ void fastd_mac_init(void) {
 	}
 }
 
+/** Configures a MAC to use a specific implementation */
 bool fastd_mac_config(const char *name, const char *impl) {
 	size_t i;
 	for (i = 0; i < array_size(macs); i++) {
@@ -87,6 +100,7 @@ bool fastd_mac_config(const char *name, const char *impl) {
 	return false;
 }
 
+/** Returns information about the MAC with the specified name if there is an implementation available */
 const fastd_mac_info_t* fastd_mac_info_get_by_name(const char *name) {
 	size_t i, j;
 	for (i = 0; i < array_size(macs); i++) {
@@ -102,6 +116,7 @@ const fastd_mac_info_t* fastd_mac_info_get_by_name(const char *name) {
 	return NULL;
 }
 
+/** Returns the chosen MAC implementation for a given cipher */
 const fastd_mac_t* fastd_mac_get(const fastd_mac_info_t *info) {
 	size_t i;
 	for (i = 0; i < array_size(macs); i++) {