Rtos API example

Embed: (wiki syntax)

« Back to documentation index

cipher.h File Reference

cipher.h File Reference

Generic cipher wrapper. More...

Go to the source code of this file.

Data Structures

struct  mbedtls_cipher_info_t
 Cipher information. More...
struct  mbedtls_cipher_context_t
 Generic cipher context. More...

Typedefs

typedef struct
mbedtls_cipher_base_t 
mbedtls_cipher_base_t
 Base cipher information (opaque struct).
typedef struct
mbedtls_cmac_context_t 
mbedtls_cmac_context_t
 CMAC context (opaque struct).

Enumerations

enum  mbedtls_cipher_padding_t {
  MBEDTLS_PADDING_PKCS7 = 0, MBEDTLS_PADDING_ONE_AND_ZEROS, MBEDTLS_PADDING_ZEROS_AND_LEN, MBEDTLS_PADDING_ZEROS,
  MBEDTLS_PADDING_NONE
}
enum  { MBEDTLS_KEY_LENGTH_NONE = 0, MBEDTLS_KEY_LENGTH_DES = 64, MBEDTLS_KEY_LENGTH_DES_EDE = 128, MBEDTLS_KEY_LENGTH_DES_EDE3 = 192 }

Functions

const int * mbedtls_cipher_list (void)
 Returns the list of ciphers supported by the generic cipher module.
const mbedtls_cipher_info_tmbedtls_cipher_info_from_string (const char *cipher_name)
 Returns the cipher information structure associated with the given cipher name.
const mbedtls_cipher_info_tmbedtls_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_info_tmbedtls_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.
void mbedtls_cipher_init (mbedtls_cipher_context_t *ctx)
 Initialize a cipher_context (as NONE)
void mbedtls_cipher_free (mbedtls_cipher_context_t *ctx)
 Free and clear the cipher-specific context of ctx.
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.
static unsigned int mbedtls_cipher_get_block_size (const mbedtls_cipher_context_t *ctx)
 Returns the block size of the given cipher.
static mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode (const mbedtls_cipher_context_t *ctx)
 Returns the mode of operation for the cipher.
static int mbedtls_cipher_get_iv_size (const mbedtls_cipher_context_t *ctx)
 Returns the size of the cipher's IV/NONCE in bytes.
static mbedtls_cipher_type_t mbedtls_cipher_get_type (const mbedtls_cipher_context_t *ctx)
 Returns the type of the given cipher.
static const char * mbedtls_cipher_get_name (const mbedtls_cipher_context_t *ctx)
 Returns the name of the given cipher, as a string.
static int mbedtls_cipher_get_key_bitlen (const mbedtls_cipher_context_t *ctx)
 Returns the key length of the cipher.
static mbedtls_operation_t mbedtls_cipher_get_operation (const mbedtls_cipher_context_t *ctx)
 Returns the operation of the given cipher.
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.
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.
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.
int mbedtls_cipher_reset (mbedtls_cipher_context_t *ctx)
 Finish preparation of the given context.
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_update (mbedtls_cipher_context_t *ctx, const unsigned char *input, size_t ilen, unsigned char *output, size_t *olen)
 Generic cipher update function.
int mbedtls_cipher_finish (mbedtls_cipher_context_t *ctx, unsigned char *output, size_t *olen)
 Generic cipher finalisation function.
int mbedtls_cipher_write_tag (mbedtls_cipher_context_t *ctx, unsigned char *tag, size_t tag_len)
 Write tag for AEAD ciphers.
int mbedtls_cipher_check_tag (mbedtls_cipher_context_t *ctx, const unsigned char *tag, size_t tag_len)
 Check tag for AEAD ciphers.
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 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).
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).

Detailed Description

Generic cipher wrapper.

Author:
Adriaan de Jong <dejong@fox-it.com>

Copyright (C) 2006-2015, ARM Limited, All Rights Reserved SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

