SA2UL

Table of Contents

• Features Supported
• SysConfig Features
• Features NOT Supported
• Usage Overview
  • SA2UL API's Supported
  • API Sequence for CBC abd ECB Algorithms
  • API Sequence for SHA Algorithms
  • API Sequence for HMAC-SHA Algorithms
  • API Sequence for AES-CMAC Algorithms
  • API Sequence for RNG (Random number generation)
  • API Sequence for PKA (Public-key accelerator)
  • Opening the SA2UL Driver
  • Ultra lite Security Accelerator
  • AES (Advanced Encryption Standard)
  • SHA (Secure Hash Algorithm)
  • HMAC-SHA (Keyed-Hash Message Authentication Code Secure Hash Algorithm)
  • AES-CMAC (Cipher-based Message Authentication Code)
  • RNG (Random number generation)
  • PKA (Public-key accelerator)
• Example Usage
• API

Ultra lite Security Accelerator(SA2_UL) subsystem is designed to provide low-cost hardware cryptographic acceleration for the Encryption and authentication.

Features Supported

• Encryption and authentication
• Crypto function library for Security acceleration
  • Secure Hash Algorithms
    • SHA256, SHA512
  • Hash-based Message Authentication Code
    • HMAC SHA-256, HMAC SHA-512, HMAC SHA1
  • Advanced Encryption Standard
    • AES-CBC(128/256)(Cipher Block Chaining)
    • AES-ECB(128/256)(Electronic Code Book)
    • AES-CMAC(128/256)(Cipher-based Message Authentication Code)
• Supports Random number generator(RNG)
  • Keys and initialization values (IVs) for encryption
  • Keys for keyed MAC algorithms
  • Private keys for digital signature algorithms
  • Values to be used in entity authentication mechanisms
  • PIN and password generation
• Supports Public-key accelerator(PKA)
  • Supports up to 4K bit key.
  • Supports Raw operations.
  • Supports RSA Public and private operations.
  • Supports RSA Sign and Verify operations.

SysConfig Features

Features NOT Supported

Usage Overview

SA2UL API's Supported

• SA2UL_init() : Initialize the SA2UL module.
• SA2UL_Params_init() : Initialize a SA2UL_Params structure with default values. Then change the parameters from non-default values as needed.
• SA2UL_open() : Open an instance of the SA2UL module, passing the initialized parameters, or NULL, and an index to the configuration to open.
• SA2UL_contextAlloc() : Function to configure secure context.
• SA2UL_contextFree() : Function to free secure context configuration.
• SA2UL_contextProcess() : Function to transfer and receive data buffer.
• SA2UL_rngSetup() : setup the SA2UL RNG module.
• SA2UL_rngRead() : Read random numbers into the output buffer.
• SA2UL_close() : De-initialize the SA2UL instance.
• SA2UL_deinit() : De-Initialize the SA2UL module.

API Sequence for CBC abd ECB Algorithms

This sequence performs Encryption and decryption operations for AES-CBC/ECB algorithms. Supported key lengths are 128 and 256 bit.

• Crypto_open() : Initializes a Crypto context and opens corresponding Secure module.
• SA2UL_contextAlloc() : Function to configure secure context.
• SA2UL_contextProcess() : Function to transfer and receive data buffer.
• SA2UL_contextFree() : Function to free secure context configuration.
• Crypto_close() : De-initialize the instance and Clears context.

API Sequence for SHA Algorithms

This sequence performs SHA-512 and SHA-256.

• Crypto_open() : Initializes a Crypto context and opens corresponding Secure module.
• SA2UL_contextAlloc() : Function to configure secure context.
• SA2UL_contextProcess() : Function to transfer and receive data buffer.
• SA2UL_contextFree() : Function to free secure context configuration.
• Crypto_close() : De-initialize the instance and Clears context.

API Sequence for HMAC-SHA Algorithms

