3.3.10. List of all SSS SE05x APIs and structures

3.3.10.1. SSS SE05x Enums and Types

group sss_sw_se05x

Manage session.

Defines

se05x_auth_context_t

deprecated : Used only for backwards compatibility

SE05x_Connect_Ctx_t

deprecated : Used only for backwards compatibility

SSS_AEAD_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

SSS_ASYMMETRIC_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

SSS_DERIVE_KEY_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

SSS_DIGEST_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

SSS_KEY_STORE_TYPE_IS_SE05X(keyStore)

Are we using SE05X as crypto subsystem?

SSS_MAC_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

SSS_OBJECT_TYPE_IS_SE05X(pObject)

Are we using SE05X as crypto subsystem?

SSS_RNG_CONTEXT_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

SSS_SESSION_TYPE_IS_SE05X(session)

Are we using SE05X as crypto subsystem?

SSS_SUBSYSTEM_TYPE_IS_SE05X(subsystem)

Are we using SE05X as crypto subsystem?

SSS_SYMMETRIC_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

SSS_TUNNEL_CONTEXT_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

SSS_TUNNEL_TYPE_IS_SE05X(context)

Are we using SE05X as crypto subsystem?

Enums

enum sss_s05x_sesion_prop_au8_t

SE050 Properties that can be represented as an array

Values:

kSSS_SE05x_SessionProp_CertUID = kSSS_SessionProp_au8_Proprietary_Start + 1
enum sss_s05x_sesion_prop_u32_t

SE050 Properties that can be represented as 32bit numbers

Values:

kSSS_SE05x_SessionProp_CertUIDLen = kSSS_SessionProp_u32_Optional_Start + 1
struct _sss_se05x_object
#include <fsl_sss_se05x_types.h>

An object (secure / non-secure) within a Key Store.

Public Members

uint32_t cipherType

cipherType type from sss_cipher_type_t

SE05x_ECCurve_t curve_id

If this is an ECC Key, the Curve ID of the key

uint8_t isPersistant

Whether this is a persistant or tansient object

uint32_t keyId

Application specific key identifier. The keyId is kept in the key store along with the key data and other properties.

sss_se05x_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

struct _sss_se05x_session
#include <fsl_sss_se05x_types.h>

Root session.

This is a singleton for each connection (physical/logical) to individual cryptographic system.

Public Members

sss_se05x_tunnel_context_t *ptun_ctx

In case connection is tunneled, context to the tunnel

Se05xSession_t s_ctx

Connection context to SE050

sss_type_t subsystem

Indicates which security subsystem is selected to be used.

struct _sss_se05x_tunnel_context
#include <fsl_sss_se05x_types.h>

Tunneling

Used for communication via another system.

Public Members

struct _sss_se05x_session *se05x_session

Pointer to the base SE050 SEssion

sss_tunnel_dest_t tunnelDest

Where exactly this tunnel terminates to

struct SE05x_Applet_Feature_Disable_t
#include <fsl_sss_se05x_types.h>

Used to disable Applet Features via sss_se05x_set_feature

Public Members

uint8_t EXTCFG_FORBID_AES_GCM

Disable feature AES_GCM B8b8

uint8_t EXTCFG_FORBID_AES_GCM_EXT_IV

Disable feature AES_GCM_EXT_IV B8b7

uint8_t EXTCFG_FORBID_ECDAA

Disable feature ECDAA B2b7

uint8_t EXTCFG_FORBID_ECDH

Disable feature ECDH B2b8

uint8_t EXTCFG_FORBID_HKDF_EXTRACT

Disable feature HKDF_EXTRACT B10b7

uint8_t EXTCFG_FORBID_RSA_LT_2K

Disable feature RSA_LT_2K B6b8

uint8_t EXTCFG_FORBID_RSA_SHA1

Disable feature RSA_SHA1 B6b7

struct SE05x_Applet_Feature_t
#include <fsl_sss_se05x_types.h>

Used to enable Applet Features via sss_se05x_set_feature

Public Members

uint8_t AppletConfig_AES

Writing AESKey objects

uint8_t AppletConfig_DES

