m2mb API docs  30.00.009.1
m2mb API sets documentation
Macros | Enumerations | Functions
M2MB_AES
M2MB_CRYPTO » M2MB_CMAC

AES CBC & ECB algorithm implementation. https://tools.ietf.org/pdf/rfc3602.pdf http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf. More...

Collaboration diagram for M2MB_AES:

Macros

#define M2MB_CRYPTO_AES_ECB_BLOCK_SIZE   16
 
#define M2MB_CRYPTO_AES_IV_SIZE   16
 

Enumerations

enum  M2MB_CRYPTO_AES_MODE_E { M2MB_CRYPTO_AES_MODE_ENCRYPT, M2MB_CRYPTO_AES_MODE_DECRYPT }
 AES operation mode (encrypt decrypt)
 

Functions

M2MB_RESULT_E m2mb_crypto_aes_init (M2MB_CRYPTO_AES_CONTEXT *ctx)
 Allocates an M2MB_CRYPTO_AES_CONTEXT structure. More...
 
M2MB_RESULT_E m2mb_crypto_aes_deinit (M2MB_CRYPTO_AES_CONTEXT ctx)
 Free an M2MB_CRYPTO_AES_CONTEXT structure. More...
 
M2MB_RESULT_E m2mb_crypto_aes_generate_key (M2MB_CRYPTO_AES_CONTEXT ctx, UINT32 keybits)
 Generates an AES encryption key for a given context. More...
 
M2MB_RESULT_E m2mb_crypto_aes_keyblob_export (M2MB_CRYPTO_AES_CONTEXT ctx, UINT8 *keyblob, UINT32 *keyblob_length)
 Exports the AES symmetric key from the given context. More...
 
M2MB_RESULT_E m2mb_crypto_aes_keyblob_import (M2MB_CRYPTO_AES_CONTEXT ctx, const UINT8 *keyblob, UINT32 keyblob_length)
 Import a symmetric key, previously generated on the same device, into a given context. More...
 
M2MB_RESULT_E m2mb_crypto_aes_externalkey_import (M2MB_CRYPTO_AES_CONTEXT ctx, const UINT8 *key, UINT32 keylength)
 Imports a symmetric key into the given context. This is a plaintext key that may have been generated externally. More...
 
M2MB_RESULT_E m2mb_crypto_aes_ecb_encdec (M2MB_CRYPTO_AES_CONTEXT ctx, M2MB_CRYPTO_AES_MODE_E mode, const UINT8 in[M2MB_CRYPTO_AES_ECB_BLOCK_SIZE], UINT8 out[M2MB_CRYPTO_AES_ECB_BLOCK_SIZE])
 Encrypts/decrypts a single 16 bytes block onto the output buffer using the AES ECB algorithm. More...
 
M2MB_RESULT_E m2mb_crypto_aes_cbc_encdec (M2MB_CRYPTO_AES_CONTEXT ctx, M2MB_CRYPTO_AES_MODE_E mode, const UINT8 *in, UINT8 *out, SIZE_T inlen, UINT8 ivec[M2MB_CRYPTO_AES_IV_SIZE])
 Encrypts/decrypts a given buffer with a given length using the AES CBC. The length must be a multiple of the block size (16 bytes). More...
 

Detailed Description

AES CBC & ECB algorithm implementation. https://tools.ietf.org/pdf/rfc3602.pdf http://csrc.nist.gov/publications/fips/fips197/fips-197.pdf.

Macro Definition Documentation

◆ M2MB_CRYPTO_AES_ECB_BLOCK_SIZE

#define M2MB_CRYPTO_AES_ECB_BLOCK_SIZE   16

AES ecb block size

◆ M2MB_CRYPTO_AES_IV_SIZE

#define M2MB_CRYPTO_AES_IV_SIZE   16

AES ecb initialization vector size

Function Documentation

◆ m2mb_crypto_aes_cbc_encdec()

M2MB_RESULT_E m2mb_crypto_aes_cbc_encdec ( M2MB_CRYPTO_AES_CONTEXT  ctx,
M2MB_CRYPTO_AES_MODE_E  mode,
const UINT8 *  in,
UINT8 *  out,
SIZE_T  inlen,
UINT8  ivec[M2MB_CRYPTO_AES_IV_SIZE] 
)

Encrypts/decrypts a given buffer with a given length using the AES CBC. The length must be a multiple of the block size (16 bytes).

