Introduction

This module contains APIs to program and use the SA3UL.

Files
file	sa3ul.h
	This file contains the prototype of SA3UL driver APIs.

Data Structures
struct	SA3UL_ContextParams
	Parameters passed to SA3UL_contextAlloc() More...

struct	SA3UL_Params
	Parameters passed to SA3UL_open() More...

struct	SA3UL_Object
	Object for a SA3UL crypto operation. More...

struct	SA3UL_Attrs
	SA3UL instance attributes - used during init time. More...

struct	SA3UL_Config
	SA3UL driver context. More...

struct	SA3UL_MCEData
	MEDdata for Encryption engine. More...

struct	SA3UL_SecCtxAuth
	SA3UL context RAM structure for authentication engine. More...

struct	SA3UL_Scctl
	SA3UL SC control structure. More...

struct	SA3UL_SecCtxEnc
	SA3UL context RAM structure for Encryption engine. More...

struct	SA3UL_SecCtx
	SA3UL context RAM structure. More...

struct	SA3UL_ContextObject
	SA3UL context object structure. More...

Functions
void	SA3UL_init (void)
	This function initializes the SA3UL module. More...

void	SA3UL_deinit (void)
	This function de-initializes the SA3UL module. More...

SA3UL_Handle	SA3UL_open (uint32_t index, const SA3UL_Params *params)
	This function opens a given SA3UL module. More...

void	SA3UL_close (SA3UL_Handle handle)
	Function to close a SA3UL module specified by the SA3UL handle. More...

int32_t	SA3UL_contextAlloc (SA3UL_Handle handle, SA3UL_ContextObject ctxObj, const SA3UL_ContextParams ctxPrms)
	Function to configure secure context. More...

int32_t	SA3UL_contextFree (SA3UL_ContextObject *pCtxObj)
	Function to free secure context configuration. More...

int32_t	SA3UL_contextProcess (SA3UL_ContextObject ctxObj, const uint8_t input, uint32_t ilen, uint8_t *output)
	Function to transfer and recieve data buffer. More...

static void	SA3UL_Params_init (SA3UL_Params *prms)
	Function to initialize default SA3UL parameters. More...

int32_t	SA3UL_rngSetup (SA3UL_Handle handle)
	setup the SA3UL RNG module. More...

int32_t	SA3UL_rngRead (SA3UL_Handle handle, uint32_t *out)
	Read random numbers into the output buffer. More...

static void	SA3UL_ContextParams_init (SA3UL_ContextParams *ctxPrms)

Typedefs
typedef void *	SA3UL_Handle
	Handle to the SA3UL driver returned by SA3UL_open() More...

Macros
#define	SA3UL_ENC_KEYSIZE_BITS(k) (128u + (64u * (k)))

SA3UL macros

#define	SA3UL_MAX_HASH_SIZE_BYTES (64U)
	Max hash size in bytes. More...

#define	SA3UL_MAX_KEY_SIZE_BYTES (32U)
	Max key size in bytes. More...

#define	SA3UL_MAX_IV_SIZE_BYTES (16U)
	Max Initialization vector (IV) size in bytes. More...

#define	SA3UL_NUMBER_OF_RINGS (3U)
	Max number of rings. More...

#define	SA3UL_CACHELINE_ALIGNMENT (128U)
	Cache line size for alignment of descriptor and buffers. More...

#define	SA3UL_SECCTX_SIZE (256U)
	Secure context memsize. More...

#define	SA3UL_INSTANCES_MAX (4U)
	Max SA3UL instances. More...

#define	SA3UL_RING_N_ELEMS (8U)
	Max SA3UL ring n elements. More...

#define	SA3UL_SW_RING_NUM (304U)
	Max SA3UL sw ring number. More...

#define	SA3UL_MAX_INPUT_LENGTH_ENC (0xFFFFU)
	Max Aes input length for encryption and decryption (64KB-1) More...

#define	SA3UL_MAX_INPUT_LENGTH_AUTH (0x3FFFFFU)
	Max input length for authentication (4MB-1) More...

SA3UL Algo Types

#define	SA3UL_HASH_ALG_NULL (0x10U)
	Hash Algo NULL. More...