This file is part of mbed TLS (https://tls.mbed.org)

Definition in file cipher.h.


Typedef Documentation

Base cipher information (opaque struct).

Definition at line 177 of file cipher.h.

CMAC context (opaque struct).

Definition at line 182 of file cipher.h.


Enumeration Type Documentation

anonymous enum
Enumerator:
MBEDTLS_KEY_LENGTH_NONE 

Undefined key length.

MBEDTLS_KEY_LENGTH_DES 

Key length, in bits (including parity), for DES keys.

MBEDTLS_KEY_LENGTH_DES_EDE 

Key length, in bits (including parity), for DES in two key EDE.

MBEDTLS_KEY_LENGTH_DES_EDE3 

Key length, in bits (including parity), for DES in three-key EDE.

Definition at line 158 of file cipher.h.

Enumerator:
MBEDTLS_PADDING_PKCS7 

PKCS7 padding (default)

MBEDTLS_PADDING_ONE_AND_ZEROS 

ISO/IEC 7816-4 padding.

MBEDTLS_PADDING_ZEROS_AND_LEN 

ANSI X.923 padding.

MBEDTLS_PADDING_ZEROS 

zero padding (not reversible!)

MBEDTLS_PADDING_NONE 

never pad (full blocks only)

Definition at line 144 of file cipher.h.


Function Documentation

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).

Parameters:
ctxgeneric cipher context
ivIV to use (or NONCE_COUNTER for CTR-mode ciphers)
iv_lenIV length for ciphers with variable-size IV; discarded by ciphers with fixed-size IV.
adAdditional data to be authenticated.
ad_lenLength of ad.
inputbuffer holding the input data
ilenlength of the input data
outputbuffer for the output data. Should be able to hold at least ilen.
olenlength of the output data, will be filled with the actual number of bytes written.
tagbuffer holding the authentication tag
tag_lenlength of the authentication tag
Returns:
0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or MBEDTLS_ERR_CIPHER_AUTH_FAILED if data isn't authentic, or a cipher specific error code.
Note:
If the data is not authentic, then the output buffer is zeroed out to prevent the unauthentic plaintext to be used by mistake, making this interface safer.

Definition at line 873 of file cipher.c.

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).

Parameters:
ctxgeneric cipher context
ivIV to use (or NONCE_COUNTER for CTR-mode ciphers)
iv_lenIV length for ciphers with variable-size IV; discarded by ciphers with fixed-size IV.
adAdditional data to authenticate.
ad_lenLength of ad.
inputbuffer holding the input data
ilenlength of the input data
outputbuffer for the output data. Should be able to hold at least ilen.
olenlength of the output data, will be filled with the actual number of bytes written.
tagbuffer for the authentication tag
tag_lendesired tag length
Returns:
0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or a cipher specific error code.

Definition at line 841 of file cipher.c.

int mbedtls_cipher_check_tag ( mbedtls_cipher_context_t ctx,
const unsigned char *  tag,
size_t  tag_len 
)

Check tag for AEAD ciphers.

Currently only supported with GCM. Must be called after mbedtls_cipher_finish().

Parameters:
ctxGeneric cipher context
tagBuffer holding the tag
tag_lenLength of the tag to check
Returns:
0 on success, or a specific error code.

Definition at line 769 of file cipher.c.

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).

Parameters:
ctxgeneric cipher context
ivIV to use (or NONCE_COUNTER for CTR-mode ciphers)
iv_lenIV length for ciphers with variable-size IV; discarded by ciphers with fixed-size IV.
inputbuffer holding the input data
ilenlength of the input data
outputbuffer for the output data. Should be able to hold at least ilen + block_size. Cannot be the same buffer as input!
olenlength of the output data, will be filled with the actual number of bytes written.
Note:
Some ciphers don't use IVs nor NONCE. For these ciphers, use iv = NULL and iv_len = 0.
Returns:
0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA, or MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption expected a full block but was not provided one, or MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding while decrypting, or a cipher specific error code.

Definition at line 812 of file cipher.c.

int mbedtls_cipher_finish ( mbedtls_cipher_context_t ctx,
unsigned char *  output,
size_t *  olen 
)

Generic cipher finalisation function.

If data still needs to be flushed from an incomplete block, data contained within it will be padded with the size of the last block, and written to the output buffer.

