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

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

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 user

    • Anything 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

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 store

  • keyObject: 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 store

  • keyObject: 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 store

  • keyObject: 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 context

  • keyObject: Reference to a key and it’s properties

  • data: Data to be stored in Key. When setting ecc private key only, do not include key header.

  • dataLen: Length of the data

  • keyBitLen: Crypto algorithm key bit length

  • options: Pointer to implementation specific options

  • optionsLen: 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.

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 keyObject

  • keyId: External Key ID. Later on this may be used by sss_key_object_get_handle

  • keyPart: See sss_key_part_t

  • cipherType: See sss_cipher_type_t

  • keyByteLenMax: Maximum storage this type of key may need. For systems that have their own internal allocation table this would help

  • options: 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: Object

  • access: 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 checked

  • purpose: 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 applied

  • access: 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 object

  • group: 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 applied

  • purpose: 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 applied

  • user: 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

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.

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 buffer

  • srcLen: Length of the input in bytes

  • destData: Output buffer

  • destLen: 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 buffer

  • srcLen: Length of the input in bytes

  • destData: Output buffer

  • destLen: 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 digest

  • digestLen: Length of the digest in bytes

  • signature: Output buffer written with the signature of the digest

  • signatureLen: 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 digest

  • digestLen: Length of the digest in bytes

  • signature: Input buffer containing the signature to verify

  • signatureLen: 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.

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

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 digest

  • digestLen: 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 message

  • messageLen: Length of the input message in bytes

  • digest: Output message digest

  • digestLen: 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.

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 MAC

  • macLen: 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 message

  • messageLen: Length of the input message in bytes

  • mac: Output message MAC

  • macLen: 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.

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 key

  • deriveDataLen: Requested length of output

  • hkdfOutput: Output buffer containing key derivation output

  • hkdfOutputLen: 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 context

  • saltKeyObject: 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

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 tag

  • 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.

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 AAD

  • aadLen: Input size in bytes of AAD

  • tag: Encryption: Output buffer filled with computed tag Decryption: Input buffer filled with received tag

  • tagLen: 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 context

  • aadData: Input buffer containing the chunk of AAD

  • aadDataLen: 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.

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 at keyObjects.

  • 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)

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

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

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

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

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

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

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

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

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

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

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

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

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
sss_policy_userid_u pin
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

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

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