mbed TLS v1.3.11
cipher.h
Go to the documentation of this file.
1 
27 #ifndef POLARSSL_CIPHER_H
28 #define POLARSSL_CIPHER_H
29 
30 #if !defined(POLARSSL_CONFIG_FILE)
31 #include "config.h"
32 #else
33 #include POLARSSL_CONFIG_FILE
34 #endif
35 
36 #include <stddef.h>
37 
38 #if defined(POLARSSL_GCM_C) || defined(POLARSSL_CCM_C)
39 #define POLARSSL_CIPHER_MODE_AEAD
40 #endif
41 
42 #if defined(POLARSSL_CIPHER_MODE_CBC)
43 #define POLARSSL_CIPHER_MODE_WITH_PADDING
44 #endif
45 
46 #if defined(POLARSSL_ARC4_C)
47 #define POLARSSL_CIPHER_MODE_STREAM
48 #endif
49 
50 #if defined(_MSC_VER) && !defined(inline)
51 #define inline _inline
52 #else
53 #if defined(__ARMCC_VERSION) && !defined(inline)
54 #define inline __inline
55 #endif /* __ARMCC_VERSION */
56 #endif /*_MSC_VER */
57 
58 #define POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
59 #define POLARSSL_ERR_CIPHER_BAD_INPUT_DATA -0x6100
60 #define POLARSSL_ERR_CIPHER_ALLOC_FAILED -0x6180
61 #define POLARSSL_ERR_CIPHER_INVALID_PADDING -0x6200
62 #define POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
63 #define POLARSSL_ERR_CIPHER_AUTH_FAILED -0x6300
65 #define POLARSSL_CIPHER_VARIABLE_IV_LEN 0x01
66 #define POLARSSL_CIPHER_VARIABLE_KEY_LEN 0x02
68 #ifdef __cplusplus
69 extern "C" {
70 #endif
71 
72 typedef enum {
77  POLARSSL_CIPHER_ID_3DES, /* Unused! */
81 } cipher_id_t;
82 
83 typedef enum {
133 } cipher_type_t;
134 
135 typedef enum {
140  POLARSSL_MODE_OFB, /* Unused! */
145 } cipher_mode_t;
146 
147 typedef enum {
154 
155 typedef enum {
159 } operation_t;
160 
161 enum {
170 };
171 
173 #define POLARSSL_MAX_IV_LENGTH 16
174 
175 #define POLARSSL_MAX_BLOCK_LENGTH 16
176 
180 typedef struct {
181 
184 
186  int (*ecb_func)( void *ctx, operation_t mode,
187  const unsigned char *input, unsigned char *output );
188 
189 #if defined(POLARSSL_CIPHER_MODE_CBC)
190 
191  int (*cbc_func)( void *ctx, operation_t mode, size_t length,
192  unsigned char *iv, const unsigned char *input,
193  unsigned char *output );
194 #endif
195 
196 #if defined(POLARSSL_CIPHER_MODE_CFB)
197 
198  int (*cfb_func)( void *ctx, operation_t mode, size_t length, size_t *iv_off,
199  unsigned char *iv, const unsigned char *input,
200  unsigned char *output );
201 #endif
202 
203 #if defined(POLARSSL_CIPHER_MODE_CTR)
204 
205  int (*ctr_func)( void *ctx, size_t length, size_t *nc_off,
206  unsigned char *nonce_counter, unsigned char *stream_block,
207  const unsigned char *input, unsigned char *output );
208 #endif
209 
210 #if defined(POLARSSL_CIPHER_MODE_STREAM)
211 
212  int (*stream_func)( void *ctx, size_t length,
213  const unsigned char *input, unsigned char *output );
214 #endif
215 
217  int (*setkey_enc_func)( void *ctx, const unsigned char *key,
218  unsigned int key_length );
219 
221  int (*setkey_dec_func)( void *ctx, const unsigned char *key,
222  unsigned int key_length);
223 
225  void * (*ctx_alloc_func)( void );
226 
228  void (*ctx_free_func)( void *ctx );
229 
230 } cipher_base_t;
231 
235 typedef struct {
238 
241 
244  unsigned int key_length;
245 
247  const char * name;
248 
251  unsigned int iv_size;
252 
254  int flags;
255 
257  unsigned int block_size;
258 
261 
262 } cipher_info_t;
263 
267 typedef struct {
270 
273 
276 
277 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
278 
279  void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
280  int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
281 #endif
282 
284  unsigned char unprocessed_data[POLARSSL_MAX_BLOCK_LENGTH];
285 
288 
290  unsigned char iv[POLARSSL_MAX_IV_LENGTH];
291 
293  size_t iv_size;
294 
296  void *cipher_ctx;
298 
305 const int *cipher_list( void );
306 
316 const cipher_info_t *cipher_info_from_string( const char *cipher_name );
317 
327 const cipher_info_t *cipher_info_from_type( const cipher_type_t cipher_type );
328 
341 const cipher_info_t *cipher_info_from_values( const cipher_id_t cipher_id,
342  int key_length,
343  const cipher_mode_t mode );
344 
348 void cipher_init( cipher_context_t *ctx );
349 
355 void cipher_free( cipher_context_t *ctx );
356 
373 int cipher_init_ctx( cipher_context_t *ctx, const cipher_info_t *cipher_info );
374 
375 #if ! defined(POLARSSL_DEPRECATED_REMOVED)
376 #if defined(POLARSSL_DEPRECATED_WARNING)
377 #define DEPRECATED __attribute__((deprecated))
378 #else
379 #define DEPRECATED
380 #endif
381 
392 #undef DEPRECATED
393 #endif /* POLARSSL_DEPRECATED_REMOVED */
394 
403 static inline unsigned int cipher_get_block_size( const cipher_context_t *ctx )
404 {
405  if( NULL == ctx || NULL == ctx->cipher_info )
406  return 0;
407 
408  return ctx->cipher_info->block_size;
409 }
410 
421 {
422  if( NULL == ctx || NULL == ctx->cipher_info )
423  return POLARSSL_MODE_NONE;
424 
425  return ctx->cipher_info->mode;
426 }
427 
437 static inline int cipher_get_iv_size( const cipher_context_t *ctx )
438 {
439  if( NULL == ctx || NULL == ctx->cipher_info )
440  return 0;
441 
442  if( ctx->iv_size != 0 )
443  return (int) ctx->iv_size;
444 
445  return ctx->cipher_info->iv_size;
446 }
447 
456 static inline cipher_type_t cipher_get_type( const cipher_context_t *ctx )
457 {
458  if( NULL == ctx || NULL == ctx->cipher_info )
459  return POLARSSL_CIPHER_NONE;
460 
461  return ctx->cipher_info->type;
462 }
463 
471 static inline const char *cipher_get_name( const cipher_context_t *ctx )
472 {
473  if( NULL == ctx || NULL == ctx->cipher_info )
474  return 0;
475 
476  return ctx->cipher_info->name;
477 }
478 
488 static inline int cipher_get_key_size( const cipher_context_t *ctx )
489 {
490  if( NULL == ctx || NULL == ctx->cipher_info )
492 
493  return ctx->cipher_info->key_length;
494 }
495 
506 {
507  if( NULL == ctx || NULL == ctx->cipher_info )
509 
510  return ctx->operation;
511 }
512 
528 int cipher_setkey( cipher_context_t *ctx, const unsigned char *key,
529  int key_length, const operation_t operation );
530 
531 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
532 
545 #endif /* POLARSSL_CIPHER_MODE_WITH_PADDING */
546 
561  const unsigned char *iv, size_t iv_len );
562 
571 int cipher_reset( cipher_context_t *ctx );
572 
573 #if defined(POLARSSL_GCM_C)
574 
586  const unsigned char *ad, size_t ad_len );
587 #endif /* POLARSSL_GCM_C */
588 
618 int cipher_update( cipher_context_t *ctx, const unsigned char *input,
619  size_t ilen, unsigned char *output, size_t *olen );
620 
639  unsigned char *output, size_t *olen );
640 
641 #if defined(POLARSSL_GCM_C)
642 
654  unsigned char *tag, size_t tag_len );
655 
668  const unsigned char *tag, size_t tag_len );
669 #endif /* POLARSSL_GCM_C */
670 
699  const unsigned char *iv, size_t iv_len,
700  const unsigned char *input, size_t ilen,
701  unsigned char *output, size_t *olen );
702 
703 #if defined(POLARSSL_CIPHER_MODE_AEAD)
704 
727  const unsigned char *iv, size_t iv_len,
728  const unsigned char *ad, size_t ad_len,
729  const unsigned char *input, size_t ilen,
730  unsigned char *output, size_t *olen,
731  unsigned char *tag, size_t tag_len );
732 
761  const unsigned char *iv, size_t iv_len,
762  const unsigned char *ad, size_t ad_len,
763  const unsigned char *input, size_t ilen,
764  unsigned char *output, size_t *olen,
765  const unsigned char *tag, size_t tag_len );
766 #endif /* POLARSSL_CIPHER_MODE_AEAD */
767 
773 int cipher_self_test( int verbose );
774 
775 #ifdef __cplusplus
776 }
777 #endif
778 
779 #endif /* POLARSSL_CIPHER_H */
int key_length
Key length to use.
Definition: cipher.h:272
int cipher_finish(cipher_context_t *ctx, unsigned char *output, size_t *olen)
Generic cipher finalisation function.
static int cipher_get_iv_size(const cipher_context_t *ctx)
Returns the size of the cipher's IV/NONCE in bytes.
Definition: cipher.h:437
Generic cipher context.
Definition: cipher.h:267
Key length, in bits (including parity), for DES keys.
Definition: cipher.h:165
cipher_type_t type
Full cipher identifier (e.g.
Definition: cipher.h:237
void cipher_init(cipher_context_t *ctx)
Initialize a cipher_context (as NONE)
static cipher_mode_t cipher_get_cipher_mode(const cipher_context_t *ctx)
Returns the mode of operation for the cipher.
Definition: cipher.h:420
int cipher_write_tag(cipher_context_t *ctx, unsigned char *tag, size_t tag_len)
Write tag for AEAD ciphers.
Cipher information.
Definition: cipher.h:235
zero padding (not reversible!)
Definition: cipher.h:151
const cipher_info_t * cipher_info_from_type(const cipher_type_t cipher_type)
Returns the cipher information structure associated with the given cipher type.
static unsigned int cipher_get_block_size(const cipher_context_t *ctx)
Returns the block size of the given cipher.
Definition: cipher.h:403
const cipher_info_t * cipher_info_from_string(const char *cipher_name)
Returns the cipher information structure associated with the given cipher name.
Configuration options (set of defines)
static const char * cipher_get_name(const cipher_context_t *ctx)
Returns the name of the given cipher, as a string.
Definition: cipher.h:471
static cipher_type_t cipher_get_type(const cipher_context_t *ctx)
Returns the type of the given cipher.
Definition: cipher.h:456
ISO/IEC 7816-4 padding.
Definition: cipher.h:149
int cipher_crypt(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).
const cipher_info_t * cipher_info
Information about the associated cipher.
Definition: cipher.h:269
operation_t operation
Operation that the context's key has been initialised for.
Definition: cipher.h:275
cipher_mode_t
Definition: cipher.h:135
cipher_type_t
Definition: cipher.h:83
#define POLARSSL_MAX_BLOCK_LENGTH
Maximum block size of any cipher, in bytes.
Definition: cipher.h:175
size_t unprocessed_len
Number of bytes that still need processing.
Definition: cipher.h:287
int cipher_update_ad(cipher_context_t *ctx, const unsigned char *ad, size_t ad_len)
Add additional data (for AEAD ciphers).
unsigned int key_length
Cipher key length, in bits (default length for variable sized ciphers) (Includes parity bits for ciph...
Definition: cipher.h:244
operation_t
Definition: cipher.h:155
int cipher_set_iv(cipher_context_t *ctx, const unsigned char *iv, size_t iv_len)
Set the initialization vector (IV) or nonce.
int cipher_auth_encrypt(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).
int cipher_update(cipher_context_t *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen)
Generic cipher update function.
int cipher_auth_decrypt(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).
Key length, in bits (including parity), for DES in three-key EDE.
Definition: cipher.h:169
const char * name
Name of the cipher.
Definition: cipher.h:247
cipher_id_t
Definition: cipher.h:72
#define POLARSSL_MAX_IV_LENGTH
Maximum length of any IV, in bytes.
Definition: cipher.h:173
int cipher_reset(cipher_context_t *ctx)
Finish preparation of the given context.
#define DEPRECATED
Definition: cipher.h:379
cipher_id_t cipher
Base Cipher type (e.g.
Definition: cipher.h:183
int cipher_free_ctx(cipher_context_t *ctx) DEPRECATED
Free the cipher-specific context of ctx.
void cipher_free(cipher_context_t *ctx)
Free and clear the cipher-specific context of ctx.
int cipher_set_padding_mode(cipher_context_t *ctx, cipher_padding_t mode)
Set padding mode, for cipher modes that use padding.
cipher_mode_t mode
Cipher mode (e.g.
Definition: cipher.h:240
cipher_padding_t
Definition: cipher.h:147
static operation_t cipher_get_operation(const cipher_context_t *ctx)
Returns the operation of the given cipher.
Definition: cipher.h:505
PKCS7 padding (default)
Definition: cipher.h:148
int cipher_init_ctx(cipher_context_t *ctx, const cipher_info_t *cipher_info)
Initialises and fills the cipher context structure with the appropriate values.
int cipher_setkey(cipher_context_t *ctx, const unsigned char *key, int key_length, const operation_t operation)
Set the key to use with the given context.
never pad (full blocks only)
Definition: cipher.h:152
Base cipher information.
Definition: cipher.h:180
const cipher_base_t * base
Base cipher information and functions.
Definition: cipher.h:260
const int * cipher_list(void)
Returns the list of ciphers supported by the generic cipher module.
Undefined key length.
Definition: cipher.h:163
ANSI X.923 padding.
Definition: cipher.h:150
unsigned int block_size
block size, in bytes
Definition: cipher.h:257
void * cipher_ctx
Cipher-specific context.
Definition: cipher.h:296
static int cipher_get_key_size(const cipher_context_t *ctx)
Returns the key length of the cipher.
Definition: cipher.h:488
int cipher_self_test(int verbose)
Checkup routine.
size_t iv_size
IV size in bytes (for ciphers with variable-length IVs)
Definition: cipher.h:293
int flags
Flags for variable IV size, variable key size, etc.
Definition: cipher.h:254
int cipher_check_tag(cipher_context_t *ctx, const unsigned char *tag, size_t tag_len)
Check tag for AEAD ciphers.
unsigned int iv_size
IV/NONCE size, in bytes.
Definition: cipher.h:251
Key length, in bits (including parity), for DES in two key EDE.
Definition: cipher.h:167
const cipher_info_t * cipher_info_from_values(const cipher_id_t cipher_id, int key_length, const cipher_mode_t mode)
Returns the cipher information structure associated with the given cipher id, key size and mode...