From 144b8596db7b45e22448e63d115b9902c14259fd Mon Sep 17 00:00:00 2001 From: Egor Tensin Date: Fri, 12 Jun 2015 03:36:57 +0300 Subject: add function docs to parts of the library --- include/aesni/all.h | 6 + include/aesni/block.h | 332 +++++++++++++++++++++++++++++++++++++++++++++++++ include/aesni/buffer.h | 1 + include/aesni/data.h | 2 + include/aesni/error.h | 1 + include/aesni/raw.h | 115 +++++++++++++++++ 6 files changed, 457 insertions(+) (limited to 'include') diff --git a/include/aesni/all.h b/include/aesni/all.h index 4653eca..6f00fb7 100644 --- a/include/aesni/all.h +++ b/include/aesni/all.h @@ -4,10 +4,16 @@ * \date 2015 * \copyright This file is licensed under the terms of the MIT License. * See LICENSE.txt for details. + * \brief Include this file to use libaesni. + * Includes all of the other libaesni's header files. */ #pragma once +/** + * \defgroup aesni AesNI + */ + #include "block.h" #include "buffer.h" #include "data.h" diff --git a/include/aesni/block.h b/include/aesni/block.h index 0909744..37dfa65 100644 --- a/include/aesni/block.h +++ b/include/aesni/block.h @@ -4,10 +4,44 @@ * \date 2015 * \copyright This file is licensed under the terms of the MIT License. * See LICENSE.txt for details. + * \brief Declares 128-bit block encryption/decryption functions. */ #pragma once +/** + * \defgroup aesni_block_api Block API + * \brief 128-bit block encryption/decryption functions. + * \ingroup aesni + * \{ + * + * For each of AES-128/192/256, two functions are defined: + * + * * a key schedule "expansion" function to prepare for encryption, + * * a key schedule "reversion" function to prepare for decryption. + * + * The functions, respectively, are: + * + * * `aesni_expand_key_scheduleNNN`, + * * `aesni_reverse_key_scheduleNNN`, + * + * where `NNN` is either `128`, `192` or `256`. + * + * For each of AES-128/192/256 and modes of operation ECB, CBC, CFB, OFB, and + * CTR, two functions are defined: + * + * * a 128-bit block encryption function, + * * a 128-bit block decryption function. + * + * The functions, respectively, are: + * + * * `aesni_encrypt_block_XXXNNN`, + * * `aesni_decrypt_block_XXXNNN`, + * + * where `XXX` is either `ecb`, `cbc`, `cfb`, `ofb` or `ctr`, and `NNN` is + * either `128`, `192` or `256`. + */ + #include "data.h" #include "raw.h" @@ -18,6 +52,12 @@ extern "C" { #endif +/** + * Expands a key schedule for AES-128 encryption. + * + * \param[in] key The AES-128 key. + * \param[out] key_schedule The AES-128 encryption key schedule. Must not be `NULL`. + */ static __inline void __fastcall aesni_expand_key_schedule128( AesNI_Block128 key, AesNI_KeySchedule128* key_schedule) @@ -27,6 +67,12 @@ static __inline void __fastcall aesni_expand_key_schedule128( aesni_raw_expand_key_schedule128(key, key_schedule); } +/** + * "Reverses" a key schedule for AES-128 "equivalent inverse cipher" decryption. + * + * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`. + * \param[out] inverted_schedule The AES-128 decryption key schedule. Must not be `NULL`. + */ static __inline void __fastcall aesni_invert_key_schedule128( AesNI_KeySchedule128* key_schedule, AesNI_KeySchedule128* inverted_schedule) @@ -37,6 +83,13 @@ static __inline void __fastcall aesni_invert_key_schedule128( aesni_raw_invert_key_schedule128(key_schedule, inverted_schedule); } +/** + * Encrypts a 128-bit block using AES-128 in ECB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-128 encryption schedule. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb128( AesNI_Block128 plain, AesNI_KeySchedule128* key_schedule) @@ -46,6 +99,13 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb128( return aesni_raw_encrypt_block128(plain, key_schedule); } +/** + * Decrypts a 128-bit block using AES-128 in ECB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-128 decryption ("reversed") key schedule. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb128( AesNI_Block128 cipher, AesNI_KeySchedule128* inverted_schedule) @@ -55,6 +115,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb128( return aesni_raw_decrypt_block128(cipher, inverted_schedule); } +/** + * Encrypts a 128-bit block using AES-128 in CBC mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`. + * \param[in] init_vector The CBC initialization vector. + * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc128( AesNI_Block128 plain, AesNI_KeySchedule128* key_schedule, @@ -69,6 +138,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc128( return cipher; } +/** + * Decrypts a 128-bit block using AES-128 in CBC mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-128 decryption (reversed) key schedule. Must not be `NULL`. + * \param[in] init_vector The CBC initialization vector. + * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc128( AesNI_Block128 cipher, AesNI_KeySchedule128* inverted_schedule, @@ -83,6 +161,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc128( return plain; } +/** + * Encrypts a 128-bit block using AES-128 in CFB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-128 encryption schedule. Must not be `NULL`. + * \param[in] init_vector The CFB initialization vector. + * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb128( AesNI_Block128 plain, AesNI_KeySchedule128* key_schedule, @@ -97,6 +184,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb128( return cipher; } +/** + * Decrypts a 128-bit block using AES-128 in CFB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-128 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The CFB initialization vector. + * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb128( AesNI_Block128 cipher, AesNI_KeySchedule128* key_schedule, @@ -111,6 +207,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb128( return plain; } +/** + * Encrypts a 128-bit block using AES-128 in OFB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-128 encryption schedule. Must not be `NULL`. + * \param[in] init_vector The OFB initialization vector. + * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb128( AesNI_Block128 plain, AesNI_KeySchedule128* key_schedule, @@ -125,6 +230,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb128( return _mm_xor_si128(tmp, plain); } +/** + * Decrypts a 128-bit block using AES-128 in OFB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-128 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The OFB initialization vector. + * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb128( AesNI_Block128 cipher, AesNI_KeySchedule128* key_schedule, @@ -139,6 +253,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb128( return _mm_xor_si128(tmp, cipher); } +/** + * Encrypts a 128-bit block using AES-128 in CTR mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`. + * \param[in] init_vector The CTR initialization vector. + * \param[in] counter The counter, typically incremented between consecutive calls. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr128( AesNI_Block128 plain, AesNI_KeySchedule128* key_schedule, @@ -153,6 +276,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr128( return _mm_xor_si128(plain, aesni_raw_encrypt_block128(init_vector, key_schedule)); } +/** + * Decrypts a 128-bit block using AES-128 in CTR mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-128 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The CTR initialization vector. + * \param[in] counter The counter, typically incremented between consecutive calls. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr128( AesNI_Block128 cipher, AesNI_KeySchedule128* key_schedule, @@ -167,6 +299,12 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr128( return _mm_xor_si128(cipher, aesni_raw_encrypt_block128(init_vector, key_schedule)); } +/** + * Expands a key schedule for AES-192 encryption. + * + * \param[in] key The AES-192 key. Must not be `NULL`. + * \param[out] key_schedule The AES-192 encryption key schedule. Must not be `NULL`. + */ static __inline void __fastcall aesni_expand_key_schedule192( AesNI_Block192* key, AesNI_KeySchedule192* key_schedule) @@ -177,6 +315,12 @@ static __inline void __fastcall aesni_expand_key_schedule192( aesni_raw_expand_key_schedule192(key->lo, key->hi, key_schedule); } +/** + * "Reverses" a key schedule for AES-192 "equivalent inverse cipher" decryption. + * + * \param[in] key_schedule The AES-192 encryption key schedule. Must not be `NULL`. + * \param[out] inverted_schedule The AES-192 decryption key schedule. Must not be `NULL`. + */ static __inline void __fastcall aesni_invert_key_schedule192( AesNI_KeySchedule192* key_schedule, AesNI_KeySchedule192* inverted_schedule) @@ -187,6 +331,13 @@ static __inline void __fastcall aesni_invert_key_schedule192( aesni_raw_invert_key_schedule192(key_schedule, inverted_schedule); } +/** + * Encrypts a 128-bit block using AES-192 in ECB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-192 encryption schedule. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb192( AesNI_Block128 plain, AesNI_KeySchedule192* key_schedule) @@ -196,6 +347,13 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb192( return aesni_raw_encrypt_block192(plain, key_schedule); } +/** + * Decrypts a 128-bit block using AES-192 in ECB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-192 decryption (reversed) key schedule. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb192( AesNI_Block128 cipher, AesNI_KeySchedule192* inverted_schedule) @@ -205,6 +363,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb192( return aesni_raw_decrypt_block192(cipher, inverted_schedule); } +/** + * Encrypts a 128-bit block using AES-192 in CBC mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-192 encryption schedule. Must not be `NULL`. + * \param[in] init_vector The CBC initialization vector. + * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc192( AesNI_Block128 plain, AesNI_KeySchedule192* key_schedule, @@ -219,6 +386,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc192( return cipher; } +/** + * Decrypts a 128-bit block using AES-192 in CBC mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-192 decryption (reversed) key schedule. Must not be `NULL`. + * \param[in] init_vector The CBC initialization vector. + * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc192( AesNI_Block128 cipher, AesNI_KeySchedule192* inverted_schedule, @@ -233,6 +409,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc192( return plain; } +/** + * Encrypts a 128-bit block using AES-192 in CFB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-192 encryption schedule. Must not be `NULL`. + * \param[in] init_vector The CFB initialization vector. + * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb192( AesNI_Block128 plain, AesNI_KeySchedule192* key_schedule, @@ -247,6 +432,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb192( return cipher; } +/** + * Decrypts a 128-bit block using AES-192 in CFB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-192 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The CFB initialization vector. + * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb192( AesNI_Block128 cipher, AesNI_KeySchedule192* key_schedule, @@ -261,6 +455,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb192( return plain; } +/** + * Encrypts a 128-bit block using AES-192 in OFB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-192 encryption schedule. Must not be `NULL`. + * \param[in] init_vector The OFB initialization vector. + * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb192( AesNI_Block128 plain, AesNI_KeySchedule192* key_schedule, @@ -275,6 +478,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb192( return _mm_xor_si128(tmp, plain); } +/** + * Decrypts a 128-bit block using AES-192 in OFB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-192 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The OFB initialization vector. + * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb192( AesNI_Block128 cipher, AesNI_KeySchedule192* key_schedule, @@ -289,6 +501,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb192( return _mm_xor_si128(tmp, cipher); } +/** + * Encrypts a 128-bit block using AES-192 in CTR mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-192 encryption key schedule. Must not be `NULL`. + * \param[in] init_vector The CTR initialization vector. + * \param[in] counter The counter, typically incremented between consecutive calls. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr192( AesNI_Block128 plain, AesNI_KeySchedule192* key_schedule, @@ -303,6 +524,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr192( return _mm_xor_si128(plain, aesni_raw_encrypt_block192(init_vector, key_schedule)); } +/** + * Decrypts a 128-bit block using AES-192 in CTR mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-192 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The CTR initialization vector. + * \param[in] counter The counter, typically incremented between consecutive calls. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr192( AesNI_Block128 cipher, AesNI_KeySchedule192* key_schedule, @@ -317,6 +547,12 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr192( return _mm_xor_si128(cipher, aesni_raw_encrypt_block192(init_vector, key_schedule)); } +/** + * Expands a key schedule for AES-256 encryption. + * + * \param[in] key The AES-256 key. Must not be `NULL`. + * \param[out] key_schedule The AES-256 encryption key schedule. Must not be `NULL`. + */ static __inline void __fastcall aesni_expand_key_schedule256( AesNI_Block256* key, AesNI_KeySchedule256* key_schedule) @@ -327,6 +563,12 @@ static __inline void __fastcall aesni_expand_key_schedule256( aesni_raw_expand_key_schedule256(key->lo, key->hi, key_schedule); } +/** + * "Reverses" a key schedule for AES-256 "equivalent inverse cipher" decryption. + * + * \param[in] key_schedule The AES-256 encryption key schedule. Must not be `NULL`. + * \param[out] inverted_schedule The AES-256 decryption key schedule. Must not be `NULL`. + */ static __inline void __fastcall aesni_invert_key_schedule256( AesNI_KeySchedule256* key_schedule, AesNI_KeySchedule256* inverted_schedule) @@ -337,6 +579,13 @@ static __inline void __fastcall aesni_invert_key_schedule256( aesni_raw_invert_key_schedule256(key_schedule, inverted_schedule); } +/** + * Encrypts a 128-bit block using AES-256 in ECB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-256 encryption schedule. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb256( AesNI_Block128 plain, AesNI_KeySchedule256* key_schedule) @@ -346,6 +595,13 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ecb256( return aesni_raw_encrypt_block256(plain, key_schedule); } +/** + * Decrypts a 128-bit block using AES-256 in ECB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-256 decryption (reversed) key schedule. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb256( AesNI_Block128 cipher, AesNI_KeySchedule256* inverted_schedule) @@ -355,6 +611,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ecb256( return aesni_raw_decrypt_block256(cipher, inverted_schedule); } +/** + * Encrypts a 128-bit block using AES-256 in CBC mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-256 encryption schedule. Must not be `NULL`. + * \param[in] init_vector The CBC initialization vector. + * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc256( AesNI_Block128 plain, AesNI_KeySchedule256* key_schedule, @@ -369,6 +634,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cbc256( return cipher; } +/** + * Decrypts a 128-bit block using AES-256 in CBC mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-256 decryption (reversed) key schedule. Must not be `NULL`. + * \param[in] init_vector The CBC initialization vector. + * \param[out] next_init_vector The next CBC initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc256( AesNI_Block128 cipher, AesNI_KeySchedule256* inverted_schedule, @@ -383,6 +657,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cbc256( return plain; } +/** + * Encrypts a 128-bit block using AES-256 in CFB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-256 encryption schedule. Must not be `NULL`. + * \param[in] init_vector The CFB initialization vector. + * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb256( AesNI_Block128 plain, AesNI_KeySchedule256* key_schedule, @@ -397,6 +680,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_cfb256( return cipher; } +/** + * Decrypts a 128-bit block using AES-256 in CFB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-256 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The CFB initialization vector. + * \param[out] next_init_vector The next CFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb256( AesNI_Block128 cipher, AesNI_KeySchedule256* key_schedule, @@ -411,6 +703,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_cfb256( return plain; } +/** + * Encrypts a 128-bit block using AES-256 in OFB mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-256 encryption schedule. Must not be `NULL`. + * \param[in] init_vector The OFB initialization vector. + * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb256( AesNI_Block128 plain, AesNI_KeySchedule256* key_schedule, @@ -425,6 +726,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ofb256( return _mm_xor_si128(tmp, plain); } +/** + * Decrypts a 128-bit block using AES-256 in OFB mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-256 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The OFB initialization vector. + * \param[out] next_init_vector The next OFB initialization vector to be used as the initialization vector for the next call. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb256( AesNI_Block128 cipher, AesNI_KeySchedule256* key_schedule, @@ -439,6 +749,15 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ofb256( return _mm_xor_si128(tmp, cipher); } +/** + * Encrypts a 128-bit block using AES-256 in CTR mode of operation. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-256 encryption key schedule. Must not be `NULL`. + * \param[in] init_vector The CTR initialization vector. + * \param[in] counter The counter, typically incremented between consecutive calls. + * \return The encrypted 128-bit ciphertext. + */ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr256( AesNI_Block128 plain, AesNI_KeySchedule256* key_schedule, @@ -453,6 +772,15 @@ static __inline AesNI_Block128 __fastcall aesni_encrypt_block_ctr256( return _mm_xor_si128(plain, aesni_raw_encrypt_block256(init_vector, key_schedule)); } +/** + * Decrypts a 128-bit block using AES-256 in CTR mode of operation. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] key_schedule The AES-256 **encryption** key schedule. Must not be `NULL`. + * \param[in] init_vector The CTR initialization vector. + * \param[in] counter The counter, typically incremented between consecutive calls. + * \return The decrypted 128-bit plaintext. + */ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr256( AesNI_Block128 cipher, AesNI_KeySchedule256* key_schedule, @@ -470,3 +798,7 @@ static __inline AesNI_Block128 __fastcall aesni_decrypt_block_ctr256( #ifdef __cplusplus } #endif + +/** + * \} + */ diff --git a/include/aesni/buffer.h b/include/aesni/buffer.h index 13f19da..6222f4f 100644 --- a/include/aesni/buffer.h +++ b/include/aesni/buffer.h @@ -4,6 +4,7 @@ * \date 2015 * \copyright This file is licensed under the terms of the MIT License. * See LICENSE.txt for details. + * \brief Declares variable-length buffer encryption/decryption functions. */ #pragma once diff --git a/include/aesni/data.h b/include/aesni/data.h index de03110..4de3c0e 100644 --- a/include/aesni/data.h +++ b/include/aesni/data.h @@ -4,6 +4,8 @@ * \date 2015 * \copyright This file is licensed under the terms of the MIT License. * See LICENSE.txt for details. + * \brief Declares necessary data structures (for blocks, keys, etc.) + * and auxiliary IO functions. */ #pragma once diff --git a/include/aesni/error.h b/include/aesni/error.h index 47bd0d6..91bf168 100644 --- a/include/aesni/error.h +++ b/include/aesni/error.h @@ -4,6 +4,7 @@ * \date 2015 * \copyright This file is licensed under the terms of the MIT License. * See LICENSE.txt for details. + * \brief Declares error codes, error formatting functions, etc. */ #pragma once diff --git a/include/aesni/raw.h b/include/aesni/raw.h index 4432231..2a1902e 100644 --- a/include/aesni/raw.h +++ b/include/aesni/raw.h @@ -4,10 +4,35 @@ * \date 2015 * \copyright This file is licensed under the terms of the MIT License. * See LICENSE.txt for details. + * \brief *Don't use.* Declares "raw" 128-bit block encryption/decryption + * functions. */ #pragma once +/** + * \defgroup aesni_raw_api Raw API + * \brief *Don't use.* "Raw" 128-bit block encryption/decryption functions. + * \ingroup aesni + * \{ + * + * For each of AES-128/192/256, four functions are defined: + * + * * a key schedule "expansion" function to prepare for encryption, + * * a 128-bit block encryption function using the key schedule, + * * a key schedule "reversion" function to prepare for decryption, + * * a 128-bit block decryption function using the "inverted" key schedule. + * + * The functions, respectively, are: + * + * * `aesni_raw_expand_key_scheduleNNN`, + * * `aesni_raw_encrypt_blockNNN`, + * * `aesni_raw_invert_key_scheduleNNN`, + * * `aesni_raw_decrypt_blockNNN`, + * + * where `NNN` is key length (either `128`, `192` or `256`). + */ + #include "data.h" #ifdef __cplusplus @@ -15,46 +40,132 @@ extern "C" { #endif +/** + * Expands a key schedule for AES-128 encryption. + * + * \param[in] key The AES-128 key. + * \param[out] key_schedule The AES-128 encryption key schedule. Must not be `NULL`. + */ void __fastcall aesni_raw_expand_key_schedule128( AesNI_Block128 key, AesNI_KeySchedule128* key_schedule); + +/** + * "Reverses" a key schedule for AES-128 "equivalent inverse cipher" decryption. + * + * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`. + * \param[out] inverted_schedule The AES-128 decryption key schedule. Must not be `NULL`. + */ void __fastcall aesni_raw_invert_key_schedule128( AesNI_KeySchedule128* key_schedule, AesNI_KeySchedule128* inverted_schedule); +/** + * Encrypts a 128-bit block using AES-128. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-128 encryption key schedule. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ AesNI_Block128 __fastcall aesni_raw_encrypt_block128( AesNI_Block128 plain, AesNI_KeySchedule128* key_schedule); + +/** + * Decrypts a 128-bit block using AES-128. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-128 decryption ("reversed") key schedule. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ AesNI_Block128 __fastcall aesni_raw_decrypt_block128( AesNI_Block128 cipher, AesNI_KeySchedule128* inverted_schedule); +/** + * Expands a key schedule for AES-192 encryption. + * + * \param[in] key_lo The least significant part of the AES-192 key. + * \param[in] key_hi The most significant part of the AES-192 key. + * \param[out] key_schedule The AES-192 encryption key schedule. Must not be `NULL`. + */ void __fastcall aesni_raw_expand_key_schedule192( AesNI_Block128 key_lo, AesNI_Block128 key_hi, AesNI_KeySchedule192* key_schedule); + +/** + * "Reverses" a key schedule for AES-192 "equivalent inverse cipher" decryption. + * + * \param[in] key_schedule The AES-192 encryption key schedule. Must not be `NULL`. + * \param[out] inverted_schedule The AES-192 decryption key schedule. Must not be `NULL`. + */ void __fastcall aesni_raw_invert_key_schedule192( AesNI_KeySchedule192* key_schedule, AesNI_KeySchedule192* inverted_schedule); +/** + * Encrypts a 128-bit block using AES-192. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-192 encryption key schedule. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ AesNI_Block128 __fastcall aesni_raw_encrypt_block192( AesNI_Block128 plain, AesNI_KeySchedule192* key_schedule); + +/** + * Decrypts a 128-bit block using AES-192. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-192 decryption ("reversed") key schedule. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ AesNI_Block128 __fastcall aesni_raw_decrypt_block192( AesNI_Block128 cipher, AesNI_KeySchedule192* inverted_schedule); +/** + * Expands a key schedule for AES-256 encryption. + * + * \param[in] key_lo The least significant part of the AES-256 key. + * \param[in] key_hi The most significant part of the AES-256 key. + * \param[out] key_schedule The AES-256 encryption key schedule. Must not be `NULL`. + */ void __fastcall aesni_raw_expand_key_schedule256( AesNI_Block128 key_lo, AesNI_Block128 key_hi, AesNI_KeySchedule256* key_schedule); + +/** + * "Reverses" a key schedule for AES-256 "equivalent inverse cipher" decryption. + * + * \param[in] key_schedule The AES-256 encryption key schedule. Must not be `NULL`. + * \param[out] inverted_schedule The AES-256 decryption key schedule. Must not be `NULL`. + */ void __fastcall aesni_raw_invert_key_schedule256( AesNI_KeySchedule256* key_schedule, AesNI_KeySchedule256* inverted_schedule); +/** + * Encrypts a 128-bit block using AES-256. + * + * \param[in] plain The plaintext to be encrypted. + * \param[in] key_schedule The AES-256 encryption key schedule. Must not be `NULL`. + * \return The encrypted 128-bit ciphertext. + */ AesNI_Block128 __fastcall aesni_raw_encrypt_block256( AesNI_Block128 plain, AesNI_KeySchedule256* key_schedule); + +/** + * Decrypts a 128-bit block using AES-256. + * + * \param[in] cipher The ciphertext to be decrypted. + * \param[in] inverted_schedule The AES-256 decryption ("reversed") key schedule. Must not be `NULL`. + * \return The decrypted 128-bit plaintext. + */ AesNI_Block128 __fastcall aesni_raw_decrypt_block256( AesNI_Block128 cipher, AesNI_KeySchedule256* inverted_schedule); @@ -62,3 +173,7 @@ AesNI_Block128 __fastcall aesni_raw_decrypt_block256( #ifdef __cplusplus } #endif + +/** + * \} + */ -- cgit v1.2.3