1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* 3 * AES-GCM authenticated encryption and decryption 4 * 5 * Copyright 2026 Google LLC 6 */ 7 #ifndef _CRYPTO_AES_GCM_H 8 #define _CRYPTO_AES_GCM_H 9 10 #include <crypto/aes.h> 11 #include <crypto/gcm.h> 12 #include <crypto/gf128hash.h> 13 14 /** 15 * struct aes_gcm_key - A key prepared for AES-GCM encryption and decryption 16 */ 17 struct aes_gcm_key { 18 /* private: */ 19 struct aes_enckey aes; 20 struct ghash_key ghash; 21 size_t authtag_len; /* Length of authentication tags in bytes */ 22 }; 23 24 /** 25 * struct aes_gcm_ctx - Context for incrementally en/decrypting a message 26 */ 27 struct aes_gcm_ctx { 28 /* private: */ 29 /* 30 * Pointer to the key, which is assumed to live at least as long as this 31 * struct. 32 */ 33 const struct aes_gcm_key *key; 34 /* The current GHASH context */ 35 struct ghash_ctx ghash; 36 /* 37 * The current counter. This can be viewed as either a 128-bit big 38 * endian counter, or as a 96-bit nonce followed by a 32-bit big endian 39 * counter; it doesn't matter, since the last 32-bit word starts at 1, 40 * and AES-GCM is undefined for messages that would overflow that part. 41 * In practice this means that code optimized for AES-GCM can just 42 * increment the last 32-bit word (wrapping at 2^32), but when needed it 43 * can still call AES-CTR code that does a 128-bit increment. 44 * 45 * 'long' alignment is for crypto_xor() to work more efficiently. 46 */ 47 union { 48 u8 ctr[AES_BLOCK_SIZE]; 49 __be32 ctr32[AES_BLOCK_SIZE / 4]; 50 } __aligned(__alignof__(long)); 51 /* Buffered keystream for partial block updates */ 52 u8 keystream[AES_BLOCK_SIZE] __aligned(__alignof__(long)); 53 /* Encrypted counter of 1. This gets XOR'ed with the tag at the end. */ 54 u8 j0_enc[AES_BLOCK_SIZE] __aligned(__alignof__(long)); 55 /* Number of associated data bytes processed so far */ 56 u64 ad_len; 57 /* Number of en/decrypted bytes processed so far */ 58 u64 data_len; 59 }; 60 61 /** 62 * aes_gcm_preparekey() - Prepare a key for AES-GCM encryption and decryption 63 * @key: (output) The key structure to initialize 64 * @in_key: The raw AES-GCM key 65 * @key_len: Length of the raw key in bytes: 16, 24, or 32 66 * @authtag_len: Length of the authentication tag in bytes: 67 * 4, 8, 12, 13, 14, 15, or 16. 16 is recommended. 68 * 69 * Users should use memzero_explicit() to zeroize the key struct at the end of 70 * its lifetime. (But if this function fails, zeroization is unnecessary.) 71 * 72 * Context: Any context. 73 * Return: 74 * * 0 on success 75 * * -EINVAL if either of the lengths is invalid 76 */ 77 int __must_check aes_gcm_preparekey(struct aes_gcm_key *key, const u8 *in_key, 78 size_t key_len, size_t authtag_len); 79 80 /** 81 * aes_gcm_encrypt() - Encrypt a message with AES-GCM 82 * @dst: The destination ciphertext data. Can be in-place or out-of-place. 83 * For other overlaps the behavior is unspecified. 84 * @src: The source plaintext data 85 * @data_len: Length of plaintext in bytes (and ciphertext excluding the tag): 86 * at most 2^36 - 32 87 * @authtag: The output authentication tag. Length is the authtag_len that was 88 * passed to aes_gcm_preparekey(). Usually protocols using AES-GCM 89 * put the tag at the end of the ciphertext, in which case this should 90 * be set to @dst + @data_len and @dst must have room for the tag. 91 * @ad: The associated data 92 * @ad_len: Length of associated data in bytes: at most 2^61 - 1 93 * @nonce: The 12-byte nonce. All (key, nonce) pairs used MUST be distinct. 94 * @key: The key, already prepared using aes_gcm_preparekey() 95 * 96 * For AES-GMAC (i.e., AES-GCM without any data en/decrypted), use dst=NULL, 97 * src=NULL, and data_len=0 to generate the AES-GMAC value. 98 * 99 * Context: Any context. 100 */ 101 void aes_gcm_encrypt(u8 *dst, const u8 *src, size_t data_len, u8 *authtag, 102 const u8 *ad, size_t ad_len, const u8 nonce[at_least 12], 103 const struct aes_gcm_key *key); 104 105 /** 106 * aes_gcm_decrypt() - Decrypt a message with AES-GCM 107 * @dst: The destination plaintext data. Can be in-place or out-of-place. 108 * For other overlaps the behavior is unspecified. 109 * @src: The source ciphertext data 110 * @data_len: Length of plaintext in bytes (and ciphertext excluding the tag): 111 * at most 2^36 - 32 112 * @authtag: The stored authentication tag. Length is the authtag_len that was 113 * passed to aes_gcm_preparekey(). Usually protocols using AES-GCM 114 * put the tag at the end of the ciphertext, in which case this should 115 * be set to @src + @data_len and @src must have room for the tag. 116 * @ad: The associated data 117 * @ad_len: Length of associated data in bytes: at most 2^61 - 1 118 * @nonce: The 12-byte nonce 119 * @key: The key, already prepared using aes_gcm_preparekey() 120 * 121 * For AES-GMAC (i.e., AES-GCM without any data en/decrypted), use dst=NULL, 122 * src=NULL, and data_len=0 to verify the AES-GMAC value. 123 * 124 * Context: Any context. 125 * Return: 126 * * 0 on success. This is the only case where any decrypted or associated data 127 * can be used. 128 * * -EBADMSG if the message is inauthentic 129 */ 130 int __must_check aes_gcm_decrypt(u8 *dst, const u8 *src, size_t data_len, 131 const u8 *authtag, const u8 *ad, size_t ad_len, 132 const u8 nonce[at_least 12], 133 const struct aes_gcm_key *key); 134 135 /** 136 * aes_gcm_init() - Initialize context for incremental AES-GCM encryption or 137 * decryption, or for AES-GMAC computation 138 * @ctx: The context to initialize 139 * @nonce: The 12-byte nonce. All (key, nonce) pairs used for encryption or MAC 140 * generation MUST be distinct. 141 * @key: The key, already prepared using aes_gcm_preparekey(). Note that a 142 * pointer to the key is saved in the context, so the key must live at 143 * least as long as the context. 144 * 145 * The context should be zeroized at the end of its lifetime. Normally that 146 * happens in aes_gcm_encrypt_final() or aes_gcm_decrypt_final(), but callers 147 * that abandon a context without finalizing it should explicitly zeroize it. 148 * 149 * IMPORTANT: Callers that are decrypting data or computing a GMAC value for 150 * verification MUST NOT assume that any decrypted or associated data is 151 * authentic until the authentication tag has been verified. This incremental 152 * API is provided solely to support callers that can't efficiently use the 153 * one-shot functions due to using a nonlinear data layout. 154 * 155 * For incremental AES-GCM encryption, use: 156 * 157 * 1. aes_gcm_init() 158 * 2. aes_gcm_auth_update() (any number of times) 159 * 3. aes_gcm_encrypt_update() (any number of times) 160 * 4. aes_gcm_encrypt_final() 161 * 162 * For incremental AES-GCM decryption, use: 163 * 164 * 1. aes_gcm_init() 165 * 2. aes_gcm_auth_update() (any number of times) 166 * 3. aes_gcm_decrypt_update() (any number of times) 167 * 4. aes_gcm_decrypt_final() 168 * 169 * AES-GMAC is just AES-GCM with zero bytes en/decrypted. For incremental 170 * AES-GMAC computation, use: 171 * 172 * 1. aes_gcm_init() 173 * 2. aes_gcm_auth_update() (any number of times) 174 * 3. aes_gcm_encrypt_final() to return the computed tag to the caller, or 175 * aes_gcm_decrypt_final() to directly verify the computed tag 176 * 177 * Context: Any context. 178 */ 179 void aes_gcm_init(struct aes_gcm_ctx *ctx, const u8 nonce[at_least 12], 180 const struct aes_gcm_key *key); 181 182 /** 183 * aes_gcm_auth_update() - Incrementally process AES-GCM associated data 184 * @ctx: An AES-GCM context 185 * @ad: The associated data 186 * @len: Number of bytes provided. The caller must ensure that the total 187 * associated data length doesn't exceed GCM's limit of 2^61 - 1. 188 * 189 * IMPORTANT: Callers MUST NOT assume that any decrypted or associated data is 190 * authentic until the authentication tag has been verified. 191 * 192 * Context: Any context. 193 */ 194 void aes_gcm_auth_update(struct aes_gcm_ctx *ctx, const u8 *ad, size_t len); 195 196 /** 197 * aes_gcm_encrypt_update() - Incrementally encrypt data with AES-GCM 198 * @ctx: An AES-GCM context 199 * @dst: The destination buffer. Can be in-place or out-of-place. For other 200 * overlaps the behavior is unspecified. 201 * @src: The source plaintext data 202 * @len: Number of bytes to encrypt. The caller must ensure that the total 203 * number of bytes encrypted doesn't exceed GCM's limit of 2^36 - 32. 204 * 205 * This can be called only after all associated data has been processed. 206 * 207 * Context: Any context. 208 */ 209 void aes_gcm_encrypt_update(struct aes_gcm_ctx *ctx, u8 *dst, const u8 *src, 210 size_t len); 211 212 /** 213 * aes_gcm_decrypt_update() - Incrementally decrypt data with AES-GCM 214 * @ctx: An AES-GCM context 215 * @dst: The destination buffer. Can be in-place or out-of-place. For other 216 * overlaps the behavior is unspecified. 217 * @src: The source ciphertext data (not including auth tag) 218 * @len: Number of bytes to decrypt. The caller must ensure that the total 219 * number of bytes decrypted doesn't exceed GCM's limit of 2^36 - 32. 220 * 221 * This can be called only after all associated data has been processed. 222 * 223 * IMPORTANT: Callers MUST NOT assume that any decrypted or associated data is 224 * authentic until the authentication tag has been verified. 225 * 226 * Context: Any context. 227 */ 228 void aes_gcm_decrypt_update(struct aes_gcm_ctx *ctx, u8 *dst, const u8 *src, 229 size_t len); 230 231 /** 232 * aes_gcm_encrypt_final() - Finish encrypting a message with AES-GCM 233 * @ctx: An AES-GCM context 234 * @authtag: The output authentication tag. Length is the authtag_len that was 235 * passed to aes_gcm_preparekey(). 236 * 237 * This also zeroizes @ctx, so the caller doesn't need to do it. 238 * 239 * Context: Any context. 240 */ 241 void aes_gcm_encrypt_final(struct aes_gcm_ctx *ctx, u8 *authtag); 242 243 /** 244 * aes_gcm_decrypt_final() - Finish decrypting a message with AES-GCM 245 * @ctx: An AES-GCM context 246 * @authtag: The stored authentication tag. Length is the authtag_len that was 247 * passed to aes_gcm_preparekey(). 248 * 249 * This also zeroizes @ctx, so the caller doesn't need to do it. 250 * 251 * Context: Any context. 252 * Return: 253 * * 0 on success. This is the only case where any decrypted or associated data 254 * can be used. 255 * * -EBADMSG if the message is inauthentic 256 */ 257 int __must_check aes_gcm_decrypt_final(struct aes_gcm_ctx *ctx, 258 const u8 *authtag); 259 260 #endif /* _CRYPTO_AES_GCM_H */ 261