Writing DESKey objects

uint8_t AppletConfig_DH_MONT

Use of curve RESERVED_ID_ECC_MONT_DH_25519

uint8_t AppletConfig_ECDAA

Use of curve TPM_ECC_BN_P256

uint8_t AppletConfig_ECDSA_ECDH_ECDHE

EC DSA and DH support

uint8_t AppletConfig_EDDSA

Use of curve RESERVED_ID_ECC_ED_25519

uint8_t AppletConfig_HMAC

Writing HMACKey objects

uint8_t AppletConfig_I2CM

I2C Master support (see 4.17) in APDU Spec

uint8_t AppletConfig_MIFARE

Mifare DESFire support (see 4.15) in APDU Spec

uint8_t AppletConfig_PBKDF

PBKDF2

uint8_t AppletConfig_RFU1

Allocated value undefined and reserved for future use

uint8_t AppletConfig_RFU21

RFU

uint8_t AppletConfig_RSA_CRT

Writing RSAKey objects

uint8_t AppletConfig_RSA_PLAIN

Writing RSAKey objects

uint8_t AppletConfig_TLS

TLS Handshake support commands (see 4.16) in APDU Spec

struct sss_se05x_aead_t
#include <fsl_sss_se05x_types.h>

Authenticated Encryption with Additional Data.

Public Members

sss_algorithm_t algorithm

Algorithm to be used

uint8_t cache_data[16]

Cache in case of un-alined inputs

size_t cache_data_len

How much we have cached

SE05x_CryptoObjectID_t cryptoObjectId

Implementation specific part

sss_se05x_object_t *keyObject

Key to be used for asymmetric

sss_mode_t mode

High level operation (encrypt/decrypt)

sss_se05x_session_t *session

Virtual connection between application (user context) and specific security subsystem and function thereof.

struct sss_se05x_asymmetric_t
#include <fsl_sss_se05x_types.h>

Asymmetric Cryptographic operations.

e.g. RSA/ECC.

Public Members

sss_algorithm_t algorithm

Algorithm to be applied, e.g. ECDSA

sss_se05x_object_t *keyObject

KeyObject used for Asymmetric operation

sss_mode_t mode

Mode of operation for the Asymmetric operation. e.g. Sign/Verify/Encrypt/Decrypt

sss_se05x_session_t *session

Pointer to root session

struct sss_se05x_derive_key_t
#include <fsl_sss_se05x_types.h>

Key derivation

Public Members

sss_algorithm_t algorithm

Algorithm to be applied, e.g. …

sss_se05x_object_t *keyObject

KeyObject used to derive key s

sss_mode_t mode

Mode of operation for …. e.g. …

sss_se05x_session_t *session

Pointer to the session

struct sss_se05x_digest_t
#include <fsl_sss_se05x_types.h>

Message Digest operations

Public Members

sss_algorithm_t algorithm

Algorithm to be applied, e.g SHA1, SHA256

SE05x_CryptoObjectID_t cryptoObjectId

Implementation specific part

size_t digestFullLen

Full digest length per algorithm definition. This field is initialized along with algorithm.

sss_mode_t mode

Mode of operation, e.g Sign/Verify

sss_se05x_session_t *session

Virtual connection between application (user context) and specific security subsystem and function thereof.

struct sss_se05x_key_store_t
#include <fsl_sss_se05x_types.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

struct _sss_se05x_object *kekKey

In case the we are using Key Wrapping while injecting the keys, pointer to key used for wrapping

sss_se05x_session_t *session

Pointer to the session

struct sss_se05x_mac_t
#include <fsl_sss_se05x_types.h>

Message Authentication Code.

Public Members

sss_algorithm_t algorithm

copydoc sss_mac_t::algorithm

SE05x_CryptoObjectID_t cryptoObjectId

Used crypto object ID for this operation

sss_se05x_object_t *keyObject

copydoc sss_mac_t::keyObject

sss_mode_t mode

copydoc sss_mac_t::mode

sss_se05x_session_t *session

copydoc sss_mac_t::session

