The ColdFire/ColdFire+ CAU (cryptographic acceleration unit) software library is a set of low-level cryptographic functions implemented using CAU co-processor instructions. The Kinetis mmCAU (memory mapped cryptographic unit) software library uses the mmCAU co-processor that is connected to the Kinetis ARM Cortex-M4 Private Peripheral Bus (PPB). In the the rest of the chapter, CAU refers to both CAU and mmCAU unless explicitly noted. Also, both software libraries share the same application programming interface (API). Both interfaces are referenced as a single definition throughout the chapter unless explicitly noted.
Purpose
The following chapter describes how to use the CAU and mmCAU software library in any application that needs to integrate a cryptographic algorithm or hashing function supported by the software library. Freescale products supported by the software library are ColdFire, ColdFire+, and Kinetis MCU/MPUs. Check the specific Freescale product for CAU and mmCAU availability.
Library Features
The library is as compact and generic as possible to simplify integration with existing cryptographic software. The library has a standard header file with ANSI C prototypes for all functions. This software library is thread safe only if CAU registers are saved on a context switch. The ColdFire/ColdFire+ CAU software library adheres to ColdFire C language compiler conventions (ABI) using standard parameter passing (stack passing). The Kinetis mmCAU software library is also compatible to ARM C compiler conventions (EABI). Only ColdFire and Kinetis devices with the CAU or mmCAU hardware coprocessors are supported. For best performance, input and output data blocks must be aligned on 0‐modulo‐4 byte addresses.
The CAU library supports the following encryption/decryption algorithms and hashing functions:
-
AES128
-
AES192
-
AES256
-
DES
-
3DES
-
MD5
-
SHA1
-
SHA256
Note: 3DES crypto algorithms are supported by calling the corresponding DES crypto function three times. Hardware support for SHA256 is only present in the CAU version 2. See the appropriate MCU/MPU reference manual for details about availability. Additionally, the cau_sha256_initialize_output() function checks the hardware revision and returns a (‐1) value if the CAU lacks SHA256 support.
CAU and mmCAU software library overview
Table 1 shows the crypto algorithms and hashing functions included in the software library:
| Crypto Algorithms | AES128
AES192
AES256 | cau_aes_set_key |
| cau_aes_encrypt |
| cau_aes_decrypt |
| DES/3DES | cau_des_chk_parity |
| cau_des_encrypt |
| cau_des_decrypt |
| Hashing Functions | MD5 | cau_md5_initialize_output |
| cau_md5_hash_n |
| cau_md5_update |
| cau_md5_hash |
| SHA1 | cau_sha1_initialize_output |
| cau_sha1_hash_n |
| cau_sha1_update |
| cau_sha1_hash |
| SHA256 | cau_sha256_initialize_output |
| cau_sha256_hash_n |
| cau_sha256_update |
| cau_sha256_hash |
Table 1: Library Overview
CAU and mmCAU software library usage
The software library contains the following files:
| File | Description |
| cau_api.h | CAU and mmCAU header file |
| cau_lib.a | CAU library: ColdFire/ColdFire+ |
| mmcau_lib.a | mmCAU library: Kinetis |
Table 2: File Description
The header file must always be included in the project. Only the cau_lib.a or mmcau_lib.a must be included in the project depending on CAU or mmCAU hardware presence.
The header file is shared between the CAU and mmCAU software library, however only one of the following C language macros must be defined for the project to include CAU or mmCAU respectively.
| Macro | Description |
| FREESCALE_CAU | Using CAU software library |
| FREESCALE_MMCAU | Using mmCAU software library |
Table 3: C‐language Macros Description
Example:
#define FREESCALE_CAU //CAU functions are implemented in cau_lib.a library
When using FREESCALE_CAU on ColdFire/ColdFire+ products, standard memory-based parameter passing is assumed. This feature assumes arguments are provided to the library functions using the stack and NOT by using the CPU registers (register parameter passing). This argument passing format is required by Freescale CodeWarrior compiler. If using another compiler, parameter passing must be properly selected for argument stack usage.
Note:
For CodeWarrior, by adding the compiler directive __declspec (standard_abi), a function is forced to use standard parameter passing:
__declspec (standard_abi)
void
cau_aes_set_key (const
unsigned char *key, const
int key_size,
unsigned char*key_sch);
|
| void | cau_aes_set_key (const unsigned char *key, const int key_size, unsigned char *key_sch) |
| | AES: Performs an AES key expansion. More...
|
| |
| void | cau_aes_encrypt (const unsigned char *in, const unsigned char *key_sch, const int nr, unsigned char *out) |
| | AES: Encrypts a single 16‐byte block. More...
|
| |
| void | cau_aes_decrypt (const unsigned char *in, const unsigned char *key_sch, const int nr, unsigned char *out) |
| | AES: Decrypts a single 16‐byte block. More...
|
| |
| int | cau_des_chk_parity (const unsigned char *key) |
| | DES: Checks key parity. More...
|
| |
| void | cau_des_encrypt (const unsigned char *in, const unsigned char *key, unsigned char *out) |
| | DES: Encrypts a single 8‐byte block. More...
|
| |
| void | cau_des_decrypt (const unsigned char *in, const unsigned char *key, unsigned char *out) |
| | DES: Decrypts a single 8‐byte block. More...
|
| |
| void | cau_md5_initialize_output (const unsigned char *md5_state) |
| | MD5: Initializes the MD5 state variables. More...
|
| |
| void | cau_md5_hash_n (const unsigned char *msg_data, const int num_blks, unsigned char *md5_state) |
| | MD5: Updates MD5 state variables. More...
|
| |
| void | cau_md5_update (const unsigned char *msg_data, const int num_blks, unsigned char *md5_state) |
| | MD5: Updates MD5 state variables. More...
|
| |
| void | cau_md5_hash (const unsigned char *msg_data, unsigned char *md5_state) |
| | MD5: Performs MD5 hash algorithm. More...
|
| |
| void | cau_sha1_initialize_output (const unsigned int *sha1_state) |
| | SHA1: Initializes the SHA1 state variables. More...
|
| |
| void | cau_sha1_hash_n (const unsigned char *msg_data, const int num_blks, unsigned int *sha1_state) |
| | SHA1: Performs the hash and generate SHA1 state variables. More...
|
| |
| void | cau_sha1_update (const unsigned char *msg_data, const int num_blks, unsigned int *sha1_state) |
| | SHA1: Updates SHA1 state variables. More...
|
| |
| void | cau_sha1_hash (const unsigned char *msg_data, unsigned int *sha1_state) |
| | SHA1: Performs SHA1 hash algorithm. More...
|
| |
| int | cau_sha256_initialize_output (const unsigned int *output) |
| | SHA256: Initializes the hash output and checks the CAU hardware revision. More...
|
| |
| void | cau_sha256_hash_n (const unsigned char *input, const int num_blks, unsigned int *output) |
| | SHA256: Updates SHA256 digest output. More...
|
| |
| void | cau_sha256_update (const unsigned char *input, const int num_blks, unsigned int *output) |
| | SHA256: Updates SHA256 state variables. More...
|
| |
| void | cau_sha256_hash (const unsigned char *input, unsigned int *output) |
| | SHA256: Performs SHA256 hash algorithm. More...
|
| |
| void cau_aes_set_key |
( |
const unsigned char * |
key, |
|
|
const int |
key_size, |
|
|
unsigned char * |
key_sch |
|
) |
| |
This function performs an AES key expansion
- Parameters
-
| [in] | *key | pointer to input key (128, 192, 256 bits in length) |
| [in] | key_size | key_size in bits (128, 192, 256) |
| [out] | *key_sch | pointer to key schedule output (44, 52, 60 longwords) |
- Returns
- None
- Note
- Table 4 shows the requirements for the cau_aes_set_key() function when using AES128, AES192 or AES256.
| [in] Block Size (bits) | [out] Key Schedule Size (32 bit data values) |
| 128 | 44 |
| 192 | 52 |
| 256 | 60 |
Table 4: AES set_key Requirements
| void cau_aes_encrypt |
( |
const unsigned char * |
in, |
|
|
const unsigned char * |
key_sch, |
|
|
const int |
nr, |
|
|
unsigned char * |
out |
|
) |
| |
This function encrypts a single 16-byte block for AES128, AES192 or AES256
- Parameters
-
| [in] | *in | pointer to 16‐byte block of input plaintext |
| [in] | *key_sch | pointer to key schedule (44, 52, 60 longwords) |
| [in] | nr | number of AES rounds (10, 12, 14 = f(key_schedule)) |
| [out] | *out | pointer to 16‐byte block of output ciphertext |
- Returns
- None
- Note
- Input and output blocks may overlap.
Table 5 shows the requirements for the cau_aes_encrypt()/cau_aes_decrypt() function when using AES128, AES192 or AES256.
| Block Cipher | [in] Key Schedule Size (longwords) | [in] Number of AES rounds |
| AES128 | 44 | 10 |
| AES192 | 52 | 12 |
| AES256 | 60 | 14 |
Table 5: AES Encryption Requirements
| void cau_aes_decrypt |
( |
const unsigned char * |
in, |
|
|
const unsigned char * |
key_sch, |
|
|
const int |
nr, |
|
|
unsigned char * |
out |
|
) |
| |
This function decrypts a single 16‐byte block for AES128, AES192 and AES256
- Parameters
-
| [in] | *in | pointer to 16‐byte block of input ciphertext |
| [in] | *key_sch | pointer to key schedule (44, 52, 60 longwords) |
| [in] | nr | number of AES rounds (10, 12, 14 = f(key_schedule)) |
| [out] | *out | pointer to 16‐byte block of output plaintext |
- Returns
- None
- Note
- Input and output blocks may overlap.
Table 6 shows the requirements for the cau_aes_encrypt()/cau_aes_decrypt() function when using AES128, AES192 or AES256.
| Block Cipher | [in] Key Schedule Size (longwords) | [in] Number of AES rounds |
| AES128 | 44 | 10 |
| AES192 | 52 | 12 |
| AES256 | 60 | 14 |
Table 6: AES Decryption Requirements
| int cau_des_chk_parity |
( |
const unsigned char * |
key | ) |
|
This function checks the parity of a key
- Parameters
-
| [in] | *key | pointer to 64‐bit DES key with parity bits |
- Returns
- 0 no error
-
-1 parity error
| void cau_des_encrypt |
( |
const unsigned char * |
in, |
|
|
const unsigned char * |
key, |
|
|
unsigned char * |
out |
|
) |
| |
This function encrypt a single 8-byte block
- Parameters
-
| [in] | *in | pointer to 8‐byte block of input plaintext |
| [in] | *key | pointer to 64‐bit DES key with parity bits |
| [out] | *out | pointer to 8‐byte block of output ciphertext |
- Returns
- None
- Note
- Input and output blocks may overlap.
| void cau_des_decrypt |
( |
const unsigned char * |
in, |
|
|
const unsigned char * |
key, |
|
|
unsigned char * |
out |
|
) |
| |
This function decrypt a single 8-byte block
- Parameters
-
| [in] | *in | pointer to 8‐byte block of input ciphertext |
| [in] | *key | pointer to 64‐bit DES key with parity bits |
| [out] | *out | pointer to 8‐byte block of output plaintext |
- Returns
- None
- Note
- Input and output blocks may overlap.
| void cau_md5_initialize_output |
( |
const unsigned char * |
md5_state | ) |
|
This function initializes the MD5 state variables
- Parameters
-
| [out] | *md5_state | pointer to 120‐bit block of md5 state variables: a,b,c,d |
- Returns
- None
| void cau_md5_hash_n |
( |
const unsigned char * |
msg_data, |
|
|
const int |
num_blks, |
|
|
unsigned char * |
md5_state |
|
) |
| |
This function updates MD5 state variables for one or more input message blocks
- Parameters
-
| [in] | *msg_data | pointer to start of input message data |
| [in] | num_blks | number of 512‐bit blocks to process |
| [in,out] | *md5_state | pointer to 128‐bit block of MD5 state variables: a,b,c,d |
- Returns
- None
- Note
- Input message and digest output blocks must not overlap. The cau_md5_initialize_output() function must be called first. Useful when handling non‐contiguous input message blocks.
| void cau_md5_update |
( |
const unsigned char * |
msg_data, |
|
|
const int |
num_blks, |
|
|
unsigned char * |
md5_state |
|
) |
| |
This function updates MD5 state variables for one or more input message blocks
- Parameters
-
| [in] | *msg_data | pointer to start of input message data |
| [in] | num_blks | number of 512‐bit blocks to process |
| [in,out] | *md5_state | pointer to 128‐bit block of MD5 state variables: a,b,c,d |
- Returns
- None
- Note
- Input message and digest output blocks must not overlap. The cau_md5_initialize_output() function is not required. All input message blocks must be contiguous.
| void cau_md5_hash |
( |
const unsigned char * |
msg_data, |
|
|
unsigned char * |
md5_state |
|
) |
| |
This function performs MD5 hash algorithm for a single input message block
- Parameters
-
| [in] | *msg_data | pointer to start of input message data |
| [in,out] | *md5_state | pointer to 128‐bit block of MD5 state variables: a,b,c,d |
- Returns
- None
- Note
- Input message and digest output blocks must not overlap. The cau_md5_initialize_output() function must be called first. Only works for a single input message block.
| void cau_sha1_initialize_output |
( |
const unsigned int * |
sha1_state | ) |
|
This function initializes the SHA1 state variables
- Parameters
-
| [out] | *sha1_state | pointer to 160‐bit block of SHA1 state variables: a,b,c,d,e |
- Returns
- None
| void cau_sha1_hash_n |
( |
const unsigned char * |
msg_data, |
|
|
const int |
num_blks, |
|
|
unsigned int * |
sha1_state |
|
) |
| |
This function performs the hash and generate SHA1 state variables for one or more input message blocks
- Parameters
-
| [in] | *msg_data | pointer to start of input message data |
| [in] | num_blks | number of 512‐bit blocks to process |
| [in,out] | *sha1_state | pointer to 160‐bit block of SHA1 state variables: a,b,c,d,e |
- Returns
- None
- Note
- Input message and digest output blocks must not overlap. The cau_sha1_initialize_output() function must be called first. Useful when handling non‐contiguous input message blocks.
| void cau_sha1_update |
( |
const unsigned char * |
msg_data, |
|
|
const int |
num_blks, |
|
|
unsigned int * |
sha1_state |
|
) |
| |
This function updates SHA1 state variables for one or more input message blocks arguments
- Parameters
-
| [in] | *msg_data | pointer to start of input message data |
| [in] | num_blks | number of 512‐bit blocks to process |
| [out] | *sha1_state | pointer to 160‐bit block of SHA1 state variables: a,b,c,d,e |
- Returns
- None
- Note
- Input message and digest output blocks must not overlap. The cau_sha1_initialize_output() function is not required. All input message blocks must be contiguous.
| void cau_sha1_hash |
( |
const unsigned char * |
msg_data, |
|
|
unsigned int * |
sha1_state |
|
) |
| |
This function performs SHA1 hash algorithm on a single input message block
- Parameters
-
| [in] | *msg_data | pointer to start of input message data |
| [in,out] | *sha1_state | pointer to 160‐bit block of SHA1 state variables: a,b,c,d,e |
- Returns
- None
- Note
- Input message and digest output blocks must not overlap. The cau_sha1_initialize_output() function must be called first. Only works for a single input message block.
| int cau_sha256_initialize_output |
( |
const unsigned int * |
output | ) |
|
This function initializes the hash output and checks the CAU hardware revision
- Parameters
-
| [out] | *output | pointer to 256‐bit message digest output |
- Returns
- 0 No error. CAU2 hardware present. SHA256 HW support available
-
-1 Error. CAU2 hardware not present. No SHA256 HW support available
| void cau_sha256_hash_n |
( |
const unsigned char * |
input, |
|
|
const int |
num_blks, |
|
|
unsigned int * |
output |
|
) |
| |
This function updates SHA256 digest output for one or more message block arguments
- Parameters
-
| [in] | *input | pointer to start of input message |
| [in] | num_blks | number of 512‐bit blocks to process |
| [in,out] | *output | pointer to 256‐bit message digest output |
- Returns
- None
- Note
- Input message and digest output blocks must not overlap. The cau_sha256_initialize_output() function must be called first. Useful when handling non‐contiguous input message blocks.
| void cau_sha256_update |
( |
const unsigned char * |
input, |
|
|
const int |
num_blks, |
|
|
unsigned int * |
output |
|
) |
| |
This function updates SHA256 state variables for one or more input message blocks arguments
- Parameters
-
| [in] | *input | pointer to start of input message data |
| [in] | num_blks | number of 512‐bit blocks to process |
| [out] | *output | pointer to 256‐bit message digest output |
- Returns
- None
- Note
- Input message and digest output blocks must not overlap. The cau_sha256_initialize_output() function is not required. All input message blocks must be contiguous.
| void cau_sha256_hash |
( |
const unsigned char * |
input, |
|
|
unsigned int * |
output |
|
) |
| |
This function performs SHA256 hash algorithm for a single input message block
- Parameters
-
| [in] | *input | pointer to start of input message data |
| [in,out] | *output | pointer to 256‐bit message digest output |
- Returns
- None
- Note
- nput message and digest output blocks must not overlap. The cau_sha256_initialize_output() function must be called first. Only works for a single input message block.
