AES

This section introduces the AES driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, AES function groups, enums, structures and functions. More...

Overview

This section introduces the AES driver APIs including terms and acronyms, supported features, software architecture, details on how to use this driver, AES function groups, enums, structures and functions.

Terms and acronyms

Terms	Details
AES	The Advanced Encryption Standard. For more information, please refer to introduction to the AES in Wikipedia.
CBC	The Cipher Block Chaining(CBC), each block of plain text is XOR'ed with the previous cipher block before being encrypted. This way, each cipher text block depends on all plain text blocks processed up to that point.
ECB	Electronic Codebook (ECB) mode. The message is divided into blocks, and each block is encrypted separately.

Supported features

• Support CBC and ECB modes.
  Each mode has different hardware and software configuration.

How to use this driver

• Use the AES in CBC mode to encrypt and decrypt.
  
  • Step 1. Call hal_aes_cbc_encrypt() to encrypt.
  • Step 2. Call hal_aes_cbc_decrypt() to decrypt.
  • sample code:

    uint8_t aes_cbc_iv[HAL_AES_CBC_IV_LENGTH] = {
        0x61, 0x33, 0x46, 0x68, 0x55, 0x38, 0x31, 0x43,
        0x77, 0x68, 0x36, 0x33, 0x50, 0x76, 0x33, 0x46
    };
    uint8_t plain[] = {
        0, 11, 22, 33, 44, 55, 66, 77, 88, 99, 0, 11, 22, 33, 44, 55,
        66, 77, 88, 99, 0, 11, 22, 33, 44, 55, 66, 77, 88, 99
    };
    hal_aes_buffer_t plain_text = {
        .buffer = plain,
        .length = sizeof(plain)
    };
    hal_aes_buffer_t key = {
        .buffer = hardware_id,
        .length = sizeof(hardware_id)
    };
    uint8_t encrypted_buffer[32] = {0};
    hal_aes_buffer_t encrypted_text = {
        .buffer = encrypted_buffer,
        .length = sizeof(encrypted_buffer)
    };
    hal_aes_cbc_encrypt(&encrypted_text, &plain_text, &key, aes_cbc_iv);
    
    uint8_t decrypted_buffer[32] = {0};
    hal_aes_buffer_t decrypted_text = {
        .buffer = decrypted_buffer,
        .length = sizeof(decrypted_buffer)
    };
    hal_aes_cbc_decrypt(&decrypted_text, &encrypted_text, &key, aes_cbc_iv);

• Use the AES in ECB mode to encrypt and decrypt.
  
  • Step 1. Call hal_aes_ecb_encrypt() to encrypt.
  • Step 2. Call hal_aes_ecb_decrypt() to decrypt.
  • sample code:

    uint8_t hardware_id[16] = {
        0x4d, 0x54, 0x4b, 0x30, 0x30, 0x30, 0x30, 0x30,
        0x32, 0x30, 0x31, 0x34, 0x30, 0x38, 0x31, 0x35
    };
    uint8_t plain[] = {
        0, 11, 22, 33, 44, 55, 66, 77, 88, 99, 0, 11, 22, 33, 44, 55,
        66, 77, 88, 99, 0, 11, 22, 33, 44, 55, 66, 77, 88, 99
    };
    hal_aes_buffer_t plain_text = {
        .buffer = plain,
        .length = sizeof(plain)
    };
    hal_aes_buffer_t key = {
        .buffer = hardware_id,
        .length = sizeof(hardware_id)
    };
    uint8_t encrypted_buffer[32] = {0};
    hal_aes_buffer_t encrypted_text = {
        .buffer = encrypted_buffer,
        .length = sizeof(encrypted_buffer)
    };
    hal_aes_ecb_encrypt(&encrypted_text, &plain_text, &key);
    
    uint8_t decrypted_buffer[32] = {0};
    hal_aes_buffer_t decrypted_text = {
        .buffer = decrypted_buffer,
        .length = sizeof(decrypted_buffer)
    };
    hal_aes_ecb_decrypt(&decrypted_text, &encrypted_text, &key);

Functions
hal_aes_status_t	hal_aes_cbc_encrypt (hal_aes_buffer_t *encrypted_text, hal_aes_buffer_t *plain_text, hal_aes_buffer_t *key, uint8_t init_vector[HAL_AES_CBC_IV_LENGTH])
	This function provides AES encryption in CBC mode. More...
hal_aes_status_t	hal_aes_cbc_decrypt (hal_aes_buffer_t *plain_text, hal_aes_buffer_t *encrypted_text, hal_aes_buffer_t *key, uint8_t init_vector[HAL_AES_CBC_IV_LENGTH])
	This function provides AES decryption in CBC mode. More...
hal_aes_status_t	hal_aes_ecb_encrypt (hal_aes_buffer_t *encrypted_text, hal_aes_buffer_t *plain_text, hal_aes_buffer_t *key)
	This function provides AES encryption in EBC mode. More...
hal_aes_status_t	hal_aes_ecb_decrypt (hal_aes_buffer_t *plain_text, hal_aes_buffer_t *encrypted_text, hal_aes_buffer_t *key)
	This function provides AES decryption in EBC mode. More...

Modules
	Define
	Enum
	Struct

Function Documentation

hal_aes_status_t hal_aes_cbc_decrypt	(	hal_aes_buffer_t *	plain_text,
		hal_aes_buffer_t *	encrypted_text,
		hal_aes_buffer_t *	key,
		uint8_t	init_vector[HAL_AES_CBC_IV_LENGTH]
	)

This function provides AES decryption in CBC mode.

Parameters

[out]	plain_text	is the target plain text.
[in]	encrypted_text	is the source encrypted text.
[in]	key	is the AES encryption key.
[in]	init_vector	is the AES initialization vector for encryption.

Returns

HAL_AES_STATUS_OK, if the operation completed successfully.

Example

Sample code, please refer to How to use this driver

hal_aes_status_t hal_aes_cbc_encrypt	(	hal_aes_buffer_t *	encrypted_text,
		hal_aes_buffer_t *	plain_text,
		hal_aes_buffer_t *	key,
		uint8_t	init_vector[HAL_AES_CBC_IV_LENGTH]
	)

This function provides AES encryption in CBC mode.

Parameters

[out]	encrypted_text	is the target encrypted text.
[in]	plain_text	is the source plain text.
[in]	key	is the AES encryption key.
[in]	init_vector	is the AES initialzation vector for encryption.

Returns

HAL_AES_STATUS_OK, if the operation completed successfully.

Example

Sample code, please refer to How to use this driver

hal_aes_status_t hal_aes_ecb_decrypt	(	hal_aes_buffer_t *	plain_text,
		hal_aes_buffer_t *	encrypted_text,
		hal_aes_buffer_t *	key
	)

This function provides AES decryption in EBC mode.

Parameters

[out]	plain_text	is the target plain text.
[in]	encrypted_text	is the source encrypted text.
[in]	key	is the AES encryption key.

Returns

HAL_AES_STATUS_OK, if the operation completed successfully.

Example

Sample code, please refer to How to use this driver

hal_aes_status_t hal_aes_ecb_encrypt	(	hal_aes_buffer_t *	encrypted_text,
		hal_aes_buffer_t *	plain_text,
		hal_aes_buffer_t *	key
	)

This function provides AES encryption in EBC mode.

Parameters

[out]	encrypted_text	is the target encrypted text.
[in]	plain_text	is the source plain text.
[in]	key	is the AES encryption key.

Returns

HAL_AES_STATUS_OK, if the operation completed successfully.

Example

Sample code, please refer to How to use this driver