This sequence performs HMAC SHA-512, SHA-256 and SHA1.

• Crypto_open() : Initializes a Crypto context and opens corresponding Secure module.
• Crypto_hmacSha() : This function updates oPad & iPad for HMAC calculation.
• SA2UL_contextAlloc() : Function to configure secure context.
• SA2UL_contextProcess() : Function to transfer and receive data buffer.
• SA2UL_contextFree() : Function to free secure context configuration.
• Crypto_close() : De-initialize the instance and Clears context.

API Sequence for AES-CMAC Algorithms

This sequence performs AES CMAC-128 and CMAC-256.

• Crypto_open() : Initializes a Crypto context and opens corresponding Secure module.
• Crypto_cmacGenSubKeys() : This function Generate Sub keys for CMAC calculation..
• SA2UL_contextAlloc() : Function to configure secure context.
• SA2UL_contextProcess() : Function to transfer and receive data buffer.
• SA2UL_contextFree() : Function to free secure context configuration.
• Crypto_close() : De-initialize the instance and Clears context.

API Sequence for RNG (Random number generation)

This sequence to get RNG (Random number generation).

• Crypto_open() : Initializes a Crypto context and opens corresponding Secure module.
• SA2UL_rngSetup() : setup the SA2UL RNG module.
• SA2UL_rngRead() : Read random numbers into the output buffer.
• Crypto_close() : De-initialize the instance and Clears context.

API Sequence for PKA (Public-key accelerator)

This sequence performs PKA operations.

• PKA_open() : Open PKA instance, enable PKA engine, Initialize clocks and Load PKA Fw.
• PKA_RSAPrivate() : This Function performs Decryption or Signing operations.
• PKA_RSAPublic() : This Function performs Encryption or Verification operations.
• PKA_close() : Close PKA instance, Disable PKA engine, UnInitialize clocks and unload PKA Fw.

Opening the SA2UL Driver

• The application can open a SA2UL instance by calling Crypto_open(). Please note that opening SA2UL driver is taken care by the SysConfig generated code. This function takes an index into the gSa2ulConfig[] array, and the SA2UL parameters data structure. The SA2UL instance is specified by the index of the SA2UL in gSa2ulConfig[]. Calling Crypto_open() second time with the same index previously passed to Crypto_open() will result in an error. Re-use the index if the instance is closed via Crypto_close().

Ultra lite Security Accelerator

• Set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), To get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, Final output will stored in output buffer. Close sa2ul context by calling SA2UL_contextFree().

AES (Advanced Encryption Standard)

• For enabling Sa2ul Aes engine use Crypto_open() and it also do initialize Crypto context, Set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), To get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, Final output will stored in output buffer. Close sa2ul context by calling SA2UL_contextFree(). For closing sa2ul Aes engine use Crypto_close().

SHA (Secure Hash Algorithm)

• For enabling Sa2ul Sha engine use Crypto_open() and it also do initialize Crypto context, Set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), To get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, Final output will stored in gSa2ulCtxObj(computedHash) buffer. Close sa2ul context by calling SA2UL_contextFree(). For closing sa2ul Sha engine use Crypto_close().

HMAC-SHA (Keyed-Hash Message Authentication Code Secure Hash Algorithm)

• For enabling Sa2ul Sha engine use Crypto_open() and it also do initialize Crypto context, Set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), For ipad and opad call Crypto_hmacSha(), To get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, Final output will stored in computedHash buffer (present in Sa2ul Ctx Obj). Close sa2ul context by calling SA2UL_contextFree(). For closing sa2ul Sha engine use Crypto_close().

AES-CMAC (Cipher-based Message Authentication Code)

