| 1 |
|
| 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 |
|
| 19 | struct aes_enckey aes;
|
| 20 | struct ghash_key ghash;
|
| 21 | size_t authtag_len;
|
| 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 |
|
| 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 |
|
| 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 |
|
| 61 | u8 keystream[AES_BLOCK_SIZE] __aligned(__alignof__(long));
|
| 62 |
|
| 63 | u8 j0_enc[AES_BLOCK_SIZE] __aligned(__alignof__(long));
|
| 64 |
|
| 65 | u64 ad_len;
|
| 66 |
|
| 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
|