This function will encrypt/decrypt (depending on the mode parameter) <inlen> bytes from the <in> buffer and store the output into the <out> buffer. The ivec will be updated as part of this function call to allow consecuritve calls to encrypt a stream of data. If it is required to encrypt several independant buffers (which are not related to each other), the ivec should be restored by the caller (i.e. storing a local copy of the ivec).

Parameters
[in]ctxPointer to a context structure previously initialized by m2mb_crypto_aes_init()
[in]modeThe requested operation mode (encrypt/decrypt)
[in]inThe input buffer to encrypt/decrypt
[out]outThe output buffer to store the result encryption/decryption values, must have 16 bytes allocated space
[in]inlenThe length of the input data (<in>), must be multiple of block size (16 bytes)
[in]ivecInitialization vector. The ivec is updated after each use to allow working in "streaming" mode
Returns
M2MB_RESULT_SUCCESS on success
see M2MB_RESULT_E for different values in case of fail
Note
m2mb_crypto_aes_init() must be called before using this function.

◆ m2mb_crypto_aes_deinit()

M2MB_RESULT_E m2mb_crypto_aes_deinit ( M2MB_CRYPTO_AES_CONTEXT  ctx)

Free an M2MB_CRYPTO_AES_CONTEXT structure.

This function free a previously allocated AES context.

Parameters
[in]ctxPointer to a context structure to be free by this function.
Returns
M2MB_RESULT_SUCCESS on success
see M2MB_RESULT_E for different values in case of fail
Note

◆ m2mb_crypto_aes_ecb_encdec()

M2MB_RESULT_E m2mb_crypto_aes_ecb_encdec ( M2MB_CRYPTO_AES_CONTEXT  ctx,
M2MB_CRYPTO_AES_MODE_E  mode,
const UINT8  in[M2MB_CRYPTO_AES_ECB_BLOCK_SIZE],
UINT8  out[M2MB_CRYPTO_AES_ECB_BLOCK_SIZE] 
)

Encrypts/decrypts a single 16 bytes block onto the output buffer using the AES ECB algorithm.

This function will encrypt/decrypt (depending on the <mode> parameter) a given 16 bytes length input buffer and will store the result into the output 16 bytes buffer.

Parameters
[in]ctxPointer to a context structure previously initialized by m2mb_crypto_aes_init()
[in]modeThe requested operation mode (encrypt/decrypt)
[in]inThe input buffer to encrypt/decrypt, 16 bytes length
[out]outThe output buffer to store the result encryption/decryption values, must have 16 bytes allocated space
Returns
M2MB_RESULT_SUCCESS on success
see M2MB_RESULT_E for different values in case of fail
Note
m2mb_crypto_aes_init() must be called before using this function.

◆ m2mb_crypto_aes_externalkey_import()

M2MB_RESULT_E m2mb_crypto_aes_externalkey_import ( M2MB_CRYPTO_AES_CONTEXT  ctx,
const UINT8 *  key,
UINT32  keylength 
)

Imports a symmetric key into the given context. This is a plaintext key that may have been generated externally.

This function sets up a key with a given size to a context to be later used by any AES encryption function. Assumption made is that this is a plaintext key and this API is to serve a key that was generated outside of the device. AES is a symmetric encryption, i.e. same key is used for encryption and decryption.

Parameters
[in]ctxPointer to a context structure previously initialized by m2mb_crypto_aes_init().
[in]keyPointer to a key to setup. The key is in the size of keybits bits. This key is a plaintext key created externally.
[in]keylengthThe number of bytes in the given key, must be 16, 26, 32 (128, 192, 256 bits key).
Returns
M2MB_RESULT_SUCCESS on success
see M2MB_RESULT_E for different values in case of fail
Note
m2mb_crypto_aes_init() must be called before using this function.

◆ m2mb_crypto_aes_generate_key()

M2MB_RESULT_E m2mb_crypto_aes_generate_key ( M2MB_CRYPTO_AES_CONTEXT  ctx,
UINT32  keybits 
)

Generates an AES encryption key for a given context.

This function generates a symmetric AES key with a given size and stores it into the context to be later used by any AES encryption function. AES is a symmetric encryption, i.e. same key is used for encryption and decryption.

Parameters
[in]ctxPointer to a context structure previously initialized by m2mb_crypto_aes_init()
[in]keybitsThe number of bits in the given key, must be 128, 192 or 256
Returns
M2MB_RESULT_SUCCESS on success
see M2MB_RESULT_E for different values in case of fail
Note
m2mb_crypto_aes_init() must be called before using this function.

◆ m2mb_crypto_aes_init()

