Mbed TLS v3.6.4
cipher.h
Go to the documentation of this file.
1 
10 /*
11  * Copyright The Mbed TLS Contributors
12  * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later
13  */
14 
15 #ifndef MBEDTLS_CIPHER_H
16 #define MBEDTLS_CIPHER_H
17 #include "mbedtls/private_access.h"
18 
19 #include "mbedtls/build_info.h"
20 
21 #include <stddef.h>
22 #include "mbedtls/platform_util.h"
23 
24 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
25 #define MBEDTLS_CIPHER_MODE_AEAD
26 #endif
27 
28 #if defined(MBEDTLS_CIPHER_MODE_CBC)
29 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
30 #endif
31 
32 #if defined(MBEDTLS_CIPHER_NULL_CIPHER) || \
33  defined(MBEDTLS_CHACHA20_C)
34 #define MBEDTLS_CIPHER_MODE_STREAM
35 #endif
36 
38 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
39 
40 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100
41 
42 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180
43 
44 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200
45 
46 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
47 
48 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300
49 
50 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380
51 
52 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01
53 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02
55 #ifdef __cplusplus
56 extern "C" {
57 #endif
58 
66 typedef enum {
76 
84 typedef enum {
170 
172 typedef enum {
188 
190 typedef enum {
197 
199 typedef enum {
204 
205 enum {
214 };
215 
217 /* This should ideally be derived automatically from list of ciphers.
218  * This should be kept in sync with MBEDTLS_SSL_MAX_IV_LENGTH defined
219  * in library/ssl_misc.h. */
220 #define MBEDTLS_MAX_IV_LENGTH 16
221 
223 /* This should ideally be derived automatically from list of ciphers.
224  * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined
225  * in library/ssl_misc.h. */
226 #define MBEDTLS_MAX_BLOCK_LENGTH 16
227 
229 /* This should ideally be derived automatically from list of ciphers.
230  * For now, only check whether XTS is enabled which uses 64 Byte keys,
231  * and use 32 Bytes as an upper bound for the maximum key length otherwise.
232  * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined
233  * in library/ssl_misc.h, which however deliberately ignores the case of XTS
234  * since the latter isn't used in SSL/TLS. */
235 #if defined(MBEDTLS_CIPHER_MODE_XTS)
236 #define MBEDTLS_MAX_KEY_LENGTH 64
237 #else
238 #define MBEDTLS_MAX_KEY_LENGTH 32
239 #endif /* MBEDTLS_CIPHER_MODE_XTS */
240 
245 
250 
266 typedef struct mbedtls_cipher_info_t {
268  const char *MBEDTLS_PRIVATE(name);
269 
271  unsigned int MBEDTLS_PRIVATE(block_size) : 5;
272 
277  unsigned int MBEDTLS_PRIVATE(iv_size) : 3;
278 
283  unsigned int MBEDTLS_PRIVATE(key_bitlen) : 4;
284 
288  unsigned int MBEDTLS_PRIVATE(mode) : 4;
289 
296  unsigned int MBEDTLS_PRIVATE(type) : 8;
297 
302  unsigned int MBEDTLS_PRIVATE(flags) : 2;
303 
305  unsigned int MBEDTLS_PRIVATE(base_idx) : 5;
306 
308 
309 /* For internal use only.
310  * These are used to more compactly represent the fields above. */
311 #define MBEDTLS_KEY_BITLEN_SHIFT 6
312 #define MBEDTLS_IV_SIZE_SHIFT 2
313 
316 typedef struct mbedtls_cipher_context_t {
319 
321  int MBEDTLS_PRIVATE(key_bitlen);
322 
327 
328 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
329 
332  void(*MBEDTLS_PRIVATE(add_padding))(unsigned char *output, size_t olen, size_t data_len);
333  int(*MBEDTLS_PRIVATE(get_padding))(unsigned char *input, size_t ilen, size_t *data_len);
334 #endif
335 
337  unsigned char MBEDTLS_PRIVATE(unprocessed_data)[MBEDTLS_MAX_BLOCK_LENGTH];
338 
340  size_t MBEDTLS_PRIVATE(unprocessed_len);
341 
345 
347  size_t MBEDTLS_PRIVATE(iv_size);
348 
350  void *MBEDTLS_PRIVATE(cipher_ctx);
351 
352 #if defined(MBEDTLS_CMAC_C)
353 
355 #endif
356 
357 #if defined(MBEDTLS_USE_PSA_CRYPTO) && !defined(MBEDTLS_DEPRECATED_REMOVED)
358 
365  unsigned char MBEDTLS_PRIVATE(psa_enabled);
366 #endif /* MBEDTLS_USE_PSA_CRYPTO && !MBEDTLS_DEPRECATED_REMOVED */
367 
369 
383 const int *mbedtls_cipher_list(void);
384 
396 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string(const char *cipher_name);
397 
409 
425  int key_bitlen,
426  const mbedtls_cipher_mode_t mode);
427 
438  const mbedtls_cipher_info_t *info)
439 {
440  if (info == NULL) {
441  return MBEDTLS_CIPHER_NONE;
442  } else {
443  return (mbedtls_cipher_type_t) info->MBEDTLS_PRIVATE(type);
444  }
445 }
446 
457  const mbedtls_cipher_info_t *info)
458 {
459  if (info == NULL) {
460  return MBEDTLS_MODE_NONE;
461  } else {
462  return (mbedtls_cipher_mode_t) info->MBEDTLS_PRIVATE(mode);
463  }
464 }
465 
478  const mbedtls_cipher_info_t *info)
479 {
480  if (info == NULL) {
481  return 0;
482  } else {
483  return ((size_t) info->MBEDTLS_PRIVATE(key_bitlen)) << MBEDTLS_KEY_BITLEN_SHIFT;
484  }
485 }
486 
498 static inline const char *mbedtls_cipher_info_get_name(
499  const mbedtls_cipher_info_t *info)
500 {
501  if (info == NULL) {
502  return NULL;
503  } else {
504  return info->MBEDTLS_PRIVATE(name);
505  }
506 }
507 
518 static inline size_t mbedtls_cipher_info_get_iv_size(
519  const mbedtls_cipher_info_t *info)
520 {
521  if (info == NULL) {
522  return 0;
523  }
524 
525  return ((size_t) info->MBEDTLS_PRIVATE(iv_size)) << MBEDTLS_IV_SIZE_SHIFT;
526 }
527 
539  const mbedtls_cipher_info_t *info)
540 {
541  if (info == NULL) {
542  return 0;
543  }
544 
545  return (size_t) (info->MBEDTLS_PRIVATE(block_size));
546 }
547 
558  const mbedtls_cipher_info_t *info)
559 {
560  if (info == NULL) {
561  return 0;
562  }
563 
564  return info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_KEY_LEN;
565 }
566 
577  const mbedtls_cipher_info_t *info)
578 {
579  if (info == NULL) {
580  return 0;
581  }
582 
583  return info->MBEDTLS_PRIVATE(flags) & MBEDTLS_CIPHER_VARIABLE_IV_LEN;
584 }
585 
592 
603 
604 
632  const mbedtls_cipher_info_t *cipher_info);
633 
634 #if defined(MBEDTLS_USE_PSA_CRYPTO)
635 #if !defined(MBEDTLS_DEPRECATED_REMOVED)
636 
662 int MBEDTLS_DEPRECATED mbedtls_cipher_setup_psa(mbedtls_cipher_context_t *ctx,
663  const mbedtls_cipher_info_t *cipher_info,
664  size_t taglen);
665 #endif /* MBEDTLS_DEPRECATED_REMOVED */
666 #endif /* MBEDTLS_USE_PSA_CRYPTO */
667 
678 static inline unsigned int mbedtls_cipher_get_block_size(
679  const mbedtls_cipher_context_t *ctx)
680 {
681  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
682  return 0;
683  }
684 
685  return (unsigned int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(block_size);
686 }
687 
698  const mbedtls_cipher_context_t *ctx)
699 {
700  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
701  return MBEDTLS_MODE_NONE;
702  }
703 
704  return (mbedtls_cipher_mode_t) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(mode);
705 }
706 
717 static inline int mbedtls_cipher_get_iv_size(
718  const mbedtls_cipher_context_t *ctx)
719 {
720  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
721  return 0;
722  }
723 
724  if (ctx->MBEDTLS_PRIVATE(iv_size) != 0) {
725  return (int) ctx->MBEDTLS_PRIVATE(iv_size);
726  }
727 
728  return (int) (((int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(iv_size)) <<
730 }
731 
741  const mbedtls_cipher_context_t *ctx)
742 {
743  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
744  return MBEDTLS_CIPHER_NONE;
745  }
746 
747  return (mbedtls_cipher_type_t) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(type);
748 }
749 
759 static inline const char *mbedtls_cipher_get_name(
760  const mbedtls_cipher_context_t *ctx)
761 {
762  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
763  return 0;
764  }
765 
766  return ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(name);
767 }
768 
779  const mbedtls_cipher_context_t *ctx)
780 {
781  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
783  }
784 
785  return (int) ctx->MBEDTLS_PRIVATE(cipher_info)->MBEDTLS_PRIVATE(key_bitlen) <<
787 }
788 
798  const mbedtls_cipher_context_t *ctx)
799 {
800  if (ctx->MBEDTLS_PRIVATE(cipher_info) == NULL) {
801  return MBEDTLS_OPERATION_NONE;
802  }
803 
804  return ctx->MBEDTLS_PRIVATE(operation);
805 }
806 
824  const unsigned char *key,
825  int key_bitlen,
826  const mbedtls_operation_t operation);
827 
828 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
829 
846 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
847 
873  const unsigned char *iv,
874  size_t iv_len);
875 
909 
910 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
911 
924  const unsigned char *ad, size_t ad_len);
925 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
926 
957  const unsigned char *input,
958  size_t ilen, unsigned char *output,
959  size_t *olen);
960 
984  unsigned char *output, size_t *olen);
985 
986 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
987 
1004  unsigned char *tag, size_t tag_len);
1005 
1020  const unsigned char *tag, size_t tag_len);
1021 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
1022 
1057  const unsigned char *iv, size_t iv_len,
1058  const unsigned char *input, size_t ilen,
1059  unsigned char *output, size_t *olen);
1060 
1061 #if defined(MBEDTLS_CIPHER_MODE_AEAD) || defined(MBEDTLS_NIST_KW_C)
1062 
1107  const unsigned char *iv, size_t iv_len,
1108  const unsigned char *ad, size_t ad_len,
1109  const unsigned char *input, size_t ilen,
1110  unsigned char *output, size_t output_len,
1111  size_t *olen, size_t tag_len);
1112 
1163  const unsigned char *iv, size_t iv_len,
1164  const unsigned char *ad, size_t ad_len,
1165  const unsigned char *input, size_t ilen,
1166  unsigned char *output, size_t output_len,
1167  size_t *olen, size_t tag_len);
1168 #endif /* MBEDTLS_CIPHER_MODE_AEAD || MBEDTLS_NIST_KW_C */
1169 #ifdef __cplusplus
1170 }
1171 #endif
1172 
1173 #endif /* MBEDTLS_CIPHER_H */
#define MBEDTLS_CIPHER_VARIABLE_KEY_LEN
Definition: cipher.h:53
#define MBEDTLS_CIPHER_VARIABLE_IV_LEN
Definition: cipher.h:52
mbedtls_operation_t
Definition: cipher.h:199
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:498
mbedtls_cipher_padding_t
Definition: cipher.h:190
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
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:678
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:477
mbedtls_cipher_mode_t
Definition: cipher.h:172
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:576
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:759
#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:557
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:518
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:797
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:778
mbedtls_cipher_type_t
Supported {cipher type, cipher mode} pairs.
Definition: cipher.h:84
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:244
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:740
mbedtls_cipher_id_t
Supported cipher types.
Definition: cipher.h:66
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:456
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:220
Macro wrapper for struct's members.
#define MBEDTLS_DEPRECATED
Definition: platform_util.h:37
#define MBEDTLS_IV_SIZE_SHIFT
Definition: cipher.h:312
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 ctx 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:717
struct mbedtls_cipher_context_t mbedtls_cipher_context_t
#define MBEDTLS_KEY_BITLEN_SHIFT
Definition: cipher.h:311
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:437
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:538
#define MBEDTLS_MAX_BLOCK_LENGTH
Definition: cipher.h:226
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...