Parameters:
ctxGeneric cipher context
outputbuffer to write data to. Needs block_size available.
olenlength of the data written to the output buffer.
Returns:
0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if parameter verification fails, MBEDTLS_ERR_CIPHER_FULL_BLOCK_EXPECTED if decryption expected a full block but was not provided one, MBEDTLS_ERR_CIPHER_INVALID_PADDING on invalid padding while decrypting or a cipher specific error code.

Definition at line 626 of file cipher.c.

void mbedtls_cipher_free ( mbedtls_cipher_context_t ctx )

Free and clear the cipher-specific context of ctx.

Freeing ctx itself remains the responsibility of the caller.

Definition at line 136 of file cipher.c.

static unsigned int mbedtls_cipher_get_block_size ( const mbedtls_cipher_context_t ctx ) [static]

Returns the block size of the given cipher.

Parameters:
ctxcipher's context. Must have been initialised.
Returns:
size of the cipher's blocks, or 0 if ctx has not been initialised.

Definition at line 340 of file cipher.h.

static mbedtls_cipher_mode_t mbedtls_cipher_get_cipher_mode ( const mbedtls_cipher_context_t ctx ) [static]

Returns the mode of operation for the cipher.

(e.g. MBEDTLS_MODE_CBC)

Parameters:
ctxcipher's context. Must have been initialised.
Returns:
mode of operation, or MBEDTLS_MODE_NONE if ctx has not been initialised.

Definition at line 357 of file cipher.h.

static int mbedtls_cipher_get_iv_size ( const mbedtls_cipher_context_t ctx ) [static]

Returns the size of the cipher's IV/NONCE in bytes.

Parameters:
ctxcipher's context. Must have been initialised.
Returns:
If IV has not been set yet: (recommended) IV size (0 for ciphers not using IV/NONCE). If IV has already been set: actual size.

Definition at line 374 of file cipher.h.

static int mbedtls_cipher_get_key_bitlen ( const mbedtls_cipher_context_t ctx ) [static]

Returns the key length of the cipher.

Parameters:
ctxcipher's context. Must have been initialised.
Returns:
cipher's key length, in bits, or MBEDTLS_KEY_LENGTH_NONE if ctx has not been initialised.

Definition at line 425 of file cipher.h.

static const char* mbedtls_cipher_get_name ( const mbedtls_cipher_context_t ctx ) [static]

Returns the name of the given cipher, as a string.

Parameters:
ctxcipher's context. Must have been initialised.
Returns:
name of the cipher, or NULL if ctx was not initialised.

Definition at line 408 of file cipher.h.

static mbedtls_operation_t mbedtls_cipher_get_operation ( const mbedtls_cipher_context_t ctx ) [static]

Returns the operation of the given cipher.

Parameters:
ctxcipher's context. Must have been initialised.
Returns:
operation (MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT), or MBEDTLS_OPERATION_NONE if ctx has not been initialised.

Definition at line 442 of file cipher.h.

static mbedtls_cipher_type_t mbedtls_cipher_get_type ( const mbedtls_cipher_context_t ctx ) [static]

Returns the type of the given cipher.

Parameters:
ctxcipher's context. Must have been initialised.
Returns:
type of the cipher, or MBEDTLS_CIPHER_NONE if ctx has not been initialised.

Definition at line 393 of file cipher.h.

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.

Parameters:
cipher_nameName of the cipher to search for.
Returns:
the cipher information structure associated with the given cipher_name, or NULL if not found.

Definition at line 102 of file cipher.c.

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.

Parameters:
cipher_typeType of the cipher to search for.
Returns:
the cipher information structure associated with the given cipher_type, or NULL if not found.

Definition at line 91 of file cipher.c.

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.

Parameters:
cipher_idId of the cipher to search for (e.g. MBEDTLS_CIPHER_ID_AES)
key_bitlenLength of the key in bits
modeCipher mode (e.g. MBEDTLS_MODE_CBC)
Returns:
the cipher information structure associated with the given cipher_type, or NULL if not found.

Definition at line 116 of file cipher.c.

