mbed TLS v2.26.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 
30 #if !defined(MBEDTLS_CONFIG_FILE)
31 #include "mbedtls/config.h"
32 #else
33 #include MBEDTLS_CONFIG_FILE
34 #endif
35 
36 #include <stddef.h>
37 #include "mbedtls/platform_util.h"
38 
39 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
40 #define MBEDTLS_CIPHER_MODE_AEAD
41 #endif
42 
43 #if defined(MBEDTLS_CIPHER_MODE_CBC)
44 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
45 #endif
46 
47 #if defined(MBEDTLS_ARC4_C) || defined(MBEDTLS_CIPHER_NULL_CIPHER) || \
48  defined(MBEDTLS_CHACHA20_C)
49 #define MBEDTLS_CIPHER_MODE_STREAM
50 #endif
51 
52 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
53  !defined(inline) && !defined(__cplusplus)
54 #define inline __inline
55 #endif
56 
57 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
58 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100
59 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180
60 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200
61 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
62 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300
63 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380
65 /* MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED is deprecated and should not be used. */
66 #define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400
68 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01
69 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02
71 #ifdef __cplusplus
72 extern "C" {
73 #endif
74 
82 typedef enum {
94 
102 typedef enum {
184 
186 typedef enum {
201 
203 typedef enum {
210 
212 typedef enum {
217 
218 enum {
227 };
228 
230 /* This should ideally be derived automatically from list of ciphers.
231  * This should be kept in sync with MBEDTLS_SSL_MAX_IV_LENGTH defined
232  * in ssl_internal.h. */
233 #define MBEDTLS_MAX_IV_LENGTH 16
234 
236 /* This should ideally be derived automatically from list of ciphers.
237  * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined
238  * in ssl_internal.h. */
239 #define MBEDTLS_MAX_BLOCK_LENGTH 16
240 
242 /* This should ideally be derived automatically from list of ciphers.
243  * For now, only check whether XTS is enabled which uses 64 Byte keys,
244  * and use 32 Bytes as an upper bound for the maximum key length otherwise.
245  * This should be kept in sync with MBEDTLS_SSL_MAX_BLOCK_LENGTH defined
246  * in ssl_internal.h, which however deliberately ignores the case of XTS
247  * since the latter isn't used in SSL/TLS. */
248 #if defined(MBEDTLS_CIPHER_MODE_XTS)
249 #define MBEDTLS_MAX_KEY_LENGTH 64
250 #else
251 #define MBEDTLS_MAX_KEY_LENGTH 32
252 #endif /* MBEDTLS_CIPHER_MODE_XTS */
253 
258 
263 
268 typedef struct mbedtls_cipher_info_t
269 {
274 
277 
282  unsigned int key_bitlen;
283 
285  const char * name;
286 
291  unsigned int iv_size;
292 
297  int flags;
298 
300  unsigned int block_size;
301 
304 
306 
311 {
314 
317 
322 
323 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
324 
327  void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
328  int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
329 #endif
330 
333 
336 
339  unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
340 
342  size_t iv_size;
343 
345  void *cipher_ctx;
346 
347 #if defined(MBEDTLS_CMAC_C)
348 
349  mbedtls_cmac_context_t *cmac_ctx;
350 #endif
351 
352 #if defined(MBEDTLS_USE_PSA_CRYPTO)
353 
360  unsigned char psa_enabled;
361 #endif /* MBEDTLS_USE_PSA_CRYPTO */
362 
364 
378 const int *mbedtls_cipher_list( void );
379 
391 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
392 
404 
420  int key_bitlen,
421  const mbedtls_cipher_mode_t mode );
422 
429 
440 
441 
460  const mbedtls_cipher_info_t *cipher_info );
461 
462 #if defined(MBEDTLS_USE_PSA_CRYPTO)
463 
484 int mbedtls_cipher_setup_psa( mbedtls_cipher_context_t *ctx,
485  const mbedtls_cipher_info_t *cipher_info,
486  size_t taglen );
487 #endif /* MBEDTLS_USE_PSA_CRYPTO */
488 
497 static inline unsigned int mbedtls_cipher_get_block_size(
498  const mbedtls_cipher_context_t *ctx )
499 {
500  MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
501  if( ctx->cipher_info == NULL )
502  return 0;
503 
504  return ctx->cipher_info->block_size;
505 }
506 
517  const mbedtls_cipher_context_t *ctx )
518 {
520  if( ctx->cipher_info == NULL )
521  return MBEDTLS_MODE_NONE;
522 
523  return ctx->cipher_info->mode;
524 }
525 
536 static inline int mbedtls_cipher_get_iv_size(
537  const mbedtls_cipher_context_t *ctx )
538 {
539  MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
540  if( ctx->cipher_info == NULL )
541  return 0;
542 
543  if( ctx->iv_size != 0 )
544  return (int) ctx->iv_size;
545 
546  return (int) ctx->cipher_info->iv_size;
547 }
548 
558  const mbedtls_cipher_context_t *ctx )
559 {
561  ctx != NULL, MBEDTLS_CIPHER_NONE );
562  if( ctx->cipher_info == NULL )
563  return MBEDTLS_CIPHER_NONE;
564 
565  return ctx->cipher_info->type;
566 }
567 
577 static inline const char *mbedtls_cipher_get_name(
578  const mbedtls_cipher_context_t *ctx )
579 {
580  MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
581  if( ctx->cipher_info == NULL )
582  return 0;
583 
584  return ctx->cipher_info->name;
585 }
586 
597  const mbedtls_cipher_context_t *ctx )
598 {
600  ctx != NULL, MBEDTLS_KEY_LENGTH_NONE );
601  if( ctx->cipher_info == NULL )
603 
604  return (int) ctx->cipher_info->key_bitlen;
605 }
606 
616  const mbedtls_cipher_context_t *ctx )
617 {
619  ctx != NULL, MBEDTLS_OPERATION_NONE );
620  if( ctx->cipher_info == NULL )
621  return MBEDTLS_OPERATION_NONE;
622 
623  return ctx->operation;
624 }
625 
643  const unsigned char *key,
644  int key_bitlen,
645  const mbedtls_operation_t operation );
646 
647 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
648 
666 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
667 
687  const unsigned char *iv,
688  size_t iv_len );
689 
700 
701 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
702 
717  const unsigned char *ad, size_t ad_len );
718 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
719 
755  const unsigned char *input,
756  size_t ilen, unsigned char *output,
757  size_t *olen );
758 
782  unsigned char *output, size_t *olen );
783 
784 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
785 
802  unsigned char *tag, size_t tag_len );
803 
818  const unsigned char *tag, size_t tag_len );
819 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
820 
855  const unsigned char *iv, size_t iv_len,
856  const unsigned char *input, size_t ilen,
857  unsigned char *output, size_t *olen );
858 
859 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
860 #if ! defined(MBEDTLS_DEPRECATED_REMOVED)
861 #if defined(MBEDTLS_DEPRECATED_WARNING)
862 #define MBEDTLS_DEPRECATED __attribute__((deprecated))
863 #else
864 #define MBEDTLS_DEPRECATED
865 #endif /* MBEDTLS_DEPRECATED_WARNING */
866 
913  const unsigned char *iv, size_t iv_len,
914  const unsigned char *ad, size_t ad_len,
915  const unsigned char *input, size_t ilen,
916  unsigned char *output, size_t *olen,
917  unsigned char *tag, size_t tag_len )
919 
972  const unsigned char *iv, size_t iv_len,
973  const unsigned char *ad, size_t ad_len,
974  const unsigned char *input, size_t ilen,
975  unsigned char *output, size_t *olen,
976  const unsigned char *tag, size_t tag_len )
978 #undef MBEDTLS_DEPRECATED
979 #endif /* MBEDTLS_DEPRECATED_REMOVED */
980 #endif /* MBEDTLS_CIPHER_MODE_AEAD */
981 
982 #if defined(MBEDTLS_CIPHER_MODE_AEAD) || defined(MBEDTLS_NIST_KW_C)
983 
1028  const unsigned char *iv, size_t iv_len,
1029  const unsigned char *ad, size_t ad_len,
1030  const unsigned char *input, size_t ilen,
1031  unsigned char *output, size_t output_len,
1032  size_t *olen, size_t tag_len );
1033 
1084  const unsigned char *iv, size_t iv_len,
1085  const unsigned char *ad, size_t ad_len,
1086  const unsigned char *input, size_t ilen,
1087  unsigned char *output, size_t output_len,
1088  size_t *olen, size_t tag_len );
1089 #endif /* MBEDTLS_CIPHER_MODE_AEAD || MBEDTLS_NIST_KW_C */
1090 #ifdef __cplusplus
1091 }
1092 #endif
1093 
1094 #endif /* MBEDTLS_CIPHER_H */
unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH]
Definition: cipher.h:332
mbedtls_operation_t
Definition: cipher.h:212
unsigned int iv_size
Definition: cipher.h:291
mbedtls_cipher_padding_t
Definition: cipher.h:203
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:516
#define MBEDTLS_INTERNAL_VALIDATE_RET(cond, ret)
static unsigned int mbedtls_cipher_get_block_size(const mbedtls_cipher_context_t *ctx)
This function returns the block size of the given cipher.
Definition: cipher.h:497
mbedtls_cipher_mode_t
Definition: cipher.h:186
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...
int mbedtls_cipher_auth_decrypt(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 *olen, const unsigned char *tag, size_t tag_len) MBEDTLS_DEPRECATED
The generic authenticated decryption (AEAD) function.
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...
void(* add_padding)(unsigned char *output, size_t olen, size_t data_len)
Definition: cipher.h:327
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:577
Configuration options (set of defines)
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.
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.
mbedtls_cipher_mode_t mode
Definition: cipher.h:276
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...
unsigned int block_size
Definition: cipher.h:300
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:615
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:596
mbedtls_cipher_type_t
Supported {cipher type, cipher mode} pairs.
Definition: cipher.h:102
struct mbedtls_cipher_info_t mbedtls_cipher_info_t
Common and shared functions used by multiple modules in the Mbed TLS library.
const mbedtls_cipher_info_t * cipher_info
Definition: cipher.h:313
struct mbedtls_cipher_base_t mbedtls_cipher_base_t
Definition: cipher.h:257
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:557
int(* get_padding)(unsigned char *input, size_t ilen, size_t *data_len)
Definition: cipher.h:328
#define MBEDTLS_DEPRECATED
Definition: cipher.h:864
mbedtls_operation_t operation
Definition: cipher.h:321
mbedtls_cipher_id_t
Supported cipher types.
Definition: cipher.h:82
unsigned char iv[MBEDTLS_MAX_IV_LENGTH]
Definition: cipher.h:339
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.
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:233
int mbedtls_cipher_auth_encrypt(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 *olen, unsigned char *tag, size_t tag_len) MBEDTLS_DEPRECATED
The generic authenticated encryption (AEAD) function.
const char * name
Definition: cipher.h:285
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 initializes 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:536
struct mbedtls_cipher_context_t mbedtls_cipher_context_t
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().
#define MBEDTLS_MAX_BLOCK_LENGTH
Definition: cipher.h:239
unsigned int key_bitlen
Definition: cipher.h:282
mbedtls_cipher_type_t type
Definition: cipher.h:273
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...
const mbedtls_cipher_base_t * base
Definition: cipher.h:303