mbed TLS v3.4.0
cipher.h
Go to the documentation of this file.
1 
10 /*
11  * Copyright The Mbed TLS Contributors
12  * SPDX-License-Identifier: Apache-2.0
13  *
14  * Licensed under the Apache License, Version 2.0 (the "License"); you may
15  * not use this file except in compliance with the License.
16  * You may obtain a copy of the License at
17  *
18  * http://www.apache.org/licenses/LICENSE-2.0
19  *
20  * Unless required by applicable law or agreed to in writing, software
21  * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
22  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
23  * See the License for the specific language governing permissions and
24  * limitations under the License.
25  */
26 
27 #ifndef MBEDTLS_CIPHER_H
28 #define MBEDTLS_CIPHER_H
29 #include "mbedtls/private_access.h"
30 
31 #include "mbedtls/build_info.h"
32 
33 #include <stddef.h>
34 #include "mbedtls/platform_util.h"
35 
36 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
37 #define MBEDTLS_CIPHER_MODE_AEAD
38 #endif
39 
40 #if defined(MBEDTLS_CIPHER_MODE_CBC)
41 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
42 #endif
43 
44 #if defined(MBEDTLS_CIPHER_NULL_CIPHER) || \
45  defined(MBEDTLS_CHACHA20_C)
46 #define MBEDTLS_CIPHER_MODE_STREAM
47 #endif
48 
50 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
51 
52 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100
53 
54 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180
55 
56 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200
57 
58 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
59 
60 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300
61 
62 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380
63 
64 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01
65 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70 
78 typedef enum {
88 
96 typedef enum {
182 
184 typedef enum {
200 
202 typedef enum {
209 
211 typedef enum {
216 
217 enum {
226 };
227 
229 /* This should ideally be derived automatically from list of ciphers.
230  * This should be kept in sync with MBEDTLS_SSL_MAX_IV_LENGTH defined
231  * in library/ssl_misc.h. */
232 #define MBEDTLS_MAX_IV_LENGTH 16
233 
235 /* This should ideally be derived automatically from list of ciphers.
236  * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined
237  * in library/ssl_misc.h. */
238 #define MBEDTLS_MAX_BLOCK_LENGTH 16
239 
241 /* This should ideally be derived automatically from list of ciphers.
242  * For now, only check whether XTS is enabled which uses 64 Byte keys,
243  * and use 32 Bytes as an upper bound for the maximum key length otherwise.
244  * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined
245  * in library/ssl_misc.h, which however deliberately ignores the case of XTS
246  * since the latter isn't used in SSL/TLS. */
247 #if defined(MBEDTLS_CIPHER_MODE_XTS)
248 #define MBEDTLS_MAX_KEY_LENGTH 64
249 #else
250 #define MBEDTLS_MAX_KEY_LENGTH 32
251 #endif /* MBEDTLS_CIPHER_MODE_XTS */
252 
257 
262 
274 typedef struct mbedtls_cipher_info_t {
279 
282 
287  unsigned int MBEDTLS_PRIVATE(key_bitlen);
288 
290  const char *MBEDTLS_PRIVATE(name);
291 
296  unsigned int MBEDTLS_PRIVATE(iv_size);
297 
302  int MBEDTLS_PRIVATE(flags);
303 
305  unsigned int MBEDTLS_PRIVATE(block_size);
306 
309 
311 
315 typedef struct mbedtls_cipher_context_t {
318 
320  int MBEDTLS_PRIVATE(key_bitlen);
321 
326 
327 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
328 
331  void(*MBEDTLS_PRIVATE(add_padding))(unsigned char *output, size_t olen, size_t data_len);
332  int(*MBEDTLS_PRIVATE(get_padding))(unsigned char *input, size_t ilen, size_t *data_len);
333 #endif
334 
336  unsigned char MBEDTLS_PRIVATE(unprocessed_data)[MBEDTLS_MAX_BLOCK_LENGTH];
337 
339  size_t MBEDTLS_PRIVATE(unprocessed_len);
340 
344 
346  size_t MBEDTLS_PRIVATE(iv_size);
347 
349  void *MBEDTLS_PRIVATE(cipher_ctx);
350 
351 #if defined(MBEDTLS_CMAC_C)
352 
354 #endif
355 
356 #if defined(MBEDTLS_USE_PSA_CRYPTO)
357 
364  unsigned char MBEDTLS_PRIVATE(psa_enabled);
365 #endif /* MBEDTLS_USE_PSA_CRYPTO */
366 
368 
382 const int *mbedtls_cipher_list(void);
383 
395 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string(const char *cipher_name);
396 
408 
424  int key_bitlen,
425  const mbedtls_cipher_mode_t mode);
426 
437  const mbedtls_cipher_info_t *info)
438 {
439  if (info == NULL) {
440  return MBEDTLS_CIPHER_NONE;
441  } else {
442  return info->MBEDTLS_PRIVATE(type);
443  }
444 }
445 
456  const mbedtls_cipher_info_t *info)
457 {
458  if (info == NULL) {
459  return MBEDTLS_MODE_NONE;
460  } else {
461  return info->MBEDTLS_PRIVATE(mode);
462  }
463 }
464 
477  const mbedtls_cipher_info_t *info)
478 {
479  if (info == NULL) {
480  return 0;
481  } else {
482  return info->MBEDTLS_PRIVATE(key_bitlen);
483  }
484 }
485 
497 static inline const char *mbedtls_cipher_info_get_name(
498  const mbedtls_cipher_info_t *info)
499 {
500  if (info == NULL) {
501  return NULL;
502  } else {
503  return info->MBEDTLS_PRIVATE(name);
504  }
505 }
506 
517 static inline size_t mbedtls_cipher_info_get_iv_size(
518  const mbedtls_cipher_info_t *info)
519 {
520  if (info == NULL) {
521  return 0;
522  }
523 
524  return (size_t) info->MBEDTLS_PRIVATE(iv_size);
525 }
526 
538  const mbedtls_cipher_info_t *info)
539 {
540  if (info == NULL) {
541  return 0;
542  }
543 
544  return (size_t) info->MBEDTLS_PRIVATE(block_size);
545 }
546 
557  const mbedtls_cipher_info_t *info)
558 {
559  if (info == NULL) {
560  return 0;
561  }
562 
563  return info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_KEY_LEN;
564 }
565 
576  const mbedtls_cipher_info_t *info)
577 {
578  if (info == NULL) {
579  return 0;
580  }
581 
582  return info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_IV_LEN;
583 }
584 
591 
602 
603 
631  const mbedtls_cipher_info_t *cipher_info);
632 
633 #if defined(MBEDTLS_USE_PSA_CRYPTO)
634 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
635 
661 int MBEDTLS_DEPRECATED mbedtls_cipher_setup_psa(mbedtls_cipher_context_t *ctx,
662  const mbedtls_cipher_info_t *cipher_info,
663  size_t taglen);
664 #endif /* MBEDTLS_DEPRECATED_REMOVED */
665 #endif /* MBEDTLS_USE_PSA_CRYPTO */
666 
677 static inline unsigned int mbedtls_cipher_get_block_size(
678  const mbedtls_cipher_context_t *ctx)
679 {
680  MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
681  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
682  return 0;
683  }
684 
685  return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(block_size);
686 }
687 
698  const mbedtls_cipher_context_t *ctx)
699 {
701  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
702  return MBEDTLS_MODE_NONE;
703  }
704 
705  return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(mode);
706 }
707 
718 static inline int mbedtls_cipher_get_iv_size(
719  const mbedtls_cipher_context_t *ctx)
720 {
721  MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
722  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
723  return 0;
724  }
725 
726  if (ctx->MBEDTLS_PRIVATE(iv_size) != 0) {
727  return (int) ctx->MBEDTLS_PRIVATE(iv_size);
728  }
729 
730  return (int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(iv_size);
731 }
732 
742  const mbedtls_cipher_context_t *ctx)
743 {
745  ctx != NULL, MBEDTLS_CIPHER_NONE);
746  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
747  return MBEDTLS_CIPHER_NONE;
748  }
749 
750  return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(type);
751 }
752 
762 static inline const char *mbedtls_cipher_get_name(
763  const mbedtls_cipher_context_t *ctx)
764 {
765  MBEDTLS_INTERNAL_VALIDATE_RET(ctx != NULL, 0);
766  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
767  return 0;
768  }
769 
770  return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(name);
771 }
772 
783  const mbedtls_cipher_context_t *ctx)
784 {
786  ctx != NULL, MBEDTLS_KEY_LENGTH_NONE);
787  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
789  }
790 
791  return (int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(key_bitlen);
792 }
793 
803  const mbedtls_cipher_context_t *ctx)
804 {
806  ctx != NULL, MBEDTLS_OPERATION_NONE);
807  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
808  return MBEDTLS_OPERATION_NONE;
809  }
810 
811  return ctx->MBEDTLS_PRIVATE(operation);
812 }
813 
831  const unsigned char *key,
832  int key_bitlen,
833  const mbedtls_operation_t operation);
834 
835 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
836 
854 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
855 
881  const unsigned char *iv,
882  size_t iv_len);
883 
917 
918 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
919 
932  const unsigned char *ad, size_t ad_len);
933 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
934 
965  const unsigned char *input,
966  size_t ilen, unsigned char *output,
967  size_t *olen);
968 
992  unsigned char *output, size_t *olen);
993 
994 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
995 
1012  unsigned char *tag, size_t tag_len);
1013 
1028  const unsigned char *tag, size_t tag_len);
1029 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
1030 
1065  const unsigned char *iv, size_t iv_len,
1066  const unsigned char *input, size_t ilen,
1067  unsigned char *output, size_t *olen);
1068 
1069 #if defined(MBEDTLS_CIPHER_MODE_AEAD) || defined(MBEDTLS_NIST_KW_C)
1070 
1115  const unsigned char *iv, size_t iv_len,
1116  const unsigned char *ad, size_t ad_len,
1117  const unsigned char *input, size_t ilen,
1118  unsigned char *output, size_t output_len,
1119  size_t *olen, size_t tag_len);
1120 
1171  const unsigned char *iv, size_t iv_len,
1172  const unsigned char *ad, size_t ad_len,
1173  const unsigned char *input, size_t ilen,
1174  unsigned char *output, size_t output_len,
1175  size_t *olen, size_t tag_len);
1176 #endif /* MBEDTLS_CIPHER_MODE_AEAD || MBEDTLS_NIST_KW_C */
1177 #ifdef __cplusplus
1178 }
1179 #endif
1180 
1181 #endif /* MBEDTLS_CIPHER_H */
#define MBEDTLS_CIPHER_VARIABLE_KEY_LEN
Definition: cipher.h:65
#define MBEDTLS_CIPHER_VARIABLE_IV_LEN
Definition: cipher.h:64
mbedtls_operation_t
Definition: cipher.h:211
static const char * mbedtls_cipher_info_get_name(const mbedtls_cipher_info_t *info)
Retrieve the human-readable name for a cipher info structure.
Definition: cipher.h:497
mbedtls_cipher_padding_t
Definition: cipher.h:202
static mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode(const mbedtls_cipher_context_t *ctx)
This function returns the mode of operation for the cipher. For example, MBEDTLS_MODE_CBC.
Definition: cipher.h:697
#define MBEDTLS_INTERNAL_VALIDATE_RET(cond, ret)
Definition: platform_util.h:39
static unsigned int mbedtls_cipher_get_block_size(const mbedtls_cipher_context_t *ctx)
This function returns the block size of the given cipher in bytes.
Definition: cipher.h:677
static size_t mbedtls_cipher_info_get_key_bitlen(const mbedtls_cipher_info_t *info)
Retrieve the key size for a cipher info structure.
Definition: cipher.h:476
mbedtls_cipher_mode_t
Definition: cipher.h:184
const mbedtls_cipher_info_t * mbedtls_cipher_info_from_string(const char *cipher_name)
This function retrieves the cipher-information structure associated with the given cipher name...
static int mbedtls_cipher_info_has_variable_iv_size(const mbedtls_cipher_info_t *info)
This function returns a non-zero value if the IV size for the given cipher is variable.
Definition: cipher.h:575
int mbedtls_cipher_finish(mbedtls_cipher_context_t *ctx, unsigned char *output, size_t *olen)
The generic cipher finalization function. If data still needs to be flushed from an incomplete block...
int mbedtls_cipher_auth_decrypt_ext(mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, const unsigned char *ad, size_t ad_len, const unsigned char *input, size_t ilen, unsigned char *output, size_t output_len, size_t *olen, size_t tag_len)
The authenticated encryption (AEAD/NIST_KW) function.
int mbedtls_cipher_reset(mbedtls_cipher_context_t *ctx)
This function resets the cipher state.
static const char * mbedtls_cipher_get_name(const mbedtls_cipher_context_t *ctx)
This function returns the name of the given cipher as a string.
Definition: cipher.h:762
#define MBEDTLS_PRIVATE(member)
int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len)
This function sets the initialization vector (IV) or nonce.
static int mbedtls_cipher_info_has_variable_key_bitlen(const mbedtls_cipher_info_t *info)
This function returns a non-zero value if the key length for the given cipher is variable.
Definition: cipher.h:556
int mbedtls_cipher_set_padding_mode(mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode)
This function sets the padding mode, for cipher modes that use padding.
static size_t mbedtls_cipher_info_get_iv_size(const mbedtls_cipher_info_t *info)
This function returns the size of the IV or nonce for the cipher info structure, in bytes...
Definition: cipher.h:517
int mbedtls_cipher_update(mbedtls_cipher_context_t *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen)
The generic cipher update function. It encrypts or decrypts using the given cipher context...
void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx)
This function frees and clears the cipher-specific context of ctx. Freeing ctx itself remains the res...
static mbedtls_operation_t mbedtls_cipher_get_operation(const mbedtls_cipher_context_t *ctx)
This function returns the operation of the given cipher.
Definition: cipher.h:802
const int * mbedtls_cipher_list(void)
This function retrieves the list of ciphers supported by the generic cipher module.
static int mbedtls_cipher_get_key_bitlen(const mbedtls_cipher_context_t *ctx)
This function returns the key length of the cipher.
Definition: cipher.h:782
mbedtls_cipher_type_t
Supported {cipher type, cipher mode} pairs.
Definition: cipher.h:96
struct mbedtls_cipher_info_t mbedtls_cipher_info_t
Common and shared functions used by multiple modules in the Mbed TLS library.
struct mbedtls_cipher_base_t mbedtls_cipher_base_t
Definition: cipher.h:256
const mbedtls_cipher_info_t * mbedtls_cipher_info_from_values(const mbedtls_cipher_id_t cipher_id, int key_bitlen, const mbedtls_cipher_mode_t mode)
This function retrieves the cipher-information structure associated with the given cipher ID...
static mbedtls_cipher_type_t mbedtls_cipher_get_type(const mbedtls_cipher_context_t *ctx)
This function returns the type of the given cipher.
Definition: cipher.h:741
mbedtls_cipher_id_t
Supported cipher types.
Definition: cipher.h:78
int mbedtls_cipher_setkey(mbedtls_cipher_context_t *ctx, const unsigned char *key, int key_bitlen, const mbedtls_operation_t operation)
This function sets the key to use with the given context.
static mbedtls_cipher_mode_t mbedtls_cipher_info_get_mode(const mbedtls_cipher_info_t *info)
Retrieve the operation mode for a cipher info structure.
Definition: cipher.h:455
int mbedtls_cipher_auth_encrypt_ext(mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, const unsigned char *ad, size_t ad_len, const unsigned char *input, size_t ilen, unsigned char *output, size_t output_len, size_t *olen, size_t tag_len)
The authenticated encryption (AEAD/NIST_KW) function.
#define MBEDTLS_MAX_IV_LENGTH
Definition: cipher.h:232
Macro wrapper for struct's members.
#define MBEDTLS_DEPRECATED
Definition: platform_util.h:53
Build-time configuration info.
int mbedtls_cipher_crypt(mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen)
The generic all-in-one encryption/decryption function, for all ciphers except AEAD constructs...
void mbedtls_cipher_init(mbedtls_cipher_context_t *ctx)
This function initializes a cipher_context as NONE.
int mbedtls_cipher_update_ad(mbedtls_cipher_context_t *ctx, const unsigned char *ad, size_t ad_len)
This function adds additional data for AEAD ciphers. Currently supported with GCM and ChaCha20+Poly13...
int mbedtls_cipher_setup(mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info)
This function prepares a cipher context for use with the given cipher primitive.
int mbedtls_cipher_check_tag(mbedtls_cipher_context_t *ctx, const unsigned char *tag, size_t tag_len)
This function checks the tag for AEAD ciphers. Currently supported with GCM and ChaCha20+Poly1305. This must be called after mbedtls_cipher_finish().
static int mbedtls_cipher_get_iv_size(const mbedtls_cipher_context_t *ctx)
This function returns the size of the IV or nonce of the cipher, in Bytes.
Definition: cipher.h:718
struct mbedtls_cipher_context_t mbedtls_cipher_context_t
static mbedtls_cipher_type_t mbedtls_cipher_info_get_type(const mbedtls_cipher_info_t *info)
Retrieve the identifier for a cipher info structure.
Definition: cipher.h:436
int mbedtls_cipher_write_tag(mbedtls_cipher_context_t *ctx, unsigned char *tag, size_t tag_len)
This function writes a tag for AEAD ciphers. Currently supported with GCM and ChaCha20+Poly1305. This must be called after mbedtls_cipher_finish().
static size_t mbedtls_cipher_info_get_block_size(const mbedtls_cipher_info_t *info)
This function returns the block size of the given cipher info structure in bytes. ...
Definition: cipher.h:537
#define MBEDTLS_MAX_BLOCK_LENGTH
Definition: cipher.h:238
const mbedtls_cipher_info_t * mbedtls_cipher_info_from_type(const mbedtls_cipher_type_t cipher_type)
This function retrieves the cipher-information structure associated with the given cipher type...