PolarSSL is now part of ARM Official announcement and rebranded as mbed TLS.

API Documentation (Doxygen generated)

These pages are generated with doxygen directly from the source code!

cipher.h
Go to the documentation of this file.
1 
10 /*
11  * Copyright (C) 2006-2018, Arm Limited (or its affiliates), All Rights Reserved
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  * This file is part of Mbed TLS (https://tls.mbed.org)
27  */
28 
29 #ifndef MBEDTLS_CIPHER_H
30 #define MBEDTLS_CIPHER_H
31 
32 #if !defined(MBEDTLS_CONFIG_FILE)
33 #include "config.h"
34 #else
35 #include MBEDTLS_CONFIG_FILE
36 #endif
37 
38 #include <stddef.h>
39 #include "mbedtls/platform_util.h"
40 
41 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
42 #define MBEDTLS_CIPHER_MODE_AEAD
43 #endif
44 
45 #if defined(MBEDTLS_CIPHER_MODE_CBC)
46 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
47 #endif
48 
49 #if defined(MBEDTLS_ARC4_C) || defined(MBEDTLS_CIPHER_NULL_CIPHER) || \
50  defined(MBEDTLS_CHACHA20_C)
51 #define MBEDTLS_CIPHER_MODE_STREAM
52 #endif
53 
54 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
55  !defined(inline) && !defined(__cplusplus)
56 #define inline __inline
57 #endif
58 
59 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
60 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100
61 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180
62 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200
63 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
64 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300
65 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380
67 /* MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED is deprecated and should not be used. */
68 #define MBEDTLS_ERR_CIPHER_HW_ACCEL_FAILED -0x6400
70 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01
71 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02
73 #ifdef __cplusplus
74 extern "C" {
75 #endif
76 
84 typedef enum {
96 
104 typedef enum {
180 
182 typedef enum {
195 
197 typedef enum {
204 
206 typedef enum {
211 
212 enum {
221 };
222 
224 #define MBEDTLS_MAX_IV_LENGTH 16
225 
226 #define MBEDTLS_MAX_BLOCK_LENGTH 16
227 
232 
237 
242 typedef struct mbedtls_cipher_info_t
243 {
248 
251 
256  unsigned int key_bitlen;
257 
259  const char * name;
260 
265  unsigned int iv_size;
266 
271  int flags;
272 
274  unsigned int block_size;
275 
278 
280 
285 {
288 
291 
296 
297 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
298 
301  void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
302  int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
303 #endif
304 
307 
310 
313  unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
314 
316  size_t iv_size;
317 
319  void *cipher_ctx;
320 
321 #if defined(MBEDTLS_CMAC_C)
322 
323  mbedtls_cmac_context_t *cmac_ctx;
324 #endif
326 
334 const int *mbedtls_cipher_list( void );
335 
347 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
348 
360 
376  int key_bitlen,
377  const mbedtls_cipher_mode_t mode );
378 
385 
396 
397 
417  const mbedtls_cipher_info_t *cipher_info );
418 
427 static inline unsigned int mbedtls_cipher_get_block_size(
428  const mbedtls_cipher_context_t *ctx )
429 {
430  MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
431  if( ctx->cipher_info == NULL )
432  return 0;
433 
434  return ctx->cipher_info->block_size;
435 }
436 
447  const mbedtls_cipher_context_t *ctx )
448 {
450  if( ctx->cipher_info == NULL )
451  return MBEDTLS_MODE_NONE;
452 
453  return ctx->cipher_info->mode;
454 }
455 
466 static inline int mbedtls_cipher_get_iv_size(
467  const mbedtls_cipher_context_t *ctx )
468 {
469  MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
470  if( ctx->cipher_info == NULL )
471  return 0;
472 
473  if( ctx->iv_size != 0 )
474  return (int) ctx->iv_size;
475 
476  return (int) ctx->cipher_info->iv_size;
477 }
478 
488  const mbedtls_cipher_context_t *ctx )
489 {
491  ctx != NULL, MBEDTLS_CIPHER_NONE );
492  if( ctx->cipher_info == NULL )
493  return MBEDTLS_CIPHER_NONE;
494 
495  return ctx->cipher_info->type;
496 }
497 
507 static inline const char *mbedtls_cipher_get_name(
508  const mbedtls_cipher_context_t *ctx )
509 {
510  MBEDTLS_INTERNAL_VALIDATE_RET( ctx != NULL, 0 );
511  if( ctx->cipher_info == NULL )
512  return 0;
513 
514  return ctx->cipher_info->name;
515 }
516 
527  const mbedtls_cipher_context_t *ctx )
528 {
530  ctx != NULL, MBEDTLS_KEY_LENGTH_NONE );
531  if( ctx->cipher_info == NULL )
533 
534  return (int) ctx->cipher_info->key_bitlen;
535 }
536 
546  const mbedtls_cipher_context_t *ctx )
547 {
549  ctx != NULL, MBEDTLS_OPERATION_NONE );
550  if( ctx->cipher_info == NULL )
551  return MBEDTLS_OPERATION_NONE;
552 
553  return ctx->operation;
554 }
555 
573  const unsigned char *key,
574  int key_bitlen,
575  const mbedtls_operation_t operation );
576 
577 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
578 
596 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
597 
617  const unsigned char *iv,
618  size_t iv_len );
619 
630 
631 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
632 
647  const unsigned char *ad, size_t ad_len );
648 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
649 
684 int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
685  size_t ilen, unsigned char *output, size_t *olen );
686 
710  unsigned char *output, size_t *olen );
711 
712 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CHACHAPOLY_C)
713 
730  unsigned char *tag, size_t tag_len );
731 
746  const unsigned char *tag, size_t tag_len );
747 #endif /* MBEDTLS_GCM_C || MBEDTLS_CHACHAPOLY_C */
748 
783  const unsigned char *iv, size_t iv_len,
784  const unsigned char *input, size_t ilen,
785  unsigned char *output, size_t *olen );
786 
787 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
788 
819  const unsigned char *iv, size_t iv_len,
820  const unsigned char *ad, size_t ad_len,
821  const unsigned char *input, size_t ilen,
822  unsigned char *output, size_t *olen,
823  unsigned char *tag, size_t tag_len );
824 
861  const unsigned char *iv, size_t iv_len,
862  const unsigned char *ad, size_t ad_len,
863  const unsigned char *input, size_t ilen,
864  unsigned char *output, size_t *olen,
865  const unsigned char *tag, size_t tag_len );
866 #endif /* MBEDTLS_CIPHER_MODE_AEAD */
867 
868 #ifdef __cplusplus
869 }
870 #endif
871 
872 #endif /* MBEDTLS_CIPHER_H */
Camellia cipher with 128-bit CTR mode.
Definition: cipher.h:131
The Triple DES cipher.
Definition: cipher.h:89
AES cipher with 128-bit GCM mode.
Definition: cipher.h:119
DES cipher with EDE ECB mode.
Definition: cipher.h:139
unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH]
Buffer for input that has not been processed yet.
Definition: cipher.h:306
AES cipher with 128-bit CCM mode.
Definition: cipher.h:148
Aria cipher with 256-bit key and CTR mode.
Definition: cipher.h:165
mbedtls_operation_t
Type of operation.
Definition: cipher.h:206
Camellia cipher with 256-bit CFB128 mode.
Definition: cipher.h:130
unsigned int iv_size
IV or nonce size, in Bytes.
Definition: cipher.h:265
Key length in bits, including parity, for DES in two-key EDE.
Definition: cipher.h:218
Aria cipher with 128-bit key and GCM mode.
Definition: cipher.h:166
Placeholder to mark the end of cipher-pair lists.
Definition: cipher.h:105
AES cipher with 128-bit CBC mode.
Definition: cipher.h:110
mbedtls_cipher_padding_t
Supported cipher padding types.
Definition: cipher.h:197
Never pad (full blocks only).
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.
Definition: cipher.h:446
int(* get_padding)(unsigned char *input, size_t ilen, size_t *data_len)
Definition: cipher.h:302
#define MBEDTLS_INTERNAL_VALIDATE_RET(cond, ret)
AES cipher with 192-bit CBC mode.
Definition: cipher.h:111
The Aria cipher.
Definition: cipher.h:93
Camellia cipher with 128-bit GCM mode.
Definition: cipher.h:134
int flags
Bitflag comprised of MBEDTLS_CIPHER_VARIABLE_IV_LEN and MBEDTLS_CIPHER_VARIABLE_KEY_LEN indicating wh...
Definition: cipher.h:271
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:427
Aria cipher with 256-bit key and CBC mode.
Definition: cipher.h:159
mbedtls_cipher_mode_t
Supported cipher modes.
Definition: cipher.h:182
The OFB cipher mode.
Definition: cipher.h:187
The identity stream cipher.
Definition: cipher.h:106
Camellia cipher with 128-bit CCM mode.
Definition: cipher.h:151
The CMAC context structure.
Definition: cmac.h:54
Aria cipher with 192-bit key and CCM mode.
Definition: cipher.h:170
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_finish(mbedtls_cipher_context_t *ctx, unsigned char *output, size_t *olen)
The generic cipher finalization function.
Generic cipher context.
Definition: cipher.h:284
int mbedtls_cipher_reset(mbedtls_cipher_context_t *ctx)
This function resets the cipher state.
Camellia cipher with 256-bit ECB mode.
Definition: cipher.h:124
Camellia cipher with 192-bit CCM mode.
Definition: cipher.h:152
AES 256-bit cipher in XTS block mode.
Definition: cipher.h:176
Camellia cipher with 192-bit CFB128 mode.
Definition: cipher.h:129
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:507
The CTR cipher mode.
Definition: cipher.h:188
AES cipher with 256-bit CFB128 mode.
Definition: cipher.h:115
Configuration options (set of defines)
Blowfish cipher with CTR mode.
Definition: cipher.h:146
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.
Cipher information.
Definition: cipher.h:242
AES cipher with 192-bit ECB mode.
Definition: cipher.h:108
Aria cipher with 256-bit key and CFB-128 mode.
Definition: cipher.h:162
The ChaCha20 cipher.
Definition: cipher.h:94
The ChaCha-Poly cipher mode.
Definition: cipher.h:193
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.
Aria cipher with 192-bit key and ECB mode.
Definition: cipher.h:155
mbedtls_cipher_mode_t mode
The cipher mode.
Definition: cipher.h:250
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.
unsigned int block_size
The block size, in Bytes.
Definition: cipher.h:274
Base cipher information.
void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx)
This function frees and clears the cipher-specific context of ctx.
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:545
const int * mbedtls_cipher_list(void)
This function retrieves the list of ciphers supported by the generic cipher module.
ANSI X.923 padding.
Definition: cipher.h:200
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:526
Aria cipher with 192-bit key and CFB-128 mode.
Definition: cipher.h:161
mbedtls_cipher_type_t
Supported {cipher type, cipher mode} pairs.
Definition: cipher.h:104
Camellia cipher with 256-bit CBC mode.
Definition: cipher.h:127
Camellia cipher with 128-bit ECB mode.
Definition: cipher.h:122
struct mbedtls_cipher_info_t mbedtls_cipher_info_t
Cipher information.
Common and shared functions used by multiple modules in the Mbed TLS library.
const mbedtls_cipher_info_t * cipher_info
Information about the associated cipher.
Definition: cipher.h:287
AES cipher with 128-bit CFB128 mode.
Definition: cipher.h:113
Blowfish cipher with CBC mode.
Definition: cipher.h:144
Zero padding (not reversible).
Definition: cipher.h:201
ChaCha20 stream cipher.
Definition: cipher.h:177
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...
The Camellia cipher.
Definition: cipher.h:90
The RC4 cipher.
Definition: cipher.h:92
Key length in bits, including parity, for DES in three-key EDE.
Definition: cipher.h:220
DES cipher with CBC mode.
Definition: cipher.h:138
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:487
Undefined key length.
Definition: cipher.h:214
The stream cipher mode.
Definition: cipher.h:190
Placeholder to mark the end of cipher ID lists.
Definition: cipher.h:85
void * cipher_ctx
The cipher-specific context.
Definition: cipher.h:319
AES cipher with 256-bit CBC mode.
Definition: cipher.h:112
Camellia cipher with 256-bit CCM mode.
Definition: cipher.h:153
Camellia cipher with 192-bit ECB mode.
Definition: cipher.h:123
The CFB cipher mode.
Definition: cipher.h:186
ISO/IEC 7816-4 padding.
Definition: cipher.h:199
mbedtls_operation_t operation
Operation that the key of the context has been initialized for.
Definition: cipher.h:295
AES cipher with 256-bit GCM mode.
Definition: cipher.h:121
Camellia cipher with 192-bit CTR mode.
Definition: cipher.h:132
The CCM cipher mode.
Definition: cipher.h:191
mbedtls_cipher_id_t
Supported cipher types.
Definition: cipher.h:84
The XTS cipher mode.
Definition: cipher.h:192
unsigned char iv[MBEDTLS_MAX_IV_LENGTH]
Current IV or NONCE_COUNTER for CTR-mode, data unit (or sector) number for XTS-mode.
Definition: cipher.h:313
Camellia cipher with 192-bit CBC mode.
Definition: cipher.h:126
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.
AES cipher with 256-bit ECB mode.
Definition: cipher.h:109
Camellia cipher with 256-bit GCM mode.
Definition: cipher.h:136
AES 128-bit cipher in OFB mode.
Definition: cipher.h:172
Blowfish cipher with CFB64 mode.
Definition: cipher.h:145
#define MBEDTLS_MAX_IV_LENGTH
Maximum length of any IV, in Bytes.
Definition: cipher.h:224
Aria cipher with 256-bit key and ECB mode.
Definition: cipher.h:156
Aria cipher with 256-bit key and GCM mode.
Definition: cipher.h:168
Camellia cipher with 128-bit CFB128 mode.
Definition: cipher.h:128
RC4 cipher with 128-bit mode.
Definition: cipher.h:147
DES cipher with EDE CBC mode.
Definition: cipher.h:140
size_t unprocessed_len
Number of Bytes that have not been processed yet.
Definition: cipher.h:309
Camellia cipher with 192-bit GCM mode.
Definition: cipher.h:135
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)
The generic autenticated decryption (AEAD) function.
const char * name
Name of the cipher.
Definition: cipher.h:259
Blowfish cipher with ECB mode.
Definition: cipher.h:143
The CBC cipher mode.
Definition: cipher.h:185
Aria cipher with 128-bit key and CBC mode.
Definition: cipher.h:157
AES cipher with 128-bit CTR mode.
Definition: cipher.h:116
ChaCha20-Poly1305 AEAD cipher.
Definition: cipher.h:178
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)
The generic autenticated encryption (AEAD) function.
The GCM cipher mode.
Definition: cipher.h:189
The ECB cipher mode.
Definition: cipher.h:184
The AES cipher.
Definition: cipher.h:87
AES cipher with 192-bit CCM mode.
Definition: cipher.h:149
PKCS7 padding (default).
Definition: cipher.h:198
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...
Aria cipher with 128-bit key and CCM mode.
Definition: cipher.h:169
Camellia cipher with 128-bit CBC mode.
Definition: cipher.h:125
int key_bitlen
Key length to use.
Definition: cipher.h:290
void mbedtls_cipher_init(mbedtls_cipher_context_t *ctx)
This function initializes a cipher_context as NONE.
AES 192-bit cipher in OFB mode.
Definition: cipher.h:173
DES cipher with EDE3 CBC mode.
Definition: cipher.h:142
Aria cipher with 128-bit key and CFB-128 mode.
Definition: cipher.h:160
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.
The identity cipher, treated as a stream cipher.
Definition: cipher.h:86
AES 128-bit cipher in XTS block mode.
Definition: cipher.h:175
The Blowfish cipher.
Definition: cipher.h:91
int mbedtls_cipher_setup(mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info)
This function initializes and fills the cipher-context structure with the appropriate values...
Aria cipher with 192-bit key and CBC mode.
Definition: cipher.h:158
DES cipher with EDE3 ECB mode.
Definition: cipher.h:141
AES cipher with 192-bit CTR mode.
Definition: cipher.h:117
DES cipher with ECB mode.
Definition: cipher.h:137
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.
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:466
Key length, in bits (including parity), for DES keys.
Definition: cipher.h:216
Aria cipher with 128-bit key and ECB mode.
Definition: cipher.h:154
Aria cipher with 128-bit key and CTR mode.
Definition: cipher.h:163
struct mbedtls_cipher_context_t mbedtls_cipher_context_t
Generic cipher context.
void(* add_padding)(unsigned char *output, size_t olen, size_t data_len)
Padding functions to use, if relevant for the specific cipher mode.
Definition: cipher.h:301
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.
AES cipher with 192-bit GCM mode.
Definition: cipher.h:120
size_t iv_size
IV size in Bytes, for ciphers with variable-length IVs.
Definition: cipher.h:316
#define MBEDTLS_MAX_BLOCK_LENGTH
Maximum block size of any cipher, in Bytes.
Definition: cipher.h:226
Aria cipher with 192-bit key and CTR mode.
Definition: cipher.h:164
AES cipher with 128-bit ECB mode.
Definition: cipher.h:107
AES cipher with 256-bit CTR mode.
Definition: cipher.h:118
AES 256-bit cipher in OFB mode.
Definition: cipher.h:174
Camellia cipher with 256-bit CTR mode.
Definition: cipher.h:133
Aria cipher with 192-bit key and GCM mode.
Definition: cipher.h:167
The DES cipher.
Definition: cipher.h:88
AES cipher with 192-bit CFB128 mode.
Definition: cipher.h:114
unsigned int key_bitlen
The cipher key length, in bits.
Definition: cipher.h:256
mbedtls_cipher_type_t type
Full cipher identifier.
Definition: cipher.h:247
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
Struct for base cipher information and functions.
Definition: cipher.h:277
Aria cipher with 256-bit key and CCM mode.
Definition: cipher.h:171
AES cipher with 256-bit CCM mode.
Definition: cipher.h:150