void mbedtls_cipher_init ( mbedtls_cipher_context_t ctx )

Initialize a cipher_context (as NONE)

Definition at line 131 of file cipher.c.

const int* mbedtls_cipher_list ( void   )

Returns the list of ciphers supported by the generic cipher module.

Returns:
a statically allocated array of ciphers, the last entry is 0.

Definition at line 70 of file cipher.c.

int mbedtls_cipher_reset ( mbedtls_cipher_context_t ctx )

Finish preparation of the given context.

Parameters:
ctxgeneric cipher context
Returns:
0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if parameter verification fails.

Definition at line 243 of file cipher.c.

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.

Parameters:
ctxgeneric cipher context
ivIV to use (or NONCE_COUNTER for CTR-mode ciphers)
iv_lenIV length for ciphers with variable-size IV; discarded by ciphers with fixed-size IV.
Returns:
0 on success, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA
Note:
Some ciphers don't use IVs nor NONCE. For these ciphers, this function has no effect.

Definition at line 214 of file cipher.c.

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.

(Default: PKCS7 padding.)

Parameters:
ctxgeneric cipher context
modepadding mode
Returns:
0 on success, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE if selected padding mode is not supported, or MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if the cipher mode does not support padding.

Definition at line 706 of file cipher.c.

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.

Parameters:
ctxgeneric cipher context. May not be NULL. Must have been initialised using cipher_context_from_type or cipher_context_from_string.
keyThe key to use.
key_bitlenkey length to use, in bits.
operationOperation that the key will be used for, either MBEDTLS_ENCRYPT or MBEDTLS_DECRYPT.
Returns:
0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if parameter verification fails or a cipher specific error code.

Definition at line 181 of file cipher.c.

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.

Note:
Currently also clears structure. In future versions you will be required to call mbedtls_cipher_init() on the structure first.
Parameters:
ctxcontext to initialise. May not be NULL.
cipher_infocipher to use.
Returns:
0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA on parameter failure, MBEDTLS_ERR_CIPHER_ALLOC_FAILED if allocation of the cipher-specific context failed.

Definition at line 155 of file cipher.c.

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.

Encrypts/decrypts using the given cipher context. Writes as many block size'd blocks of data as possible to output. Any data that cannot be written immediately will either be added to the next block, or flushed when cipher_final is called. Exception: for MBEDTLS_MODE_ECB, expects single block in size (e.g. 16 bytes for AES)

Parameters:
ctxgeneric cipher context
inputbuffer holding the input data
ilenlength of the input data
outputbuffer for the output data. Should be able to hold at least ilen + block_size. Cannot be the same buffer as input!
olenlength of the output data, will be filled with the actual number of bytes written.
Returns:
0 on success, MBEDTLS_ERR_CIPHER_BAD_INPUT_DATA if parameter verification fails, MBEDTLS_ERR_CIPHER_FEATURE_UNAVAILABLE on an unsupported mode for a cipher or a cipher specific error code.
Note:
If the underlying cipher is GCM, all calls to this function, except the last one before mbedtls_cipher_finish(), must have ilen a multiple of the block size.

Definition at line 270 of file cipher.c.

int mbedtls_cipher_update_ad ( mbedtls_cipher_context_t ctx,
const unsigned char *  ad,
size_t  ad_len 
)

Add additional data (for AEAD ciphers).

Currently only supported with GCM. Must be called exactly once, after mbedtls_cipher_reset().

Parameters:
ctxgeneric cipher context
adAdditional data to use.
ad_lenLength of ad.
Returns:
0 on success, or a specific error code.

Definition at line 254 of file cipher.c.

int mbedtls_cipher_write_tag ( mbedtls_cipher_context_t ctx,
unsigned char *  tag,
size_t  tag_len 
)

Write tag for AEAD ciphers.

Currently only supported with GCM. Must be called after mbedtls_cipher_finish().

Parameters:
ctxGeneric cipher context
tagbuffer to write the tag
tag_lenLength of the tag to write
Returns:
0 on success, or a specific error code.

Definition at line 754 of file cipher.c.