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