3.3.9. List of all SSS APIs and structures¶
3.3.9.1. SSS Enums and Types¶
-
group
sss_types
SSS Types.
Defines
-
SSS_ENUM
(GROUP, INDEX) Helper macro to set enum value
Enums
-
enum
sss_access_permission_t
Permissions of an object
Values:
-
kAccessPermission_SSS_Read
= (1u << 0) Can read (applicable) contents of the key.
@note This is not same as @ref kAccessPermission_SSS_Use. Without reading, the object, the key can be used.
-
kAccessPermission_SSS_Write
= (1u << 1) Can change the value of an object
-
kAccessPermission_SSS_Use
= (1u << 2) Can use an object
-
kAccessPermission_SSS_Delete
= (1u << 3) Can delete an object
-
kAccessPermission_SSS_ChangeAttributes
= (1u << 4) Can change permissions applicable to an object
-
kAccessPermission_SSS_All_Permission
= 0x1F Bitwise OR of all sss_access_permission.
-
-
enum
sss_algorithm_t
Cryptographic algorithm to be applied
Values:
-
kAlgorithm_None
-
kAlgorithm_SSS_AES_ECB
= SSS_ENUM_ALGORITHM(AES, )
-
kAlgorithm_SSS_AES_CBC
= SSS_ENUM_ALGORITHM(AES, )
-
kAlgorithm_SSS_AES_CTR
= SSS_ENUM_ALGORITHM(AES, )
-
kAlgorithm_SSS_AES_GCM
= SSS_ENUM_ALGORITHM(AES, )
-
kAlgorithm_SSS_AES_CCM
= SSS_ENUM_ALGORITHM(AES, )
-
kAlgorithm_SSS_AES_GCM_INT_IV
= SSS_ENUM_ALGORITHM(AES, )
-
kAlgorithm_SSS_AES_CTR_INT_IV
= SSS_ENUM_ALGORITHM(AES, )
-
kAlgorithm_SSS_AES_CCM_INT_IV
= SSS_ENUM_ALGORITHM(AES, 0x08)
-
kAlgorithm_SSS_CHACHA_POLY
= SSS_ENUM_ALGORITHM(CHACHA, )
-
kAlgorithm_SSS_DES_ECB
= SSS_ENUM_ALGORITHM(DES, )
-
kAlgorithm_SSS_DES_CBC
= SSS_ENUM_ALGORITHM(DES, )
-
kAlgorithm_SSS_DES_CBC_ISO9797_M1
= SSS_ENUM_ALGORITHM(DES, )
-
kAlgorithm_SSS_DES_CBC_ISO9797_M2
= SSS_ENUM_ALGORITHM(DES, )
-
kAlgorithm_SSS_DES3_ECB
= SSS_ENUM_ALGORITHM(DES, )
-
kAlgorithm_SSS_DES3_CBC
= SSS_ENUM_ALGORITHM(DES, )
-
kAlgorithm_SSS_DES3_CBC_ISO9797_M1
= SSS_ENUM_ALGORITHM(DES, )
-
kAlgorithm_SSS_DES3_CBC_ISO9797_M2
= SSS_ENUM_ALGORITHM(DES, 0x08)
-
kAlgorithm_SSS_SHA1
= SSS_ENUM_ALGORITHM(SHA, )
-
kAlgorithm_SSS_SHA224
= SSS_ENUM_ALGORITHM(SHA, )
-
kAlgorithm_SSS_SHA256
= SSS_ENUM_ALGORITHM(SHA, )
-
kAlgorithm_SSS_SHA384
= SSS_ENUM_ALGORITHM(SHA, )
-
kAlgorithm_SSS_SHA512
= SSS_ENUM_ALGORITHM(SHA, )
-
kAlgorithm_SSS_CMAC_AES
= SSS_ENUM_ALGORITHM(MAC, )
-
kAlgorithm_SSS_HMAC_SHA1
= SSS_ENUM_ALGORITHM(MAC, )
-
kAlgorithm_SSS_HMAC_SHA224
= SSS_ENUM_ALGORITHM(MAC, )
-
kAlgorithm_SSS_HMAC_SHA256
= SSS_ENUM_ALGORITHM(MAC, )
-
kAlgorithm_SSS_HMAC_SHA384
= SSS_ENUM_ALGORITHM(MAC, )
-
kAlgorithm_SSS_HMAC_SHA512
= SSS_ENUM_ALGORITHM(MAC, )
-
kAlgorithm_SSS_DES_CMAC8
= SSS_ENUM_ALGORITHM(MAC, )
-
kAlgorithm_SSS_DH
= SSS_ENUM_ALGORITHM(DH, )
-
kAlgorithm_SSS_ECDH
= SSS_ENUM_ALGORITHM(DH, )
-
kAlgorithm_SSS_DSA_SHA1
= SSS_ENUM_ALGORITHM(DSA, )
-
kAlgorithm_SSS_DSA_SHA224
= SSS_ENUM_ALGORITHM(DSA, )
-
kAlgorithm_SSS_DSA_SHA256
= SSS_ENUM_ALGORITHM(DSA, )
-
kAlgorithm_SSS_RSASSA_PKCS1_V1_5_NO_HASH
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, )
-
kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA1
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, )
-
kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA224
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, )
-
kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA256
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, )
-
kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA384
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, )
-
kAlgorithm_SSS_RSASSA_PKCS1_V1_5_SHA512
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_V1_5, )
-
kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA1
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, )
-
kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA224
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, )
-
kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA256
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, )
-
kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA384
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, )
-
kAlgorithm_SSS_RSASSA_PKCS1_PSS_MGF1_SHA512
= SSS_ENUM_ALGORITHM(RSASSA_PKCS1_PSS_MGF1, )
-
kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA1
= SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, )
-
kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA224
= SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, )
-
kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA256
= SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, )
-
kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA384
= SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, )
-
kAlgorithm_SSS_RSAES_PKCS1_OAEP_SHA512
= SSS_ENUM_ALGORITHM(RSAES_PKCS1_OAEP, )
-
kAlgorithm_SSS_RSAES_PKCS1_V1_5
= SSS_ENUM_ALGORITHM(RSAES_PKCS1_V1_5, )
-
kAlgorithm_SSS_RSASSA_NO_PADDING
= SSS_ENUM_ALGORITHM(RSASSA_NO_PADDING, )
-
kAlgorithm_SSS_ECDSA_SHA1
= SSS_ENUM_ALGORITHM(ECDSA, )
-
kAlgorithm_SSS_ECDSA_SHA224
= SSS_ENUM_ALGORITHM(ECDSA, )
-
kAlgorithm_SSS_ECDSA_SHA256
= SSS_ENUM_ALGORITHM(ECDSA, )
-
kAlgorithm_SSS_ECDSA_SHA384
= SSS_ENUM_ALGORITHM(ECDSA, )
-
kAlgorithm_SSS_ECDSA_SHA512
= SSS_ENUM_ALGORITHM(ECDSA, )
-
kAlgorithm_SSS_ECDAA
= SSS_ENUM_ALGORITHM(ECDAA, )
-
-
enum
sss_cipher_type_t
For all cipher types, key bit length is provides at the time key is inserted/generated
Values:
-
kSSS_CipherType_NONE
-
kSSS_CipherType_AES
= 10
-
kSSS_CipherType_DES
= 12
-
kSSS_CipherType_CMAC
= 20
-
kSSS_CipherType_HMAC
= 21
-
kSSS_CipherType_MAC
= 30
-
kSSS_CipherType_RSA
= 31
-
kSSS_CipherType_RSA_CRT
= 32 RSA RAW format
-
kSSS_CipherType_EC_NIST_P
= 40 RSA CRT format
-
kSSS_CipherType_EC_NIST_K
= 41 Keys Part of NIST-P Family
-
kSSS_CipherType_EC_MONTGOMERY
= 50 Keys Part of NIST-K Family Montgomery Key,
-
kSSS_CipherType_EC_TWISTED_ED
= 51 twisted Edwards form elliptic curve public key
-
kSSS_CipherType_EC_BRAINPOOL
= 52 Brainpool form elliptic curve public key
-
kSSS_CipherType_EC_BARRETO_NAEHRIG
= 53 Barreto Naehrig curve
-
kSSS_CipherType_UserID
= 70
-
kSSS_CipherType_Certificate
= 71 Use kSSS_CipherType_Binary to store Certificate
-
kSSS_CipherType_Binary
= 72
-
kSSS_CipherType_Count
= 73
-
kSSS_CipherType_PCR
= 74
-
kSSS_CipherType_ReservedPin
= 75
-
-
enum
sss_connection_type_t
Destintion connection type
Values:
-
kSSS_ConnectionType_Plain
-
kSSS_ConnectionType_Password
-
kSSS_ConnectionType_Encrypted
-
-
enum
sss_key_object_mode_t
Persistent / Non persistent mode of a key
Values:
-
kKeyObject_Mode_None
= 0 kKeyObject_Mode_None
-
kKeyObject_Mode_Persistent
= 1 Key object will be persisted in memory and will retain it’s value after a closed session
-
kKeyObject_Mode_Transient
= 2 Key Object will be stored in RAM. It will lose it’s contents after a session is closed
-
-
enum
sss_key_part_t
Part of a key
Values:
-
kSSS_KeyPart_NONE
-
kSSS_KeyPart_Default
= 1 Applicable where we have UserID, Binary Files, Certificates, Symmetric Keys, PCR, HMAC-key, counter
-
kSSS_KeyPart_Public
= 2 Public part of asymmetric key
-
kSSS_KeyPart_Private
= 3 Private only part of asymmetric key
-
kSSS_KeyPart_Pair
= 4 Both, public and private part of asymmetric key
-
-
enum
sss_mode_t
High level algorihtmic operations.
Augmented by sss_algorithm_t
Values:
-
kMode_SSS_Encrypt
= 1 Encrypt.
-
kMode_SSS_Decrypt
= 2 Decrypt.
-
kMode_SSS_Sign
= 3 Sign.
-
kMode_SSS_Verify
= 4 Verify.
-
kMode_SSS_ComputeSharedSecret
= 5
-
kMode_SSS_Digest
= 6 Message Digest.
-
kMode_SSS_Mac
= 7 Message Authentication Code.
-
kMode_SSS_HKDF_ExpandOnly
= 9 HKDF Expand Only (RFC 5869)
-
kMode_SSS_HKDF_ExtractExpand
= 10 HKDF Extract and Expand (RFC 5869)
-
kMode_SSS_Mac_Validate
= 11 MAC Validate.
-
-
enum
sss_status_t
Status of the SSS APIs
Values:
-
kStatus_SSS_Success
= 0x5a5a5a5au Operation was successful
-
kStatus_SSS_Fail
= 0x3c3c0000u Operation failed
-
kStatus_SSS_InvalidArgument
= 0x3c3c0001u Operation not performed because some of the passed parameters were found inappropriate
-
kStatus_SSS_ResourceBusy
= 0x3c3c0002u Where the underlying sub-system supports multi-threading, Internal status to handle simultaneous access.
This status is not expected to be returned to higher layers.
-
-
enum
sss_type_t
Cryptographic sub system
Values:
-
kType_SSS_SubSystem_NONE
-
kType_SSS_Software
= ((0x01 << 8) | (0x00)) Software based
-
kType_SSS_mbedTLS
= ((kType_SSS_Software) | (0x01))
-
kType_SSS_OpenSSL
= ((kType_SSS_Software) | (0x02))
-
kType_SSS_HW
= ((0x02 << 8) | (0x00)) HOST HW Based
-
kType_SSS_SECO
= ((kType_SSS_HW) | (0x01))
-
kType_SSS_Isolated_HW
= ((0x04 << 8) | (0x00)) Isolated HW
-
kType_SSS_Sentinel
= ((kType_SSS_Isolated_HW) | (0x01))
-
kType_SSS_Sentinel200
= ((kType_SSS_Isolated_HW) | (0x02))
-
kType_SSS_Sentinel300
= ((kType_SSS_Isolated_HW) | (0x03))
-
kType_SSS_Sentinel400
= ((kType_SSS_Isolated_HW) | (0x04))
-
kType_SSS_Sentinel500
= ((kType_SSS_Isolated_HW) | (0x05))
-
kType_SSS_SecureElement
= (( 0x08 << 8 ) | ( 0x00 )) Secure Element
-
kType_SSS_SE_A71CH
= ((kType_SSS_SecureElement) | (0x01)) To connect to https://www.nxp.com/products/:A71CH
-
kType_SSS_SE_A71CL
= ((kType_SSS_SecureElement) | (0x02))
-
kType_SSS_SE_SE05x
= ((kType_SSS_SecureElement) | (0x03)) To connect to https://www.nxp.com/products/:SE050
-
kType_SSS_SubSystem_LAST
-
-
struct
sss_ecc_point_t
- #include <fsl_sss_api.h>
XY Co-ordinates for ECC Curves
Public Members
-
uint8_t *
X
X Point
-
uint8_t *
Y
Y Point
-
uint8_t *
-
struct
sss_eccgfp_group_t
- #include <fsl_sss_api.h>
ECC Curve Parameter
Public Members
-
uint8_t *
a
ECC parameter a
-
uint8_t *
b
ECC parameter b
-
sss_ecc_point_t *
G
ECC parameter G
-
uint8_t *
h
ECC parameter h
-
uint8_t *
n
ECC parameter n
-
uint8_t *
p
ECC parameter P
-
uint8_t *
-
3.3.9.2. SSS Session types and APIs¶
-
group
sss_session
Manage session.
Enums
-
enum
sss_session_prop_au8_t
Properties of session that are S32
From 0 to kSSS_SessionProp_Optional_Prop_Start, around 2^24 = 16777215 Properties are possible.
From 0 to kSSS_SessionProp_Optional_Prop_Start, around 2^24 = 16777215 Properties are possible.
Values:
-
kSSS_SessionProp_au8_NA
= 0 Invalid
-
kSSS_SessionProp_szName
Name of the product, string
-
kSSS_SessionProp_UID
Unique Identifier
-
kSSS_SessionProp_au8_Optional_Start
= 0x00FFFFFFu Optional Properties Start
-
kSSS_SessionProp_au8_Proprietary_Start
= 0x01FFFFFFu Proprietary Properties Start
-
-
enum
sss_session_prop_u32_t
Properties of session that are U32
From 0 to kSSS_SessionProp_Optional_Prop_Start, around 2^24 = 16777215 Properties are possible.
From 0 to kSSS_SessionProp_Optional_Prop_Start, around 2^24 = 16777215 Properties are possible.
Values:
-
kSSS_SessionProp_u32_NA
= 0 Invalid
-
kSSS_SessionProp_VerMaj
Major version
-
kSSS_SessionProp_VerMin
Minor Version
-
kSSS_SessionProp_VerDev
Development Version
-
kSSS_SessionProp_UIDLen
-
kSSS_SessionProp_u32_Optional_Start
= 0x00FFFFFFu Optional Properties Start
-
kSSS_KeyStoreProp_FreeMem_Persistant
How much persistent memory is free
-
kSSS_KeyStoreProp_FreeMem_Transient
How much transient memory is free
-
kSSS_SessionProp_u32_Proprietary_Start
= 0x01FFFFFFu Proprietary Properties Start
-
Functions
-
void
sss_session_close
(sss_session_t *session) Close session between application and security subsystem.
This function closes a session which has been opened with a security subsystem. All commands within the session must have completed before this function can be called. The implementation must do nothing if the input
session
parameter is NULL.- Parameters
session
: Session context.
-
sss_status_t
sss_session_create
(sss_session_t *session, sss_type_t subsystem, uint32_t application_id, sss_connection_type_t connection_type, void *connectionData) Same as sss_session_open but to support sub systems that explictily need a create before opening.
For the sake of portabilty across various sub systems, the applicaiton has to call sss_session_create before calling sss_session_open.
- Parameters
[inout] session
: Pointer to session context[in] subsystem
: See sss_session_open[in] application_id
: See sss_session_open[in] connection_type
: See sss_session_open[in] connectionData
: See sss_session_open
-
void
sss_session_delete
(sss_session_t *session) Counterpart to sss_session_create
Similar to contraint on sss_session_create, application may call sss_session_delete to explicitly release all underlying/used session specific resoures of that implementation.
-
sss_status_t
sss_session_open
(sss_session_t *session, sss_type_t subsystem, uint32_t application_id, sss_connection_type_t connection_type, void *connectionData) Open session between application and a security subsystem.
Open virtual session between application (user context) and a security subsystem and function thereof. Pointer to session shall be supplied to all SSS APIs as argument. Low level SSS functions can provide implementation specific behaviour based on the session argument. Note: sss_session_open() must not be called concurrently from multiple threads. The application must ensure this.
- Return
status
- Parameters
[inout] session
: Session context.[in] subsystem
: Indicates which security subsystem is selected to be used.[in] application_id
: ObjectId/AuthenticationID Connecting to:application_id
== 0 => Super use / Plaform userAnything else => Authenticated user
[in] connection_type
: How are we connecting to the system.[inout] connectionData
: subsystem specific connection parameters.
-
sss_status_t
sss_session_prop_get_au8
(sss_session_t *session, uint32_t property, uint8_t *pValue, size_t *pValueLen) Get an underlying property of the crypto sub system.
This API is used to get values that are numeric in nature.
Property can be either fixed value that is calculated at compile time and returned directly, or it may involve some access to the underlying system.
- Return
- Parameters
[in] session
: Session context[in] property
: Value that is part of sss_session_prop_au8_t[out] pValue
: Output buffer array[inout] pValueLen
: Count of values thare are/must br read
-
sss_status_t
sss_session_prop_get_u32
(sss_session_t *session, uint32_t property, uint32_t *pValue) Get an underlying property of the crypto sub system.
This API is used to get values that are numeric in nature.
Property can be either fixed value that is calculated at compile time and returned directly, or it may involve some access to the underlying system.
For applicable properties see sss_session_prop_u32_t
- Return
- Parameters
[in] session
: Session context[in] property
: Value that is part of sss_session_prop_u32_t[out] pValue
:
-
struct
sss_session_t
- #include <fsl_sss_api.h>
Root session.
This is a singleton for each connection (physical/logical) to individual cryptographic system.
Public Members
-
uint8_t
data
[(0 + (1 * sizeof(void *)) + (1 * sizeof(void *)) + (8 * sizeof(void *)) + 32)]
-
struct sss_session_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_type_t
subsystem
Indicates which security subsystem is selected.
This is set when sss_session_open is successful
-
uint8_t
-
enum
3.3.9.3. SSS Keystore types and APIs¶
-
group
sss_key_store
Secure storage for keys and certificates.
Enums
-
enum
sss_key_store_prop_au8_t
properties of a Key Store that return array
Values:
-
kSSS_KeyStoreProp_au8_Optional_Start
= 0x00FFFFFFu Optional Properties Start
-
-
enum
sss_tunnel_dest_t
Entity on the other side of the tunnel
Values:
-
kSSS_TunnelDest_None
= 0 Default value
-
kSSS_TunnelType_Se05x_Iot_applet
SE05X IoT Applet
-
Functions
-
sss_status_t
sss_key_store_allocate
(sss_key_store_t *keyStore, uint32_t keyStoreId) Get handle to key store. If the key store already exists, nothing is allocated. If the key store does not exists, new empty key store is created and initialized. Key store context structure is updated with actual information.
- Parameters
[out] keyStore
: Pointer to key store context. Key store context is updated on function return.keyStoreId
: Implementation specific ID, can be used in case security subsystem manages multiple different key stores.
-
void
sss_key_store_context_free
(sss_key_store_t *keyStore) Destructor for the key store context.
-
sss_status_t
sss_key_store_context_init
(sss_key_store_t *keyStore, sss_session_t *session) Constructor for the key store context data structure.
- Parameters
[out] keyStore
: Pointer to key store context. Key store context is updated on function return.session
: Session context.
-
sss_status_t
sss_key_store_erase_key
(sss_key_store_t *keyStore, sss_object_t *keyObject) Delete / destroy allocated keyObect .
- Return
The sss status.
- Parameters
keyStore
: The key storekeyObject
: The key object to be deleted
-
sss_status_t
sss_key_store_freeze_key
(sss_key_store_t *keyStore, sss_object_t *keyObject) The referenced key cannot be updated any more.
- Return
The sss status.
- Parameters
keyStore
: The key storekeyObject
: The key object to be locked / frozen.
-
sss_status_t
sss_key_store_generate_key
(sss_key_store_t *keyStore, sss_object_t *keyObject, size_t keyBitLen, void *options) This function generates key[] in the destination key store.
-
sss_status_t
sss_key_store_get_key
(sss_key_store_t *keyStore, sss_object_t *keyObject, uint8_t *data, size_t *dataLen, size_t *pKeyBitLen) This function exports plain key[] from key store (if constraints and user id allows reading)
-
sss_status_t
sss_key_store_load
(sss_key_store_t *keyStore) Load from persistent memory to cached objects.
-
sss_status_t
sss_key_store_open_key
(sss_key_store_t *keyStore, sss_object_t *keyObject) Access key store using one more level of encryption.
e.g. Access keys / encryption key during storage
- Return
The sss status.
- Parameters
keyStore
: The key storekeyObject
: The key object that is to be used as a KEK (Key Encryption Key)
-
sss_status_t
sss_key_store_save
(sss_key_store_t *keyStore) Save all cached persistent objects to persistent memory.
-
sss_status_t
sss_key_store_set_key
(sss_key_store_t *keyStore, sss_object_t *keyObject, const uint8_t *data, size_t dataLen, size_t keyBitLen, void *options, size_t optionsLen) This function moves data[] from memory to the destination key store.
- Return
- Parameters
keyStore
: Key store contextkeyObject
: Reference to a key and it’s propertiesdata
: Data to be stored in Key. When setting ecc private key only, do not include key header.dataLen
: Length of the datakeyBitLen
: Crypto algorithm key bit lengthoptions
: Pointer to implementation specific optionsoptionsLen
: Length of the options in bytes
-
struct
sss_key_store_t
- #include <fsl_sss_api.h>
Store for secure and non secure key objects within a cryptographic system.
A cryptographic system may have more than partitions to store such keys.
Public Members
-
uint8_t
data
[(0 + (1 * sizeof(void *)) + (4 * sizeof(void *)) + 32)]
-
struct sss_key_store_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_session_t *
session
Virtual connection between application (user context) and specific security subsystem and function thereof.
-
enum
3.3.9.4. SSS KeyObject types and APIs¶
-
group
sss_key_object
Low level iota of key/certificates in
SSS
domain.Functions
-
sss_status_t
sss_key_object_allocate_handle
(sss_object_t *keyObject, uint32_t keyId, sss_key_part_t keyPart, sss_cipher_type_t cipherType, size_t keyByteLenMax, uint32_t options) Allocate / pre-provision memory for new key.
This API allows underlying cryptographic subsystems to perform preconditions of before creating any cryptographic key object.
- Return
Status of object allocation.
- Parameters
[inout] keyObject
: The object If required, update implementation defined values inside the keyObjectkeyId
: External Key ID. Later on this may be used by sss_key_object_get_handlekeyPart
: See sss_key_part_tcipherType
: See sss_cipher_type_tkeyByteLenMax
: Maximum storage this type of key may need. For systems that have their own internal allocation table this would helpoptions
: 0 = Persistant Key (Default) or Transient Key. See sss_key_object_mode_t
-
void
sss_key_object_free
(sss_object_t *keyObject) Destructor for the key object. The function frees key object context.
- Parameters
keyObject
: Pointer to key object context.
-
sss_status_t
sss_key_object_get_access
(sss_object_t *keyObject, uint32_t *access) Check what are access restrictions on an object
- Return
- Parameters
keyObject
: Objectaccess
: What is permitted
-
sss_status_t
sss_key_object_get_handle
(sss_object_t *keyObject, uint32_t keyId) Get handle to an existing allocated/provisioned/created Object.
See @ref sss_key_object_allocate_handle. After calling this API, Ideally keyObject should become equivlant to as set after the calling of @ref sss_key_object_allocate_handle api.
- Return
The sss status.
- Parameters
keyObject
: The key object[in] keyId
: The key identifier
-
sss_status_t
sss_key_object_get_purpose
(sss_object_t *keyObject, sss_mode_t *purpose) Check what is purpose restrictions on an object
- Return
- Parameters
keyObject
: Object to be checkedpurpose
: Know what is permitted.
-
sss_status_t
sss_key_object_get_user
(sss_object_t *keyObject, uint32_t *user) get attributes
-
sss_status_t
sss_key_object_init
(sss_object_t *keyObject, sss_key_store_t *keyStore) Constructor for a key object data structure The function initializes keyObject data structure and associates it with a key store in which the plain key and other attributes are stored.
- Return
Status of the operation
- Parameters
keyObject
:keyStore
:
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_key_object_set_access
(sss_object_t *keyObject, uint32_t access, uint32_t options) Assign access permissions to a key object.
- Parameters
keyObject
: the object where permission restrictions are appliedaccess
: Logical OR of read, write, delete, use, change attributes defined by enum _sss_access_permission.options
: Transient or persistent update. Allows for transient update of persistent attributes.
-
sss_status_t
sss_key_object_set_eccgfp_group
(sss_object_t *keyObject, sss_eccgfp_group_t *group) Set elliptic curve domain parameters over Fp for a key object.
When the key object is a reference to one of ECC Private, ECC Public or ECC Pair key types, this function shall be used to specify the exact domain parameters prior to using the key object for ECDSA or ECDH algorithms.
- Parameters
keyObject
: The destination key objectgroup
: Pointer to elliptic curve domain parameters over Fp (sextuple p,a,b,G,n,h)
-
sss_status_t
sss_key_object_set_purpose
(sss_object_t *keyObject, sss_mode_t purpose, uint32_t options) Assign purpose to a key object.
- Parameters
keyObject
: the object where permission restrictions are appliedpurpose
: Usage of the key.options
: Transient or persistent update. Allows for transient update of persistent attributes.
-
sss_status_t
sss_key_object_set_user
(sss_object_t *keyObject, uint32_t user, uint32_t options) Assign user to a key object.
- Parameters
keyObject
: the object where permission restrictions are applieduser
: Assign User id for a key object. The user is kept in the key store along with the key data and other properties.options
: Transient or persistent update. Allows for transient update of persistent attributes.
-
struct
sss_object_t
- #include <fsl_sss_api.h>
An object (secure / non-secure) within a Key Store.
Public Members
-
uint32_t
cipherType
cipherType type from sss_cipher_type_t
-
uint8_t
data
[(0 + (1 * sizeof(void *)) + (2 * sizeof(int)) + (4 * sizeof(void *)) + 32)]
-
struct sss_object_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
uint32_t
keyId
Application specific key identifier. The keyId is kept in the key store along with the key data and other properties.
-
sss_key_store_t *
keyStore
key store holding the data and other properties
-
uint32_t
objectType
The type/part of object is referneced from sss_key_part_t
-
uint32_t
-
sss_status_t
3.3.9.5. SSS Symmetric types and APIs¶
-
group
sss_crypto_symmetric
Symmetric cryptographic operations like
AES
/DES/etc
.Functions
-
sss_status_t
sss_cipher_crypt_ctr
(sss_symmetric_t *context, const uint8_t *srcData, uint8_t *destData, size_t size, uint8_t *initialCounter, uint8_t *lastEncryptedCounter, size_t *szLeft) Symmetric AES in Counter mode in one blocking function call. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to symmetric crypto context.srcData
: Buffer containing the input data.destData
: Buffer containing the output data.size
: Size of source and destination data buffers in bytes.[inout] initialCounter
: Input counter (Always 16 bytes) (updates on return). When using internal IV algorithms (only encrypt) for SE051, initialCounter buffer will be filled with genereted Initial counter.[out] lastEncryptedCounter
: Output cipher of last counter, for chained CTR calls. NULL can be passed if chained calls are not used.[out] szLeft
: Output number of bytes in left unused in lastEncryptedCounter block. NULL can be passed if chained calls are not used.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_cipher_finish
(sss_symmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen) Symmetric cipher finalize.
- Return
Status of the operation
- Parameters
context
: Pointer to symmetric crypto context.srcData
: Buffer containing final chunk of input data.srcLen
: Length of final chunk of input data in bytes.destData
: Buffer containing output data.[inout] destLen
: Length of output data in bytes. Buffer length on entry, reflects actual output size on return.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_cipher_init
(sss_symmetric_t *context, uint8_t *iv, size_t ivLen) Symmetric cipher init. The function starts the symmetric cipher operation.
- Return
Status of the operation
- Parameters
context
: Pointer to symmetric crypto context.iv
: Buffer containing the symmetric operation Initialization Vector. When using internal IV algorithms (only encrypt) for SE051, iv buffer will be filled with genereted Initialization Vector.ivLen
: Length of the Initialization Vector in bytes.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_cipher_one_go
(sss_symmetric_t *context, uint8_t *iv, size_t ivLen, const uint8_t *srcData, uint8_t *destData, size_t dataLen) Symmetric cipher in one blocking function call. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to symmetric crypto context.iv
: Buffer containing the symmetric operation Initialization Vector. When using internal IV algorithms (only encrypt) for SE051, iv buffer will be filled with genereted Initialization Vector.ivLen
: Length of the Initialization Vector in bytes.srcData
: Buffer containing the input data (block aligned).destData
: Buffer containing the output data.dataLen
: Size of input and output data buffer in bytes.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_cipher_one_go_v2
(sss_symmetric_t *context, uint8_t *iv, size_t ivLen, const uint8_t *srcData, const size_t srcLen, uint8_t *destData, size_t *dataLen) Symmetric cipher in one blocking function call. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to symmetric crypto context.iv
: Buffer containing the symmetric operation Initialization Vector. When using internal IV algorithms (only encrypt) for SE051, iv buffer will be filled with genereted Initialization Vector.ivLen
: Length of the Initialization Vector in bytes.srcData
: Buffer containing the input data (block aligned).srcLen
: Length of buffer srcData.destData
: Buffer containing the output data.pDataLen
: Pointer to Size of buffer destData in bytes.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_cipher_update
(sss_symmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen) Symmetric cipher update. Input data does not have to be a multiple of block size. Subsequent calls to this function are possible. Unless one or more calls of this function have supplied sufficient input data, no output is generated. The cipher operation is finalized with a call to sss_cipher_finish().
- Return
Status of the operation
- Parameters
context
: Pointer to symmetric crypto context.srcData
: Buffer containing the input data.srcLen
: Length of the input data in bytes.destData
: Buffer containing the output data.[inout] destLen
: Length of the output data in bytes. Buffer length on entry, reflects actual output size on return.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
void
sss_symmetric_context_free
(sss_symmetric_t *context) Symmetric context release. The function frees symmetric context.
- Parameters
context
: Pointer to symmetric crypto context.
-
sss_status_t
sss_symmetric_context_init
(sss_symmetric_t *context, sss_session_t *session, sss_object_t *keyObject, sss_algorithm_t algorithm, sss_mode_t mode) Symmetric context init. The function initializes symmetric context with initial values.
- Return
Status of the operation
- Parameters
context
: Pointer to symmetric crypto context.session
: Associate SSS session with symmetric context.keyObject
: Associate SSS key object with symmetric context.algorithm
: One of the symmetric algorithms defined by sss_algorithm_t.mode
: One of the modes defined by sss_mode_t.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
struct
sss_symmetric_t
- #include <fsl_sss_api.h>
Typedef for the symmetric crypto context.
Public Members
-
sss_algorithm_t
algorithm
Algorithm to be applied, e.g AES_ECB / CBC
-
uint8_t
data
[(0 + (2 * sizeof(void *)) + (2 * sizeof(int)) + (2 * sizeof(void *)) + 16 + 4 + 32)]
-
struct sss_symmetric_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_object_t *
keyObject
Key to be used for the symmetric operation
-
sss_mode_t
mode
Mode of operation, e.g Encryption/Decryption
-
sss_session_t *
session
Virtual connection between application (user context) and specific security subsystem and function thereof.
-
sss_algorithm_t
-
sss_status_t
3.3.9.6. SSS Asymmetric types and APIs¶
-
group
sss_crypto_asymmetric
Asymmetric cryptographic operations like
RSA
/ECC/etc
.Functions
-
void
sss_asymmetric_context_free
(sss_asymmetric_t *context) Asymmetric context release. The function frees asymmetric context.
- Parameters
context
: Pointer to asymmetric context.
-
sss_status_t
sss_asymmetric_context_init
(sss_asymmetric_t *context, sss_session_t *session, sss_object_t *keyObject, sss_algorithm_t algorithm, sss_mode_t mode) Asymmetric context init. The function initializes asymmetric context with initial values.
- Return
Status of the operation
- Parameters
context
: Pointer to asymmetric crypto context.session
: Associate SSS session with asymmetric context.keyObject
: Associate SSS key object with asymmetric context.algorithm
: One of the asymmetric algorithms defined by sss_algorithm_t.mode
: One of the modes defined by sss_mode_t.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_asymmetric_decrypt
(sss_asymmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen) Asymmetric decryption The function uses asymmetric algorithm to decrypt data. Private key portion of a key pair is used for decryption.
- Return
Status of the operation
- Parameters
context
: Pointer to asymmetric context.srcData
: Input buffersrcLen
: Length of the input in bytesdestData
: Output bufferdestLen
: Length of the output in bytes
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_asymmetric_encrypt
(sss_asymmetric_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen) Asymmetric encryption The function uses asymmetric algorithm to encrypt data. Public key portion of a key pair is used for encryption.
- Return
Status of the operation
- Parameters
context
: Pointer to asymmetric context.srcData
: Input buffersrcLen
: Length of the input in bytesdestData
: Output bufferdestLen
: Length of the output in bytes
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_asymmetric_sign_digest
(sss_asymmetric_t *context, uint8_t *digest, size_t digestLen, uint8_t *signature, size_t *signatureLen) Asymmetric signature of a message digest The function signs a message digest.
- Return
Status of the operation
- Parameters
context
: Pointer to asymmetric context.digest
: Input buffer containing the input message digestdigestLen
: Length of the digest in bytessignature
: Output buffer written with the signature of the digestsignatureLen
: Length of the signature in bytes
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_asymmetric_verify_digest
(sss_asymmetric_t *context, uint8_t *digest, size_t digestLen, uint8_t *signature, size_t signatureLen) Asymmetric verify of a message digest The function verifies a message digest.
- Return
Status of the operation
- Parameters
context
: Pointer to asymmetric context.digest
: Input buffer containing the input message digestdigestLen
: Length of the digest in bytessignature
: Input buffer containing the signature to verifysignatureLen
: Length of the signature in bytes
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
void
3.3.9.7. SSS RNG types and APIs¶
-
group
sss_rng
Functions
-
sss_status_t
sss_rng_context_free
(sss_rng_context_t *context) free random genertor context.
- Return
status
- Parameters
context
: generator context.
-
sss_status_t
sss_rng_context_init
(sss_rng_context_t *context, sss_session_t *session) Initialise random generator context between application and a security subsystem.
- Warning
API Changed
Earlier: sss_status_t sss_rng_context_init( sss_session_t *session, sss_rng_context_t *context); Now: Parameters are swapped sss_status_t sss_rng_context_init( sss_rng_context_t *context, sss_session_t *session);
- Return
status
- Parameters
session
: Session context.context
: random generator context.
-
sss_status_t
sss_rng_get_random
(sss_rng_context_t *context, uint8_t *random_data, size_t dataLen) Generate random number.
- Return
status
- Parameters
context
: random generator context.random_data
: buffer to hold random data.dataLen
: required random number length
-
struct
sss_rng_context_t
- #include <fsl_sss_api.h>
Random number generator context
Public Members
-
struct sss_rng_context_t::[anonymous]
context
Reserved memory for implementation specific extension
-
uint8_t
data
[(0 + (1 * sizeof(void *)) + (2 * sizeof(void *)) + 32)]
-
sss_session_t *
session
Pointer to the session
-
struct sss_rng_context_t::[anonymous]
-
sss_status_t
3.3.9.8. SSS Digest types and APIs¶
-
group
sss_crypto_digest
Functions
-
void
sss_digest_context_free
(sss_digest_t *context) Digest context release. The function frees digest context.
- Parameters
context
: Pointer to digest context.
-
sss_status_t
sss_digest_context_init
(sss_digest_t *context, sss_session_t *session, sss_algorithm_t algorithm, sss_mode_t mode) Digest context init. The function initializes digest context with initial values.
- Return
Status of the operation
- Parameters
context
: Pointer to digest context.session
: Associate SSS session with digest context.algorithm
: One of the digest algorithms defined by sss_algorithm_t.mode
: One of the modes defined by sss_mode_t.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_digest_finish
(sss_digest_t *context, uint8_t *digest, size_t *digestLen) Finish digest for a message. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to digest context.digest
: Output message digestdigestLen
: Message digest byte length
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_digest_init
(sss_digest_t *context) Init digest for a message. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to digest context.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_digest_one_go
(sss_digest_t *context, const uint8_t *message, size_t messageLen, uint8_t *digest, size_t *digestLen) Message digest in one blocking function call. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to digest context.message
: Input messagemessageLen
: Length of the input message in bytesdigest
: Output message digestdigestLen
: Message digest byte length
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_digest_update
(sss_digest_t *context, const uint8_t *message, size_t messageLen) Update digest for a message.
The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to digest context.message
: Buffer with a message chunk.messageLen
: Length of the input buffer in bytes.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
struct
sss_digest_t
- #include <fsl_sss_api.h>
Message Digest operations
Public Members
-
sss_algorithm_t
algorithm
Algorithm to be applied, e.g SHA1, SHA256
-
uint8_t
data
[(0 + (1 * sizeof(void *)) + (3 * sizeof(int)) + (2 * sizeof(void *)) + 32)]
-
size_t
digestFullLen
Full digest length per algorithm definition. This field is initialized along with algorithm.
-
struct sss_digest_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_mode_t
mode
Mode of operation, e.g Sign/Verify
-
sss_session_t *
session
Virtual connection between application (user context) and specific security subsystem and function thereof.
-
sss_algorithm_t
-
void
3.3.9.9. SSS MAC types and APIs¶
-
group
sss_crypto_mac
Functions
-
void
sss_mac_context_free
(sss_mac_t *context) MAC context release. The function frees mac context.
- Parameters
context
: Pointer to mac context.
-
sss_status_t
sss_mac_context_init
(sss_mac_t *context, sss_session_t *session, sss_object_t *keyObject, sss_algorithm_t algorithm, sss_mode_t mode) MAC context init. The function initializes mac context with initial values.
- Return
Status of the operation
- Parameters
context
: Pointer to mac context.session
: Associate SSS session with mac context.keyObject
: Associate SSS key object with mac context.algorithm
: One of the mac algorithms defined by sss_algorithm_t.mode
: One of the modes defined by sss_mode_t.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_mac_finish
(sss_mac_t *context, uint8_t *mac, size_t *macLen) Finish mac for a message. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to mac context.mac
: Output message MACmacLen
: Computed MAC byte length
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_mac_init
(sss_mac_t *context) Init mac for a message. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to mac context.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_mac_one_go
(sss_mac_t *context, const uint8_t *message, size_t messageLen, uint8_t *mac, size_t *macLen) Message MAC in one blocking function call. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to mac context.message
: Input messagemessageLen
: Length of the input message in bytesmac
: Output message MACmacLen
: Computed MAC byte length
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_mac_update
(sss_mac_t *context, const uint8_t *message, size_t messageLen) Update mac for a message.
The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to mac context.message
: Buffer with a message chunk.messageLen
: Length of the input buffer in bytes.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
struct
sss_mac_t
- #include <fsl_sss_api.h>
Message Authentication Code.
Public Members
-
sss_algorithm_t
algorithm
Algorithm to be applied, e.g. MAC/CMAC
-
uint8_t
data
[(0 + (2 * sizeof(void *)) + (2 * sizeof(int)) + (2 * sizeof(void *)) + 32)]
-
struct sss_mac_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_object_t *
keyObject
Key to be used for …
-
sss_mode_t
mode
Mode of operation for MAC (kMode_SSS_Mac)
-
sss_session_t *
session
Virtual connection between application (user context) and specific security subsystem and function thereof.
-
sss_algorithm_t
-
void
3.3.9.10. SSS Key derivation types and APIs¶
-
group
sss_crypto_derive_key
Derive Key.
Operations that use mutiple keys from multiple security systems and dervive and output key, e.g. Diffie Hellman exchange.
Functions
-
void
sss_derive_key_context_free
(sss_derive_key_t *context) Derive key context release. The function frees derive key context.
- Parameters
context
: Pointer to derive key context.
-
sss_status_t
sss_derive_key_context_init
(sss_derive_key_t *context, sss_session_t *session, sss_object_t *keyObject, sss_algorithm_t algorithm, sss_mode_t mode) Derive key context init. The function initializes derive key context with initial values.
- Return
Status of the operation
- Parameters
context
: Pointer to derive key context.session
: Associate SSS session with the derive key context.keyObject
: Associate SSS key object with the derive key context.algorithm
: One of the derive key algorithms defined by sss_algorithm_t.mode
: One of the modes defined by sss_mode_t.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_derive_key_dh
(sss_derive_key_t *context, sss_object_t *otherPartyKeyObject, sss_object_t *derivedKeyObject) Asymmetric key derivation Diffie-Helmann The function cryptographically derives a key from another key. For example Diffie-Helmann.
- Return
Status of the operation
- Parameters
context
: Pointer to derive key context.otherPartyKeyObject
: Public key of the other party in the Diffie-Helmann algorithm[inout] derivedKeyObject
: Reference to a derived key
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_derive_key_go
(sss_derive_key_t *context, const uint8_t *saltData, size_t saltLen, const uint8_t *info, size_t infoLen, sss_object_t *derivedKeyObject, uint16_t deriveDataLen, uint8_t *hkdfOutput, size_t *hkdfOutputLen) Symmetric key derivation The function cryptographically derives a key from another key. For example MIFARE key derivation, PRF, HKDF-Extract.
- Return
Status of the operation
- Parameters
context
: Pointer to derive key context.saltData
: Input data buffer, typically with some random data.saltLen
: Length of saltData buffer in bytes.info
: Input data buffer, typically with some fixed info.infoLen
: Length of info buffer in bytes.[inout] derivedKeyObject
: Reference to a derived keyderiveDataLen
: Requested length of outputhkdfOutput
: Output buffer containing key derivation outputhkdfOutputLen
: Output containing length of hkdfOutput
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_derive_key_one_go
(sss_derive_key_t *context, const uint8_t *saltData, size_t saltLen, const uint8_t *info, size_t infoLen, sss_object_t *derivedKeyObject, uint16_t deriveDataLen) Symmetric key derivation (replaces the deprecated function sss_derive_key_go) The function cryptographically derives a key from another key. For example MIFARE key derivation, PRF, HKDF-Extract-Expand, HKDF-Expand. Refer to sss_derive_key_sobj_one_go in case the Salt is available as a key object.
- Return
Status of the operation
- Parameters
context
: Pointer to derive key context.saltData
: Input data buffer, typically with some random data.saltLen
: Length of saltData buffer in bytes.info
: Input data buffer, typically with some fixed info.infoLen
: Length of info buffer in bytes.[inout] derivedKeyObject
: Reference to a derived key[in] deriveDataLen
: Expected length of derived key.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_derive_key_sobj_one_go
(sss_derive_key_t *context, sss_object_t *saltKeyObject, const uint8_t *info, size_t infoLen, sss_object_t *derivedKeyObject, uint16_t deriveDataLen) Symmetric key derivation (salt in key object) Refer to sss_derive_key_one_go in case the salt is not available as a key object.
- Return
Status of the operation
- Parameters
context
: Pointer to derive key contextsaltKeyObject
: Reference to salt. The salt key object must reside in the same keystore as the derive key context.[in] info
: Input data buffer, typically with some fixed info.[in] infoLen
: Length of info buffer in bytes.derivedKeyObject
: Reference to a derived key[in] deriveDataLen
: The derive data length
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
struct
sss_derive_key_t
- #include <fsl_sss_api.h>
Key derivation
Public Members
-
sss_algorithm_t
algorithm
Algorithm to be applied, e.g. …
-
uint8_t
data
[(0 + (2 * sizeof(void *)) + (2 * sizeof(int)) + (2 * sizeof(void *)) + 32)]
-
struct sss_derive_key_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_object_t *
keyObject
KeyObject used to derive key s
-
sss_mode_t
mode
Mode of operation for …. e.g. …
-
sss_session_t *
session
Pointer to the session
-
sss_algorithm_t
-
void
3.3.9.11. SSS AEAD types and APIs¶
-
group
sss_crypto_aead
Authenticated Encryption with Additional Data.
Functions
-
void
sss_aead_context_free
(sss_aead_t *context) AEAD context release. The function frees aead context.
- Parameters
context
: Pointer to aead context.
-
sss_status_t
sss_aead_context_init
(sss_aead_t *context, sss_session_t *session, sss_object_t *keyObject, sss_algorithm_t algorithm, sss_mode_t mode) AEAD context init. The function initializes aead context with initial values.
- Return
Status of the operation
- Parameters
context
: Pointer to aead crypto context.session
: Associate SSS session with aead context.keyObject
: Associate SSS key object with aead context.algorithm
: One of the aead algorithms defined by sss_algorithm_t.mode
: One of the modes defined by sss_mode_t.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_aead_finish
(sss_aead_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen, uint8_t *tag, size_t *tagLen) Finalize AEAD. The functions processes data that has not been processed by previous calls to sss_aead_update() as well as srcData. It finalizes the AEAD operations and computes the tag (encryption) or compares the computed tag with the tag supplied in the parameter (decryption).
- Return
Status of the operation
- Parameters
context
: Pointer to aead crypto context.srcData
: Buffer containing final chunk of input data.srcLen
: Length of final chunk of input data in bytes.destData
: Buffer containing output data.[inout] destLen
: Length of output data in bytes. Buffer length on entry, reflects actual output size on return.tag
: Encryption: Output buffer filled with computed tag Decryption: Input buffer filled with received tagtagLen
: Length of the computed or received tag in bytes. For AES-GCM it must be 4,8,12,13,14,15 or 16. For AES-CCM it must be 4,6,8,10,12,14 or 16.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_aead_init
(sss_aead_t *context, uint8_t *nonce, size_t nonceLen, size_t tagLen, size_t aadLen, size_t payloadLen) AEAD init. The function starts the aead operation.
- Return
Status of the operation
- Parameters
context
: Pointer to aead crypto context.nonce
: The operation nonce or IV. When using internal IV algorithms (only encrypt) for SE051, iv buffer will be filled with genereted Initialization Vector.nonceLen
: The length of nonce in bytes. For AES-GCM it must be >= 1. For AES-CCM it must be 7, 8, 9, 10, 11, 12, or 13.tagLen
: Length of the computed or received tag in bytes. For AES-GCM it must be 4,8,12,13,14,15 or 16. For AES-CCM it must be 4,6,8,10,12,14 or 16.aadLen
: Input size in bytes of AAD. Used only for AES-CCM. Ignored for AES-GCM.payloadLen
: Length in bytes of the payload. Used only for AES-CCM. Ignored for AES-GCM.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_aead_one_go
(sss_aead_t *context, const uint8_t *srcData, uint8_t *destData, size_t size, uint8_t *nonce, size_t nonceLen, const uint8_t *aad, size_t aadLen, uint8_t *tag, size_t *tagLen) AEAD in one blocking function call. The function blocks current thread until the operation completes or an error occurs.
- Return
Status of the operation
- Parameters
context
: Pointer to aead crypto context.srcData
: Buffer containing the input data.destData
: Buffer containing the output data.size
: Size of input and output data buffer in bytes.nonce
: The operation nonce or IV. When using internal IV algorithms (only encrypt) for SE051, iv buffer will be filled with genereted Initialization Vector.nonceLen
: The length of nonce in bytes. For AES-GCM it must be >= 1. For AES-CCM it must be 7, 8, 9, 10, 11, 12, or 13.aad
: Input additional authentication data AADaadLen
: Input size in bytes of AADtag
: Encryption: Output buffer filled with computed tag Decryption: Input buffer filled with received tagtagLen
: Length of the tag in bytes. For AES-GCM it must be 4,8,12,13,14,15 or 16. For AES-CCM it must be 4,6,8,10,12,14 or 16.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.
-
sss_status_t
sss_aead_update
(sss_aead_t *context, const uint8_t *srcData, size_t srcLen, uint8_t *destData, size_t *destLen) AEAD data update. Feeds a new chunk of the data payload. Input data does not have to be a multiple of block size. Subsequent calls to this function are possible. Unless one or more calls of this function have supplied sufficient input data, no output is generated. The integration check is done by sss_aead_finish(). Until then it is not sure if the decrypt data is authentic.
- Return
Status of the operation
- Parameters
context
: Pointer to aead crypto context.srcData
: Buffer containing the input data.srcLen
: Length of the input data in bytes.destData
: Buffer containing the output data.[inout] destLen
: Length of the output data in bytes. Buffer length on entry, reflects actual output size on return.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
sss_status_t
sss_aead_update_aad
(sss_aead_t *context, const uint8_t *aadData, size_t aadDataLen) Feeds a new chunk of the AAD. Subsequent calls of this function are possible.
- Return
Status of the operation
- Parameters
context
: Pointer to aead crypto contextaadData
: Input buffer containing the chunk of AADaadDataLen
: Length of the AAD data in bytes.
- Return Value
kStatus_SSS_Success
: The operation has completed successfully.kStatus_SSS_Fail
: The operation has failed.kStatus_SSS_InvalidArgument
: One of the arguments is invalid for the function to execute.
-
struct
sss_aead_t
- #include <fsl_sss_api.h>
Authenticated Encryption with Additional Data.
Public Members
-
sss_algorithm_t
algorithm
Algorithm to be used
-
uint8_t
data
[(0 + (5 * sizeof(void *)) + (6 * sizeof(int)) + (5 * sizeof(void *)) + 32)]
-
struct sss_aead_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_object_t *
keyObject
Key to be used for asymmetric
-
sss_mode_t
mode
High level operation (encrypt/decrypt)
-
sss_session_t *
session
Virtual connection between application (user context) and specific security subsystem and function thereof.
-
sss_algorithm_t
-
void
3.3.9.12. SSS Tunnel types and APIs¶
-
group
sss_crypto_tunnel
Tunnel session.
Functions
-
sss_status_t
sss_tunnel
(sss_tunnel_t *context, uint8_t *data, size_t dataLen, sss_object_t *keyObjects, uint32_t keyObjectCount, uint32_t tunnelType) Tunnelling service.
- Parameters
[inout] context
: Pointer to tunnel context.data
: Pointer to data to be send to subsystem.dataLen
: Length of the data in bytes.keyObjects
: Objects references used by the service.keyObjectCount
: Number of key references atkeyObjects
.tunnelType
: Implementation specific id of the service.
-
void
sss_tunnel_context_free
(sss_tunnel_t *context) Destructor for the tunnelling service context.
- Parameters
[out] context
: Pointer to tunnel context.
-
sss_status_t
sss_tunnel_context_init
(sss_tunnel_t *context, sss_session_t *session) Constructor for the tunnelling service context.
Earlier: sss_status_t sss_tunnel_context_init( sss_session_t *session, sss_tunnel_t *context); Now: Parameters are swapped sss_status_t sss_tunnel_context_init( sss_tunnel_t *context, sss_session_t *session);
- Parameters
[out] context
: Pointer to tunnel context. Tunnel context is updated on function return.session
: Pointer to session this tunnelling service belongs to.
-
struct
sss_tunnel_t
- #include <fsl_sss_api.h>
Tunneling
Used for communication via another system.
Public Members
-
uint8_t
data
[(0 + (1 * sizeof(void *)) + (2 * sizeof(int)) + (2 * sizeof(void *)) + 32)]
-
struct sss_tunnel_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_session_t *
session
Pointer to the session
-
uint32_t
tunnelType
Tunnel to which Applet (Currently unused)
-
uint8_t
-
sss_status_t
3.3.9.13. SSS Policy types and APIs¶
-
group
sss_policy
Policies to restrict and control sessions and objects.
Enums
-
enum
sss_policy_type_u
Type of policy
Values:
-
KPolicy_None
No policy applied
-
KPolicy_Session
Policy related to session.
- See
sss_policy_session_u
-
KPolicy_Sym_Key
Policy related to key.
- See
sss_policy_key_u
-
KPolicy_Asym_Key
-
KPolicy_UserID
-
KPolicy_File
-
KPolicy_Counter
-
KPolicy_PCR
-
KPolicy_Common
-
KPolicy_Common_PCR_Value
-
KPolicy_Desfire_Changekey_Auth_Id
-
KPolicy_Derive_Master_Key_Id
-
KPolicy_Internal_Sign
-
-
struct
sss_policy_asym_key_u
- #include <fsl_sss_policy.h>
Policies applicable to Asymmetric KEY
Public Members
-
uint8_t
can_Attest
Allow to attest an object
-
uint8_t
can_Decrypt
Allow decryption
-
uint8_t
can_Encrypt
Allow encryption
-
uint8_t
can_Gen
Allow to (re)generate the object
-
uint8_t
can_Import_Export
Allow to imported or exported
-
uint8_t
can_KA
Allow key agreement
-
uint8_t
can_KD
Allow key derivation
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Sign
Allow signature generation
-
uint8_t
can_Verify
Allow signature verification
-
uint8_t
can_Wrap
Allow key wrapping
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
forbid_Derived_Output
Forbid derived output
-
uint8_t
-
struct
sss_policy_common_pcr_value_u
- #include <fsl_sss_policy.h>
Common PCR Value Policies for all object types
Public Members
-
uint8_t
pcrExpectedValue
[32] Expected value of the PCR
-
uint32_t
pcrObjId
PCR object ID
-
uint8_t
-
struct
sss_policy_common_u
- #include <fsl_sss_policy.h>
Common Policies for all object types
Public Members
-
uint8_t
can_Delete
Allow to delete the object
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
forbid_All
Forbid all operations
-
uint8_t
req_pcr_val
Require PCR value
-
uint8_t
req_Sm
Require having secure messaging enabled with encryption and integrity on the command
-
uint8_t
-
struct
sss_policy_counter_u
- #include <fsl_sss_policy.h>
All policies related to secure object type Counter
Public Members
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
-
struct
sss_policy_desfire_changekey_authId_value_u
- #include <fsl_sss_policy.h>
DESFire ChangeKey - authentication key identifier.
Public Members
-
uint32_t
desfire_authId
DESFire authentication object ID
-
uint32_t
-
struct
sss_policy_file_u
- #include <fsl_sss_policy.h>
All policies related to secure object type File
Public Members
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
-
struct
sss_policy_internal_sign_tbs_value_u
- #include <fsl_sss_policy.h>
Allow internal sign.
Public Members
-
uint32_t
tbsItemList_KeyId
identifier of the tbsItemList Secure Object
-
uint32_t
-
struct
sss_policy_key_drv_master_keyid_value_u
- #include <fsl_sss_policy.h>
Key Derive - Master key identifier.
Public Members
-
uint32_t
master_keyId
Master key ID
-
uint32_t
-
struct
sss_policy_pcr_u
- #include <fsl_sss_policy.h>
All policies related to secure object type PCR
Public Members
-
uint8_t
can_Read
Allow to read the object
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
-
struct
sss_policy_session_u
- #include <fsl_sss_policy.h>
Policy applicable to a session
Public Members
-
uint8_t
allowRefresh
Whether this session can be refreshed without losing context. And also reset maxDurationOfSession_sec / maxOperationsInSession
-
uint8_t
has_MaxDurationOfSession_sec
Whether maxOperationsInSession is set. This is to ensure ‘0 == maxDurationOfSession_sec’ does not get set by middleware.
-
uint8_t
has_MaxOperationsInSession
Whether maxOperationsInSession is set. This is to ensure ‘0 == maxOperationsInSession’ does not get set by middleware.
-
uint16_t
maxDurationOfSession_sec
Session can be used for this much time, in seconds
-
uint16_t
maxOperationsInSession
Number of operations permitted in a session
-
uint8_t
-
struct
sss_policy_sym_key_u
- #include <fsl_sss_policy.h>
Policies applicable to Symmetric KEY
Public Members
-
uint8_t
allow_kdf_ext_rnd
Allow kdf(prf) external random
-
uint8_t
can_Decrypt
Allow decryption
-
uint8_t
can_Desfire_Auth
Allow to perform DESFire authentication
-
uint8_t
can_Desfire_Dump
Allow to dump DESFire session keys
-
uint8_t
can_Desfire_KD
Allow Desfire key derivation
-
uint8_t
can_Encrypt
Allow encryption
-
uint8_t
can_Gen
Allow to (re)generate the object
-
uint8_t
can_HKDF
Allow HKDF
-
uint8_t
can_Import_Export
Allow to imported or exported
-
uint8_t
can_KA
Allow key agreement. Only for SE051H, key agreement is applicable for symm objects
-
uint8_t
can_KD
Allow key derivation
-
uint8_t
can_PBKDF
Allow PBKDF
-
uint8_t
can_Sign
Allow signature generation
-
uint8_t
can_TLS_KDF
Allow TLS PRF key derivation
-
uint8_t
can_TLS_PMS_KD
Allow TLS PMS key derivation
-
uint8_t
can_usage_hmac_pepper
Allow usage as hmac pepper
-
uint8_t
can_Verify
Allow signature verification
-
uint8_t
can_Wrap
Allow key wrapping
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
forbid_Derived_Output
Forbid derived output
-
uint8_t
forbid_external_iv
Forbid External iv
-
uint8_t
-
struct
sss_policy_t
- #include <fsl_sss_policy.h>
An array of policies sss_policy_u
Public Members
-
size_t
nPolicies
Number of policies
-
const sss_policy_u *
policies
[(10)] Array of unique policies, this needs to be allocated based nPolicies
-
size_t
-
struct
sss_policy_u
- #include <fsl_sss_policy.h>
Unique/individual policy. For any operation, you need array of sss_policy_u.
Public Members
-
sss_policy_asym_key_u
asymmkey
-
uint32_t
auth_obj_id
Auth ID for each Object Policy, invalid for session policy type == KPolicy_Session
-
sss_policy_common_u
common
-
sss_policy_common_pcr_value_u
common_pcr_value
-
sss_policy_counter_u
counter
-
sss_policy_desfire_changekey_authId_value_u
desfire_auth_id
-
sss_policy_file_u
file
-
sss_policy_key_drv_master_keyid_value_u
master_key_id
-
sss_policy_pcr_u
pcr
-
union sss_policy_u::[anonymous]
policy
Union of applicable policies based on the type of object
-
sss_policy_session_u
session
-
sss_policy_sym_key_u
symmkey
-
sss_policy_internal_sign_tbs_value_u
tbsItemList
-
sss_policy_type_u
type
Secure Object Type
-
sss_policy_asym_key_u
-
struct
sss_policy_userid_u
- #include <fsl_sss_policy.h>
All policies related to secure object type UserID
Public Members
-
uint8_t
can_Write
Allow to write the object
-
uint8_t
-
enum
3.3.9.14. SSS Str log types and APIs¶
-
group
sss_str_log
Functions
-
const char *
sss_cipher_type_sz
(sss_cipher_type_t cipher_type) Returns string error code for sss_cipher_type_t.
- Return
String conversion of
cipher_type
to String.- Parameters
[in] status
: See sss_cipher_type_t
-
const char *
sss_status_sz
(sss_status_t status) Returns string error code for sss_status_t.
- Return
String conversion of
status
to String.- Parameters
[in] status
: See sss_status_t
-
const char *