mbed TLS v2.3.0
cipher.h
Go to the documentation of this file.
1 
26 #ifndef MBEDTLS_CIPHER_H
27 #define MBEDTLS_CIPHER_H
28 
29 #if !defined(MBEDTLS_CONFIG_FILE)
30 #include "config.h"
31 #else
32 #include MBEDTLS_CONFIG_FILE
33 #endif
34 
35 #include <stddef.h>
36 
37 #if defined(MBEDTLS_GCM_C) || defined(MBEDTLS_CCM_C)
38 #define MBEDTLS_CIPHER_MODE_AEAD
39 #endif
40 
41 #if defined(MBEDTLS_CIPHER_MODE_CBC)
42 #define MBEDTLS_CIPHER_MODE_WITH_PADDING
43 #endif
44 
45 #if defined(MBEDTLS_ARC4_C)
46 #define MBEDTLS_CIPHER_MODE_STREAM
47 #endif
48 
49 #if ( defined(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
50  !defined(inline) && !defined(__cplusplus)
51 #define inline __inline
52 #endif
53 
54 #define MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
55 #define MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA -0x6100
56 #define MBEDTLS_ERR_CIPHER_ALLOC_FAILED -0x6180
57 #define MBEDTLS_ERR_CIPHER_INVALID_PADDING -0x6200
58 #define MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
59 #define MBEDTLS_ERR_CIPHER_AUTH_FAILED -0x6300
60 #define MBEDTLS_ERR_CIPHER_INVALID_CONTEXT -0x6380
62 #define MBEDTLS_CIPHER_VARIABLE_IV_LEN 0x01
63 #define MBEDTLS_CIPHER_VARIABLE_KEY_LEN 0x02
65 #ifdef __cplusplus
66 extern "C" {
67 #endif
68 
69 typedef enum {
79 
80 typedef enum {
131 
132 typedef enum {
137  MBEDTLS_MODE_OFB, /* Unused! */
143 
144 typedef enum {
151 
152 typedef enum {
157 
158 enum {
167 };
168 
170 #define MBEDTLS_MAX_IV_LENGTH 16
171 
172 #define MBEDTLS_MAX_BLOCK_LENGTH 16
173 
178 
182 typedef struct {
184  mbedtls_cipher_type_t type;
185 
187  mbedtls_cipher_mode_t mode;
188 
191  unsigned int key_bitlen;
192 
194  const char * name;
195 
198  unsigned int iv_size;
199 
201  int flags;
202 
204  unsigned int block_size;
205 
208 
210 
214 typedef struct {
217 
220 
222  mbedtls_operation_t operation;
223 
224 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
225 
226  void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
227  int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
228 #endif
229 
231  unsigned char unprocessed_data[MBEDTLS_MAX_BLOCK_LENGTH];
232 
235 
237  unsigned char iv[MBEDTLS_MAX_IV_LENGTH];
238 
240  size_t iv_size;
241 
243  void *cipher_ctx;
245 
252 const int *mbedtls_cipher_list( void );
253 
263 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_string( const char *cipher_name );
264 
274 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_type( const mbedtls_cipher_type_t cipher_type );
275 
288 const mbedtls_cipher_info_t *mbedtls_cipher_info_from_values( const mbedtls_cipher_id_t cipher_id,
289  int key_bitlen,
290  const mbedtls_cipher_mode_t mode );
291 
296 
303 
321 
330 static inline unsigned int mbedtls_cipher_get_block_size( const mbedtls_cipher_context_t *ctx )
331 {
332  if( NULL == ctx || NULL == ctx->cipher_info )
333  return 0;
334 
335  return ctx->cipher_info->block_size;
336 }
337 
347 static inline mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode( const mbedtls_cipher_context_t *ctx )
348 {
349  if( NULL == ctx || NULL == ctx->cipher_info )
350  return MBEDTLS_MODE_NONE;
351 
352  return ctx->cipher_info->mode;
353 }
354 
365 {
366  if( NULL == ctx || NULL == ctx->cipher_info )
367  return 0;
368 
369  if( ctx->iv_size != 0 )
370  return (int) ctx->iv_size;
371 
372  return (int) ctx->cipher_info->iv_size;
373 }
374 
383 static inline mbedtls_cipher_type_t mbedtls_cipher_get_type( const mbedtls_cipher_context_t *ctx )
384 {
385  if( NULL == ctx || NULL == ctx->cipher_info )
386  return MBEDTLS_CIPHER_NONE;
387 
388  return ctx->cipher_info->type;
389 }
390 
398 static inline const char *mbedtls_cipher_get_name( const mbedtls_cipher_context_t *ctx )
399 {
400  if( NULL == ctx || NULL == ctx->cipher_info )
401  return 0;
402 
403  return ctx->cipher_info->name;
404 }
405 
416 {
417  if( NULL == ctx || NULL == ctx->cipher_info )
419 
420  return (int) ctx->cipher_info->key_bitlen;
421 }
422 
432 static inline mbedtls_operation_t mbedtls_cipher_get_operation( const mbedtls_cipher_context_t *ctx )
433 {
434  if( NULL == ctx || NULL == ctx->cipher_info )
435  return MBEDTLS_OPERATION_NONE;
436 
437  return ctx->operation;
438 }
439 
455 int mbedtls_cipher_setkey( mbedtls_cipher_context_t *ctx, const unsigned char *key,
456  int key_bitlen, const mbedtls_operation_t operation );
457 
458 #if defined(MBEDTLS_CIPHER_MODE_WITH_PADDING)
459 
471 int mbedtls_cipher_set_padding_mode( mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode );
472 #endif /* MBEDTLS_CIPHER_MODE_WITH_PADDING */
473 
488  const unsigned char *iv, size_t iv_len );
489 
499 
500 #if defined(MBEDTLS_GCM_C)
501 
513  const unsigned char *ad, size_t ad_len );
514 #endif /* MBEDTLS_GCM_C */
515 
545 int mbedtls_cipher_update( mbedtls_cipher_context_t *ctx, const unsigned char *input,
546  size_t ilen, unsigned char *output, size_t *olen );
547 
566  unsigned char *output, size_t *olen );
567 
568 #if defined(MBEDTLS_GCM_C)
569 
581  unsigned char *tag, size_t tag_len );
582 
595  const unsigned char *tag, size_t tag_len );
596 #endif /* MBEDTLS_GCM_C */
597 
626  const unsigned char *iv, size_t iv_len,
627  const unsigned char *input, size_t ilen,
628  unsigned char *output, size_t *olen );
629 
630 #if defined(MBEDTLS_CIPHER_MODE_AEAD)
631 
654  const unsigned char *iv, size_t iv_len,
655  const unsigned char *ad, size_t ad_len,
656  const unsigned char *input, size_t ilen,
657  unsigned char *output, size_t *olen,
658  unsigned char *tag, size_t tag_len );
659 
688  const unsigned char *iv, size_t iv_len,
689  const unsigned char *ad, size_t ad_len,
690  const unsigned char *input, size_t ilen,
691  unsigned char *output, size_t *olen,
692  const unsigned char *tag, size_t tag_len );
693 #endif /* MBEDTLS_CIPHER_MODE_AEAD */
694 
695 #ifdef __cplusplus
696 }
697 #endif
698 
699 #endif /* MBEDTLS_CIPHER_H */
mbedtls_operation_t
Definition: cipher.h:152
unsigned int iv_size
IV/NONCE size, in bytes.
Definition: cipher.h:198
Key length, in bits (including parity), for DES in two key EDE.
Definition: cipher.h:164
mbedtls_cipher_padding_t
Definition: cipher.h:144
never pad (full blocks only)
Definition: cipher.h:149
static mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode(const mbedtls_cipher_context_t *ctx)
Returns the mode of operation for the cipher.
Definition: cipher.h:347
int flags
Flags for variable IV size, variable key size, etc.
Definition: cipher.h:201
static unsigned int mbedtls_cipher_get_block_size(const mbedtls_cipher_context_t *ctx)
Returns the block size of the given cipher.
Definition: cipher.h:330
mbedtls_cipher_mode_t
Definition: cipher.h:132
const mbedtls_cipher_info_t * mbedtls_cipher_info_from_string(const char *cipher_name)
Returns 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)
Generic cipher finalisation function.
Generic cipher context.
Definition: cipher.h:214
int mbedtls_cipher_reset(mbedtls_cipher_context_t *ctx)
Finish preparation of the given context.
static const char * mbedtls_cipher_get_name(const mbedtls_cipher_context_t *ctx)
Returns the name of the given cipher, as a string.
Definition: cipher.h:398
Configuration options (set of defines)
int mbedtls_cipher_set_iv(mbedtls_cipher_context_t *ctx, const unsigned char *iv, size_t iv_len)
Set the initialization vector (IV) or nonce.
Cipher information.
Definition: cipher.h:182
int mbedtls_cipher_set_padding_mode(mbedtls_cipher_context_t *ctx, mbedtls_cipher_padding_t mode)
Set padding mode, for cipher modes that use padding.
mbedtls_cipher_mode_t mode
Cipher mode (e.g.
Definition: cipher.h:187
int mbedtls_cipher_update(mbedtls_cipher_context_t *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen)
Generic cipher update function.
unsigned int block_size
block size, in bytes
Definition: cipher.h:204
void mbedtls_cipher_free(mbedtls_cipher_context_t *ctx)
Free and clear the cipher-specific context of ctx.
static mbedtls_operation_t mbedtls_cipher_get_operation(const mbedtls_cipher_context_t *ctx)
Returns the operation of the given cipher.
Definition: cipher.h:432
const int * mbedtls_cipher_list(void)
Returns the list of ciphers supported by the generic cipher module.
ANSI X.923 padding.
Definition: cipher.h:147
static int mbedtls_cipher_get_key_bitlen(const mbedtls_cipher_context_t *ctx)
Returns the key length of the cipher.
Definition: cipher.h:415
mbedtls_cipher_type_t
Definition: cipher.h:80
const mbedtls_cipher_info_t * cipher_info
Information about the associated cipher.
Definition: cipher.h:216
zero padding (not reversible!)
Definition: cipher.h:148
struct mbedtls_cipher_base_t mbedtls_cipher_base_t
Base cipher information (opaque struct).
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)
Returns the cipher information structure associated with the given cipher id, key size and mode...
Key length, in bits (including parity), for DES in three-key EDE.
Definition: cipher.h:166
static mbedtls_cipher_type_t mbedtls_cipher_get_type(const mbedtls_cipher_context_t *ctx)
Returns the type of the given cipher.
Definition: cipher.h:383
Undefined key length.
Definition: cipher.h:160
void * cipher_ctx
Cipher-specific context.
Definition: cipher.h:243
ISO/IEC 7816-4 padding.
Definition: cipher.h:146
mbedtls_operation_t operation
Operation that the context&#39;s key has been initialised for.
Definition: cipher.h:222
mbedtls_cipher_id_t
Definition: cipher.h:69
int mbedtls_cipher_setkey(mbedtls_cipher_context_t *ctx, const unsigned char *key, int key_bitlen, const mbedtls_operation_t operation)
Set the key to use with the given context.
#define MBEDTLS_MAX_IV_LENGTH
Maximum length of any IV, in bytes.
Definition: cipher.h:170
size_t unprocessed_len
Number of bytes that still need processing.
Definition: cipher.h:234
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)
Generic autenticated decryption (AEAD ciphers).
const char * name
Name of the cipher.
Definition: cipher.h:194
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)
Generic autenticated encryption (AEAD ciphers).
PKCS7 padding (default)
Definition: cipher.h:145
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)
Generic all-in-one encryption/decryption (for all ciphers except AEAD constructs).
int key_bitlen
Key length to use.
Definition: cipher.h:219
void mbedtls_cipher_init(mbedtls_cipher_context_t *ctx)
Initialize a cipher_context (as NONE)
int mbedtls_cipher_update_ad(mbedtls_cipher_context_t *ctx, const unsigned char *ad, size_t ad_len)
Add additional data (for AEAD ciphers).
int mbedtls_cipher_setup(mbedtls_cipher_context_t *ctx, const mbedtls_cipher_info_t *cipher_info)
Initialises and fills the cipher context structure with the appropriate values.
int mbedtls_cipher_check_tag(mbedtls_cipher_context_t *ctx, const unsigned char *tag, size_t tag_len)
Check tag for AEAD ciphers.
static int mbedtls_cipher_get_iv_size(const mbedtls_cipher_context_t *ctx)
Returns the size of the cipher&#39;s IV/NONCE in bytes.
Definition: cipher.h:364
Key length, in bits (including parity), for DES keys.
Definition: cipher.h:162
int mbedtls_cipher_write_tag(mbedtls_cipher_context_t *ctx, unsigned char *tag, size_t tag_len)
Write tag for AEAD ciphers.
size_t iv_size
IV size in bytes (for ciphers with variable-length IVs)
Definition: cipher.h:240
#define MBEDTLS_MAX_BLOCK_LENGTH
Maximum block size of any cipher, in bytes.
Definition: cipher.h:172
unsigned int key_bitlen
Cipher key length, in bits (default length for variable sized ciphers) (Includes parity bits for ciph...
Definition: cipher.h:191
mbedtls_cipher_type_t type
Full cipher identifier (e.g.
Definition: cipher.h:184
const mbedtls_cipher_info_t * mbedtls_cipher_info_from_type(const mbedtls_cipher_type_t cipher_type)
Returns the cipher information structure associated with the given cipher type.
const mbedtls_cipher_base_t * base
Base cipher information and functions.
Definition: cipher.h:207