From 2fe678653b7dd9f61dbbcd5e7d862360882bd7e8 Mon Sep 17 00:00:00 2001 From: Matthias Schiffer Date: Thu, 29 May 2014 05:00:11 +0200 Subject: Document *everything* --- src/crypto/cipher/aes128_ctr/aes128_ctr.c | 7 ++++++ .../aes128_ctr/nacl/cipher_aes128_ctr_nacl.c | 14 +++++++++++- .../cipher/aes128_ctr/openssl/aes128_ctr_openssl.c | 14 +++++++++++- src/crypto/cipher/ciphers.c.in | 25 ++++++++++++++++------ src/crypto/cipher/null/memcpy/null_memcpy.c | 10 +++++++++ src/crypto/cipher/null/null.c | 7 ++++++ src/crypto/cipher/salsa20/nacl/salsa20_nacl.c | 14 +++++++++++- src/crypto/cipher/salsa20/salsa20.c | 7 ++++++ src/crypto/cipher/salsa20/xmm/salsa20_xmm.c | 22 +++++++++++++++---- src/crypto/cipher/salsa2012/nacl/salsa2012_nacl.c | 14 +++++++++++- src/crypto/cipher/salsa2012/salsa2012.c | 7 ++++++ src/crypto/cipher/salsa2012/xmm/salsa2012_xmm.c | 22 +++++++++++++++---- src/crypto/mac/ghash/builtin/ghash_builtin.c | 16 +++++++++++++- src/crypto/mac/ghash/ghash.c | 8 +++++++ src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.c | 8 +++++++ src/crypto/mac/ghash/pclmulqdq/ghash_pclmulqdq.h | 6 ++++++ .../mac/ghash/pclmulqdq/ghash_pclmulqdq_impl.c | 22 ++++++++++++++++--- src/crypto/mac/macs.c.in | 25 +++++++++++++++++----- 18 files changed, 221 insertions(+), 27 deletions(-) (limited to 'src/crypto') 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 +/** 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 +/** 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 #include @@ -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 +/** 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 +/** 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 @@ -30,16 +36,19 @@ #include +/** 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 #include @@ -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++) { -- cgit v1.2.3