• For enabling Sa2ul Aes engine use Crypto_open() and it also do initialize Crypto context, Set the ctx parameters using SA2UL_ContextParams structure, all necessary parameters set to SA2UL_ContextParams variables and allocate sa2ul context by calling SA2UL_contextAlloc(), For key1 and key2 call Crypto_cmacGenSubKeys(), To get expected result by calling SA2UL_contextProcess() with input buffer and output buffer as parameters, Final output will stored in output buffer. Close sa2ul context by calling SA2UL_contextFree(). For closing sa2ul Sha engine use Crypto_close().

RNG (Random number generation)

• For enabling SA2UL RNG use Crypto_open(), Setup rng module by calling SA2UL_rngSetup(), To get 128 bit Random number by calling SA2UL_rngRead() with output buffer as parameters, Final 128 bit random number will stored in output buffer. For disabling SA2UL RNG use Crypto_close().

PKA (Public-key accelerator)

• For Loading pka fw, clock enable and pka engine enable use PKA_open(), For Encryption or verification use PKA_RSAPublic(), For decryption or Signing use PKA_RSAPrivate(), To close pka engine, clock disable and fw unload use PKA_close().

Example Usage

Include the below file to access the SA2UL SHA APIs

 
#include<stdio.h>
#include <security/crypto.h>
#include <security/crypto/sa2ul/sa2ul.h>
 
Crypto_Context gCryptoSha512Context;
static uint8_t gCryptoSha512TestBuf[9] = {"abcdefpra"};
SA2UL_ContextObject  gCtxObj;

sa2ul_sha Example

 
    int32_t             status;
    uint8_t             sha512sum[64];
    Crypto_Handle       shaHandle;
    SA2UL_ContextParams ctxParams;
 
    /* Init SA */
    SA2UL_init();
 
    /* Open SHA instance */
    shaHandle = Crypto_open(&gCryptoSha512Context);
 
    /* Configure secure context */
    ctxParams.opType    = SA2UL_OP_AUTH;
    ctxParams.hashAlg   = SA2UL_HASH_ALG_SHA2_512;
    ctxParams.inputLen  = sizeof(gCryptoSha512TestBuf);
    gCtxObj.totalLengthInBytes = sizeof(gCryptoSha512TestBuf);
    status = SA2UL_contextAlloc(gCryptoSha512Context.drvHandle,&gCtxObj,&ctxParams);
 
    /* Perform SHA operation */
    status = SA2UL_contextProcess(&gCtxObj,&gCryptoSha512TestBuf[0], sizeof(gCryptoSha512TestBuf), sha512sum);
 
    /* Free the secure context configuration */
    SA2UL_contextFree(&gCtxObj);
 
    /* Close SHA instance */
    status = Crypto_close(shaHandle);
 
    /*deinit SA */
    SA2UL_deinit();
 

Include the below file to access the SA2UL AES CBC APIs

 
#include<stdio.h>
#include <security/crypto.h>
#include <security/crypto/sa2ul/sa2ul.h>
 
/* input or output length*/
#define APP_CRYPTO_AES_CBC_256_INOUT_LENGTH           (16U)
/* Aes max key length*/
#define APP_CRYPTO_AES_CBC_256_MAX_KEY_LENGTH         (32U)
/* Aes max IV length*/
#define APP_CRYPTO_AES_CBC_256_MAX_IV_LENGTH          (16U)
/* Aes key length in bites*/
#define APP_CRYPTO_AES_CBC_256_KEY_LENGTH_IN_BITS     (256U)
/* Alignment */
#define APP_CRYPTO_AES_CBC_ALIGNMENT                  (128U)
 
/* input buffer for encryption or decryption */
static uint8_t gCryptoAesCbc256InputBuf[APP_CRYPTO_AES_CBC_256_INOUT_LENGTH] =
{
    0x81, 0xEA, 0x5B, 0xA4, 0x69, 0x45, 0xC1, 0x70,
    0x5F, 0x6F, 0x89, 0x77, 0x88, 0x68, 0xCC, 0x67
};
 
