mbed TLS v1.3.18
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(__ARMCC_VERSION) || defined(_MSC_VER) ) && \
51  !defined(inline) && !defined(__cplusplus)
52 #define inline __inline
53 #endif
54 
55 #define POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
56 #define POLARSSL_ERR_CIPHER_BAD_INPUT_DATA -0x6100
57 #define POLARSSL_ERR_CIPHER_ALLOC_FAILED -0x6180
58 #define POLARSSL_ERR_CIPHER_INVALID_PADDING -0x6200
59 #define POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
60 #define POLARSSL_ERR_CIPHER_AUTH_FAILED -0x6300
62 #define POLARSSL_CIPHER_VARIABLE_IV_LEN 0x01
63 #define POLARSSL_CIPHER_VARIABLE_KEY_LEN 0x02
65 #ifdef __cplusplus
66 extern "C" {
67 #endif
68 
69 typedef enum {
74  POLARSSL_CIPHER_ID_3DES, /* Unused! */
78 } cipher_id_t;
79 
80 typedef enum {
130 } cipher_type_t;
131 
132 typedef enum {
137  POLARSSL_MODE_OFB, /* Unused! */
142 } cipher_mode_t;
143 
144 typedef enum {
151 
152 typedef enum {
156 } operation_t;
157 
158 enum {
167 };
168 
170 #define POLARSSL_MAX_IV_LENGTH 16
171 
172 #define POLARSSL_MAX_BLOCK_LENGTH 16
173 
177 typedef struct {
178 
181 
183  int (*ecb_func)( void *ctx, operation_t mode,
184  const unsigned char *input, unsigned char *output );
185 
186 #if defined(POLARSSL_CIPHER_MODE_CBC)
187 
188  int (*cbc_func)( void *ctx, operation_t mode, size_t length,
189  unsigned char *iv, const unsigned char *input,
190  unsigned char *output );
191 #endif
192 
193 #if defined(POLARSSL_CIPHER_MODE_CFB)
194 
195  int (*cfb_func)( void *ctx, operation_t mode, size_t length, size_t *iv_off,
196  unsigned char *iv, const unsigned char *input,
197  unsigned char *output );
198 #endif
199 
200 #if defined(POLARSSL_CIPHER_MODE_CTR)
201 
202  int (*ctr_func)( void *ctx, size_t length, size_t *nc_off,
203  unsigned char *nonce_counter, unsigned char *stream_block,
204  const unsigned char *input, unsigned char *output );
205 #endif
206 
207 #if defined(POLARSSL_CIPHER_MODE_STREAM)
208 
209  int (*stream_func)( void *ctx, size_t length,
210  const unsigned char *input, unsigned char *output );
211 #endif
212 
214  int (*setkey_enc_func)( void *ctx, const unsigned char *key,
215  unsigned int key_length );
216 
218  int (*setkey_dec_func)( void *ctx, const unsigned char *key,
219  unsigned int key_length);
220 
222  void * (*ctx_alloc_func)( void );
223 
225  void (*ctx_free_func)( void *ctx );
226 
227 } cipher_base_t;
228 
232 typedef struct {
235 
238 
241  unsigned int key_length;
242 
244  const char * name;
245 
248  unsigned int iv_size;
249 
251  int flags;
252 
254  unsigned int block_size;
255 
258 
259 } cipher_info_t;
260 
264 typedef struct {
267 
270 
273 
274 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
275 
276  void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
277  int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
278 #endif
279 
281  unsigned char unprocessed_data[POLARSSL_MAX_BLOCK_LENGTH];
282 
285 
287  unsigned char iv[POLARSSL_MAX_IV_LENGTH];
288 
290  size_t iv_size;
291 
293  void *cipher_ctx;
295 
302 const int *cipher_list( void );
303 
313 const cipher_info_t *cipher_info_from_string( const char *cipher_name );
314 
324 const cipher_info_t *cipher_info_from_type( const cipher_type_t cipher_type );
325 
338 const cipher_info_t *cipher_info_from_values( const cipher_id_t cipher_id,
339  int key_length,
340  const cipher_mode_t mode );
341 
345 void cipher_init( cipher_context_t *ctx );
346 
352 void cipher_free( cipher_context_t *ctx );
353 
370 int cipher_init_ctx( cipher_context_t *ctx, const cipher_info_t *cipher_info );
371 
372 #if ! defined(POLARSSL_DEPRECATED_REMOVED)
373 #if defined(POLARSSL_DEPRECATED_WARNING)
374 #define DEPRECATED __attribute__((deprecated))
375 #else
376 #define DEPRECATED
377 #endif
378 
389 #undef DEPRECATED
390 #endif /* POLARSSL_DEPRECATED_REMOVED */
391 
400 static inline unsigned int cipher_get_block_size( const cipher_context_t *ctx )
401 {
402  if( NULL == ctx || NULL == ctx->cipher_info )
403  return 0;
404 
405  return ctx->cipher_info->block_size;
406 }
407 
418 {
419  if( NULL == ctx || NULL == ctx->cipher_info )
420  return POLARSSL_MODE_NONE;
421 
422  return ctx->cipher_info->mode;
423 }
424 
434 static inline int cipher_get_iv_size( const cipher_context_t *ctx )
435 {
436  if( NULL == ctx || NULL == ctx->cipher_info )
437  return 0;
438 
439  if( ctx->iv_size != 0 )
440  return (int) ctx->iv_size;
441 
442  return ctx->cipher_info->iv_size;
443 }
444 
453 static inline cipher_type_t cipher_get_type( const cipher_context_t *ctx )
454 {
455  if( NULL == ctx || NULL == ctx->cipher_info )
456  return POLARSSL_CIPHER_NONE;
457 
458  return ctx->cipher_info->type;
459 }
460 
468 static inline const char *cipher_get_name( const cipher_context_t *ctx )
469 {
470  if( NULL == ctx || NULL == ctx->cipher_info )
471  return 0;
472 
473  return ctx->cipher_info->name;
474 }
475 
485 static inline int cipher_get_key_size( const cipher_context_t *ctx )
486 {
487  if( NULL == ctx || NULL == ctx->cipher_info )
489 
490  return ctx->cipher_info->key_length;
491 }
492 
503 {
504  if( NULL == ctx || NULL == ctx->cipher_info )
506 
507  return ctx->operation;
508 }
509 
525 int cipher_setkey( cipher_context_t *ctx, const unsigned char *key,
526  int key_length, const operation_t operation );
527 
528 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
529 
542 #endif /* POLARSSL_CIPHER_MODE_WITH_PADDING */
543 
558  const unsigned char *iv, size_t iv_len );
559 
568 int cipher_reset( cipher_context_t *ctx );
569 
570 #if defined(POLARSSL_GCM_C)
571 
583  const unsigned char *ad, size_t ad_len );
584 #endif /* POLARSSL_GCM_C */
585 
615 int cipher_update( cipher_context_t *ctx, const unsigned char *input,
616  size_t ilen, unsigned char *output, size_t *olen );
617 
636  unsigned char *output, size_t *olen );
637 
638 #if defined(POLARSSL_GCM_C)
639 
651  unsigned char *tag, size_t tag_len );
652 
665  const unsigned char *tag, size_t tag_len );
666 #endif /* POLARSSL_GCM_C */
667 
696  const unsigned char *iv, size_t iv_len,
697  const unsigned char *input, size_t ilen,
698  unsigned char *output, size_t *olen );
699 
700 #if defined(POLARSSL_CIPHER_MODE_AEAD)
701 
724  const unsigned char *iv, size_t iv_len,
725  const unsigned char *ad, size_t ad_len,
726  const unsigned char *input, size_t ilen,
727  unsigned char *output, size_t *olen,
728  unsigned char *tag, size_t tag_len );
729 
758  const unsigned char *iv, size_t iv_len,
759  const unsigned char *ad, size_t ad_len,
760  const unsigned char *input, size_t ilen,
761  unsigned char *output, size_t *olen,
762  const unsigned char *tag, size_t tag_len );
763 #endif /* POLARSSL_CIPHER_MODE_AEAD */
764 
770 int cipher_self_test( int verbose );
771 
772 #ifdef __cplusplus
773 }
774 #endif
775 
776 #endif /* POLARSSL_CIPHER_H */
int key_length
Key length to use.
Definition: cipher.h:269
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:434
Generic cipher context.
Definition: cipher.h:264
Key length, in bits (including parity), for DES keys.
Definition: cipher.h:162
cipher_type_t type
Full cipher identifier (e.g.
Definition: cipher.h:234
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:417
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:232
zero padding (not reversible!)
Definition: cipher.h:148
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:400
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:468
static cipher_type_t cipher_get_type(const cipher_context_t *ctx)
Returns the type of the given cipher.
Definition: cipher.h:453
ISO/IEC 7816-4 padding.
Definition: cipher.h:146
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:266
operation_t operation
Operation that the context's key has been initialised for.
Definition: cipher.h:272
cipher_mode_t
Definition: cipher.h:132
cipher_type_t
Definition: cipher.h:80
#define POLARSSL_MAX_BLOCK_LENGTH
Maximum block size of any cipher, in bytes.
Definition: cipher.h:172
size_t unprocessed_len
Number of bytes that still need processing.
Definition: cipher.h:284
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:241
operation_t
Definition: cipher.h:152
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:166
const char * name
Name of the cipher.
Definition: cipher.h:244
cipher_id_t
Definition: cipher.h:69
#define POLARSSL_MAX_IV_LENGTH
Maximum length of any IV, in bytes.
Definition: cipher.h:170
int cipher_reset(cipher_context_t *ctx)
Finish preparation of the given context.
#define DEPRECATED
Definition: cipher.h:376
cipher_id_t cipher
Base Cipher type (e.g.
Definition: cipher.h:180
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:237
cipher_padding_t
Definition: cipher.h:144
static operation_t cipher_get_operation(const cipher_context_t *ctx)
Returns the operation of the given cipher.
Definition: cipher.h:502
PKCS7 padding (default)
Definition: cipher.h:145
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:149
Base cipher information.
Definition: cipher.h:177
const cipher_base_t * base
Base cipher information and functions.
Definition: cipher.h:257
const int * cipher_list(void)
Returns the list of ciphers supported by the generic cipher module.
Undefined key length.
Definition: cipher.h:160
ANSI X.923 padding.
Definition: cipher.h:147
unsigned int block_size
block size, in bytes
Definition: cipher.h:254
void * cipher_ctx
Cipher-specific context.
Definition: cipher.h:293
static int cipher_get_key_size(const cipher_context_t *ctx)
Returns the key length of the cipher.
Definition: cipher.h:485
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:290
int flags
Flags for variable IV size, variable key size, etc.
Definition: cipher.h:251
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:248
Key length, in bits (including parity), for DES in two key EDE.
Definition: cipher.h:164
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...