This example project demonstrates the use of the following PolarFire User Crypto Services functions:
- CALSymEncAuth()
- CALSymEncAuthDMA()
- CALMAC()
- CALMACDMA()
- CALHash()
- CALHashDMA()
The User Crypto message authentication service provides a way to ensure the message integrity and to confirm that the message came from the stated sender (its authenticity). This example project demonstrate the use of MAC services to generate message authenticate code, authenticated encryption (the input message), and hash service to covert data of arbitrary length to a fixed length.
On connecting PolarFire SoC Video kit J12 to the host PC, you should see 4 COM port interfaces connected. To use this project configure the COM port interface1 as below:
- 115200 baud
- 8 data bits
- 1 stop bit
- no parity
- no flow control
The example project will display instructions over the serial port. To execute the particular service, user has to enter the required information as shown over the serial port. This example project will also displays the return data from User Crypto processor for message authentication and hash service.
Select option '1' to perform authenticated encryption using Galois/counter mode (GCM) algorithm. This example project reads the 256 bit key, IV, 16 bytes plain text, and additional authentication data (AAD) from UART terminal and calls the CALSymEncAuth() or CALSymEncAuthDMA() function. This function performs authenticated encryption with associated data for confidentiality and integrity. The plain text is both encrypted and used in computation of message authentication code according to the SATSYMTYPE_AES256 encryption algorithm and GCM mode. Both the encrypted data and tag are displayed on UART terminal.
NOTE: In Case of GCM, in place of IV paramter user has to pass JO value which is calculated according to the algorithm mentioned in the following document.
Select option '2' to calculate message authentication code using HMAC SHA-256 algorithms. This example project reads the key and message from UART terminal and calls the CALMAC() or CALMACDMA() function. The CALMAC() and CALMACDMA() functions calculate the MAC for the message based on SHA256 algorithm and the secret key. The calculated MAC is also displayed on UART terminal.
Select option '3' to calculated message authentication code using AES-CMAC-256 algorithms. This example project reads the key and message from UART terminal and calls the CALMAC function. The CALMAC() functions calculates the MAC for the message based on AES CMAC 256 algorithm and the secret key. The calculated MAC is also displayed on UART terminal.
NOTE: MAC computation using DMA (i.e. CALMACDMA function) doesn’t support AES-CMAC-256 Algorithm.
Select option '4' to perform hashing. This service reads 64 bytes of message value and performs the hash operation using SHA-256 hash algorithm on the stored data. The hash results are stored at user memory location and also displayed on UART terminal.
This example project is targeted at PolarFire SoC Video kit (MPFS250TS-1FCG1152I). The reference design for the PolarFire SoC video kit is available in the following GitHub repository: PolarFire® SoC Video Kit Reference Design.
The steps mentioned here can be used to generate a FlashPro Express job file from above mentioned tcl script.
This project provides build configurations and debug launchers as explained here
- PolarFire User Crypto Driver Configuration
-
config_user.h is a custom configuration file for PolarFire SoC CAL library. Following are the recommended configuration for config_user.h file.
- Define g_user_crypto_base_address global variable as shown below. This will used to configure the PKX0_BASE (defined in config_user.h) and to connect to the User Crypto Co-processor in the Libero design.
uint32_t g_user_crypto_base_addr 0x22000000UL;- SAT_LITTLE_ENDIAN - Endianness of the processor executing CAL Library customization definitions. These definitions enable the respective cryptographic services in the CAL which are supported by the User Crypto Processor. It is recommended that these definitions are not removed or changed unless required.
-
A symbol INC_STDINT_H is defined in project preprocessor setting. For more detail, please refer to caltypes.h file present in CAL folder.
-
NOTE:
- If you try to enter data values other than 0 - 9, a - f, A - F, an error message will be displayed on the serial terminal.
- You must enter all input data as whole bytes. If you enter the 128-bit key {1230...0} as 0x12 0x3 and press return, this will be treated as byte0 = 0x12, byte1 = 0x30, byte2-127 = 0x00.
A macro script is provided with this example which automatically enters the NIST vectors and associated data to verify the functionality.
The following Tera Term macro scripts are present in "script" folder. You can use these script for testing Message Authentication and Hashing services.
- MAC-gcm_msg_auth.ttl - Data Authenticated Encryption
- MAC-hmac_aes_cmac_256.ttl - Generate MAC Using AES-CMAC-256 Algorithms
- MAC-hmac_sha_256.ttl - Generate MAC Using HMAC SHA-256 Algorithms
- SHA-256.ttl - Hashing
NOTE:
- Tera Term Macros don’t work with Windows 10 build 14393.0. You should update to Windows 10 build 14393.0.105 or later.
- Before running Tera Term Macro script, set language as English (Setup->General->Language). Also setup transmit delay in (Setup->Serial port) to 5msec/char and 5msec/line.
- By default, Tera Term log will be stored in Tera Term installation Directory.
This example is tested on PolarFire SoC Video kit (MPFS250TS-1FCG1152I).
The CAL source code is bound by license agreement. If you need access to the CAL source code, please contact FPGA_marketing@microchip.com for further details on NDA requirements.