projects/linux·blob master · refs

278 lines · 10.2 KiB

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 */
17struct 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 */
28static 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 */
36struct 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 */
74static 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 */
95int __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 */
119void 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 */
148int __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 */
197void 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 */
212void 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 */
227void 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 */
246void 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 */
259void 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 */
275int __must_check aes_gcm_decrypt_final(struct aes_gcm_ctx *ctx,
276 const u8 *authtag);
277
278#endif /* _CRYPTO_AES_GCM_H */