#define	SA3UL_HASH_ALG_SHA1 (0x12U)
	Hash Algo SHA-1. More...

#define	SA3UL_HASH_ALG_SHA2_256 (0x14U)
	Hash Algo SHA-256. More...

#define	SA3UL_HASH_ALG_SHA2_512 (0x16U)
	Hash Algo SHA-512. More...

SA3UL Operations Sequence

#define	SA3UL_OP_ENC (0x01U)
	SA3UL operations encryption. More...

#define	SA3UL_OP_AUTH (0x02U)
	SA3UL operations authentication. More...

#define	SA3UL_OP_ENC_THEN_AUTH (0x03U)
	SA3UL operation encryption then authentication. More...

#define	SA3UL_OP_AUTH_THEN_ENC (0x04U)
	SA3UL operations authentication then encryption. More...

SA3UL engine operation type

#define	SA3UL_ENGINE_CODE_DEFAULT_ENGINE_ID (0U)
	SA3UL default engine Id. More...

#define	SA3UL_ENGINE_CODE_ENCRYPTION_MODULE_P1 (2U)
	SA3UL Encryption engine module p1. More...

#define	SA3UL_ENGINE_CODE_ENCRYPTION_MODULE_P2 (3U)
	SA3UL Encryption engine module p2. More...

#define	SA3UL_ENGINE_CODE_AUTHENTICATION_MODULE_P1 (4U)
	SA3UL Authentication engine module p1. More...

#define	SA3UL_ENGINE_CODE_AUTHENTICATION_MODULE_P2 (5U)
	SA3UL Authentication engine module p2. More...

#define	SA3UL_ENGINE_CODE_DEFAULT_EGRESS_PORT (20U)
	SA3UL Default Engress Port. More...

SA3UL Encryption Algos

#define	SA3UL_ENC_ALG_AES (0x0U)
	SA3UL AES Encryption Algorithm. More...

#define	SA3UL_ENC_ALG_TDES (0x1U)
	SA3UL TDES Encryption Algorithm. More...

#define	SA3UL_ENC_ALG_MAX (0x2U)
	SA3UL Encryption Maximun number of Algorithms. More...

SA3UL Encryption direction

#define	SA3UL_ENC_DIR_ENCRYPT (0x0U)
	Encryption direction. More...

#define	SA3UL_ENC_DIR_DECRYPT (0x1U)
	Decryption direction. More...

SA3UL Encryption modes

#define	SA3UL_ENC_MODE_ECB (0x0U)
	ECB mode. More...

#define	SA3UL_ENC_MODE_CBC (0x1U)
	CBC mode. More...

#define	SA3UL_ENC_MODE_MAX (0x2U)
	Maximun Encryption modes. More...

SA3UL Encryption key sizes

#define	SA3UL_ENC_KEYSIZE_128 (0x0U)
	Encryption 128 bit key size. More...

#define	SA3UL_ENC_KEYSIZE_192 (0x1U)
	Encryption 192 bit key size. More...

#define	SA3UL_ENC_KEYSIZE_256 (0x2U)
	Encryption 256 bit key size. More...

#define	SA3UL_ENC_KEYSIZE_MAX (0x3U)
	Max key size. More...

Macro Definition Documentation

◆ SA3UL_MAX_HASH_SIZE_BYTES

#define SA3UL_MAX_HASH_SIZE_BYTES (64U)

Max hash size in bytes.

◆ SA3UL_MAX_KEY_SIZE_BYTES

#define SA3UL_MAX_KEY_SIZE_BYTES (32U)

Max key size in bytes.

◆ SA3UL_MAX_IV_SIZE_BYTES

#define SA3UL_MAX_IV_SIZE_BYTES (16U)

Max Initialization vector (IV) size in bytes.

◆ SA3UL_NUMBER_OF_RINGS

#define SA3UL_NUMBER_OF_RINGS (3U)

Max number of rings.

◆ SA3UL_CACHELINE_ALIGNMENT

#define SA3UL_CACHELINE_ALIGNMENT (128U)

Cache line size for alignment of descriptor and buffers.

◆ SA3UL_SECCTX_SIZE

#define SA3UL_SECCTX_SIZE (256U)

Secure context memsize.

◆ SA3UL_INSTANCES_MAX