struct sss_se05x_rng_context_t
#include <fsl_sss_se05x_types.h>

Random number generator context

Public Members

sss_se05x_session_t *session

Pointer to the session

struct sss_se05x_symmetric_t
#include <fsl_sss_se05x_types.h>

Typedef for the symmetric crypto context.

Public Members

sss_algorithm_t algorithm

Algorithm to be applied, e.g AES_ECB / CBC

uint8_t cache_data[16]

Since underlying system conly only process in fixed chunks, chache them on host to complete the operation sanely

size_t cache_data_len

Length of bytes cached on host

SE05x_CryptoObjectID_t cryptoObjectId

Used crypto object ID for this operation

sss_se05x_object_t *keyObject

Reference to key and it’s properties.

sss_mode_t mode

Mode of operation, e.g Encryption/Decryption

sss_se05x_session_t *session

Virtual connection between application (user context) and specific security subsystem and function thereof.

3.3.10.2. SSS SE05x Session types and APIs

group sss_se05x_session

Manage session.

Functions

void sss_se05x_session_close(sss_se05x_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_se05x_session_create(sss_se05x_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_se05x_session_delete(sss_se05x_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_se05x_session_open(sss_se05x_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_se05x_session_prop_get_au8(sss_se05x_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_se05x_session_prop_get_u32(sss_se05x_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:

3.3.10.3. SSS SE05x Keystore types and APIs

group sss_se05x_keystore

Manage session.

Functions

sss_status_t sss_se05x_key_store_allocate(sss_se05x_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.

This API does not do anything special on SE05X.

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_se05x_key_store_context_free(sss_se05x_key_store_t *keyStore)

Destructor for the key store context.

sss_status_t sss_se05x_key_store_context_init(sss_se05x_key_store_t *keyStore, sss_se05x_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_se05x_key_store_erase_key(sss_se05x_key_store_t *keyStore, sss_se05x_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_se05x_key_store_export_key(sss_se05x_key_store_t *keyStore, sss_se05x_object_t *keyObject, uint8_t *key, size_t *keylen)

Export Key from SE050 to host

Only Transient keys can be exported.

sss_status_t sss_se05x_key_store_freeze_key(sss_se05x_key_store_t *keyStore, sss_se05x_object_t *keyObject)

Not available for SE05X

sss_status_t sss_se05x_key_store_generate_key(sss_se05x_key_store_t *keyStore, sss_se05x_object_t *keyObject, size_t keyBitLen, void *options)

This function generates key[] in the destination key store.

sss_status_t sss_se05x_key_store_get_key(sss_se05x_key_store_t *keyStore, sss_se05x_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_se05x_key_store_import_key(sss_se05x_key_store_t *keyStore, sss_se05x_object_t *keyObject, uint8_t *key, size_t keylen)

Re Import previously exported SE05X key from host to the SE05X

Only Transient keys can be imported.

sss_status_t sss_se05x_key_store_load(sss_se05x_key_store_t *keyStore)

Load from persistent memory to cached objects.

This API does not do anything special on SE05X.

sss_status_t sss_se05x_key_store_open_key(sss_se05x_key_store_t *keyStore, sss_se05x_object_t *keyObject)

Access key store using one more level of encryption.

e.g. Access keys / encryption key during storage

In SE05X, these keys can be used as KEK encryption key

Return

The sss status.

Parameters
  • keyStore: The key store

  • keyObject: The key object that is to be used as a KEK (Key Encryption Key)

If keyObject == NULL, then subsequent key injection does not use any KEK.

Return

The sss status.

sss_status_t sss_se05x_key_store_save(sss_se05x_key_store_t *keyStore)

Save all cached persistent objects to persistent memory.

This API does not do anything special on SE05X.

sss_status_t sss_se05x_key_store_set_key(sss_se05x_key_store_t *keyStore, sss_se05x_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

3.3.10.4. SSS SE05x KeyObject types and APIs

group sss_se05x_keyobj

Manage session.

Functions

sss_status_t sss_se05x_key_object_allocate_handle(sss_se05x_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.

On SE050, the memory get reserved only when the actual object is created and hence there is no memory reservation happening in this API call. but internally it checks if the object already exists or not . if the object is already existing it returns a failure.

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_se05x_key_object_free(sss_se05x_object_t *keyObject)

Destructor for the key object. The function frees key object context.

On SE050, this has no impact on physical Key Object.

Parameters
  • keyObject: Pointer to key object context.

sss_status_t sss_se05x_key_object_get_access(sss_se05x_object_t *keyObject, uint32_t *access)

Not Available for SE05X

sss_status_t sss_se05x_key_object_get_handle(sss_se05x_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.

On SE05X, this API uses

Se05x_API_ReadType and fetches parameters of the API.
Return

The sss status.

Parameters
  • keyObject: The key object

  • [in] keyId: The key identifier

sss_status_t sss_se05x_key_object_get_purpose(sss_se05x_object_t *keyObject, sss_mode_t *purpose)

Not Available for SE05X

sss_status_t sss_se05x_key_object_get_user(sss_se05x_object_t *keyObject, uint32_t *user)

Not Available for SE05X

sss_status_t sss_se05x_key_object_init(sss_se05x_object_t *keyObject, sss_se05x_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_se05x_key_object_set_access(sss_se05x_object_t *keyObject, uint32_t access, uint32_t options)

Not Available for SE05X

sss_status_t sss_se05x_key_object_set_eccgfp_group(sss_se05x_object_t *keyObject, sss_eccgfp_group_t *group)

Not Available for SE05X

sss_status_t sss_se05x_key_object_set_purpose(sss_se05x_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_se05x_key_object_set_user(sss_se05x_object_t *keyObject, uint32_t user, uint32_t options)

Not Available for SE05X

3.3.10.5. SSS SE05x Symmetric types and APIs

group sss_se05x_symm

Manage session.

Functions

sss_status_t sss_se05x_cipher_crypt_ctr(sss_se05x_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_se05x_cipher_finish(sss_se05x_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_se05x_cipher_init(sss_se05x_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_se05x_cipher_one_go(sss_se05x_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_se05x_cipher_one_go_v2(sss_se05x_symmetric_t *context, uint8_t *iv, size_t ivLen, const uint8_t *srcData, const size_t srcLen, uint8_t *destData, size_t *pDataLen)

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_se05x_cipher_update(sss_se05x_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_se05x_symmetric_context_free(sss_se05x_symmetric_t *context)

Symmetric context release. The function frees symmetric context.

Parameters
  • context: Pointer to symmetric crypto context.

sss_status_t sss_se05x_symmetric_context_init(sss_se05x_symmetric_t *context, sss_se05x_session_t *session, sss_se05x_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.

3.3.10.6. SSS SE05x Asymmetric types and APIs

group sss_se05x_asym

Manage session.

Functions

void sss_se05x_asymmetric_context_free(sss_se05x_asymmetric_t *context)

Asymmetric context release. The function frees asymmetric context.

Parameters
  • context: Pointer to asymmetric context.

sss_status_t sss_se05x_asymmetric_context_init(sss_se05x_asymmetric_t *context, sss_se05x_session_t *session, sss_se05x_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_se05x_asymmetric_decrypt(sss_se05x_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_se05x_asymmetric_encrypt(sss_se05x_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_se05x_asymmetric_sign(sss_se05x_asymmetric_t *context, uint8_t *srcData, size_t srcLen, uint8_t *signature, size_t *signatureLen)

Similar to sss_se05x_asymmetric_sign_digest,

but hashing/digest done by SE

sss_status_t sss_se05x_asymmetric_sign_digest(sss_se05x_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_se05x_asymmetric_verify(sss_se05x_asymmetric_t *context, uint8_t *srcData, size_t srcLen, uint8_t *signature, size_t signatureLen)

Similar to sss_se05x_asymmetric_verify_digest, but hashing/digest done by SE

sss_status_t sss_se05x_asymmetric_verify_digest(sss_se05x_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.10.7. SSS SE05x RNG types and APIs

group sss_se05x_rng

Manage session.

Functions

sss_status_t sss_se05x_rng_context_free(sss_se05x_rng_context_t *context)

free random genertor context.

Return

status

Parameters
  • context: generator context.

sss_status_t sss_se05x_rng_context_init(sss_se05x_rng_context_t *context, sss_se05x_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_se05x_rng_get_random(sss_se05x_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

3.3.10.8. SSS SE05x Digest types and APIs

group sss_se05x_md

Manage session.

Functions

void sss_se05x_digest_context_free(sss_se05x_digest_t *context)

Digest context release. The function frees digest context.

Parameters
  • context: Pointer to digest context.

sss_status_t sss_se05x_digest_context_init(sss_se05x_digest_t *context, sss_se05x_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_se05x_digest_finish(sss_se05x_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_se05x_digest_init(sss_se05x_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_se05x_digest_one_go(sss_se05x_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_se05x_digest_update(sss_se05x_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.

3.3.10.9. SSS SE05x MAC types and APIs

group sss_se05x_mac

Manage session.

Functions

void sss_se05x_mac_context_free(sss_se05x_mac_t *context)

MAC context release. The function frees mac context.

Parameters
  • context: Pointer to mac context.

sss_status_t sss_se05x_mac_context_init(sss_se05x_mac_t *context, sss_se05x_session_t *session, sss_se05x_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_se05x_mac_finish(sss_se05x_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_se05x_mac_init(sss_se05x_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_se05x_mac_one_go(sss_se05x_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_se05x_mac_update(sss_se05x_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.

sss_status_t sss_se05x_mac_validate_one_go(sss_se05x_mac_t *context, const uint8_t *message, size_t messageLen, uint8_t *mac, size_t macLen)

MAC Validate

3.3.10.10. SSS SE05x Key derivation types and APIs

group sss_se05x_keyderive

Manage session.

Functions

void sss_se05x_derive_key_context_free(sss_se05x_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_se05x_derive_key_context_init(sss_se05x_derive_key_t *context, sss_se05x_session_t *session, sss_se05x_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_se05x_derive_key_dh(sss_se05x_derive_key_t *context, sss_se05x_object_t *otherPartyKeyObject, sss_se05x_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_se05x_derive_key_go(sss_se05x_derive_key_t *context, const uint8_t *saltData, size_t saltLen, const uint8_t *info, size_t infoLen, sss_se05x_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_se05x_derive_key_one_go(sss_se05x_derive_key_t *context, const uint8_t *saltData, size_t saltLen, const uint8_t *info, size_t infoLen, sss_se05x_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_se05x_derive_key_sobj_one_go(sss_se05x_derive_key_t *context, sss_se05x_object_t *saltKeyObject, const uint8_t *info, size_t infoLen, sss_se05x_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.

3.3.10.11. SSS SE05x AEAD types and APIs

group sss_se05x_aead

Manage session.

Functions

void sss_se05x_aead_context_free(sss_se05x_aead_t *context)

AEAD context release. The function frees aead context.

Parameters
  • context: Pointer to aead context.

sss_status_t sss_se05x_aead_context_init(sss_se05x_aead_t *context, sss_se05x_session_t *session, sss_se05x_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_se05x_aead_finish(sss_se05x_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_se05x_aead_init(sss_se05x_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_se05x_aead_one_go(sss_se05x_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_se05x_aead_update(sss_se05x_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_se05x_aead_update_aad(sss_se05x_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.

3.3.10.12. SSS SE05x Tunnel types and APIs

group sss_se05x_tunnel

Manage session.

Functions

sss_status_t sss_se05x_tunnel(sss_se05x_tunnel_context_t *context, uint8_t *data, size_t dataLen, sss_se05x_object_t *keyObjects, uint32_t keyObjectCount, uint32_t tunnelType)

Tunneling

Used for communication via another system.

void sss_se05x_tunnel_context_free(sss_se05x_tunnel_context_t *context)

Destructor for the tunnelling service context.

Parameters
  • [out] context: Pointer to tunnel context.

sss_status_t sss_se05x_tunnel_context_init(sss_se05x_tunnel_context_t *context, sss_se05x_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.

3.3.10.13. SSS SE05x I2C Master types and APIs

group se050_i2cm

I2C Master APIs in SE050 for secure sensor.

Enums

enum SE05x_I2CM_Baud_Rate_t

Configuration for I2CM

Values:

kSE05x_I2CM_Baud_Rate_100Khz = 0
kSE05x_I2CM_Baud_Rate_400Khz
enum SE05x_I2CM_securityReq_t

Additional operation on data read by I2C

Values:

kSE05x_Security_None = 0
kSE05x_Sign_Request
kSE05x_Sign_Enc_Request
enum SE05x_I2CM_status_t

Status of I2CM Transaction

Values:

kSE05x_I2CM_Success = 0x5A
kSE05x_I2CM_I2C_Nack_Fail = 0x01
kSE05x_I2CM_I2C_Write_Error = 0x02
kSE05x_I2CM_I2C_Read_Error = 0x03
kSE05x_I2CM_I2C_Time_Out_Error = 0x05
kSE05x_I2CM_Invalid_Tag = 0x11
kSE05x_I2CM_Invalid_Length = 0x12
kSE05x_I2CM_Invalid_Length_Encode = 0x13
kSE05x_I2CM_I2C_Config = 0x21
enum SE05x_I2CM_TAG_t

I2C Master micro operation.

Values:

kSE05x_TAG_I2CM_Config = 0x01
kSE05x_TAG_I2CM_Write = 0x03
kSE05x_TAG_I2CM_Read = 0x04
enum SE05x_I2CM_TLV_type_t

Types of entries in an I2CM Transaction

Values:

kSE05x_I2CM_None = 0

Do nothing

kSE05x_I2CM_Configure

Configure the address, baudrate

kSE05x_I2CM_Write = 3

Write to I2C Slave

kSE05x_I2CM_Read

Read from I2C Slave

kSE05x_I2CM_StructuralIssue = 0xFF

Response from SE05x that there is something wrong

Functions

smStatus_t Se05x_i2c_master_attst_txn(sss_session_t *sess, sss_object_t *keyObject, SE05x_I2CM_cmd_t *p, uint8_t *random_attst, size_t random_attstLen, SE05x_AttestationAlgo_t attst_algo, sss_se05x_attst_comp_data_t *pattest_data, uint8_t *rspbuffer, size_t *rspbufferLen, uint8_t noOftags)

Se05x_i2c_master_attst_txn.

I2CM Read With Attestation

Pre

p describes I2C master commands.

Post

p contains execution state of I2C master commands, the I2C master commands can be overwritten to report on execution failure.

Parameters
  • [in] sess: session identifier

  • [in] keyObject: Keyobject which contains 4 byte attestaion KeyId

  • [inout] p: Array of structure type capturing a sequence of i2c master cmd/rsp transactions.

  • [in] random_attst: 16-byte freshness random

  • [in] random_attstLen: length of freshness random

  • [in] attst_algo: 1 byte attestationAlgo

  • [out] ptimeStamp: timestamp

  • [out] timeStampLen: Length for timestamp

  • [out] freshness: freshness (random)

  • [out] pfreshnessLen: Length for freshness

  • [out] chipId: unique chip Id

  • [out] pchipIdLen: Length for chipId

  • [out] signature: signature

  • [out] psignatureLen: Length for signature

  • [in] noOftags: Amount of structures contained in p

smStatus_t Se05x_i2c_master_txn(sss_session_t *sess, SE05x_I2CM_cmd_t *cmds, uint8_t cmdLen)

Se05x_i2c_master_txn.

I2CM Transaction

Pre

p describes I2C master commands.

Post

p contains execution state of I2C master commands, the I2C master commands can be overwritten to report on execution failure.

Parameters
  • [in] sess: session identifier

  • [inout] cmds: Array of structure type capturing a sequence of i2c master cmd/rsp transactions.

  • [in] cmdLen: Amount of structures contained in cmds

struct _SE05x_I2CM_cmd
#include <fsl_sss_se05x_types.h>

Individual entry in array of TLV commands, with type

Se05x_i2c_master_txn would expect an array of these.

Public Members

SE05x_I2CM_INS_type_t cmd

Individual entry in array of TLV commands.

SE05x_I2CM_TLV_type_t type
struct SE05x_I2CM_configData_t
#include <fsl_sss_se05x_types.h>

Data Configuration for I2CM

Public Members

uint8_t I2C_addr

7 Bit address of I2C slave

SE05x_I2CM_Baud_Rate_t I2C_baudRate

What baud rate

SE05x_I2CM_status_t status

return status of the config operation

union SE05x_I2CM_INS_type_t
#include <fsl_sss_se05x_types.h>

Individual entry in array of TLV commands.

Public Members

SE05x_I2CM_configData_t cfg

Data Configuration for I2CM

SE05x_I2CM_structuralIssue_t issue

Used to report error response, not for outgoing command

SE05x_I2CM_readData_t rd

Read to I2CM from I2C Slave

SE05x_I2CM_securityData_t sec

Security Configuration for I2CM.

SE05x_I2CM_writeData_t w

Write From I2CM to I2C Slave.

struct SE05x_I2CM_readData_t
#include <fsl_sss_se05x_types.h>

Read to I2CM from I2C Slave

Public Members

uint8_t *rdBuf

Output. rdBuf will point to Host buffer.

SE05x_I2CM_status_t rdStatus

[Out] status of the operation

uint16_t readLength

How many bytes to read

struct SE05x_I2CM_securityData_t
#include <fsl_sss_se05x_types.h>

Security Configuration for I2CM.

Public Members

uint32_t keyObject

object used for the operation

SE05x_I2CM_securityReq_t operation

Additional operation on data read by I2C

struct SE05x_I2CM_structuralIssue_t
#include <fsl_sss_se05x_types.h>

Used to report error response, not for outgoing command

Public Members

SE05x_I2CM_status_t issueStatus

[Out] In case there is any structural issue

struct SE05x_I2CM_writeData_t
#include <fsl_sss_se05x_types.h>

Write From I2CM to I2C Slave.

Public Members

uint8_t *writebuf

Buffer to be written

uint8_t writeLength

How many bytes to write

SE05x_I2CM_status_t wrStatus

[Out] status of the operation

3.3.10.14. SSS SE05x Attestation types and APIs

group se05x_attest

Functions

sss_status_t sss_se05x_key_store_get_key_attst(sss_se05x_key_store_t *keyStore, sss_se05x_object_t *keyObject, uint8_t *key, size_t *keylen, size_t *pKeyBitLen, sss_se05x_object_t *keyObject_attst, sss_algorithm_t algorithm_attst, uint8_t *random_attst, size_t randomLen_attst, sss_se05x_attst_data_t *attst_data)

Read with attestation

struct sss_se05x_attst_comp_data_t
#include <fsl_sss_se05x_types.h>

Attestation data

Public Members

uint8_t attribute[MAX_POLICY_BUFFER_SIZE + 15]

Attributes

size_t attributeLen

Length of Attribute

uint8_t chipId[SE050_MODULE_UNIQUE_ID_LEN]

Uinquie ID of SE050

size_t chipIdLen

Lenght of the Unique ID

uint8_t outrandom[16]

Random used during attestation

size_t outrandomLen

length of outrandom

uint8_t signature[512]

Signature for attestation

size_t signatureLen

Length of signature

SE05x_TimeStamp_t timeStamp

time stamp

size_t timeStampLen

Length of timeStamp

struct sss_se05x_attst_data_t
#include <fsl_sss_se05x_types.h>

Data to be read with attestation

Public Members

sss_se05x_attst_comp_data_t data[SE05X_MAX_ATTST_DATA]

Whle reading RSA Objects, modulus and public exporent get attested separately,

uint8_t valid_number

How many entries to attest

3.3.10.15. SSS SE05x Other types and APIs

group se05x_other

Functions

sss_status_t sss_se05x_set_feature(sss_se05x_session_t *session, SE05x_Applet_Feature_t feature, SE05x_Applet_Feature_Disable_t disable_features)

Set features of the Applet.

See Se05x_API_SetAppletFeatures