--- a/salld.h
+++ b/salld.h
* @brief SA LLD Interface Unit API and Data Definitions
*
* ============================================================================
- * Copyright (c) Texas Instruments Incorporated 2009-2012
+ * Copyright (c) Texas Instruments Incorporated 2009-2018
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
#include <ti/drv/sa/saver.h>
+/*
+ * Shut off: remark #880-D: parameter "descType" was never referenced
+ *
+ * This is better than removing the argument since removal would break
+ * backwards compatibility
+ */
+#ifdef _TMS320C6X
+#pragma diag_suppress 880
+#pragma diag_suppress 681
+#elif defined(__GNUC__)
+/* Same for GCC:
+ * warning: unused parameter descType [-Wunused-parameter]
+ * expectation is all these catch up with some other intelligent
+ * tools like coverity, Klocwork etc, instead of dump GNU
+ * warnings
+ */
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wunused-parameter"
+#pragma GCC diagnostic ignored "-Wmaybe-uninitialized"
+#endif
+
+
/* Define SALLD Module as a master group in Doxygen format and add all SA LLD API
definitions to this group. */
/** @defgroup salld_module SA LLD Module API
#define sa_ERR_NOMEM -3
/**
- * @def sa_ERR_INV_BUF
+ * @def sa_ERR_INV_BUF (deprecated)
* SALLD Return Codes -- Invalid buffers.
*/
#define sa_ERR_INV_BUF -4
#define sa_ERR_MODULE_UNAVAIL -16
/**
* @def sa_ERR_PKA_TIMEOUT
- * SALLD Return Codes -- PKA operation timeout..
+ * SALLD Return Codes -- PKA operation timeout.
*/
#define sa_ERR_PKA_TIMEOUT -17
/**
* @def sa_ERR_PACKET
* SALLD Return Codes -- Error in the input packet such that SALLD is not able to process this packet.
*/
-#define sa_ERR_PACKET -22
+#define sa_ERR_PACKET -22
/**
* @def sa_ERR_INV_INT_MEM
* SALLD Return Codes -- Invalid internal memory buffer for key storage
*/
-#define sa_ERR_INV_INT_MEM -23
+#define sa_ERR_INV_INT_MEM -23
+
+/**
+ * @def sa_ERR_API_UNSUPPORTED
+ * The API is not supported by this generation of SASS
+ */
+#define sa_ERR_API_UNSUPPORTED -24
+
+/**
+ * @def sa_ERR_PKA_OP_UNSUPPORTED
+ * The required PKA operation is not supported by this generation of PKA module
+ */
+#define sa_ERR_PKA_OP_UNSUPPORTED -25
+
+/**
+ * @def sa_ERR_PKA_NOT_READY
+ * Some PKA operation in in progress and it is not ready for new operation.
+ */
+#define sa_ERR_PKA_NOT_READY -26
+
+/**
+ * @def sa_ERR_PKA_OP_ERROR
+ * The PKA operation return error.
+ */
+#define sa_ERR_PKA_OP_ERROR -27
+
+/**
+ * @def sa_ERR_PKA_INVALID_STATE
+ * PKA API is invoked at inavlid state.
+ */
+#define sa_ERR_PKA_INVALID_STATE -28
+
+/**
+ * @def sa_ERR_PKA_WORKSPACE_ERROR
+ * There is no enough workspace to execute the PKA complex operaion.
+ */
+#define sa_ERR_PKA_WORKSPACE_ERROR -29
+
+/**
+ * @def sa_ERR_PKA_DOWNLOAD_FAIL
+ * The PKA Firmware download failure.
+ */
+#define sa_ERR_PKA_DOWNLOAD_FAIL -30
+
+/**
+ * @def sa_ERR_ENGINE_STATE
+ * The SA2UL engines are in an unexpected state
+ */
+#define sa_ERR_ENGINE_STATE -31
+
+/**
+ * @def sa_PKA_OP_IN_PROGRESS
+ * The current PKA operation is still in progress.
+ */
+#define sa_PKA_OP_IN_PROGRESS 1
+
+/**
+ * @def sa_PKA_OP_CONTINUE
+ * The current PKA operation is completed and it has started the next operation in sequence.
+ */
+#define sa_PKA_OP_CONTINUE 2
+
+/**
+ * @def sa_PKA_OP_COMPLETE
+ * All PKA operations in sequence are completed and the final results are ready.
+ */
+#define sa_PKA_OP_COMPLETE sa_ERR_OK
+
+/**
+ * @def sa_MAX_PS_AI_WORD_COUNT
+ * upto 12 32-bit words of 'personalizatoin string' and 'additional input' used for
+ * SP-800-90A AES-256 DRBG
+ */
+
+#define sa_MAX_PS_AI_WORD_COUNT 12
+
/*@}*/
/** @} */
sa_AuthMode_SHA1, /**< SHA1 mode */
sa_AuthMode_SHA2_224, /**< 224-bit SHA2 mode */
sa_AuthMode_SHA2_256, /**< 256-bit SHA2 mode */
+ sa_AuthMode_SHA2_384, /**< 384-bit SHA2 mode
+ @note: This mode is used at Data Mode only for SA2_UL */
+ sa_AuthMode_SHA2_512, /**< 512-bit SHA2 mode
+ @note: This mode is used at Data Mode only for SA2_UL */
sa_AuthMode_HMAC_MD5, /**< HMAC with MD5 mode */
sa_AuthMode_HMAC_SHA1, /**< HMAC with SHA1 mode */
sa_AuthMode_HMAC_SHA2_224, /**< HMAC with 224-bit SHA2 mode */
sa_AuthMode_HMAC_SHA2_256, /**< HMAC with 256-bit SHA2 mode */
+ sa_AuthMode_HMAC_SHA2_384, /**< HMAC with 224-bit SHA mode
+ @note: This mode is used at Data Mode only for SA2_UL */
+ sa_AuthMode_HMAC_SHA2_512, /**< HMAC with 256-bit SHA mode
+ @note: This mode is used at Data Mode only for SA2_UL */
sa_AuthMode_GMAC, /**< Galois Message Authentication Code mode */
sa_AuthMode_GMAC_AH, /**< Galois Message Authentication Code mode for IPSEC AH operation
@note: This mode is used at Data Mode only */
#define sa_SIZE_CONFIG_SASS_GEN2 0x0002
+/**
+ * @def sa_SIZE_CONFIG_SASS_UL_GEN2
+ * Control Info -- 0:First generation Security Accelerator Ultra Lite Sub-System (SAUL)
+ * 1:Second generattion Security Aaccelerator Ultra Lite Sub-System (SA2_UL)
+ * at more advanced keystone3 devices such as Maxwell
+ */
+
+#define sa_SIZE_CONFIG_SASS_UL_GEN2 0x0003
+
+
/*@}*/
/** @} */
uint16_t sessionSaltSize; /**< Specify the size of the session salt in bytes */
uint16_t ivSize; /**< Specify the size of the initialization vector in bytes */
uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
- uint16_t nextHdr; /**< Specify the next protocol header */
+ uint16_t nextHdr; /**< Specify the next protocol header */
+ /**< @note: This parameter is no longer used. */
uint32_t spi; /**< Specify the SPI (Security Parameter Index) */
- uint32_t esnLo; /**< Specify the initial value of the extended sequence Number (lower 32-bit) */
+ uint32_t esnLo; /**< Specify the initial value of the (extended) sequence Number (lower 32-bit) */
uint32_t esnHi; /**< Specify the initial value of the extended sequence Number (upper 32-bit) */
} Sa_IpsecConfigParams_t;
* @def sa_AC_CONFIG_KEY_IN_SCRATCH
* Control Info -- 0:key is copied into security context by lld
* 1:key is copied into scratch memory by lld
+ * @note: This feature is not supported for KeyStone devices such as C6678
*/
#define sa_AC_CONFIG_KEY_IN_SCRATCH 0x0800
uint16_t macSize; /**< Specify the size of the authentication tag in bytes */
} Sa_AcConfigParams_t;
+/**
+ * @defgroup SALLDDmConfigCtrlBit Data Mode Configuration Control Bit Definitions
+ * @ingroup salld_api_constants
+ * @{
+ *
+ * @name Data Mode Configuration Control Bit Definitions
+ *
+ * Bitmap definition of the ctrlBitMap in Sa_DmConfigParams_t.
+ *
+ */
+/*@{*/
+/**
+ * @def sa_DM_CONFIG_SELECT_AIR_CIPHER_ENG
+ * Control Info -- 1: indicate selection of Air Cipher engine in data mode
+ * 0: use Encryption engine (default)
+ * @note: There are Encryption Engine and Air Cipher Engine in SASS. There are
+ * certain types of algorithms such as AES_CTR which both of these engines are
+ * capable of executing. By default the data mode selects to use the encryption
+ * engine for the algorithms such as AES_CTR. To seperate the Air Cipher traffic
+ * from the IPSec traffic, application may select the air cipher engine
+ * for the encryption by setting this bit.
+ *
+ * For devices such as K2G (NSS_LITE) which do not have air cipher engine
+ * setting this bit would cause error during datamode channel control configuration.
+ *
+ * This bit is supported for SA LLD releases version 3.0.0.15 or higher
+ */
+#define sa_DM_CONFIG_SELECT_AIR_CIPHER_ENG ((uint16_t) (0x0001U))
+
+/**
+ * @def sa_DM_CONFIG_PROMOTE_NONSECURE
+ * Control Info -- 1: promotion of normal world packet to secure packet
+ * intended to land in the secure memory (only for sa2ul)
+ * 0: no promotion
+ * @note: Promotion of non-secure packet to be secure packet also always requires
+ * the 48-bit SCPTR that comes with the packet to be within the range
+ * of 'SCPTR Promote Range' registers.
+ *
+ * For devices that do not have SA2UL setting this bit would cause no action
+ *
+ */
+#define sa_DM_CONFIG_PROMOTE_CHANNEL ((uint16_t) (0x0002U))
+
+/**
+ * @def sa_DM_CONFIG_DEMOTE_SECURE
+ * Control Info -- 1: demotion of secure packet to normal world packet
+ * intended to land in the secure memory (only for sa2ul)
+ * 0: no demotion
+ *
+ * For devices that do not have SA2UL setting this bit would cause no action
+ *
+ */
+#define sa_DM_CONFIG_DEMOTE_CHANNEL ((uint16_t) (0x0004U))
+
+/**
+ * @def sa_DM_CONFIG_USE_SECURE_CTX_FOR_NON_SECURE_CHANNEL
+ * Control Info -- 1: a normal world packet may use secure context
+ * 0: non-secure packet for this context can't use secure context
+ *
+ * For devices that do not have SA2UL setting this bit would cause no action
+ *
+ */
+#define sa_DM_CONFIG_USE_SECURE_CTX_FOR_NON_SECURE_CHANNEL ((uint16_t) (0x0008U))
+
+/**
+ * @def sa_DM_CONFIG_USE_DKEK
+ * Control Info -- 1: Set the USE_DKEK flag in the security context so
+ * that DKEK programmed by DMSC is loaded in-band
+ * instead of user-supplied key
+ * 0: Do not set USE_DKEK flag. User supplies a key
+ * directly.
+ *
+ * For devices that do not have SA2UL setting this bit would cause no action
+ *
+ */
+#define sa_DM_CONFIG_USE_DKEK ((uint16_t) (0x0010U))
+
+
+/*@}*/
+/** @} */
+
/**
* @ingroup salld_api_structures
* @brief Data Mode Configuration Parameters structure
*
- * Data structure defines the Data Mode specific configuration parameters excluding the keys
+ * Data structure defines the Data Mode specific configuration parameters excluding the keys.
*
+ * Due to hardware limiations in IP, below restrictions apply :
+ *
+ @verbatim
+ ---------------------------------------------------------------------------
+ | Cipher Mode | Restriction |
+ ---------------------------------------------------------------------------
+ | - sa_CipherMode_CCM | - (IV Size + Salt Size) should not exceed 13 |
+ | | - AAD size should not exceed 14 |
+ | | - authentication mode should be null |
+ ---------------------------------------------------------------------------
+ | - sa_CipherMode_GCM | - (IV Size + Salt Size) should be 12 |
+ | | - AAD size should not exceed 16 |
+ | | - authentication mode should be null |
+ ---------------------------------------------------------------------------
+ | - sa_CipherMode_DES_CBC | - (IV Size should be 8 |
+ | | - Salt size should be 0 |
+ ---------------------------------------------------------------------------
+ | - sa_CipherMode_3DES_CBC | - (IV Size should be 8 |
+ | | - Salt size should be 0 |
+ ---------------------------------------------------------------------------
+ | - sa_CipherMode_KASUMI_F8| - (IV Size should be 8 |
+ | | |
+ ---------------------------------------------------------------------------
+ | - sa_CipherMode_SNOW3G_F8| - (IV Size should be 16 |
+ | | |
+ ---------------------------------------------------------------------------
+
+ ---------------------------------------------------------------------------
+ | Auth Mode | Restriction |
+ ---------------------------------------------------------------------------
+ | - sa_AuthMode_GMAC | - (IV Size + Salt Size) should be 12 |
+ | | - AAD size should not exceed 16 |
+ | | - cipher mode should be null |
+ ---------------------------------------------------------------------------
+ | - sa_AuthMode_GMAC_AH | - (IV Size should be 8 |
+ | | - Salt size should be 4 |
+ | | - cipher mode should be null |
+ ---------------------------------------------------------------------------
+ | - sa_AuthMode_KASUMI_F9 | - (IV Size should be 8 |
+ | | |
+ ---------------------------------------------------------------------------
+ @endverbatim
*/
typedef struct {
+ uint16_t ctrlBitMap; /**< Various control information as specified at @ref SALLDDmConfigCtrlBit */
uint16_t sessionEncKeySize; /**< Specify the size of the session encryption key in bytes */
uint16_t sessionMacKeySize; /**< Specify the size of the session mac key in bytes */
uint16_t sessionSaltSize; /**< Specify the size of the session salt used in the GCM/CCM operation in bytes */
uint16_t aadSize; /**< Specify the size of the additional authenticated data in bytes used in CCM and GCM modes */
uint16_t enc; /**< TRUE: Encryption(To-Air); FALSE: Decryption (From-Air)*/
uint16_t enc1st; /**< TRUE: Perform encryption first; FALSE: Perform authentication first */
+#if defined(NSS_LITE2)
+ uint8_t priv; /**< Specify the priv for the security context creation */
+ uint8_t privId; /**< Specify the priv ID for the security context to checking with incoming packets to match */
+#endif
} Sa_DataModeConfigParams_t;
/**
uint8_t ctrlBitfield; /**< Control Bit Map to specify destination related operations such as local DMA
as defined at @ref SALLDDestInfoCtrlBit */
- uint8_t flowID; /**< Specify the 8-bit CPPI Flow ID */
- uint16_t queueID; /**< Specify the 16-bit destination Queue ID */
+ uint16_t flowID; /**< Specify the CPPI Flow ID */
+ uint16_t queueID; /**< Specify the 16-bit destination Queue ID (OR Ring ID for SA2UL) */
uint32_t swInfo0; /**< User-defined channel-specific parameter which will be placed in SwInfo0 for packets from SA */
uint32_t swInfo1; /**< User-defined channel-specific parameter which will be placed in SwInfo1 for packets from SA */
-} Sa_DestInfo_t;
+} Sa_DestInfo_t;
/**
* @ingroup salld_api_structures
* @ingroup salld_api_constants
* @brief Define the maximum key size supported by SASS
*/
+#if defined(NSS_LITE2)
+#define SALLD_MAX_KEY_SIZE 64
+#else
#define SALLD_MAX_KEY_SIZE 32
+#endif
/**
* @defgroup SALLDIpsecKeyCtrlInfo SALLD IPSEC Key Control Info Bit Definitions
* Control Info -- Set: SALT available
*/
#define sa_DATA_MODE_KEY_CTRL_SALT 0x0004
+/**
+ * @def sa_DATA_MODE_KEY_USE_DKEK
+ * Control Info -- Set: USE_DKEK field in security context
+ */
+#define sa_DATA_MODE_KEY_USE_DKEK 0x0008
/*@}*/
/** @} */
/**
* @defgroup SALLDKeyCtrlInfo SALLD Key Control Info Control Bit Definitions
* @ingroup salld_api_constants
+
* @{
*
* @name SALLD Key Control Info Control Bit Definitions
* @ingroup salld_api_constants
* @brief Define the maxmium number of software info parameters at @ref Sa_SWInfo_t.
*/
-#define sa_MAX_SW_INFO_SIZE 3
+#define sa_MAX_SW_INFO_SIZE 3
/**
* @ingroup salld_api_structures
* be delivered to SA. It will be provided by the SA LLD based on the channel configuration
* parameters and the security protocols.The software information words should be copied
* to the CPPI Software words area as provided through the CPPI LLD or equivalent component.
+ *
+ * for SA2_UL (Ultra Lite Generation 2) devices, size is always 4 and the swInfo[3] would
+ * hold the first 32 bits of Protocol Specific data of CPPI
*/
typedef struct {
uint16_t size; /**< Specify the software info size in 32-bit words */
uint32_t swInfo[sa_MAX_SW_INFO_SIZE]; /**< Specify the software information for SA */
} Sa_SWInfo_t;
+
/**
* @ingroup salld_api_macros
* @brief sa_SWINFO_UPDATE_DEST_INFO is used to update the destination information within swInfo[2] at @ref Sa_SWInfo_t
*
+ * @note this macro is not applicable for socs such as AM65XX or J721E that have second generation SA Ultra Lite (SA2_UL)
+ *
* @details The application may want to deliver output packets to different queues for load balance.
* This macro is used to update the destination queue and CPPI flow number in the Sa_SWInfo_t data structure
* provided by Sa_chanSendData()
* @name Data Sub Operation Modes
*
* Definition of the sub operation modes in Data mode.
+ * Enhanced the sub modes to more general types of protocols such as WiMax.
+ * Pleae refer to @ref Sa_DataModeConfigParams_t restrictions table
+ * on supported IV, Salt and AAD sizes
*
*/
/*@{*/
typedef enum {
sa_DM_GEN = 0, /**< General operation mode */
- sa_DM_CCM, /**< CCM */
- sa_DM_GCM, /**< GCM */
- sa_DM_GMAC, /**< GMAC */
+ sa_DM_CCM, /**< CCM IPSEC */
+ sa_DM_CCM_GEN, /**< CCM non IPSEC */
+ sa_DM_GCM, /**< GCM IPSEC */
+ sa_DM_GCM_GEN, /**< GCM non IPSEC */
+ sa_DM_GMAC, /**< GMAC IPSec */
+ sa_DM_GMAC_GEN, /**< GMAC non IPSec*/
sa_DM_GMAC_AH /**< GMAC for IPSEC AH */
} Sa_DM_subMode_e;
/*@}*/
/**
* @ingroup salld_api_constants
+ * Note: For NSS_LITE2 the effective command label size is 4 bytes less than the maximum size
* @brief Define the maxmium size of the command label stored at cmdLbBuf of @ref Sa_CmdLabelInfo_t.
*/
-#define sa_MAX_CMDLB_SIZE 96
-
+#if defined (NSS_LITE2)
+#define sa_MAX_CMDLB_SIZE ((uint32_t)(100U))
+#else
+#define sa_MAX_CMDLB_SIZE ((uint32_t)(96U))
+#endif
/**
* @ingroup salld_api_structures
* @brief SA Command Label Information structure
uint8_t* aad; /**< Contain the additional authenticated data in GCM/GMAC/CCM modes */
} Sa_PayloadInfo_t;
+/**
+ * @ingroup salld_api_structures
+ * @brief SA Rx Payload Information structure
+ *
+ * Data structure providing the miscellaneous header information of the received packets which is
+ * required for the IPSEC post-processing function to patch the outer IP header when the inner IP
+ * fragments have been reassembled by the hardware IP reassembly engine (RA) on the NSS Gen2 devices.
+ *
+ * @note: This structure should be provided at the Sa_chanReceiveData() call when the RA engine is enabled
+ * for inner IP. If it is not provided, the IPSEC post-processing function will not be able to handle
+ * inner IP reassembled packets correctly.
+ */
+typedef struct {
+ uint8_t ipOffset; /**< Specify the offset to the outer IP in the packet in bytes */
+ uint8_t ipOffset2; /**< Specify the offset to the inner IP in the packet in bytes
+ (0: indicates there is no inner IP) */
+} Sa_RxPayloadInfo_t;
+
+
/**
* @ingroup salld_api_structures
* @brief SA IPSEC NAT-T structure
* - natTInfo is present
*/
#define sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO 0x0010
+/**
+ * @def sa_PKT_INFO_VALID_RX_PAYLOAD_INFO
+ * - rxPayloadInfo is present
+ */
+#define sa_PKT_INFO_VALID_RX_PAYLOAD_INFO 0x0020
+
/*@}*/
/** @} */
* - espTxRx_natTInfo is present
*/
#define sa_ESP_TXRX_VALID_IPSEC_NAT_T_INFO sa_PKT_INFO_VALID_IPSEC_NAT_T_INFO
+/**
+ * @def sa_ESP_TXRX_VALID_RX_PAYLOAD_INFO
+ * - rxPayloadInfo is present
+ */
+#define sa_ESP_TXRX_VALID_RX_PAYLOAD_INFO sa_PKT_INFO_VALID_RX_PAYLOAD_INFO
+
/*@}*/
/** @} */
4: AES-CTR or other stream-like encryption with 4-byte
alignment
block size: block encryption algorithm */
- Sa_ipsecNatTInfo_t natTInfo; /**< Specify the IPSEC NAT-T parameters, if natTInfo is present*/
+ Sa_ipsecNatTInfo_t natTInfo; /**< Specify the IPSEC NAT-T parameters, if natTInfo is present*/
+ Sa_RxPayloadInfo_t rxPayloadInfo;/**< Specify the received payload information in IPSEC modes */
} salldIpsecEspTxRxInfo_t;
/**
Sa_CmdLabelInfo_t cmdlb; /**< Specify the command label in data mode */
Sa_PayloadInfo_t payloadInfo;/**< Specify the payload information in data mode */
Sa_ipsecNatTInfo_t natTInfo; /**< Specify the IPSEC NAT-T parameters */
+ Sa_RxPayloadInfo_t rxPayloadInfo;/**< Specify the received payload information in IPSEC modes */
} Sa_PktInfo_t;
/**
typedef struct {
uint16_t scSize; /**< Specify the size of the required security context */
uint16_t scID; /**< Security Context ID specified by the application */
- uint8_t* scBuf; /**< Security Context Buffer provided by the application
+ uintptr_t scBuf; /**< Security Context Buffer provided by the application
(16-byte alignment required) */
} Sa_ScReqInfo_t;
*/
typedef void* Sa_Handle;
+/**
+ * @defgroup saConfigCtrlBit SA Configuration Control Bit Definitions
+ * @ingroup salld_api_constants
+ * @{
+ *
+ * @name SA Configuration Control Bit Definitions
+ *
+ * Bitmap definition of the ctrlBitMap in Sa_Config_t.
+ *
+ */
+/*@{*/
+/**
+ * @def sa_CONFIG_CTRL_BITMAP_TRIGGER_SYS_ERR_HALT
+ * Control Info -- 0:Disable trigger PDSP halt during system errors (refer to @ref appendix3)
+ * 1:Enables trigger PDSP halt during system errors (for Debug Purpose only).
+ */
+
+#define sa_CONFIG_CTRL_BITMAP_TRIGGER_SYS_ERR_HALT 0x0001
+
+/**
+ * @def sa_CONFIG_CTRL_BITMAP_TRIGGER_PKT_INFO_LOG
+ * Control Info -- 0:Disable internal internal packet information data collection (refer to @ref appendix3)
+ * 1:Enables internal internal packet information data collection (for Debug Purpose only)
+ *
+ * @note This control bit is applicable to Air Cipher channels only. This fetaure should not be enabled if there might be
+ * both Air Cipher and SRTP channels. This feature bit is not supported for C6678 device.
+ */
+
+#define sa_CONFIG_CTRL_BITMAP_TRIGGER_PKT_INFO_LOG 0x0002
+
+/**
+ * @def sa_CONFIG_CTRL_BITMAP_SET_SCPTR_RANGE
+ * Control Info -- 0:Disable setting of security context pointer range limit set
+ * 1:Enables security context pointer range limit set
+ *
+ * @note This control bit is applicable to SA2UL only (for other generations it is don't care).
+ * For SA2UL promote (packet from non secure to secure operations), the security context range needs to be
+ * set in SCPTR_Promote_Range registers
+ */
+
+#define sa_CONFIG_CTRL_BITMAP_SET_SCPTR_RANGE 0x0004
+
+/**
+ * @def sa_CONFIG_CTRL_BITMAP_LIMIT_ACCESS
+ * Control Info -- 0: All SA2UL registers may be accessed
+ * 1: Limit access to SA2UL registers which are reserved
+ * for use by DMSC firmware
+ *
+ * @note This control bit is applicable to SA2UL only (for other generations it is don't care).
+ * It is furthermore only necessary on High Secure (HS) device variants
+ * when an application wishes to share access to the SA2UL instance which
+ * is owned by DMSC firmware. DMSC prohibits read/write access to MMRA
+ * region on this instance, so this bit has the following effect:
+ *
+ * * Bypasses programming ENGINE_ENABLE register. DMSC sets all engines
+ * to enabled at device boot. The driver can confirm engine status
+ * through the ENGINE_STATUS register.
+ *
+ * * Ignores the SET_SCPTR_RANGE control flag and bypasses any attempt to
+ * access the SCPTR promote registers
+ */
+
+#define sa_CONFIG_CTRL_BITMAP_LIMIT_ACCESS 0x0008
+
+
+
+/*@}*/
+/** @} */
+
/**
* @ingroup salld_api_structures
* @brief The SALLD Call-out function table
*
* @sa Sa_ScReqInfo_t
*
+ * @note:Both the base address and size of the security context buffer should be cache-line and csche-line size
+ * aligned if it is allocated at cacheable memory, otherwise, the base address should be 16-byte aligned.
+ * It is highly recommended to place the security context buffers at non-cacheable memory
+ * since they are accessed and maintained by the SA sub-system primarily
*/
void (*ScAlloc) (Sa_ChanHandle handle, Sa_ScReqInfo_t* scReqInfo);
uint16_t ctrlBitMap; /**< Various configuration information as specified at @ref saSizeConfigCtrlBit */
} Sa_SizeCfg_t;
+/**
+ * @ingroup salld_api_structures
+ * @brief SA Security Context Range Structure for promote operations
+ *
+ * @details for SA2UL promote operations, the range register needs to be set with correct address ranges
+ */
+typedef struct {
+ uint32_t scPtrPromoteLowRangeL; /**< The lower 32-bits of SCPTR lower limit (must be 4KB aligned) */
+ uint32_t scPtrPromoteLowRangeH; /**< The upper 16-bits of SCPTR lower limit */
+ uint32_t scPtrPromoteHighRangeL; /**< The lower 32-bits of SCPTR upper limit (must be 4KB aligned) */
+ uint32_t scPtrPromoteHighRangeH; /**< The upper 16-bits of SCPTR upper limit */
+} Sa_ScPtrRangeCfg_t;
+
/**
* @defgroup saEngSelMode SA Engine Selector Algorithms
* @ingroup salld_api_constants
void *instPoolBaseAddr; /**< Base address of the global shared memory pool from which global
LLD instance & channel instance memory is allocated.*/
void *scPoolBaseAddr; /**< Base address of the global shared memory pool from which SA
- security context memory is allocated. This is a DMA\92able memory */
+ security context memory is allocated. This is a DMA-able memory */
+ Sa_ScPtrRangeCfg_t scPtrRange; /**< Security Context Buffer Range low and high address configuration */
+ uint32_t ctrlBitMap; /**< Various configuration information as specified at @ref saConfigCtrlBit */
} Sa_Config_t;
/**
* @name PKA Arithmetic Operation Types
*
* Definition of PKA Arithmetic Operation Types
- * Parameter operation of Sa_PkaReqInfo_t should be set to one of these types.
+ * Parameter operation of @ref Sa_PkaReqInfo_t and @ref Sa_PkaReqInfo2_t should be set
+ * to one of these types.
*/
/*@{*/
typedef enum {
+ /**
+ * List of PKA basic operations supported by both NSS PKA Gen1 and Gen2 devices.
+ */
sa_PKA_OP_ADD = 0, /**< Large Vector Addition (A+B)*/
sa_PKA_OP_SUB, /**< Large Vector Subtraction (A-B)*/
sa_PKA_OP_MUL, /**< Large Vector Mutiplication (A*B)*/
sa_PKA_OP_LSHIFT, /**< Large Vector Shift Left (A<<shiftval)*/
sa_PKA_OP_COMP, /**< Large Vector Comparison (A?B)*/
sa_PKA_OP_COPY, /**< Large Vector Copy (A->C)*/
- sa_PKA_OP_EXP2, /**< Large Vector Exponentiation (Cexp(A)mod(B))(2-bit ACT) */
- sa_PKA_OP_EXP4 /**< Large Vector Exponentiation (Cexp(A)mod(B))(4-bit ACT) */
+ sa_PKA_OP_EXP2, /**< Large Vector Exponentiation (Cexp(A)mod(B))(2-bit ACT) (NSS PKA Gen1 only) */
+ sa_PKA_OP_EXP4, /**< Large Vector Exponentiation (Cexp(A)mod(B))(4-bit ACT) (NSS PKA Gen1 only) */
+ sa_PKA_OP_ADD_SUB, /**< Large Vector Addition plus Substraction (A+C-B) (NSS PKA Gen2 only) */
+ sa_PKA_OP_MOD, /**< Large Vector Modulo (A%B) (NSS PKA Gen2 only) */
+ /**
+ * List of PKA complex operations supported by NSS PKA Gen2 devices only.
+ */
+ sa_PKA_OP_MODEXP, /**< Large Vector Modular Exponentiation: M**E(mod N) */
+ sa_PKA_OP_MODEXP_CRT, /**< Large Vector Modular Exponentiation: CRT CRTpq(Mp**Dp (mod p), Mq**Dq (mod q), qInv) */
+ sa_PKA_OP_MODINVp, /**< Large Vector Modular Inversion (prime): (1/Z) (mod N) */
+ sa_PKA_OP_MODINV2m, /**< Large Vector Modular Inversion (binary): (1/Z) (mod N) */
+ sa_PKA_OP_ECp_ADD, /**< Large Vector Point Add on a Prime Field Curve:
+ * P1_xyx + P2_xyx ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) */
+ sa_PKA_OP_ECp_MUL, /**< Large Vector Point Multiply on a Prime Field Curve:
+ * k*P1_xyx ==> P0_xyz with P1_z = 1, on prime curve y**2=x**3+ax+b (mod p) */
+ sa_PKA_OP_ECp_SCALE, /**< Large Vector Point Scale on a Prime Field Curve:
+ * P1_xyx ==> P0_xyz with P0_z = 1, on prime curve y**2=x**3+ax+b (mod p) */
+ sa_PKA_OP_ECp_MUL_SACLE, /**< Large Vector Point Multiply following by Scale on a Prime Field Curve:
+ * k*P1_xyx ==> P0_xyz with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p) */
+ sa_PKA_OP_EC2m_ADD, /**< Large Vector Point Add on a Binary Field Curve:
+ * P1_xyx + P2_xyx ==> P0_xyz, on binary curve y**2=x**3 + ax + b (mod p) */
+ sa_PKA_OP_EC2m_MUL, /**< Large Vector Point Multiply on a Binary Field Curve:
+ * k*P1_xyx ==> P0_xyz with P1_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
+ sa_PKA_OP_EC2m_SCALE, /**< Large Vector Point Scale on a Binary Field Curve:
+ * P1_xyx ==> P0_xyz with P0_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
+ sa_PKA_OP_EC2m_MUL_SACLE, /**< Large Vector Point Multiply following by Scale on a Binary Field Curve:
+ * k*P1_xyx ==> P0_xyz with P1_z = 1 and P0_z = 1, on binary curve y**2+xy =x**3+ax**2+b (mod p) */
+ sa_PKA_OP_ECp_DSA_SIGN, /**< Large Vector ECDSA sign operation on a Prime Field Curve:
+ * k*P1_xyx ==> P0_xyz with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p)
+ * r = P0x mod N, s = 1/k * (h + rd) mod N where h = hash(m)n, d = private key
+ */
+ sa_PKA_OP_ECp_DSA_VERIFY /**< Large Vector ECDSA verify operation on a Prime Field Curve:
+ * u1*P1_xyx + u2 * Y ==> P0_xyz with P1_z = 1 and P0_z = 1, on prime curve y**2=x**3 + ax + b (mod p)
+ * u1 = h * w(mod N) and u2 = r * w mod N where where w = 1/s * mod N, h = hash(m)n, Y = public key
+ */
} Sa_PkaOpTypes_t;
/*@}*/
/** @} */
+/**
+ * @defgroup PkaOpStatusCodes PKA Complex Operation Status Codes
+ * @ingroup salld_api_constants
+ * @{
+ *
+ * @name PKA Complex Operation Status Codes
+ *
+ * Status codes returned by PKA module for complex operation.
+ */
+/*@{*/
+/**
+ * @def sa_PKA_OP_STATUS_SUCCESS
+ * PKA Complex Operation executed successfully
+ */
+#define sa_PKA_OP_STATUS_SUCCESS 0x01
+/**
+ * @def sa_PKA_OP_STATUS_PARAM_EVEN
+ * Error: Modulus or Prime polynomial is even
+ */
+#define sa_PKA_OP_STATUS_PARAM_EVEN 0x03
+/**
+ * @def sa_PKA_OP_STATUS_PARAM_ZERO
+ * Error: Exponent or Multiplier k is zero
+ */
+#define sa_PKA_OP_STATUS_PARAM_ZERO 0x05
+/**
+ * @def sa_PKA_OP_STATUS_PARAM_SHORT
+ * Error: Modulus is too short
+ */
+#define sa_PKA_OP_STATUS_PARAM_SHORT 0x07
+/**
+ * @def sa_PKA_OP_STATUS_PARAM_ONE
+ * Error: Exponent or Multiplier k is one
+ */
+#define sa_PKA_OP_STATUS_PARAM_ONE 0x09
+/**
+ * @def sa_PKA_OP_STATUS_INFINITY
+ * Result is "at-infinity" (Z=0, not an error if
+ * the scalar 'k' was the curve's order)
+ */
+#define sa_PKA_OP_STATUS_INFINITY 0x0D
+/**
+ * @def sa_PKA_OP_STATUS_ERR_INFINITY
+ * Error: An intermediate result of ECpMUL was "at-infinity"
+ */
+#define sa_PKA_OP_STATUS_ERR_INFINITY 0x0F
+/**
+ * @def sa_PKA_OP_STATUS_NO_INVERSE
+ * Error: No inverse exist
+ */
+#define sa_PKA_OP_STATUS_NO_INVERSE 0x17
+
+/*@}*/
+/** @} */
+
+
/**
* @defgroup PkaCompResults PKA Comparison Results
* @ingroup salld_api_constants
/*
* @ingroup salld_api_constants
- * @brief Define the maxmium size of the PKA operands in 32-bit words.
+ * @brief Define the maxmium sizes of the PKA operands in 32-bit words.
*/
-#define sa_MAX_PKA_OPERAND_SIZE 128 /**< 4k-bits or 128 32-bit words */
-#define sa_MAX_PKA_OPERAND_SIZE_EXP4 64 /**< 2k-bits or 64 32-bit words */
+#define sa_MAX_PKA_OPERAND_SIZE_GEN1 128 /**< General Operations 4k-bits or 128 32-bit words */
+#define sa_MAX_PKA_OPERAND_SIZE_EXP4 64 /**< EXP4 operation: 2k-bits or 64 32-bit words */
+
+#define sa_MAX_PKA_OPERAND_SIZE_GEN2 130 /**< General operations 4160 bits or 130 32-bit words */
+#define sa_MAX_PKA_OPERAND_SIZE_ECp 24 /**< Prime Curve related operations: 24 32-bit words */
+#define sa_MAX_PKA_OPERAND_SIZE_EC2m 18 /**< Binary Curve related operations:18 32-bit words */
+#ifdef NSS_PKA_GEN2
+#define sa_MAX_PKA_OPERAND_SIZE sa_MAX_PKA_OPERAND_SIZE_GEN2
+#else
+#define sa_MAX_PKA_OPERAND_SIZE sa_MAX_PKA_OPERAND_SIZE_GEN1
+#endif
+
/**
* @ingroup salld_api_structures
* @brief SALLD PKA Operation Request Structure
* @par
*
* Restrictions of input parameters:
- * - Add: Alength, Blength > 0
- * - Subtract: Alength, Blength > 0; Alength >= Blength
- * - Multiply: Alength, Blength > 0
+ * - Add: 0 < Alength, Blength <= Max Len (128)
+ * - Subtract:0 < Alength, Blength <= Max Len (128); Aoperand >= Boperand
+ * - Multiply: 0 < Alength, Blength <= Max Len (128)
* - Divide:
* - Alength, Blength > 1
* - Alength >= Blength
- * - Boperand cannot be zero
* - Most significant word of Boperand can not be zero
- * - Right/Left Shift: Alength > 0
- * - Compare: Alength, Blength > 0; Alength = Blength
- * - Copy: Alength > 0
+ * - Right/Left Shift: 0 < Alength <= Max Len (128)
+ * - Compare: 0 < Alength, Blength <= Max Len (128); Alength = Blength
+ * - Copy: 0 < Alength <= Max Len (128)
* - Exponentitation (2-bit/4-bit ACT):
* - Alength > 0
* - Blength > 1
} Sa_PkaReqInfo_t;
/**
- * @defgroup SALLDRngConfigCtrlInfo SALLD RNG Configuration Control Info Bit Definitions
- * @ingroup salld_api_constants
- * @{
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Basic Operation Parameters Structure
*
- * @name RNG Configuration Control Info Bit Definitions
+ * This structure defines the input and output parameters for PKA basic operations
*
- * Bitmap definition of the ctrlBitfield in @ref Sa_RngConfigParams_t.
- */
-/*@{*/
-/**
- * @def sa_RNG_CTRL_REINIT
- * Control Info -- Set: Force re-initialization
- * Clear: Perform initialization only if not actived
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - Add: 0 < ALen, BLen <= Max Len (130)
+ * - Subtract: 0 < ALen, BLen <= Max Len (130); A >= B
+ * - AddSub: 0 < ALen <= Max Len (130); (A+C) >= B; A, B, C all use ALen and BLen is ignored.
+ * - Multiply: 0 < ALen, BLen <= Max Len (130)
+ * - Divide and Modulo:
+ * - ALen, BLen > 1
+ * - ALen >= BLen
+ * - Most significant 32-bit word of B operand cannot be zero
+ * - Right/Left Shift: 0 < ALen <= Max Len (130)
+ * - Compare: 0 < ALen <= Max Len (130); Both A and B use ALen and BLen is ignored.
+ * - Copy: 0 < ALen <= Max Len (130)
*/
-#define sa_RNG_CTRL_REINIT 0x0001
+typedef struct {
+ uint32_t* pA; /**< Pointers to Aoperand in 32-bit word array */
+ uint32_t* pB; /**< Pointers to Boperand in 32-bit word array */
+ uint32_t* pC; /**< Pointers to Coperand in 32-bit word array */
+ uint32_t numShiftBits; /**< Specify number of bits in shift operation */
+ uint32_t* pRem; /**< Pointer to the 32-bit word buffer to store the reminder */
+ uint32_t* pResult; /**< Pointer to the 32-bit word buffer to store the operation result */
+ uint16_t resultSize; /**< Store the size of operation result in 32-bit words */
+ uint16_t remSize; /**< Store the size of reminder in 32-bit words of Divide/Modulo operations*/
+ Sa_PkaCompResults_t cmpResult; /**< Store the comparison result */
+} Sa_PkaBasicOpParams_t;
+
/**
- * @def sa_RNG_CTRL_ENABLE_INT
- * Control Info -- Set: Interrupt mode
- * Clear: Poll mode
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Modular Exponentiation Operation Parameters Structure
+ *
+ * This structure defines the input and output parameters of PKA Modular Exponentiation operation as
+ * described with the following formula:
+ *
+ * M**E(mod N) ==> R
+ *
+ * E: ALen
+ * M, N, R: BLen
+ *
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - 0 < ALen <= Max Len (130)
+ * - 1 < BLen <= Max Len (130)
+ * - Modulus N must be odd (i.e. the least significant bit must be ONE)
+ * - Modulus N > 2**32
+ * - Base M < Modulus N
+ * - Number of pre-calculated odd powers to use >= 1
+ *
*/
-#define sa_RNG_CTRL_ENABLE_INT 0x0002
+typedef struct {
+ uint32_t* pE; /**< Pointer to Exponent in 32-bit word array */
+ uint32_t* pN; /**< Pointer to Modulus N in 32-bit word array */
+ uint32_t* pM; /**< Pointer to Message (Base) M in 32-bit word array */
+ uint32_t numOddPowers; /**< Specify number of pre-calculated odd powers to use */
+ uint32_t* pResult; /**< Pointer to the 32-bit word buffer to store the operation result */
+} Sa_PkaModExpParams_t;
+
/**
- * @def sa_RNG_CTRL_RESET
- * Control Info -- Set: RNG reset
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Modular Exponentiation CRT Operation Parameters Structure
+ *
+ * This structure defines the input and output parameters of PKA Modular Exponentiation CRT operation as
+ * described with the following formula:
+ *
+ * CRTpq(Mp**Dp mod p, Mq**Dq mod q, qInv) ==> R
+ *
+ * where Mp = M mod p, Mq = M mod q and CRTpq(a, b, qInv) = ((a-b)*qInv mod p)*q + b
+ *
+ * Dp, Dq: ALen
+ * p, q, qInv: BLen
+ * M, R: 2*Blen
+ *
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - 0 < ALen <= Max Len (130)
+ * - 1 < BLen <= Max Len (130)
+ * - Modulus p and Modulus q must be odd (i.e. the least significant bit must be ONE)
+ * - Modulus p > Modulus q > 2**32
+ * - Modulus p and Modulus q must be co-prime (GCD(p,q) = 1)
+ * - TBD: 0 < Exp P < (Mod P - 1)
+ * - TBD: 0 < Exp Q < (Mod Q - 1)
+ * - (qInv * q) = 1 (mod p)
+ * - Base M < p*q
+ * - Number of pre-calculated odd powers to use >= 1
+ *
*/
-#define sa_RNG_CTRL_RESET 0x0004
-/*@}*/
-/** @} */
-
-
+typedef struct {
+ uint32_t* pDp; /**< Pointer to Exponent mod p in 32-bit word array */
+ uint32_t* pDq; /**< Pointer to Exponent mod q in 32-bit word array */
+ uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
+ uint32_t* pModQ; /**< Pointer to Modulus q in 32-bit word array */
+ uint32_t* pQInv; /**< Pointer to Modulus qInv in 32-bit word array */
+ uint32_t* pM; /**< Pointer to Message (Base) M in 32-bit word array */
+ uint32_t numOddPowers; /**< Specify number of pre-calculated odd powers to use */
+ uint32_t* pResult; /**< Pointer to the 32-bit word buffer to store the operation result */
+} Sa_PkaModExpCRTParams_t;
/**
* @ingroup salld_api_structures
- * @brief SALLD RNG Configuration Structure
+ * @brief SALLD PKA Modular Inversion Operation Parameters Structure
*
- * Data structure defines the RNG configuration related parameters
+ * This structure defines the input and output parameters of PKA Modular Inversion operation as
+ * described with the following formula:
+ *
+ * 1/Z (mod N) ==> R
+ *
+ * Z: ALen
+ * N, R: BLen
+ *
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - ModINVp: 0 < ALen <= Max Len (130)
+ * - ModINVp: 0 < BLen <= Max Len (130)
+ * - ModINV2m: 0 < ALen <= 18
+ * - ModINV2m: 0 < BLen <= 18
+ * - ModINV2m: Z < Modulus N
+ * - Modulus N must be odd (i.e. the least significant bit must be ONE)
+ * - Modulus N should not be 1
+ * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
*
*/
typedef struct {
- uint16_t ctrlBitfield; /**< Specify the initialization mode and other control information as defined
- at @ref SALLDRngConfigCtrlInfo */
- uint16_t clockDiv; /**< Specify the clock divider (1, 16) 0: default */
- uint32_t startupCycles; /**< Specify the number of clock cycles (2**8, 2**24) to start up
- the random number generator initially(0:default) */
- uint32_t minRefillCycles; /**< Specify the minimum number of clock cycles (2**6, 2**14) to generate
- the next random number (0:default) */
- uint32_t maxRefillCycles; /**< Specify the maximum number of clock cycles (2**8, 2**24) to generate
- the next random number (0:default) */
-} Sa_RngConfigParams_t;
+ uint32_t* pN; /**< Pointer to Modulus N in 32-bit word array */
+ uint32_t* pZ; /**< Pointer to operand Z in 32-bit word array */
+ uint32_t* pResult; /**< Pointer to the 32-bit word buffer to store the operation result */
+} Sa_PkaModInvParams_t;
/**
* @ingroup salld_api_structures
- * @brief SALLD RNG Output Structure
+ * @brief SALLD PKA Field Curve Point Structure
*
- * This structure defines the random number output provided upon request
- * with @ref Sa_getRandomNum().
+ * This structure specifies a point in projective format (X, Y, Z) on the Prime or Binary Field Curve used by
+ * ECp or EC2m related operations
+ *
+ * Where the EC (Elliptic Curve) is represented as y**2=x**3 + ax + b (mod p) and
+ * point in affine format (x,y) = (X/Z, Y/Z).
+ *
*/
typedef struct {
- uint32_t hi; /**< Upper 32 bits of the 64-bit Random Number output */
- uint32_t lo; /**< Lower 32 bits of the 64-bit Random Number output */
-} Sa_RngData_t;
+ uint32_t* pX; /**< Pointer to X in 32-bit word array */
+ uint32_t* pY; /**< Pointer to Y in 32-bit word array */
+ uint32_t* pZ; /**< Pointer to Z in 32-bit word array */
+} Sa_PkaECPoint_t;
/**
- * @ingroup salld_api_constants
- * @brief Define the maximum number of buffers the module (SALLD) can request
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Elliptic Curve (EC) Point Add Operation Parameters Structure
+ *
+ * This structure defines the input and output parameters of Point Add operation on a
+ * Prime (Binary) Field Curve as described below
+ *
+ * P1_xyz + P2_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or
+ * binary curve y**2+xy=x**3+ax**2+b (mod p)
+ *
+ * ALen: not used
+ * p, a, b, P1_x, P1_y, P1_z, P2_x, P2_y, P2_z, P0_x, P0_y, P0_z: BLen
+ *
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
+ * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
+ * - Binary Curve: Modulus p must be a prime
+ * - Prime Curve: Modulus p must be a prime > 2**63
+ * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
+ * - a < p and b < p
+ * - P1 and P2 must be on the curve
+ */
+typedef struct {
+ uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
+ uint32_t* pEcA; /**< Pointer to EC curve parameter a in 32-bit word array */
+ uint32_t* pEcB; /**< Pointer to EC curve parameter b in 32-bit word array */
+ Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
+ Sa_PkaECPoint_t point2; /**< Pointers to input point 2 (P2_xyz) */
+ Sa_PkaECPoint_t point0; /**< Pointers to output point 0 (P0_xyz) */
+} Sa_PkaECAddParams_t;
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Elliptic Curve (EC) Point Multiply Operation Parameters Structure
+ *
+ * This structure defines the input and output parameters of Point Multiply operation on a
+ * Prime (Binary) Field Curve as described below
+ *
+ * k*P1_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or where P1_z = 1
+ * binary curve y**2+xy=x**3+ax**2+b (mod p)
+ * k: Alen
+ * p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
+ *
+ * c**2 = b (md p) on the binary curve
+ *
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
+ * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
+ * - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
+ * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
+ * - Binary Curve: Modulus p must be a prime
+ * - Prime Curve: Modulus p must be a prime > 2**63
+ * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
+ * - a < p and b < p
+ * - P1 must be on the curve
+ * - 1 < k <= n, where n is the curve's order.
+ */
+typedef struct {
+ uint32_t* pK; /**< Pointer to parameter k in 32-bit word array */
+ uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
+ uint32_t* pEcA; /**< Pointer to EC curve parameter a in 32-bit word array */
+ uint32_t* pEcBC; /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
+ Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
+ Sa_PkaECPoint_t point0; /**< Pointers to output point 0 (P0_xyz) */
+} Sa_PkaECMulParams_t;
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Elliptic Curve (EC) Point Scale Operation Parameters Structure
+ *
+ * This structure defines the input and output parameters of Point Scale operation on a
+ * Prime (Binary) Field Curve as described below
+ *
+ * P1_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or where P0_z = 1
+ * binary curve y**2+xy=x**3+ax**2+b (mod p)
+ * Alen (not used)
+ * p, a, b, P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
+ *
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
+ * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
+ * - Binary Curve: Modulus p must be a prime
+ * - Prime Curve: Modulus p must be a prime > 2**63
+ * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
+ * - a < p and b < p
+ * - P1 must be on the curve
+ */
+typedef struct {
+ uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
+ uint32_t* pEcA; /**< Pointer to equation parameter a in 32-bit word array */
+ uint32_t* pEcB; /**< Pointer to equation parameter b in 32-bit word array */
+ Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
+ Sa_PkaECPoint_t point0; /**< Pointers to output point 0 (P0_xyz) */
+} Sa_PkaECScaleParams_t;
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Elliptic Curve (EC) DSA Sign Operation Parameters Structure
+ *
+ * This structure defines the input and output parameters of DSA Sign operation on a
+ * Prime (Binary) Field Curve as described below
+ *
+ * k*P1_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or where P1_z = 1
+ * binary curve y**2+xy=x**3+ax**2+b (mod p)
+ * k: Alen
+ * p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
+ *
+ * c**2 = b (md p) on the binary curve
+ *
+ * N: multiplicative (integer) order of the point P1 means that n times P1 = O
+ * h: messgae hash truncated to n bit Hash(m)n
+ * d: private key
+ *
+ * Output:
+ * r = P0x mod n;
+ * s = (1/k)(h + dr) mod N
+ *
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
+ * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
+ * - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
+ * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
+ * - Binary Curve: Modulus p must be a prime
+ * - Prime Curve: Modulus p must be a prime > 2**63
+ * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
+ * - a < p and b < p
+ * - P1 must be on the curve
+ * - 1 < k <= n, where n is the curve's order.
+ */
+typedef struct {
+ uint32_t* pK; /**< Pointer to parameter k in 32-bit word array */
+ uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
+ uint32_t* pEcA; /**< Pointer to EC curve parameter a in 32-bit word array */
+ uint32_t* pEcBC; /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
+ uint32_t* pN; /**< Pointer to multiplicative (integer) order N in 32-bit word array */
+ uint32_t* pH; /**< Pointer to hash data (h) in 32-bit word array */
+ uint32_t* pD; /**< Pointer to private key (d) in 32-bit word array */
+ Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
+ uint32_t* pR; /**< Pointer to output parameter r in 32-bit word array */
+ uint32_t* pS; /**< Pointer to output parameter s in 32-bit word array */
+} Sa_PkaECDSASignParams_t;
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Elliptic Curve (EC) DSA Verify Operation Parameters Structure
+ *
+ * This structure defines the input and output parameters of ECDSA Verify operation on a
+ * Prime (Binary) Field Curve as described below
+ *
+ * k*P1_xyz ==> P0_xyz, on prime curve y**2=x**3+ax+b (mod p) or where P1_z = 1
+ * binary curve y**2+xy=x**3+ax**2+b (mod p)
+ * k: Alen
+ * p, a, b (c), P1_x, P1_y, P1_z, P0_x, P0_y, P0_z: BLen
+ *
+ * c**2 = b (md p) on the binary curve
+ *
+ * N: multiplicative (integer) order of the point P1 means that n times P1 = O
+ * h: messgae hash truncated to n bit Hash(m)n
+ * d: private key
+ *
+ * Output:
+ * r = P0x mod n;
+ * s = (1/k)(h + dr) mod N
+ *
+ * @par
+ *
+ * Restrictions of input parameters:
+ * - Prime Curve: 1 < ALen <= 24 (maximum vector length is 768 bits)
+ * - Prime Curve: 1 < BLen <= 24 (maximum vector length is 768 bits)
+ * - Binary Curve: 1 < ALen <= 18 (maximum vector length is 571 bits)
+ * - Binary Curve: 1 < BLen <= 18 (maximum vector length is 571 bits)
+ * - Binary Curve: Modulus p must be a prime
+ * - Prime Curve: Modulus p must be a prime > 2**63
+ * - The highest word of the modulus vector, as indicated by BLen, may not be zero.
+ * - a < p and b < p
+ * - P1 must be on the curve
+ * - 1 < k <= n, where n is the curve's order.
+ */
+typedef struct {
+ uint32_t* pModP; /**< Pointer to Modulus p in 32-bit word array */
+ uint32_t* pEcA; /**< Pointer to EC curve parameter a in 32-bit word array */
+ uint32_t* pEcBC; /**< Pointer to EC curve parameter b (or c) in 32-bit word array */
+ uint32_t* pN; /**< Pointer to multiplicative (integer) order N in 32-bit word array */
+ uint32_t* pH; /**< Pointer to hash data (h) in 32-bit word array */
+ Sa_PkaECPoint_t pY; /**< Pointer to public key (y) in 32-bit word array */
+ Sa_PkaECPoint_t point1; /**< Pointers to input point 1 (P1_xyz) */
+ uint32_t* pR; /**< Pointer to signature parameter r in 32-bit word array */
+ uint32_t* pS; /**< Pointer to signature parameter s in 32-bit word array */
+ uint32_t* pRes; /**< Pointer to output parameter Result (res) in 32-bit word array */
+} Sa_PkaECDSAVerifyParams_t;
+
+/**
+ * @defgroup PkaOpModes PKA Operation Modes
+ * @ingroup salld_api_constants
+ * @{
+ *
+ * @name PKA Operation Modes
+ *
+ * Definition of PKA Operation Modes
+ * Parameter mode of @ref Sa_PkaReqInfo2_t should be set to one of these modes.
+ */
+/*@{*/
+typedef enum {
+ /**
+ * The API Sa_pkaOperation2() operates in blocking mode. The API call will not return until all specified operations
+ * are completed or some error occurs.
+ */
+ sa_PKA_MODE_WAIT = 0,
+
+ /**
+ * The API Sa_pkaOperation2() operates in non-blocking mode. The API call will return immediately when the first PKA
+ * operation is triggered or some input error occurs. The application should invoke API @ref Sa_pkaPoll() periodically
+ * until all specified PKA operations are completed or PKA error occurs.
+ *
+ */
+ sa_PKA_MODE_POLL,
+
+ /**
+ * The API Sa_pkaOperation2 operates in non-blocking mode. The API call will return immediately when the first PKA
+ * operation is triggered or some input error occurs. The application should invoke API @ref Sa_pkaPoll() when
+ * PKA interrupt occurs until all specified PKA operations are completed or PKA error occurs.
+ *
+ */
+ sa_PKA_MODE_INT
+
+} Sa_PkaOpModes_t;
+/*@}*/
+/** @} */
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD PKA Operation Request Structure for second generation PKA module
+ *
+ * This structure defines PKA request information which is used to perform the basic
+ * and complex large vector arithmetic operations on the second generation PKA.
+ *
+ */
+typedef struct {
+ Sa_PkaOpTypes_t operation; /**< Specify the arithmetic operation as defined at salldPkaOpTypes_t */
+ Sa_PkaOpModes_t mode; /**< Specify the operation mode as defined at salldPkaOpModes_t */
+ uint16_t aLen; /**< Specify the parameter ALen in 32-bit words */
+ uint16_t bLen; /**< Specify the parameter BLen in 32-bit words */
+ int statusCode; /**< Status code of the complex operation as defined at PkaOpStatusCodes */
+ union {
+ Sa_PkaBasicOpParams_t basicOp; /**< Specify the input/output parameters for all basic PKA operations */
+ Sa_PkaModExpParams_t modExp; /**< Specify the input/output parameters for modular exponentitation operation */
+ Sa_PkaModExpCRTParams_t modExpCRT; /**< Specify the input/output parameters for modular exponentitation CRT operation */
+ Sa_PkaModInvParams_t modInv; /**< Specify the input/output parameters for modular inversion operation */
+ Sa_PkaECAddParams_t ecAdd; /**< Specify the input/output parameters for EC point add operation */
+ Sa_PkaECMulParams_t ecMul; /**< Specify the input/output parameters for EC point multiply operation */
+ Sa_PkaECScaleParams_t ecScale; /**< Specify the input/output parameters for EC point scale operation */
+ Sa_PkaECDSASignParams_t ecDSASign; /**< Specify the input/output parameters for ECDSA Sign operation */
+ Sa_PkaECDSAVerifyParams_t ecDSAVerify; /**< Specify the input/output parameters for ECDSA Sign operation */
+ } params; /**< Specify the operation specific input/output parameters */
+} Sa_PkaReqInfo2_t;
+
+/**
+ * @defgroup SALLDRngConfigCtrlInfo SALLD RNG Configuration Control Info Bit Definitions
+ * @ingroup salld_api_constants
+ * @{
+ *
+ * @name RNG Configuration Control Info Bit Definitions
+ *
+ * Bitmap definition of the ctrlBitfield in @ref Sa_RngConfigParams_t.
+ */
+/*@{*/
+/**
+ * @def sa_RNG_CTRL_REINIT
+ * Control Info -- Set: Force re-initialization
+ * Clear: Perform initialization only if not actived
+ */
+#define sa_RNG_CTRL_REINIT 0x0001
+/**
+ * @def sa_RNG_CTRL_ENABLE_INT
+ * Control Info -- Set: Interrupt mode
+ * Clear: Poll mode
+ */
+#define sa_RNG_CTRL_ENABLE_INT 0x0002
+/**
+ * @def sa_RNG_CTRL_RESET
+ * Control Info -- Set: RNG reset
+ */
+#define sa_RNG_CTRL_RESET 0x0004
+
+/*@}*/
+
+
+/**
+ * @defgroup SALLDRng2ConfigCtrlInfo SALLD RNG2 Configuration Control Info Bit Definitions
+ * @ingroup salld_api_constants
+ * @{
+ *
+ * @name RNG2 Configuration Control Info Bit Definitions
+ *
+ * Bitmap definition of the ctrlBitfield in @ref Sa_Rng2ConfigParams_t.
+ */
+/*@{*/
+/**
+ * @def sa_RNG2_CTRL_REINIT
+ * Control Info -- Set: Force re-initialization
+ * Clear: Perform initialization only if not actived
+ */
+#define sa_RNG2_CTRL_REINIT 0x0001
+
+/**
+ * @def sa_RNG_CTRL_RESET
+ * Control Info -- Set: RNG2 reset
+ */
+#define sa_RNG2_CTRL_RESET 0x0002
+
+/**
+ * @def sa_RNG2_CTRL_DRBG_USE
+ * Control Info -- Set: DRBG use for SA2UL
+ * Clear: No DRBG for SA2UL
+ */
+#define sa_RNG2_CTRL_DRBG_USE 0x0004
+
+/**
+ * @def sa_RNG2_CTRL_DRBG_KNOWN_TESTS
+ * Control Info -- Set: DRBG use for SA2UL
+ * Clear: No DRBG for SA2UL
+ */
+#define sa_RNG2_CTRL_DRBG_KNOWN_TESTS 0x0008
+
+
+/*@}*/
+
+/** @} */
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD RNG Configuration Structure
+ *
+ * Data structure defines the RNG configuration related parameters
+ *
+ */
+typedef struct {
+ uint16_t ctrlBitfield; /**< Specify the initialization mode and other control information as defined
+ at @ref SALLDRngConfigCtrlInfo */
+ uint16_t clockDiv; /**< Specify the clock divider (1, 16) 0: default */
+ uint32_t startupCycles; /**< Specify the number of clock cycles (2**8, 2**24) to start up
+ the random number generator initially(0:default) */
+ uint32_t minRefillCycles; /**< Specify the minimum number of clock cycles (2**6, 2**14) to generate
+ the next random number (0:default) */
+ uint32_t maxRefillCycles; /**< Specify the maximum number of clock cycles (2**8, 2**24) to generate
+ the next random number (0:default) */
+} Sa_RngConfigParams_t;
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD RNG2 Configuration Structure
+ *
+ * Data structure defines the RNG2 configuration related parameters
+ *
+ */
+typedef struct {
+ uint16_t ctrlBitfield; /**< Specify the initialization mode and other control information as defined
+ at @ref SALLDRng2ConfigCtrlInfo */
+ uint16_t clockDiv; /**< Specify the clock divider (1, 16) 0: default */
+ uint32_t sampleCycles; /**< Sets the number of FRO samples that are XOR-ed together into one bit
+ to be shifted into the main shift register.
+ This value must be such that there is at least one bit of entropy (in total)
+ in each 8 bits that are shifted.
+ Note: Value 0 in this field selects 65536 FRO samples to be XOR-ed together */
+ uint32_t pStringLen; /** < Personalization string length in 32-bit words (valid values 1 thorugh 12) */
+ uint32_t pStringData[sa_MAX_PS_AI_WORD_COUNT]; /** < Personalization String and Additional Input for SP-800-90A
+ AES-256 DRBG (valid when DRBG is enabled */
+
+} Sa_Rng2ConfigParams_t;
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD RNG Output Structure
+ *
+ * This structure defines the random number output provided upon request
+ * with @ref Sa_getRandomNum().
+ */
+typedef struct {
+ uint32_t hi; /**< Upper 32 bits of the lower 64-bit Random Number output */
+ uint32_t lo; /**< Lower 32 bits of the lower 64-bit Random Number output */
+} Sa_RngData_t;
+
+/**
+ * @ingroup salld_api_structures
+ * @brief SALLD RNG2 Output Structure
+ *
+ * This structure defines the random number output provided upon request
+ * with @ref Sa_getRandomNum2().
+ */
+typedef struct {
+ uint32_t hihi; /**< Upper 32 bits of the higher 64-bit Random Number output */
+ uint32_t hilo; /**< Lower 32 bits of the higher 64-bit Random Number output */
+ uint32_t hi; /**< Upper 32 bits of the lower 64-bit Random Number output */
+ uint32_t lo; /**< Lower 32 bits of the lower 64-bit Random Number output */
+} Sa_Rng2Data_t;
+
+
+/**
+ * @ingroup salld_api_constants
+ * @brief Define the maximum number of buffers the module (SALLD) can request
*
*/
#define sa_N_BUFS 1
@@ -2564,6 +3553,22 @@ int16_t Sa_downloadImage (Sa_Handle handle, int modId, void* image, int sizeByte
*/
int16_t Sa_rngInit (Sa_Handle handle, Sa_RngConfigParams_t* cfg);
+/**
+ * @ingroup salld_api_functions
+ * @brief The function is called to initialize and configure the RNG (Random Number Generator) module
+ * inside SA2UL
+ *
+ * @remark For a multi-core device, it is up to the upper-layer application to make sure that only
+ * the master core performs the RNG hardware initialization.
+ *
+ * @param[in] handle SALLD instance identifier.
+ * @param[in] cfg Pointer the RNG configuration parameters as defined at @ref Sa_RngConfigParams_t
+ * @retval Value @ref salldRetCodes
+ * @pre None
+ */
+int16_t Sa_rng2Init (Sa_Handle handle, Sa_Rng2ConfigParams_t* cfg);
+
+
/**
* @ingroup salld_api_functions
* @brief This function returns a 64-bit true random number
*/
int16_t Sa_getRandomNum (Sa_Handle handle, uint16_t f_isr, Sa_RngData_t* rnd);
+/**
+ * @ingroup salld_api_functions
+ * @brief This function returns a 128-bit true random number
+ *
+ * @details This function is called to get a 64-bit true random number. It is a non-blocking function
+ * call which indicates the random number is not available if the RNG is still in the
+ * process of generating the next random number.
+ * @remark For a multi-core device, it is up to the application to prevent this function from being invoked
+ * by multiple CGEM cores simultaneously.
+ *
+ * @param[in] handle SALLD instance identifier.
+ * @param[in] f_isr Flag to indicate whether it is called from interrupt srevice routine
+ * @param[in] rnd Pointer to the 128-bit random number
+ * @retval Value @ref salldRetCodes
+ * @pre RNG is initialized
+ */
+int16_t Sa_getRandomNum2 (Sa_Handle handle, uint16_t f_isr, Sa_Rng2Data_t* rnd);
+
/**
* @ingroup salld_api_functions
* @brief Sa_rngClose decativates the SA RNG module
@@ -2593,6 +3616,18 @@ int16_t Sa_getRandomNum (Sa_Handle handle, uint16_t f_isr, Sa_RngData_t* rnd);
*/
int16_t Sa_rngClose (Sa_Handle handle);
+/**
+ * @ingroup salld_api_functions
+ * @brief Sa_rngClose decativates the SA RNG module
+ *
+ * @details This function deactivates the SA RNG module and clears LLD internal state.
+ *
+ * @param[in] handle The PA LLD instance identifier
+ * @retval Value @ref salldRetCodes
+ */
+int16_t Sa_rng2Close (Sa_Handle handle);
+
+
/**
* @ingroup salld_api_functions
* @brief This function initializes the PKA (Public Key Accelerator) module inside SA
*/
int16_t Sa_pkaInit (Sa_Handle handle);
+/**
+ * @ingroup salld_api_functions
+ * @brief This function downloads the PKA firmware image to the second generation PKA module.
+ *
+ * @details This function is used to download an executable firmware image to the second
+ * generation PKA module, triggers the firmware to run and verify its operation.
+ * The PKA firmware is required for PKA to perform complex operations such as
+ * modular exponentiation and etc.
+ *
+ * @param[in] handle SALLD instance identifier.
+ * @param[in] image The image to download
+ * @param[in] sizeWords The size of the image in 32-bit words
+ * @param[out] pVersion The pointer to PKA firmware reversion number
+ * @retval Value @ref salldRetCodes
+ * @pre The PKA module has been initialized through API @ref Sa_pkaInit.
+ */
+int16_t Sa_pkaDownloadImage (Sa_Handle handle, void* image, int sizeWords, uint32_t* pVersion);
+
/**
* @ingroup salld_api_functions
* @brief This function triggers a large vector arithmetic operation through the PKA module
* perform the previous operation or when timeout occurs.
* @remark For a multi-core device, it is up to the application to prevent this function from being invoked
* by multiple CGEM cores simultaneously.
+ * @note This API does not support the second generation PKA module
*
* @param[in] handle SALLD instance identifier.
* @param[in] pkaReqInfo Pointer to the PKA operation request information structure
*/
int16_t Sa_pkaOperation (Sa_Handle handle, Sa_PkaReqInfo_t* pkaReqInfo);
+/**
+ * @ingroup salld_api_functions
+ * @brief This function triggers a large vector arithmetic operation through the PKA module
+ *
+ * @details Sa_pkaOperation2 is the next generation of PKA API to replace @ref Sa_pkaOperation eventually.
+ * This new API supports both the first generation and second generation of PKA module.
+ * The function is called to perform basic or complex large vector arithmetic operations through
+ * the PKA module. It can operate in either blocking or non-blocking mode. In blocking mode, this API
+ * will not return until the PKA module completes all requested large vector arithmetic operations.
+ * In non-blocking mode, this API will returns immediately after it sets up and starts the first
+ * requested PKA operation. And then the API @ref Sa_pkaPoll() should be invoked periodically or
+ * per PKA interrupt until all PKA operations are completed and the final results are available.
+ * This function also returns with error code immediately if the PKA is still in the process to
+ * perform the previous operation or when timeout occurs.
+ *
+ * @note All simple operations should be done in blocking mode since it will only take a few cycles to
+ * complete those operaion.
+ *
+ * @param[in] handle SALLD instance identifier.
+ * @param[in] pPkaReqInfo Pointer to the PKA operation request information structure
+ * @retval Value @ref salldRetCodes
+ * @pre PKA is initialized. The complex operation will not work until the firmware image
+ * is downloaded through API @ref Sa_pkaDownloadImage.
+ */
+int16_t Sa_pkaOperation2 (Sa_Handle handle, Sa_PkaReqInfo2_t* pPkaReqInfo);
+
+/**
+ * @ingroup salld_api_functions
+ * @brief This function checks the status of the current large vector arithmetic operation and continue
+ * the operation accordingly..
+ *
+ * @details Sa_pkaPoll is used to support non-blocking PKA operations. It should be called periodically
+ * in Poll mode or per PKA interrupt in Interrupt mode. When it is invoked, this function checks
+ * the status of the current PKA operation. If the operation is still in progress, it just
+ * returns sa_PKA_OP_IN_PROGRESS. If the operation is complete and more operation is required,
+ * it will prepare and trigger the next (complex) operation and then return sa_PKA_OP_CONTINUE,
+ * otherwise, it copies operation results from the PKA registers and vector RAM to the result
+ * locations specified by the PKA request information data structure and return sa_PKA_OP_COMPLETE.
+ *
+ * @param[in] handle SALLD instance identifier.
+ * @param[out] pPkaReqInfo Pointer to the local copy of PKA operation request information structure
+ * @retval Value @ref salldRetCodes
+ * @pre PKA is initialized and Sa_pkaOperation2 has been invoked in non-block mode.
+ */
+int16_t Sa_pkaPoll (Sa_Handle handle, Sa_PkaReqInfo2_t* pPkaReqInfo);
+
/**
* @ingroup salld_api_functions
* @brief Sa_pkaClose decativates the SA PKA module
@@ -2766,13 +3866,14 @@ int16_t Sa_chanCreate (Sa_Handle handle, Sa_ChanConfig_t *cfg, void* bases[],
*/
int16_t Sa_chanClose (Sa_ChanHandle handle, void* bases[]);
-/**
+ /**
* @ingroup salld_api_functions
* @brief This function controls the operations of a channel instance of SALLD. It is
* used to configure and/or re-configure the SALLD channel with various control
* information. This function should be called multiple times to configure and
- * activate the SALLD channel during the call setup period. Then it is typically
- * called to perform re-key operation subsequently.
+ * activate the SALLD channel during the call setup period. Reconfiguration is
+ * applicable for SRTP for re-key operations and there is no reconfiguration
+ * supported for IPSec and Air Ciphering modes.
*
* @param[in] handle SALLD channel instance identifier.
* @param[in] chanCtrlInfo Pointer to SALLD channel control config structure.
@@ -2943,6 +4044,36 @@ int16_t Sa_chanGetSwInfo (Sa_ChanHandle handle, uint16_t dir, Sa_SWInfo_t* pChan
*
*/
uint16_t Sa_isScBufFree (uint8_t* scBuf);
+
+/**
+ * @ingroup salld_api_constants
+ * @brief Define the core dump collect buffer size in words (32 bit) supported by SASS.
+ */
+#define sa_CORE_DUMP_BUF_SIZE 2048
+
+/**
+ * @ingroup salld_api_functions
+ * @brief This function snap shots the internal registers and scratch memory locations
+ * for furt
+ *
+ * @param[in] handle SA system handle.
+ * @param[in] dbgInfoBuf Debug information collection buffer pointer
+ * @param[in] bufSize Debug information collection buffer size
+ * @retval TRUE if collection is successful; FALSE if otherwise
+ *
+ * @warning Note that system is halted after @ref Sa_coreDump is initiated. After the call to this API,
+ * it is up to the application software to redownload the firmware and restart SASS.
+ *
+ * @note This API is used to provide dump of internal data when requested by TI.
+ * These can be submitted via e2e.ti.com or your contracted support vehicle.
+ * When there is a JTAG connected to the system for collecting the data,
+ * Please use the fprintf() code provided in the SaUnitTest application to save
+ * the coredump, to avoid formatting issues.
+ * There is also user space utility saCoreDumpUtil.out provided to collect
+ * the debug information when requested from linux user space.
+ */
+int16_t Sa_coreDump(Sa_Handle handle, uint32_t *dbgInfoBuf, uint16_t bufSize);
+
/*@}*/ /* @name Utility APIs */
void sa_mDmResetCmdLb(Sa_CmdLbUpdateInfo_t* updateInfo,
uint32_t* cmdLb)
{
+
+#ifdef NSS_LITE2
+ cmdLb++;
+#endif
+
if (updateInfo->validBitfield & sa_CMDL_UPDATE_VALID_ENC)
{
/* Clear the encSize and encOffset field to simplify the operation in command label updating Macros */
cmdLb[updateInfo->authOffsetInfo.index] &= 0x00ffffffUL;
}
- if (updateInfo->subMode == sa_DM_CCM)
+ if ( (updateInfo->subMode == sa_DM_CCM) ||
+ (updateInfo->subMode == sa_DM_CCM_GEN) )
{
/* Clear AAD length field */
cmdLb[2] &= 0xffff0000UL;
/**
*
* @ingroup salld_api_macros
- * @brief sa_mDmUpdateCmdLb: Update the command label for Data Mode
+ * @brief salld_form_32bits_util: form 32 bits command label from a byte array
+ *
+ * @details Inline macro API can be used to generate the 32 bits word array from
+ * byte array as b[0]<<24 | b[1]<<16 | b[2] << 8 | b[3].
+ *
+ * @param[in] cmdLb Command Label Buffer
+ * @param[in] index start index of cmdLb
+ * @param[in] offset start offset in the cmdLb 32-bit word
+ * @param[in] bPtr byte array pointer
+ * @param[in] bSize byte array size
+ *
+ */
+static inline
+void salld_form_32bits_util(uint32_t* cmdLb, uint8_t index, uint8_t offset, uint8_t* bPtr, uint8_t bSize)
+{
+ uint32_t temp = 0;
+ int bIndex = 0;
+ int8_t iShift = 8 *( 3 - offset);
+ int w32Size, bytesInlast32bWord;
+
+ /* number of bytes to be formed in last 32-bit word */
+ bytesInlast32bWord = (bSize + offset ) & 3;
+
+ /* number of bytes to be formed into full 32-bit words */
+ w32Size = bSize - offset - bytesInlast32bWord;
+
+ /* Handle the un-aligned first 32 word that needs update specially */
+ if (offset != 0)
+ {
+ while (iShift >= 0) {
+ temp |= bPtr[bIndex ++] << iShift;
+ iShift -= 8;
+ }
+ cmdLb[index ++] |= temp;
+ }
+
+ /* the loop runs for all full 32-bit words */
+ while (bIndex < w32Size)
+ {
+ cmdLb[index ++] = bPtr[bIndex] << 24 | bPtr[bIndex+1] << 16 | \
+ bPtr[bIndex + 2] << 8 | bPtr[bIndex + 3];
+ bIndex += 4;
+ }
+
+ /* Handle any un-handled (remaining) bytes towards the end */
+ if (bytesInlast32bWord)
+ {
+ iShift = 24;
+ temp = 0;
+ while (bytesInlast32bWord) {
+ temp |= bPtr[bIndex ++] << iShift;
+ iShift -= 8;
+ bytesInlast32bWord --;
+ }
+ cmdLb[index] = temp;
+ }
+}
+
+/**
+ *
+ * @ingroup salld_api_macros
+ * @brief sa_mDmUpdateCmdLb_ccm_gen: Update the command label for Data Mode in CCM general case
+ *
+ * @details Inline macro API can be used to update the command label per packet
+ * for Data Mode during Encryption/Decryption request to SA.
+ *
+ * @param[in] encOffset Offset to the encrypted/decrypted data in the
+ * packet in bytes
+ * @param[in] encSize Number of bytes to be encrypted or decrypted
+ * @param[in] pEncIV Initialization vectors if applicable for
+ * encryption mode.
+ * @param[in] aadSize Number of additional data to be authenticated in bytes
+ * @param[in] aad Pointer to the additional authenticated data
+ * @param[in] pCmdlUpdate Command label updating control structure returned from SA LLD
+ * @param[in] cmdLb Command Label Buffer
+ *
+ * @note: It is just a sample implemenation for generic CCM use cases
+ *
+ */
+static inline
+void sa_mDmUpdateCmdLb_ccm_gen(uint8_t encOffset,
+ uint16_t encSize,
+ uint8_t* pEncIV,
+ uint8_t aadSize,
+ uint8_t* aad,
+ Sa_CmdLbUpdateInfo_t* pCmdlUpdate,
+ uint32_t* cmdLb)
+{
+ uint8_t *iv = pEncIV;
+
+#ifdef NSS_LITE2
+ cmdLb++;
+#endif
+
+ /* Handle Option 1, (Option 2 & Option 3) in two different groups */
+ /* Update the command label header (8 byte) */
+ cmdLb[0] |= encSize;
+ cmdLb[1] |= ((uint32_t)encOffset << 24);
+
+ /* Option 1 Update: if AAD size is 0, no updates to Option 1 */
+ if ( (aadSize > 0) &&
+ (aadSize <= 14) )
+ {
+ /* Option 1: B1 (aadlen | AAD ) (16 byte) */
+ /* update AAD */
+ salld_form_32bits_util(&cmdLb[0], pCmdlUpdate->aadInfo.index, \
+ pCmdlUpdate->aadInfo.offset, &aad[0], aadSize);
+ }
+
+ /* Option 2 update IV: B0 (flag | salt | IV | encypted data len) (16 byte) */
+ salld_form_32bits_util(&cmdLb[0], pCmdlUpdate->encIvInfo.index, \
+ pCmdlUpdate->encIvInfo.offset, iv, pCmdlUpdate->encIvInfo.size);
+
+ cmdLb[9] &= 0xFFFF0000UL; /* Clear the lower 16 bits */
+ cmdLb[9] |= encSize; /* Set with encoder size */
+
+ /* Option 3: AES-CTR IV (salt| IV | 0) (16 byte) */
+ /* Insert IV and encrypted data len */
+ /* IV1 & 2*/
+ cmdLb[10] = cmdLb[6] & 0x07FFFFFFUL;
+ cmdLb[11] = cmdLb[7];
+ cmdLb[12] = cmdLb[8];
+ cmdLb[13] = cmdLb[9] & 0xFFFF0000UL;
+}
+
+/**
+ *
+ * @ingroup salld_api_macros
+ * @brief sa_mDmUpdateCmdLb_ccm_wimax: Update the command label for CCM-WiMax
+ *
+ * @details Inline macro API can be used to update the command label per packet
+ * for Data Mode during Encryption/Decryption request to SA.
+ *
+ * @param[in] encOffset Offset to the encrypted/decrypted data in the
+ * packet in bytes
+ * @param[in] encSize Number of bytes to be encrypted or decrypted
+ * @param[in] gmh generic mac header pointer.
+ * @param[in] sn sequence number pointer
+ * @param[in] cmdLb Command Label Buffer
+ *
+ * @note: It is just a sample implemenation for CCM-WiMax (optimal implementation)
+ *
+ */
+static inline
+void sa_mDmUpdateCmdLb_ccm_wimax (
+ uint8_t encOffset,
+ uint16_t encSize,
+ uint8_t* gmh, /* 5 bytes (excluding HCS (header check sequence) */
+ uint8_t* sn, /* 4 bytes of sequence number */
+ uint32_t* cmdLb)
+{
+
+#ifdef NSS_LITE2
+ cmdLb++;
+#endif
+
+ cmdLb[0] |= encSize;
+ cmdLb[1] |= ((uint32_t)encOffset << 24);
+
+ /* AAD (none) */
+
+ /* Option 2: B0 (flag | nonce | encypted data len) (16 byte) */
+ /* Insert IV and encrypted data len */
+ cmdLb[6] |= ((gmh[0] << 16) | \
+ (gmh[1] << 8) | \
+ (gmh[2]) );
+ cmdLb[7] = ((gmh[3] << 24) | (gmh[4] << 16));
+ cmdLb[8] = ((sn[0] << 8) | (sn[1]));
+ cmdLb[9] = ((sn[2] << 24) | (sn[3] << 16) | encSize);
+
+ /* Option 3: AES-CTR IV (flag | nonce | 0) (16 byte) */
+ cmdLb[10] = cmdLb[6] & 0x07FFFFFFUL;
+ cmdLb[11] = cmdLb[7];
+ cmdLb[12] = cmdLb[8];
+ cmdLb[13] = cmdLb[9] & 0xFFFF0000UL;
+}
+
+/**
+ *
+ * @ingroup salld_api_macros
+ * @brief sa_mDmUpdateCmdLb: Update the command label for Data Mode for IPSEC,SRTP
*
* @details Inline macro API can be used to update the command label per packet
* for Data Mode during Encryption/Decryption request to SA.
* @param[in] updateInfo Command label updating control structure returned from SA LLD
* @param[in] cmdLb Command Label Buffer
*
- * @note: It is just a sample implemenation which should be optimized per use case
+ * @note: It is just a sample implemenation for below use cases:
+ * IPSEC
+ * SRTP
*
*/
static inline
Sa_CmdLbUpdateInfo_t* updateInfo,
uint32_t* cmdLb)
{
-
+#ifdef NSS_LITE2
+ cmdLb++;
+#endif
+
switch (updateInfo->subMode)
{
case sa_DM_GEN: /* General Mode operation */
@@ -3465,7 +4787,52 @@ static inline void sa_PSINFO_SET_IV(Sa_psInfo_t *x, uint32_t *iv, int ivSize)
* - Control Path at ARM and Data Path at DSPs
*
*/
-
+
+/**
+ * @page appendix3 SA2_UL Requirements for packet to pass Security Attributes Checkes
+ *
+ * In addition to the first-level check that the context fetch must pass is to satisfy
+ * the external firewall module's check at the soc level configured by DMSC, the second-level check
+ * that SA2_UL does is to compare the incoming packet\92s security attributes
+ * against the attributes that are stored as part of the SCCTL inside the security context.
+ * The following table summarizes the evaluation that will occur before a context is used for the packet
+ * processing. The rightmost column shows the possible change in 'secure' attribute of the packet
+ * if and only if the check passes. If packet check fails, the original packet attribute is untouched.
+ *
+ * @verbatim
+ * |----------------------------------------------------|-------------------------------------------------|----------------|
+ * | Incoming Packet Attributes | Attributes in Security Context | |
+ * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------| Impact |
+ * | Secure | Promote | Demote | NS | Priv | PrivID | Ctx | Ctx | Ctx | Ctx | Priv | PrivID | on out |
+ * | | | | Crypto | | | Secure | Promote | Demote | NS | | | pkt attributes |
+ * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
+ * | 0 | 0 | 0 | 0 | b | c | 0 | 0 | 0 | 0 | b | c | No Change |
+ * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
+ * | 1 | 0 | 0 | 0 | b | c | 1 | 0 | 0 | 0 | b | c | No Change |
+ * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
+ * | 0 | 1 | 0 | 0 | b | c | 1 | 1 | 0 | 0 | b | c | Secure=1(note2)|
+ * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
+ * | 1 | 0 | 1 | 0 | b | c | 1 | 0 | 1 | 0 | b | c | Secure=0(note3)|
+ * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
+ * | 0 | 0 | 0 | 1 | b | c | 1 | 0 | 0 | 1 | b | c |No Change(note4)|
+ * |--------|---------|--------|--------|------|--------|--------|---------|--------|-----|------|--------|----------------|
+ *
+ * @endverbatim
+ * Legend:
+ * The 'b' and 'c' can be any legal value of 2-bit priv and 8-bit privid respectively. The priv attribute on the
+ * input packet must match the priv attribute in the context. Similarly the privid attribute on the input packet
+ * must match the privid attribute in the context, except when the privid in the context is using the wildcard
+ * value (0xC3) which will bypass the privid check.
+ * Note 1: Promotion of non-secure packet to be secure packet also always requires the 48-bit SCPTR that
+ * comes with the packet to be within the range of 'SCPTR Promote Range' registers.
+ * Note 2: Output packet (with secure attribute = 1) is intended to land in a secure memory.
+ * Note 3: Output packet (with secure attribute = 0) is intended to land in a non-secure memory.
+ * Note 4: When the input packet has NS_crypto = 1 and the context has AllowNS = 1, a non-secure packet
+ * is allowed to use a secure context without knowing the key, but the output packet is intended to land in a
+ * non-secure memory (secure attribute on the packet stays at 0).
+ * Any other attributes combinations from the table above will result in security exceptions.
+ *
+ */
#ifdef __cplusplus
}