PolarSSL v1.3.8
cipher.h
Go to the documentation of this file.
1 
30 #ifndef POLARSSL_CIPHER_H
31 #define POLARSSL_CIPHER_H
32 
33 #if !defined(POLARSSL_CONFIG_FILE)
34 #include "config.h"
35 #else
36 #include POLARSSL_CONFIG_FILE
37 #endif
38 
39 #if defined(POLARSSL_GCM_C) || defined(POLARSSL_CCM_C)
40 #define POLARSSL_CIPHER_MODE_AEAD
41 #endif
42 
43 #if defined(POLARSSL_CIPHER_MODE_CBC)
44 #define POLARSSL_CIPHER_MODE_WITH_PADDING
45 #endif
46 
47 #include <string.h>
48 
49 #if defined(_MSC_VER) && !defined(inline)
50 #define inline _inline
51 #else
52 #if defined(__ARMCC_VERSION) && !defined(inline)
53 #define inline __inline
54 #endif /* __ARMCC_VERSION */
55 #endif /*_MSC_VER */
56 
57 #define POLARSSL_ERR_CIPHER_FEATURE_UNAVAILABLE -0x6080
58 #define POLARSSL_ERR_CIPHER_BAD_INPUT_DATA -0x6100
59 #define POLARSSL_ERR_CIPHER_ALLOC_FAILED -0x6180
60 #define POLARSSL_ERR_CIPHER_INVALID_PADDING -0x6200
61 #define POLARSSL_ERR_CIPHER_FULL_BLOCK_EXPECTED -0x6280
62 #define POLARSSL_ERR_CIPHER_AUTH_FAILED -0x6300
64 #define POLARSSL_CIPHER_VARIABLE_IV_LEN 0x01
65 #define POLARSSL_CIPHER_VARIABLE_KEY_LEN 0x02
67 #ifdef __cplusplus
68 extern "C" {
69 #endif
70 
71 typedef enum {
80 } cipher_id_t;
81 
82 typedef enum {
132 } cipher_type_t;
133 
134 typedef enum {
139  POLARSSL_MODE_OFB, /* Unused! */
144 } cipher_mode_t;
145 
146 typedef enum {
153 
154 typedef enum {
158 } operation_t;
159 
160 enum {
169 };
170 
172 #define POLARSSL_MAX_IV_LENGTH 16
173 
174 #define POLARSSL_MAX_BLOCK_LENGTH 16
175 
179 typedef struct {
180 
183 
185  int (*ecb_func)( void *ctx, operation_t mode,
186  const unsigned char *input, unsigned char *output );
187 
189  int (*cbc_func)( void *ctx, operation_t mode, size_t length,
190  unsigned char *iv, const unsigned char *input,
191  unsigned char *output );
192 
194  int (*cfb_func)( void *ctx, operation_t mode, size_t length, size_t *iv_off,
195  unsigned char *iv, const unsigned char *input,
196  unsigned char *output );
197 
199  int (*ctr_func)( void *ctx, size_t length, size_t *nc_off,
200  unsigned char *nonce_counter, unsigned char *stream_block,
201  const unsigned char *input, unsigned char *output );
202 
204  int (*stream_func)( void *ctx, size_t length,
205  const unsigned char *input, unsigned char *output );
206 
208  int (*setkey_enc_func)( void *ctx, const unsigned char *key,
209  unsigned int key_length );
210 
212  int (*setkey_dec_func)( void *ctx, const unsigned char *key,
213  unsigned int key_length);
214 
216  void * (*ctx_alloc_func)( void );
217 
219  void (*ctx_free_func)( void *ctx );
220 
221 } cipher_base_t;
222 
226 typedef struct {
229 
232 
235  unsigned int key_length;
236 
238  const char * name;
239 
242  unsigned int iv_size;
243 
245  int flags;
246 
248  unsigned int block_size;
249 
252 
253 } cipher_info_t;
254 
258 typedef struct {
261 
264 
267 
269  void (*add_padding)( unsigned char *output, size_t olen, size_t data_len );
270  int (*get_padding)( unsigned char *input, size_t ilen, size_t *data_len );
271 
273  unsigned char unprocessed_data[POLARSSL_MAX_BLOCK_LENGTH];
274 
277 
279  unsigned char iv[POLARSSL_MAX_IV_LENGTH];
280 
282  size_t iv_size;
283 
285  void *cipher_ctx;
287 
294 const int *cipher_list( void );
295 
305 const cipher_info_t *cipher_info_from_string( const char *cipher_name );
306 
316 const cipher_info_t *cipher_info_from_type( const cipher_type_t cipher_type );
317 
330 const cipher_info_t *cipher_info_from_values( const cipher_id_t cipher_id,
331  int key_length,
332  const cipher_mode_t mode );
333 
337 void cipher_init( cipher_context_t *ctx );
338 
344 void cipher_free( cipher_context_t *ctx );
345 
362 int cipher_init_ctx( cipher_context_t *ctx, const cipher_info_t *cipher_info );
363 
375 
384 static inline unsigned int cipher_get_block_size( const cipher_context_t *ctx )
385 {
386  if( NULL == ctx || NULL == ctx->cipher_info )
387  return 0;
388 
389  return ctx->cipher_info->block_size;
390 }
391 
402 {
403  if( NULL == ctx || NULL == ctx->cipher_info )
404  return POLARSSL_MODE_NONE;
405 
406  return ctx->cipher_info->mode;
407 }
408 
418 static inline int cipher_get_iv_size( const cipher_context_t *ctx )
419 {
420  if( NULL == ctx || NULL == ctx->cipher_info )
421  return 0;
422 
423  if( ctx->iv_size != 0 )
424  return (int) ctx->iv_size;
425 
426  return ctx->cipher_info->iv_size;
427 }
428 
437 static inline cipher_type_t cipher_get_type( const cipher_context_t *ctx )
438 {
439  if( NULL == ctx || NULL == ctx->cipher_info )
440  return POLARSSL_CIPHER_NONE;
441 
442  return ctx->cipher_info->type;
443 }
444 
452 static inline const char *cipher_get_name( const cipher_context_t *ctx )
453 {
454  if( NULL == ctx || NULL == ctx->cipher_info )
455  return 0;
456 
457  return ctx->cipher_info->name;
458 }
459 
469 static inline int cipher_get_key_size ( const cipher_context_t *ctx )
470 {
471  if( NULL == ctx || NULL == ctx->cipher_info )
473 
474  return ctx->cipher_info->key_length;
475 }
476 
487 {
488  if( NULL == ctx || NULL == ctx->cipher_info )
490 
491  return ctx->operation;
492 }
493 
509 int cipher_setkey( cipher_context_t *ctx, const unsigned char *key,
510  int key_length, const operation_t operation );
511 
512 #if defined(POLARSSL_CIPHER_MODE_WITH_PADDING)
513 
526 #endif /* POLARSSL_CIPHER_MODE_WITH_PADDING */
527 
542  const unsigned char *iv, size_t iv_len );
543 
552 int cipher_reset( cipher_context_t *ctx );
553 
554 #if defined(POLARSSL_GCM_C)
555 
567  const unsigned char *ad, size_t ad_len );
568 #endif /* POLARSSL_GCM_C */
569 
599 int cipher_update( cipher_context_t *ctx, const unsigned char *input,
600  size_t ilen, unsigned char *output, size_t *olen );
601 
620  unsigned char *output, size_t *olen );
621 
622 #if defined(POLARSSL_GCM_C)
623 
635  unsigned char *tag, size_t tag_len );
636 
649  const unsigned char *tag, size_t tag_len );
650 #endif /* POLARSSL_GCM_C */
651 
680  const unsigned char *iv, size_t iv_len,
681  const unsigned char *input, size_t ilen,
682  unsigned char *output, size_t *olen );
683 
684 #if defined(POLARSSL_CIPHER_MODE_AEAD)
685 
708  const unsigned char *iv, size_t iv_len,
709  const unsigned char *ad, size_t ad_len,
710  const unsigned char *input, size_t ilen,
711  unsigned char *output, size_t *olen,
712  unsigned char *tag, size_t tag_len );
713 
742  const unsigned char *iv, size_t iv_len,
743  const unsigned char *ad, size_t ad_len,
744  const unsigned char *input, size_t ilen,
745  unsigned char *output, size_t *olen,
746  const unsigned char *tag, size_t tag_len );
747 #endif /* POLARSSL_CIPHER_MODE_AEAD */
748 
754 int cipher_self_test( int verbose );
755 
756 #ifdef __cplusplus
757 }
758 #endif
759 
760 #endif /* POLARSSL_CIPHER_H */
int key_length
Key length to use.
Definition: cipher.h:263
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:418
Generic cipher context.
Definition: cipher.h:258
Key length, in bits (including parity), for DES keys.
Definition: cipher.h:164
cipher_type_t type
Full cipher identifier (e.g.
Definition: cipher.h:228
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:401
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:226
zero padding (not reversible!)
Definition: cipher.h:150
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:384
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:452
static cipher_type_t cipher_get_type(const cipher_context_t *ctx)
Returns the type of the given cipher.
Definition: cipher.h:437
ISO/IEC 7816-4 padding.
Definition: cipher.h:148
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:260
operation_t operation
Operation that the context's key has been initialised for.
Definition: cipher.h:266
cipher_mode_t
Definition: cipher.h:134
cipher_type_t
Definition: cipher.h:82
#define POLARSSL_MAX_BLOCK_LENGTH
Maximum block size of any cipher, in bytes.
Definition: cipher.h:174
size_t unprocessed_len
Number of bytes that still need processing.
Definition: cipher.h:276
int cipher_free_ctx(cipher_context_t *ctx)
Free the cipher-specific context of ctx.
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:235
operation_t
Definition: cipher.h:154
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:168
const char * name
Name of the cipher.
Definition: cipher.h:238
cipher_id_t
Definition: cipher.h:71
#define POLARSSL_MAX_IV_LENGTH
Maximum length of any IV, in bytes.
Definition: cipher.h:172
int cipher_reset(cipher_context_t *ctx)
Finish preparation of the given context.
cipher_id_t cipher
Base Cipher type (e.g.
Definition: cipher.h:182
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:231
cipher_padding_t
Definition: cipher.h:146
static operation_t cipher_get_operation(const cipher_context_t *ctx)
Returns the operation of the given cipher.
Definition: cipher.h:486
PKCS7 padding (default)
Definition: cipher.h:147
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:151
Base cipher information.
Definition: cipher.h:179
const cipher_base_t * base
Base cipher information and functions.
Definition: cipher.h:251
const int * cipher_list(void)
Returns the list of ciphers supported by the generic cipher module.
Undefined key length.
Definition: cipher.h:162
ANSI X.923 padding.
Definition: cipher.h:149
unsigned int block_size
block size, in bytes
Definition: cipher.h:248
void * cipher_ctx
Cipher-specific context.
Definition: cipher.h:285
static int cipher_get_key_size(const cipher_context_t *ctx)
Returns the key length of the cipher.
Definition: cipher.h:469
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:282
int flags
Flags for variable IV size, variable key size, etc.
Definition: cipher.h:245
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:242
Key length, in bits (including parity), for DES in two key EDE.
Definition: cipher.h:166
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...