#define SA3UL_INSTANCES_MAX (4U)

Max SA3UL instances.

◆ SA3UL_RING_N_ELEMS

#define SA3UL_RING_N_ELEMS (8U)

Max SA3UL ring n elements.

◆ SA3UL_SW_RING_NUM

#define SA3UL_SW_RING_NUM (304U)

Max SA3UL sw ring number.

◆ SA3UL_MAX_INPUT_LENGTH_ENC

#define SA3UL_MAX_INPUT_LENGTH_ENC (0xFFFFU)

Max Aes input length for encryption and decryption (64KB-1)

◆ SA3UL_MAX_INPUT_LENGTH_AUTH

#define SA3UL_MAX_INPUT_LENGTH_AUTH (0x3FFFFFU)

Max input length for authentication (4MB-1)

◆ SA3UL_HASH_ALG_NULL

#define SA3UL_HASH_ALG_NULL (0x10U)

Hash Algo NULL.

◆ SA3UL_HASH_ALG_SHA1

#define SA3UL_HASH_ALG_SHA1 (0x12U)

Hash Algo SHA-1.

◆ SA3UL_HASH_ALG_SHA2_256

#define SA3UL_HASH_ALG_SHA2_256 (0x14U)

Hash Algo SHA-256.

◆ SA3UL_HASH_ALG_SHA2_512

#define SA3UL_HASH_ALG_SHA2_512 (0x16U)

Hash Algo SHA-512.

◆ SA3UL_OP_ENC

#define SA3UL_OP_ENC (0x01U)

SA3UL operations encryption.

◆ SA3UL_OP_AUTH

#define SA3UL_OP_AUTH (0x02U)

SA3UL operations authentication.

◆ SA3UL_OP_ENC_THEN_AUTH

#define SA3UL_OP_ENC_THEN_AUTH (0x03U)

SA3UL operation encryption then authentication.

◆ SA3UL_OP_AUTH_THEN_ENC

#define SA3UL_OP_AUTH_THEN_ENC (0x04U)

SA3UL operations authentication then encryption.

◆ SA3UL_ENGINE_CODE_DEFAULT_ENGINE_ID

#define SA3UL_ENGINE_CODE_DEFAULT_ENGINE_ID (0U)

SA3UL default engine Id.

◆ SA3UL_ENGINE_CODE_ENCRYPTION_MODULE_P1

#define SA3UL_ENGINE_CODE_ENCRYPTION_MODULE_P1 (2U)

SA3UL Encryption engine module p1.

◆ SA3UL_ENGINE_CODE_ENCRYPTION_MODULE_P2

#define SA3UL_ENGINE_CODE_ENCRYPTION_MODULE_P2 (3U)

SA3UL Encryption engine module p2.

◆ SA3UL_ENGINE_CODE_AUTHENTICATION_MODULE_P1

#define SA3UL_ENGINE_CODE_AUTHENTICATION_MODULE_P1 (4U)

SA3UL Authentication engine module p1.

◆ SA3UL_ENGINE_CODE_AUTHENTICATION_MODULE_P2

#define SA3UL_ENGINE_CODE_AUTHENTICATION_MODULE_P2 (5U)

SA3UL Authentication engine module p2.

◆ SA3UL_ENGINE_CODE_DEFAULT_EGRESS_PORT

#define SA3UL_ENGINE_CODE_DEFAULT_EGRESS_PORT (20U)

SA3UL Default Engress Port.

◆ SA3UL_ENC_ALG_AES

#define SA3UL_ENC_ALG_AES (0x0U)

SA3UL AES Encryption Algorithm.

◆ SA3UL_ENC_ALG_TDES

#define SA3UL_ENC_ALG_TDES (0x1U)

SA3UL TDES Encryption Algorithm.

◆ SA3UL_ENC_ALG_MAX

#define SA3UL_ENC_ALG_MAX (0x2U)

SA3UL Encryption Maximun number of Algorithms.

◆ SA3UL_ENC_DIR_ENCRYPT

#define SA3UL_ENC_DIR_ENCRYPT (0x0U)

Encryption direction.

◆ SA3UL_ENC_DIR_DECRYPT

#define SA3UL_ENC_DIR_DECRYPT (0x1U)

