1/**
2 * \file gcm.h
3 *
4 * \brief This file contains GCM definitions and functions.
5 *
6 * The Galois/Counter Mode (GCM) for 128-bit block ciphers is defined
7 * in <em>D. McGrew, J. Viega, The Galois/Counter Mode of Operation
8 * (GCM), Natl. Inst. Stand. Technol.</em>
9 *
10 * For more information on GCM, see <em>NIST SP 800-38D: Recommendation for
11 * Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em>.
12 *
13 */
14/*
15 * Copyright The Mbed TLS Contributors
16 * SPDX-License-Identifier: Apache-2.0
17 *
18 * Licensed under the Apache License, Version 2.0 (the "License"); you may
19 * not use this file except in compliance with the License.
20 * You may obtain a copy of the License at
21 *
22 * http://www.apache.org/licenses/LICENSE-2.0
23 *
24 * Unless required by applicable law or agreed to in writing, software
25 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
26 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
27 * See the License for the specific language governing permissions and
28 * limitations under the License.
29 */
30
31#ifndef MBEDTLS_GCM_H
32#define MBEDTLS_GCM_H
33
34#if !defined(MBEDTLS_CONFIG_FILE)
35#include "mbedtls/config.h"
36#else
37#include MBEDTLS_CONFIG_FILE
38#endif
39
40#include "mbedtls/cipher.h"
41
42#include <stdint.h>
43
44#define MBEDTLS_GCM_ENCRYPT 1
45#define MBEDTLS_GCM_DECRYPT 0
46
47/** Authenticated decryption failed. */
48#define MBEDTLS_ERR_GCM_AUTH_FAILED -0x0012
49
50/* MBEDTLS_ERR_GCM_HW_ACCEL_FAILED is deprecated and should not be used. */
51/** GCM hardware accelerator failed. */
52#define MBEDTLS_ERR_GCM_HW_ACCEL_FAILED -0x0013
53
54/** Bad input parameters to function. */
55#define MBEDTLS_ERR_GCM_BAD_INPUT -0x0014
56
57#ifdef __cplusplus
58extern "C" {
59#endif
60
61#if !defined(MBEDTLS_GCM_ALT)
62
63/**
64 * \brief The GCM context structure.
65 */
66typedef struct mbedtls_gcm_context {
67 mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
68 uint64_t HL[16]; /*!< Precalculated HTable low. */
69 uint64_t HH[16]; /*!< Precalculated HTable high. */
70 uint64_t len; /*!< The total length of the encrypted data. */
71 uint64_t add_len; /*!< The total length of the additional data. */
72 unsigned char base_ectr[16]; /*!< The first ECTR for tag. */
73 unsigned char y[16]; /*!< The Y working value. */
74 unsigned char buf[16]; /*!< The buf working value. */
75 int mode; /*!< The operation to perform:
76 #MBEDTLS_GCM_ENCRYPT or
77 #MBEDTLS_GCM_DECRYPT. */
78}
79mbedtls_gcm_context;
80
81#else /* !MBEDTLS_GCM_ALT */
82#include "gcm_alt.h"
83#endif /* !MBEDTLS_GCM_ALT */
84
85/**
86 * \brief This function initializes the specified GCM context,
87 * to make references valid, and prepares the context
88 * for mbedtls_gcm_setkey() or mbedtls_gcm_free().
89 *
90 * The function does not bind the GCM context to a particular
91 * cipher, nor set the key. For this purpose, use
92 * mbedtls_gcm_setkey().
93 *
94 * \param ctx The GCM context to initialize. This must not be \c NULL.
95 */
96void mbedtls_gcm_init(mbedtls_gcm_context *ctx);
97
98/**
99 * \brief This function associates a GCM context with a
100 * cipher algorithm and a key.
101 *
102 * \param ctx The GCM context. This must be initialized.
103 * \param cipher The 128-bit block cipher to use.
104 * \param key The encryption key. This must be a readable buffer of at
105 * least \p keybits bits.
106 * \param keybits The key size in bits. Valid options are:
107 * <ul><li>128 bits</li>
108 * <li>192 bits</li>
109 * <li>256 bits</li></ul>
110 *
111 * \return \c 0 on success.
112 * \return A cipher-specific error code on failure.
113 */
114int mbedtls_gcm_setkey(mbedtls_gcm_context *ctx,
115 mbedtls_cipher_id_t cipher,
116 const unsigned char *key,
117 unsigned int keybits);
118
119/**
120 * \brief This function performs GCM encryption or decryption of a buffer.
121 *
122 * \note For encryption, the output buffer can be the same as the
123 * input buffer. For decryption, the output buffer cannot be
124 * the same as input buffer. If the buffers overlap, the output
125 * buffer must trail at least 8 Bytes behind the input buffer.
126 *
127 * \warning When this function performs a decryption, it outputs the
128 * authentication tag and does not verify that the data is
129 * authentic. You should use this function to perform encryption
130 * only. For decryption, use mbedtls_gcm_auth_decrypt() instead.
131 *
132 * \param ctx The GCM context to use for encryption or decryption. This
133 * must be initialized.
134 * \param mode The operation to perform:
135 * - #MBEDTLS_GCM_ENCRYPT to perform authenticated encryption.
136 * The ciphertext is written to \p output and the
137 * authentication tag is written to \p tag.
138 * - #MBEDTLS_GCM_DECRYPT to perform decryption.
139 * The plaintext is written to \p output and the
140 * authentication tag is written to \p tag.
141 * Note that this mode is not recommended, because it does
142 * not verify the authenticity of the data. For this reason,
143 * you should use mbedtls_gcm_auth_decrypt() instead of
144 * calling this function in decryption mode.
145 * \param length The length of the input data, which is equal to the length
146 * of the output data.
147 * \param iv The initialization vector. This must be a readable buffer of
148 * at least \p iv_len Bytes.
149 * \param iv_len The length of the IV.
150 * \param add The buffer holding the additional data. This must be of at
151 * least that size in Bytes.
152 * \param add_len The length of the additional data.
153 * \param input The buffer holding the input data. If \p length is greater
154 * than zero, this must be a readable buffer of at least that
155 * size in Bytes.
156 * \param output The buffer for holding the output data. If \p length is greater
157 * than zero, this must be a writable buffer of at least that
158 * size in Bytes.
159 * \param tag_len The length of the tag to generate.
160 * \param tag The buffer for holding the tag. This must be a writable
161 * buffer of at least \p tag_len Bytes.
162 *
163 * \return \c 0 if the encryption or decryption was performed
164 * successfully. Note that in #MBEDTLS_GCM_DECRYPT mode,
165 * this does not indicate that the data is authentic.
166 * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
167 * not valid or a cipher-specific error code if the encryption
168 * or decryption failed.
169 */
170int mbedtls_gcm_crypt_and_tag(mbedtls_gcm_context *ctx,
171 int mode,
172 size_t length,
173 const unsigned char *iv,
174 size_t iv_len,
175 const unsigned char *add,
176 size_t add_len,
177 const unsigned char *input,
178 unsigned char *output,
179 size_t tag_len,
180 unsigned char *tag);
181
182/**
183 * \brief This function performs a GCM authenticated decryption of a
184 * buffer.
185 *
186 * \note For decryption, the output buffer cannot be the same as
187 * input buffer. If the buffers overlap, the output buffer
188 * must trail at least 8 Bytes behind the input buffer.
189 *
190 * \param ctx The GCM context. This must be initialized.
191 * \param length The length of the ciphertext to decrypt, which is also
192 * the length of the decrypted plaintext.
193 * \param iv The initialization vector. This must be a readable buffer
194 * of at least \p iv_len Bytes.
195 * \param iv_len The length of the IV.
196 * \param add The buffer holding the additional data. This must be of at
197 * least that size in Bytes.
198 * \param add_len The length of the additional data.
199 * \param tag The buffer holding the tag to verify. This must be a
200 * readable buffer of at least \p tag_len Bytes.
201 * \param tag_len The length of the tag to verify.
202 * \param input The buffer holding the ciphertext. If \p length is greater
203 * than zero, this must be a readable buffer of at least that
204 * size.
205 * \param output The buffer for holding the decrypted plaintext. If \p length
206 * is greater than zero, this must be a writable buffer of at
207 * least that size.
208 *
209 * \return \c 0 if successful and authenticated.
210 * \return #MBEDTLS_ERR_GCM_AUTH_FAILED if the tag does not match.
211 * \return #MBEDTLS_ERR_GCM_BAD_INPUT if the lengths or pointers are
212 * not valid or a cipher-specific error code if the decryption
213 * failed.
214 */
215int mbedtls_gcm_auth_decrypt(mbedtls_gcm_context *ctx,
216 size_t length,
217 const unsigned char *iv,
218 size_t iv_len,
219 const unsigned char *add,
220 size_t add_len,
221 const unsigned char *tag,
222 size_t tag_len,
223 const unsigned char *input,
224 unsigned char *output);
225
226/**
227 * \brief This function starts a GCM encryption or decryption
228 * operation.
229 *
230 * \param ctx The GCM context. This must be initialized.
231 * \param mode The operation to perform: #MBEDTLS_GCM_ENCRYPT or
232 * #MBEDTLS_GCM_DECRYPT.
233 * \param iv The initialization vector. This must be a readable buffer of
234 * at least \p iv_len Bytes.
235 * \param iv_len The length of the IV.
236 * \param add The buffer holding the additional data, or \c NULL
237 * if \p add_len is \c 0.
238 * \param add_len The length of the additional data. If \c 0,
239 * \p add may be \c NULL.
240 *
241 * \return \c 0 on success.
242 */
243int mbedtls_gcm_starts(mbedtls_gcm_context *ctx,
244 int mode,
245 const unsigned char *iv,
246 size_t iv_len,
247 const unsigned char *add,
248 size_t add_len);
249
250/**
251 * \brief This function feeds an input buffer into an ongoing GCM
252 * encryption or decryption operation.
253 *
254 * ` The function expects input to be a multiple of 16
255 * Bytes. Only the last call before calling
256 * mbedtls_gcm_finish() can be less than 16 Bytes.
257 *
258 * \note For decryption, the output buffer cannot be the same as
259 * input buffer. If the buffers overlap, the output buffer
260 * must trail at least 8 Bytes behind the input buffer.
261 *
262 * \param ctx The GCM context. This must be initialized.
263 * \param length The length of the input data. This must be a multiple of
264 * 16 except in the last call before mbedtls_gcm_finish().
265 * \param input The buffer holding the input data. If \p length is greater
266 * than zero, this must be a readable buffer of at least that
267 * size in Bytes.
268 * \param output The buffer for holding the output data. If \p length is
269 * greater than zero, this must be a writable buffer of at
270 * least that size in Bytes.
271 *
272 * \return \c 0 on success.
273 * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
274 */
275int mbedtls_gcm_update(mbedtls_gcm_context *ctx,
276 size_t length,
277 const unsigned char *input,
278 unsigned char *output);
279
280/**
281 * \brief This function finishes the GCM operation and generates
282 * the authentication tag.
283 *
284 * It wraps up the GCM stream, and generates the
285 * tag. The tag can have a maximum length of 16 Bytes.
286 *
287 * \param ctx The GCM context. This must be initialized.
288 * \param tag The buffer for holding the tag. This must be a writable
289 * buffer of at least \p tag_len Bytes.
290 * \param tag_len The length of the tag to generate. This must be at least
291 * four.
292 *
293 * \return \c 0 on success.
294 * \return #MBEDTLS_ERR_GCM_BAD_INPUT on failure.
295 */
296int mbedtls_gcm_finish(mbedtls_gcm_context *ctx,
297 unsigned char *tag,
298 size_t tag_len);
299
300/**
301 * \brief This function clears a GCM context and the underlying
302 * cipher sub-context.
303 *
304 * \param ctx The GCM context to clear. If this is \c NULL, the call has
305 * no effect. Otherwise, this must be initialized.
306 */
307void mbedtls_gcm_free(mbedtls_gcm_context *ctx);
308
309#if defined(MBEDTLS_SELF_TEST)
310
311/**
312 * \brief The GCM checkup routine.
313 *
314 * \return \c 0 on success.
315 * \return \c 1 on failure.
316 */
317int mbedtls_gcm_self_test(int verbose);
318
319#endif /* MBEDTLS_SELF_TEST */
320
321#ifdef __cplusplus
322}
323#endif
324
325
326#endif /* gcm.h */
327