AES-128-GCM.h (3808B)
1 /* 2 * AES-128-GCM.h - AES-128-GCM Interface 3 * 4 * Compliant with: 5 * - FIPS 197 (AES) 6 * - NIST SP 800-38D (GCM) 7 * 8 * Security Features: 9 * - Hardware acceleration (AES-NI + PCLMULQDQ) 10 * - Constant-time tag comparison 11 * - Authenticated encryption 12 * - 128-bit key size 13 * - 96-bit IV (recommended) 14 * - 128-bit authentication tag 15 */ 16 17 #ifndef AES_128_GCM_H 18 #define AES_128_GCM_H 19 20 #include <stdint.h> 21 #include <stdlib.h> 22 #include <immintrin.h> 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /* AES-128 uses 10 rounds */ 29 #define AES128_ROUNDS 10 30 #define AES128_KEY_SIZE 16 31 #define AES_BLOCK_SIZE 16 32 #define GCM_IV_SIZE 12 33 #define GCM_TAG_SIZE 16 34 35 /* AES-128 key schedule structure */ 36 typedef struct { 37 __m128i round_keys[AES128_ROUNDS + 1]; 38 int nr; /* Number of rounds */ 39 } aes128_key_schedule; 40 41 /* AES-128-GCM context */ 42 typedef struct { 43 aes128_key_schedule key_schedule; 44 __m128i H; /* Hash subkey */ 45 __m128i H_powers[8]; /* Precomputed powers of H for performance */ 46 } aes128_gcm_context; 47 48 /** 49 * Initialize AES-128-GCM context 50 * 51 * @param ctx Pointer to context structure 52 * @param key 128-bit (16 byte) encryption key 53 * @return 0 on success, -1 on error 54 * 55 * Security: Requires AES-NI and PCLMULQDQ CPU support 56 */ 57 int aes128_gcm_init(aes128_gcm_context *ctx, const uint8_t *key); 58 59 /** 60 * AES-128-GCM Encryption 61 * 62 * @param ctx Initialized context 63 * @param iv Initialization vector (recommended 12 bytes) 64 * @param iv_len IV length in bytes (12 recommended, others supported) 65 * @param aad Additional authenticated data (can be NULL) 66 * @param aad_len AAD length in bytes 67 * @param plaintext Input plaintext 68 * @param pt_len Plaintext length in bytes 69 * @param ciphertext Output ciphertext buffer (must be pt_len bytes) 70 * @param tag Output authentication tag (must be tag_len bytes) 71 * @param tag_len Tag length in bytes (1-16, recommend 16) 72 * @return 0 on success, -1 on error 73 * 74 * Security Notes: 75 * - NEVER reuse IV with the same key 76 * - Use random 96-bit IV for each encryption 77 * - Maximum plaintext: 2^36 - 32 bytes per key 78 * - Maximum AAD: 2^61 - 1 bytes 79 */ 80 int aes128_gcm_encrypt(aes128_gcm_context *ctx, 81 const uint8_t *iv, size_t iv_len, 82 const uint8_t *aad, size_t aad_len, 83 const uint8_t *plaintext, size_t pt_len, 84 uint8_t *ciphertext, 85 uint8_t *tag, size_t tag_len); 86 87 /** 88 * AES-128-GCM Decryption 89 * 90 * @param ctx Initialized context 91 * @param iv Initialization vector 92 * @param iv_len IV length in bytes 93 * @param aad Additional authenticated data (must match encryption) 94 * @param aad_len AAD length in bytes 95 * @param ciphertext Input ciphertext 96 * @param ct_len Ciphertext length in bytes 97 * @param tag Authentication tag from encryption 98 * @param tag_len Tag length in bytes 99 * @param plaintext Output plaintext buffer (must be ct_len bytes) 100 * @return 0 on success, -1 on authentication failure 101 * 102 * Security Notes: 103 * - Returns -1 if authentication tag doesn't match 104 * - Plaintext is NOT valid if function returns -1 105 * - Uses constant-time comparison for tag verification 106 * - MUST verify return value before using plaintext 107 */ 108 int aes128_gcm_decrypt(aes128_gcm_context *ctx, 109 const uint8_t *iv, size_t iv_len, 110 const uint8_t *aad, size_t aad_len, 111 const uint8_t *ciphertext, size_t ct_len, 112 const uint8_t *tag, size_t tag_len, 113 uint8_t *plaintext); 114 115 /** 116 * Clean up context (zeros sensitive data) 117 * 118 * @param ctx Context to clean 119 * 120 * Security: Call this to ensure key material is zeroed from memory 121 */ 122 void aes128_gcm_cleanup(aes128_gcm_context *ctx); 123 124 #ifdef __cplusplus 125 } 126 #endif 127 128 #endif /* AES_128_GCM_H */