Decryption direction.

◆ SA3UL_ENC_MODE_ECB

#define SA3UL_ENC_MODE_ECB (0x0U)

ECB mode.

◆ SA3UL_ENC_MODE_CBC

#define SA3UL_ENC_MODE_CBC (0x1U)

CBC mode.

◆ SA3UL_ENC_MODE_MAX

#define SA3UL_ENC_MODE_MAX (0x2U)

Maximun Encryption modes.

◆ SA3UL_ENC_KEYSIZE_128

#define SA3UL_ENC_KEYSIZE_128 (0x0U)

Encryption 128 bit key size.

◆ SA3UL_ENC_KEYSIZE_192

#define SA3UL_ENC_KEYSIZE_192 (0x1U)

Encryption 192 bit key size.

◆ SA3UL_ENC_KEYSIZE_256

#define SA3UL_ENC_KEYSIZE_256 (0x2U)

Encryption 256 bit key size.

◆ SA3UL_ENC_KEYSIZE_MAX

#define SA3UL_ENC_KEYSIZE_MAX (0x3U)

Max key size.

◆ SA3UL_ENC_KEYSIZE_BITS

#define SA3UL_ENC_KEYSIZE_BITS ( k ) (128u + (64u * (k)))

Typedef Documentation

◆ SA3UL_Handle

typedef void* SA3UL_Handle

Handle to the SA3UL driver returned by SA3UL_open()

Function Documentation

◆ SA3UL_init()

void SA3UL_init ( void )

This function initializes the SA3UL module.

◆ SA3UL_deinit()

void SA3UL_deinit ( void )

This function de-initializes the SA3UL module.

◆ SA3UL_open()

SA3UL_Handle SA3UL_open	(	uint32_t	index,
		const SA3UL_Params *	params
	)

This function opens a given SA3UL module.

Parameters

index	Index of config to use in the SA3UL_Config array
params	Pointer to open parameters. If NULL is passed, then default values will be used

Returns: A SA3UL_Handle on success or a NULL on an error or if it has been opened already

◆ SA3UL_close()

void SA3UL_close ( SA3UL_Handle handle )

Function to close a SA3UL module specified by the SA3UL handle.

Parameters

handle SA3UL_Handle returned from SA3UL_open()

◆ SA3UL_contextAlloc()

int32_t SA3UL_contextAlloc	(	SA3UL_Handle	handle,
		SA3UL_ContextObject *	ctxObj,
		const SA3UL_ContextParams *	ctxPrms
	)

Function to configure secure context.

Parameters

handle	SA3UL_Handle returned from SA3UL_open()
ctxObj	Pointer to SA3UL_ContextObject structure
ctxPrms	Pointer to secure context parameters.If NULL is passed, then default values will be used

Returns: A SystemP_SUCCESS on success or a NULL on an error or if the instance index has NOT been opened yet

◆ SA3UL_contextFree()

int32_t SA3UL_contextFree ( SA3UL_ContextObject * pCtxObj )

Function to free secure context configuration.

Parameters

pCtxObj Pointer to SA3UL_ContextObject structure

Returns: A SystemP_SUCCESS on success or a NULL on an error or if the instance index has NOT been opened yet

◆ SA3UL_contextProcess()

int32_t SA3UL_contextProcess	(	SA3UL_ContextObject *	ctxObj,
		const uint8_t *	input,
		uint32_t	ilen,
		uint8_t *	output
	)

Function to transfer and recieve data buffer.

Parameters

ctxObj	Pointer to SA3UL_ContextObject structure
input	Pointer to input buffer to be processed
ilen	Length of the input buffer
output	Pointer to output buffer after the process is complete

Returns: A SystemP_SUCCESS on success or a NULL on an error or if the instance index has NOT been opened yet

◆ SA3UL_Params_init()

static void SA3UL_Params_init ( SA3UL_Params * prms )

inlinestatic

Function to initialize default SA3UL parameters.

Parameters

prms	Pointer to open parameters.

◆ SA3UL_rngSetup()

int32_t SA3UL_rngSetup ( SA3UL_Handle handle )

setup the SA3UL RNG module.

Parameters

handle SA3UL_Handle returned from SA3UL_open()