/* The AES encryption algorithm encrypts and decrypts data in blocks of 128 bits. It can do this using 128-bit, 192-bit, or 256-bit keys */
static uint8_t gCryptoAesCbc256Key[APP_CRYPTO_AES_CBC_256_MAX_KEY_LENGTH] =
{
    0x33, 0xA3, 0x66, 0x46, 0xFE, 0x56, 0xF7, 0x0D,
    0xC0, 0xC5, 0x1A, 0x31, 0x17, 0xE6, 0x39, 0xF1,
    0x82, 0xDE, 0xF8, 0xCA, 0xB5, 0xC0, 0x66, 0x71,
    0xEE, 0xA0, 0x40, 0x7C, 0x48, 0xA9, 0xC7, 0x57
};
 
/* initialization vector (IV) is an arbitrary number that can be used along with a secret key for data encryption/decryption. */
static uint8_t gCryptoAesCbc256Iv[APP_CRYPTO_AES_CBC_256_MAX_IV_LENGTH] =
{
    0x7C, 0xE2, 0xAB, 0xAF, 0x8B, 0xEF, 0x23, 0xC4,
    0x81, 0x6D, 0xC8, 0xCE, 0x84, 0x20, 0x48, 0xA7
};
 
/* Encryption output buf */
uint8_t     gCryptoAesCbc256EncResultBuf[APP_CRYPTO_AES_CBC_256_INOUT_LENGTH] __attribute__ ((aligned (APP_CRYPTO_AES_CBC_ALIGNMENT)));
/* Decryption output buf */
uint8_t     gCryptoAesCbc256DecResultBuf[APP_CRYPTO_AES_CBC_256_INOUT_LENGTH] __attribute__ ((aligned (APP_CRYPTO_AES_CBC_ALIGNMENT)));
 
/* Context memory */
static Crypto_Context gCryptoAesCbcContext __attribute__ ((aligned (SA2UL_CACHELINE_ALIGNMENT)));
 
/* Context Object */
SA2UL_ContextObject  gSa2ulCtxObj __attribute__ ((aligned (SA2UL_CACHELINE_ALIGNMENT)));
 

sa2ul_aes_cbc Example

    int32_t             status;
    Crypto_Handle       aesHandle;
    SA2UL_ContextParams ctxParams;
 
    aesHandle = Crypto_open(&gCryptoAesCbcContext);
 
    /* Configure secure context */
    ctxParams.opType       = SA2UL_OP_ENC;
    ctxParams.encAlg       = SA2UL_ENC_ALG_AES;
    ctxParams.encMode      = SA2UL_ENC_MODE_CBC;
    ctxParams.encKeySize   = SA2UL_ENC_KEYSIZE_256;
    ctxParams.encDirection = SA2UL_ENC_DIR_ENCRYPT;
    memcpy( &ctxParams.key[0], &gCryptoAesCbc256Key[0], SA2UL_MAX_KEY_SIZE_BYTES);
    memcpy( &ctxParams.iv[0], &gCryptoAesCbc256Iv[0], SA2UL_MAX_IV_SIZE_BYTES);
    ctxParams.inputLen = sizeof(gCryptoAesCbc256InputBuf);
    gSa2ulCtxObj.totalLengthInBytes = sizeof(gCryptoAesCbc256InputBuf);
 
    /* Function to configure secure context */
    status = SA2UL_contextAlloc(gCryptoAesCbcContext.drvHandle, &gSa2ulCtxObj, &ctxParams);
 
    /* Encryption */
    /* Function to transfer and receive data buffer */
    status = SA2UL_contextProcess(&gSa2ulCtxObj,&gCryptoAesCbc256InputBuf[0], sizeof(gCryptoAesCbc256InputBuf), gCryptoAesCbc256EncResultBuf);
 
    /* Function to free secure context configuration*/
    status = SA2UL_contextFree(&gSa2ulCtxObj);
 
    /* Close AES instance */
    status = Crypto_close(aesHandle);
 
    return;

API

• APIs for SA2UL
• PKA