M2MB_RESULT_E m2mb_crypto_aes_init ( M2MB_CRYPTO_AES_CONTEXT *  ctx)

Allocates an M2MB_CRYPTO_AES_CONTEXT structure.

This function allocates an AES context to be later used by any AES ciphering function.

Parameters
[in]ctxPointer to a context structure to be allocated by this function. Any consecutive call to AES function must use the context.
Returns
M2MB_RESULT_SUCCESS on success
see M2MB_RESULT_E for different values in case of fail
Note

◆ m2mb_crypto_aes_keyblob_export()

M2MB_RESULT_E m2mb_crypto_aes_keyblob_export ( M2MB_CRYPTO_AES_CONTEXT  ctx,
UINT8 *  keyblob,
UINT32 *  keyblob_length 
)

Exports the AES symmetric key from the given context.

This function exports the AES symmetric key from the given context. The key information will be exported from the given context (assuming context has keys associated, either imported or via m2mb_crypto_aes_generate_key()). The key blob is encrypted with a device specific key and can only be used on the same HW originating it.

Parameters
[in]ctxPointer to a context structure previously allocated by m2mb_crypto_rsa_init.
[out]keyblobThe buffer that will hold the result keyblob representing the exported AES symmetric key. If keyblob ptr is NULL, this function will return the number of bytes required for the keyblob via the keyblob_length pointer. The key blob is encrypted with a device specific key and can only be used on the same HW originating it.
[out]keyblob_lengthThe length of the AES key blob
Returns
M2MB_RESULT_SUCCESS on success
see M2MB_RESULT_E for different values in case of fail
Note
m2mb_crypto_aes_init() & m2mb_crypto_aes_generate_key() (or keys were set via m2mb_crypto_aes_set_encrypt_key(), m2mb_crypto_aes_set_decrypt_key()) must be called before using this function.

Example

int main()
{
M2MB_RESULT_E res ;
M2MB_CRYPTO_AES_CONTEXT_T * ctx = NULL;
UINT8 *keyblob = NULL;
UINT32 keyblob_length;
......
res = m2mb_crypto_aes_init( &ctx );
res = m2mb_crypto_aes_generate_key( ctx,256);
res = m2mb_crypto_aes_keyblob_export( ctx,
keyblob,
&keyblob_length );
keyblob = (UINT8*)m2mb_os_malloc( keyblob_length );
.....
res = m2mb_crypto_aes_keyblob_export( ctx,
keyblob,
&keyblob_length );
}

◆ m2mb_crypto_aes_keyblob_import()

M2MB_RESULT_E m2mb_crypto_aes_keyblob_import ( M2MB_CRYPTO_AES_CONTEXT  ctx,
const UINT8 *  keyblob,
UINT32  keyblob_length 
)

Import a symmetric key, previously generated on the same device, into a given context.

This function keyblob into a context to be later used by any AES encryption function. Assumption made is that this is not a plaintext key but a ciphered key that was previously generated via m2mb_crypto_aes_generate_key() and was exported via m2mb_crypto_aes_key_export(). Another option might be that the key was generated via the ECDH key derivation (via m2mb_crypto_ecdh_shared_key_derive()). AES is a symmetric encryption, i.e. same key is used for encryption and decryption.

Parameters
[in]ctxPointer to a context structure previously initialized by m2mb_crypto_aes_init().
[in]keyblobPointer to a keyblob to setup. The key blob is encrypted with a device specific key and can only be used on the same HW originating it.
[in]keyblob_lengthThe length of the keyblob buffer.
Returns
M2MB_RESULT_SUCCESS on success
see M2MB_RESULT_E for different values in case of fail
Note
m2mb_crypto_aes_init() must be called before using this function.

m2mb_crypto_aes_keyblob_export
M2MB_RESULT_E m2mb_crypto_aes_keyblob_export(M2MB_CRYPTO_AES_CONTEXT ctx, UINT8 *keyblob, UINT32 *keyblob_length)
Exports the AES symmetric key from the given context.
m2mb_os_malloc
void * m2mb_os_malloc(UINT32 size)
Allocates bytes of memory.
m2mb_crypto_aes_init
M2MB_RESULT_E m2mb_crypto_aes_init(M2MB_CRYPTO_AES_CONTEXT *ctx)
Allocates an M2MB_CRYPTO_AES_CONTEXT structure.
m2mb_crypto_aes_generate_key
M2MB_RESULT_E m2mb_crypto_aes_generate_key(M2MB_CRYPTO_AES_CONTEXT ctx, UINT32 keybits)
Generates an AES encryption key for a given context.