Returns: SystemP_SUCCESS if successful

◆ SA3UL_rngRead()

int32_t SA3UL_rngRead	(	SA3UL_Handle	handle,
		uint32_t *	out
	)

Read random numbers into the output buffer.

Parameters

handle	SA3UL_Handle returned from SA3UL_open()
out	pointer to the buffer for the 128 bit random data.

Returns: returns SystemP_SUCCESS if requested data is available. SystemP_FAILURE if RNG is not initialized.

◆ SA3UL_ContextParams_init()

static void SA3UL_ContextParams_init ( SA3UL_ContextParams * ctxPrms )

inlinestatic

Variable Documentation

◆ gSa3ulConfig

SA3UL_Config gSa3ulConfig[]

extern

Externally defined driver configuration array.

◆ gSa3ulConfigNum

uint32_t gSa3ulConfigNum

extern

Externally defined driver configuration Num.

Introduction

Files

Data Structures

Functions

Typedefs

Macros

SA3UL macros

SA3UL Algo Types

SA3UL Operations Sequence

SA3UL engine operation type

SA3UL Encryption Algos

SA3UL Encryption direction

SA3UL Encryption modes

SA3UL Encryption key sizes

Macro Definition Documentation

◆ SA3UL_MAX_HASH_SIZE_BYTES

◆ SA3UL_MAX_KEY_SIZE_BYTES

◆ SA3UL_MAX_IV_SIZE_BYTES

◆ SA3UL_NUMBER_OF_RINGS

◆ SA3UL_CACHELINE_ALIGNMENT

◆ SA3UL_SECCTX_SIZE

◆ SA3UL_INSTANCES_MAX

◆ SA3UL_RING_N_ELEMS

◆ SA3UL_SW_RING_NUM

◆ SA3UL_MAX_INPUT_LENGTH_ENC

◆ SA3UL_MAX_INPUT_LENGTH_AUTH

◆ SA3UL_HASH_ALG_NULL

◆ SA3UL_HASH_ALG_SHA1

◆ SA3UL_HASH_ALG_SHA2_256

◆ SA3UL_HASH_ALG_SHA2_512

◆ SA3UL_OP_ENC

◆ SA3UL_OP_AUTH

◆ SA3UL_OP_ENC_THEN_AUTH

◆ SA3UL_OP_AUTH_THEN_ENC

◆ SA3UL_ENGINE_CODE_DEFAULT_ENGINE_ID

◆ SA3UL_ENGINE_CODE_ENCRYPTION_MODULE_P1

◆ SA3UL_ENGINE_CODE_ENCRYPTION_MODULE_P2

◆ SA3UL_ENGINE_CODE_AUTHENTICATION_MODULE_P1

◆ SA3UL_ENGINE_CODE_AUTHENTICATION_MODULE_P2

◆ SA3UL_ENGINE_CODE_DEFAULT_EGRESS_PORT

◆ SA3UL_ENC_ALG_AES

◆ SA3UL_ENC_ALG_TDES

◆ SA3UL_ENC_ALG_MAX

◆ SA3UL_ENC_DIR_ENCRYPT

◆ SA3UL_ENC_DIR_DECRYPT

◆ SA3UL_ENC_MODE_ECB

◆ SA3UL_ENC_MODE_CBC

◆ SA3UL_ENC_MODE_MAX

◆ SA3UL_ENC_KEYSIZE_128

◆ SA3UL_ENC_KEYSIZE_192

◆ SA3UL_ENC_KEYSIZE_256

◆ SA3UL_ENC_KEYSIZE_MAX

◆ SA3UL_ENC_KEYSIZE_BITS

Typedef Documentation

◆ SA3UL_Handle

Function Documentation

◆ SA3UL_init()

◆ SA3UL_deinit()

◆ SA3UL_open()

◆ SA3UL_close()

◆ SA3UL_contextAlloc()

◆ SA3UL_contextFree()

◆ SA3UL_contextProcess()

◆ SA3UL_Params_init()

◆ SA3UL_rngSetup()

◆ SA3UL_rngRead()

◆ SA3UL_ContextParams_init()

Variable Documentation

◆ gSa3ulConfig

◆ gSa3ulConfigNum