NCBI C++ ToolKit
ccm.h
Go to the documentation of this file.

Go to the SVN repository for this file.

1 /**
2  * \file ccm.h
3  *
4  * \brief This file provides an API for the CCM authenticated encryption
5  * mode for block ciphers.
6  *
7  * CCM combines Counter mode encryption with CBC-MAC authentication
8  * for 128-bit block ciphers.
9  *
10  * Input to CCM includes the following elements:
11  * <ul><li>Payload - data that is both authenticated and encrypted.</li>
12  * <li>Associated data (Adata) - data that is authenticated but not
13  * encrypted, For example, a header.</li>
14  * <li>Nonce - A unique value that is assigned to the payload and the
15  * associated data.</li></ul>
16  *
17  * Definition of CCM:
18  * http://csrc.nist.gov/publications/nistpubs/800-38C/SP800-38C_updated-July20_2007.pdf
19  * RFC 3610 "Counter with CBC-MAC (CCM)"
20  *
21  * Related:
22  * RFC 5116 "An Interface and Algorithms for Authenticated Encryption"
23  *
24  * Definition of CCM*:
25  * IEEE 802.15.4 - IEEE Standard for Local and metropolitan area networks
26  * Integer representation is fixed most-significant-octet-first order and
27  * the representation of octets is most-significant-bit-first order. This is
28  * consistent with RFC 3610.
29  */
30 /*
31  * Copyright The Mbed TLS Contributors
32  * SPDX-License-Identifier: Apache-2.0
33  *
34  * Licensed under the Apache License, Version 2.0 (the "License"); you may
35  * not use this file except in compliance with the License.
36  * You may obtain a copy of the License at
37  *
38  * http://www.apache.org/licenses/LICENSE-2.0
39  *
40  * Unless required by applicable law or agreed to in writing, software
41  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
42  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
43  * See the License for the specific language governing permissions and
44  * limitations under the License.
45  */
46 
47 #ifndef MBEDTLS_CCM_H
48 #define MBEDTLS_CCM_H
49 
50 #if !defined(MBEDTLS_CONFIG_FILE)
51 #include "mbedtls/config.h"
52 #else
53 #include MBEDTLS_CONFIG_FILE
54 #endif
55 
56 #include "mbedtls/cipher.h"
57 
58 /** Bad input parameters to the function. */
59 #define MBEDTLS_ERR_CCM_BAD_INPUT -0x000D
60 /** Authenticated decryption failed. */
61 #define MBEDTLS_ERR_CCM_AUTH_FAILED -0x000F
62 
63 /* MBEDTLS_ERR_CCM_HW_ACCEL_FAILED is deprecated and should not be used. */
64 /** CCM hardware accelerator failed. */
65 #define MBEDTLS_ERR_CCM_HW_ACCEL_FAILED -0x0011
66 
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70 
71 #if !defined(MBEDTLS_CCM_ALT)
72 // Regular implementation
73 //
74 
75 /**
76  * \brief The CCM context-type definition. The CCM context is passed
77  * to the APIs called.
78  */
79 typedef struct mbedtls_ccm_context {
80  mbedtls_cipher_context_t cipher_ctx; /*!< The cipher context used. */
81 }
83 
84 #else /* MBEDTLS_CCM_ALT */
85 #include "ccm_alt.h"
86 #endif /* MBEDTLS_CCM_ALT */
87 
88 /**
89  * \brief This function initializes the specified CCM context,
90  * to make references valid, and prepare the context
91  * for mbedtls_ccm_setkey() or mbedtls_ccm_free().
92  *
93  * \param ctx The CCM context to initialize. This must not be \c NULL.
94  */
96 
97 /**
98  * \brief This function initializes the CCM context set in the
99  * \p ctx parameter and sets the encryption key.
100  *
101  * \param ctx The CCM context to initialize. This must be an initialized
102  * context.
103  * \param cipher The 128-bit block cipher to use.
104  * \param key The encryption key. This must not be \c NULL.
105  * \param keybits The key size in bits. This must be acceptable by the cipher.
106  *
107  * \return \c 0 on success.
108  * \return A CCM or cipher-specific error code on failure.
109  */
111  mbedtls_cipher_id_t cipher,
112  const unsigned char *key,
113  unsigned int keybits);
114 
115 /**
116  * \brief This function releases and clears the specified CCM context
117  * and underlying cipher sub-context.
118  *
119  * \param ctx The CCM context to clear. If this is \c NULL, the function
120  * has no effect. Otherwise, this must be initialized.
121  */
123 
124 /**
125  * \brief This function encrypts a buffer using CCM.
126  *
127  * \note The tag is written to a separate buffer. To concatenate
128  * the \p tag with the \p output, as done in <em>RFC-3610:
129  * Counter with CBC-MAC (CCM)</em>, use
130  * \p tag = \p output + \p length, and make sure that the
131  * output buffer is at least \p length + \p tag_len wide.
132  *
133  * \param ctx The CCM context to use for encryption. This must be
134  * initialized and bound to a key.
135  * \param length The length of the input data in Bytes.
136  * \param iv The initialization vector (nonce). This must be a readable
137  * buffer of at least \p iv_len Bytes.
138  * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
139  * or 13. The length L of the message length field is
140  * 15 - \p iv_len.
141  * \param add The additional data field. If \p add_len is greater than
142  * zero, \p add must be a readable buffer of at least that
143  * length.
144  * \param add_len The length of additional data in Bytes.
145  * This must be less than `2^16 - 2^8`.
146  * \param input The buffer holding the input data. If \p length is greater
147  * than zero, \p input must be a readable buffer of at least
148  * that length.
149  * \param output The buffer holding the output data. If \p length is greater
150  * than zero, \p output must be a writable buffer of at least
151  * that length.
152  * \param tag The buffer holding the authentication field. This must be a
153  * writable buffer of at least \p tag_len Bytes.
154  * \param tag_len The length of the authentication field to generate in Bytes:
155  * 4, 6, 8, 10, 12, 14 or 16.
156  *
157  * \return \c 0 on success.
158  * \return A CCM or cipher-specific error code on failure.
159  */
161  const unsigned char *iv, size_t iv_len,
162  const unsigned char *add, size_t add_len,
163  const unsigned char *input, unsigned char *output,
164  unsigned char *tag, size_t tag_len);
165 
166 /**
167  * \brief This function encrypts a buffer using CCM*.
168  *
169  * \note The tag is written to a separate buffer. To concatenate
170  * the \p tag with the \p output, as done in <em>RFC-3610:
171  * Counter with CBC-MAC (CCM)</em>, use
172  * \p tag = \p output + \p length, and make sure that the
173  * output buffer is at least \p length + \p tag_len wide.
174  *
175  * \note When using this function in a variable tag length context,
176  * the tag length has to be encoded into the \p iv passed to
177  * this function.
178  *
179  * \param ctx The CCM context to use for encryption. This must be
180  * initialized and bound to a key.
181  * \param length The length of the input data in Bytes.
182  * \param iv The initialization vector (nonce). This must be a readable
183  * buffer of at least \p iv_len Bytes.
184  * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
185  * or 13. The length L of the message length field is
186  * 15 - \p iv_len.
187  * \param add The additional data field. This must be a readable buffer of
188  * at least \p add_len Bytes.
189  * \param add_len The length of additional data in Bytes.
190  * This must be less than 2^16 - 2^8.
191  * \param input The buffer holding the input data. If \p length is greater
192  * than zero, \p input must be a readable buffer of at least
193  * that length.
194  * \param output The buffer holding the output data. If \p length is greater
195  * than zero, \p output must be a writable buffer of at least
196  * that length.
197  * \param tag The buffer holding the authentication field. This must be a
198  * writable buffer of at least \p tag_len Bytes.
199  * \param tag_len The length of the authentication field to generate in Bytes:
200  * 0, 4, 6, 8, 10, 12, 14 or 16.
201  *
202  * \warning Passing \c 0 as \p tag_len means that the message is no
203  * longer authenticated.
204  *
205  * \return \c 0 on success.
206  * \return A CCM or cipher-specific error code on failure.
207  */
209  const unsigned char *iv, size_t iv_len,
210  const unsigned char *add, size_t add_len,
211  const unsigned char *input, unsigned char *output,
212  unsigned char *tag, size_t tag_len);
213 
214 /**
215  * \brief This function performs a CCM authenticated decryption of a
216  * buffer.
217  *
218  * \param ctx The CCM context to use for decryption. This must be
219  * initialized and bound to a key.
220  * \param length The length of the input data in Bytes.
221  * \param iv The initialization vector (nonce). This must be a readable
222  * buffer of at least \p iv_len Bytes.
223  * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
224  * or 13. The length L of the message length field is
225  * 15 - \p iv_len.
226  * \param add The additional data field. This must be a readable buffer
227  * of at least that \p add_len Bytes..
228  * \param add_len The length of additional data in Bytes.
229  * This must be less than 2^16 - 2^8.
230  * \param input The buffer holding the input data. If \p length is greater
231  * than zero, \p input must be a readable buffer of at least
232  * that length.
233  * \param output The buffer holding the output data. If \p length is greater
234  * than zero, \p output must be a writable buffer of at least
235  * that length.
236  * \param tag The buffer holding the authentication field. This must be a
237  * readable buffer of at least \p tag_len Bytes.
238  * \param tag_len The length of the authentication field to generate in Bytes:
239  * 4, 6, 8, 10, 12, 14 or 16.
240  *
241  * \return \c 0 on success. This indicates that the message is authentic.
242  * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
243  * \return A cipher-specific error code on calculation failure.
244  */
246  const unsigned char *iv, size_t iv_len,
247  const unsigned char *add, size_t add_len,
248  const unsigned char *input, unsigned char *output,
249  const unsigned char *tag, size_t tag_len);
250 
251 /**
252  * \brief This function performs a CCM* authenticated decryption of a
253  * buffer.
254  *
255  * \note When using this function in a variable tag length context,
256  * the tag length has to be decoded from \p iv and passed to
257  * this function as \p tag_len. (\p tag needs to be adjusted
258  * accordingly.)
259  *
260  * \param ctx The CCM context to use for decryption. This must be
261  * initialized and bound to a key.
262  * \param length The length of the input data in Bytes.
263  * \param iv The initialization vector (nonce). This must be a readable
264  * buffer of at least \p iv_len Bytes.
265  * \param iv_len The length of the nonce in Bytes: 7, 8, 9, 10, 11, 12,
266  * or 13. The length L of the message length field is
267  * 15 - \p iv_len.
268  * \param add The additional data field. This must be a readable buffer of
269  * at least that \p add_len Bytes.
270  * \param add_len The length of additional data in Bytes.
271  * This must be less than 2^16 - 2^8.
272  * \param input The buffer holding the input data. If \p length is greater
273  * than zero, \p input must be a readable buffer of at least
274  * that length.
275  * \param output The buffer holding the output data. If \p length is greater
276  * than zero, \p output must be a writable buffer of at least
277  * that length.
278  * \param tag The buffer holding the authentication field. This must be a
279  * readable buffer of at least \p tag_len Bytes.
280  * \param tag_len The length of the authentication field in Bytes.
281  * 0, 4, 6, 8, 10, 12, 14 or 16.
282  *
283  * \warning Passing \c 0 as \p tag_len means that the message is nos
284  * longer authenticated.
285  *
286  * \return \c 0 on success.
287  * \return #MBEDTLS_ERR_CCM_AUTH_FAILED if the tag does not match.
288  * \return A cipher-specific error code on calculation failure.
289  */
291  const unsigned char *iv, size_t iv_len,
292  const unsigned char *add, size_t add_len,
293  const unsigned char *input, unsigned char *output,
294  const unsigned char *tag, size_t tag_len);
295 
296 #if defined(MBEDTLS_SELF_TEST) && defined(MBEDTLS_AES_C)
297 /**
298  * \brief The CCM checkup routine.
299  *
300  * \return \c 0 on success.
301  * \return \c 1 on failure.
302  */
303 int mbedtls_ccm_self_test(int verbose);
304 #endif /* MBEDTLS_SELF_TEST && MBEDTLS_AES_C */
305 
306 #ifdef __cplusplus
307 }
308 #endif
309 
310 #endif /* MBEDTLS_CCM_H */
void mbedtls_ccm_free(mbedtls_ccm_context *ctx)
This function releases and clears the specified CCM context and underlying cipher sub-context.
int mbedtls_ccm_star_auth_decrypt(mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, const unsigned char *tag, size_t tag_len)
This function performs a CCM* authenticated decryption of a buffer.
int mbedtls_ccm_setkey(mbedtls_ccm_context *ctx, mbedtls_cipher_id_t cipher, const unsigned char *key, unsigned int keybits)
This function initializes the CCM context set in the ctx parameter and sets the encryption key.
int mbedtls_ccm_star_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len)
This function encrypts a buffer using CCM*.
int mbedtls_ccm_encrypt_and_tag(mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, unsigned char *tag, size_t tag_len)
This function encrypts a buffer using CCM.
int mbedtls_ccm_auth_decrypt(mbedtls_ccm_context *ctx, size_t length, const unsigned char *iv, size_t iv_len, const unsigned char *add, size_t add_len, const unsigned char *input, unsigned char *output, const unsigned char *tag, size_t tag_len)
This function performs a CCM authenticated decryption of a buffer.
struct mbedtls_ccm_context mbedtls_ccm_context
The CCM context-type definition.
void mbedtls_ccm_init(mbedtls_ccm_context *ctx)
This function initializes the specified CCM context, to make references valid, and prepare the contex...
This file contains an abstraction interface for use with the cipher primitives provided by the librar...
mbedtls_cipher_id_t
Supported cipher types.
Definition: cipher.h:90
CS_CONTEXT * ctx
Definition: t0006.c:12
static int input()
const struct ncbi::grid::netcache::search::fields::KEY key
const char * tag
static SQLCHAR output[256]
Definition: print.c:5
true_type verbose
Definition: processing.cpp:890
Configuration options (set of defines)
The CCM context-type definition.
Definition: ccm.h:79
mbedtls_cipher_context_t cipher_ctx
Definition: ccm.h:80
Generic cipher context.
Definition: cipher.h:317
Modified on Fri Mar 01 10:07:12 2024 by modify_doxy.py rev. 669887