7.6. SEMSLite Types and APIs

7.6.1. SEMSLite Agent Types

group sems_lite_agent_types

SEMSLite Types to be used with SEMSLite APIs.

Typedefs

typedef sems_lite_SEAppInfoList_t sems_lite_PKGInfoList_t

Same as sems_lite_SEAppInfoList_t for for list of installed packages

Enums

enum _sems_lite_recovery_status_t

Values:

sems_lite_recovery_not_started = 0

Recovery Not Started

sems_lite_recovery_started = 1

Recovery Started

enum _sems_lite_status

Status of SEMS Lite update operation

Values:

kStatus_SEMS_Lite_Success = 0x00

Operation was successful

kStatus_SEMS_Lite_ERR_COM

Communication Error

kStatus_SEMS_Lite_ERR_DoReRun

Update not completed please provide update package again.

kStatus_SEMS_Lite_ERR_NotApplicable

Update not applicable on this Chip/type.

kStatus_SEMS_Lite_ERR_DoRecovery

Update can not be completed. Please provide recovery package, to roll back to last working version.

kStatus_SEMS_Lite_ERR_Fatal

Unresolvable error.

kStatus_SEMS_Lite_ERR_NotEnoughNVMemory

Not enough NV memory.

kStatus_SEMS_Lite_ERR_NotEnoughTransientMemory

Not enough transient memory.

kStatus_SEMS_Lite_ERR_MinPreviousVersion

Current SE version not meet min previous version request.

kStatus_SEMS_Lite_ERR_OlderVersion

Older than current SE version

kStatus_SEMS_Lite_ERR_General

General error.

enum _sems_lite_tearDown_status_t

Check Tear down Amd-I section 4.14

Values:

sems_lite_notear = 0

The script has been completely executed

sems_lite_tear = 1

Script execution was interrupted because of teardown.

sems_lite_tearDown_status_invalid = 0x7F
enum _sems_lite_upgradeProgress_status_t

Values:

sems_lite_upgrade_not_inProgress = 0

Upgrade session Not in Progress

sems_lite_upgrade_inProgress = 1

Upgrade session In Progress

sems_lite_upgrade_invalid = 0x7F
enum _sems_lite_version_check_result_t

Status of SEMS Lite version check result

Values:

kStatus_SEMS_Lite_Version_Pass = 0x00

Operation was successful

kStatus_SEMS_Lite_Version_ERR_MIN

Failed due to min previous version.

kStatus_SEMS_Lite_Version_ERR_Downgrade

Failed due to downgrade.

struct _sems_lite_available_mem_t

Public Members

uint32_t availableCODMemory
uint32_t availableCORMemory
uint32_t availableIDX
uint32_t availablePersistentMemory
uint32_t freePHeapCentralGap
uint32_t freeTransient
struct _sub_component_metaData_t

Public Members

size_t aidLen
uint8_t minimumPreviousVersion[2]
size_t nameLen
const uint8_t *pAid
char *pName
struct _sub_component_metaData_t *pNextSubComponentMetaData
uint8_t version[2]
struct multicast_package_t

Public Members

size_t multicastCommandsLen
size_t multicastPackageNameLen
uint8_t multicastPackageVersion[2]
const uint8_t *pMulticastCommands
const char *pMulticastPackageName
const uint8_t *pSignatureOverCommands
const sub_component_metaData_t *pSubComponentMetaData
uint32_t requiredFreeBytesNonVolatileMemory
uint32_t requiredFreeBytesTransientMemory
uint32_t semsLiteAPIVersion
size_t signatureOverCommandsLen
uint8_t target12Nc[6]
uint8_t targetEntityID[16]
struct sems_lite_agent_ctx_t

Public Members

uint32_t freePHeapCentralGap
uint32_t freeTransient
Se05xSession_t *pS05x_Ctx

Boot context

bool recovery_executed

Flag for get recovery script

bool session_opened

Flag for session status: Open/Close

bool skip_next_commands

Skip following commands

Internal state variable.

When one APDU in this APDU stream has failed, skip through all the next APDUs (do not send them) and return back to the caller.

uint32_t status_word

Status word of last R-APDU.

struct sems_lite_agent_request_ctx_t

Public Members

int checkpoint_index
int current_command_index
int retry_count
struct sems_lite_SEAppInfoList_t
#include <sems_lite_api.h>

Information of about Applet/Package

See Table 11-36: GlobalPlatform Registry Data (TLV), GPCardSpc_v2.2.pdf

The response from Applet is put to rspBuf

After parsing that response, the pointers to respective members is set and it points to relevant part in rspBuf, this way saving memory. However, the Length is updated so that application use this information.

Public Members

uint8_t AIDLen

Length of the Applet ID

uint8_t LifeCycleState

Life-cycle state

uint8_t LoadFileAIDLen

Length of LoadFileAID.

uint8_t LoadFileVersionNumberLen

Length of pLoadFileVersionNumber.

uint8_t *pAID

Applet ID

uint8_t *pLoadFileAID

Application’s Executable Load File AID.

uint8_t *pLoadFileVersionNumber

Executable Load File Version Number.

uint8_t *pPriviledges

Privileges.

uint8_t PriviledgesLen

Length of Privileges

uint8_t *pSecurityDomainAID

Associated Security Domain’s AID.

uint8_t rspBuf[(256 + 5)]

Response from Applet.

size_t rspBufLen

Length of response from Applet.

uint8_t SecurityDomainAIDLen

Length of SecurityDomainAID.

7.6.2. SEMSLite Agent APIs

group sems_lite_agent

API to load an available update package on the SE.

Functions

sss_status_t sems_lite_agent_init_context(sems_lite_agent_ctx_t *context, sss_session_t *boot_ctx)

Initialize SEMS Lite agent context.

This function is used to initialize SEMS Lite agent context.

Return

Status of the operation

Parameters
  • context: Pointer to sems lite agent context.

  • boot_ctx: Pointer to sss session context

Return Value
  • kStatus_SEMS_Lite_Success: The operation has completed successfully.

  • kStatus_SEMS_Lite_ERR_General: The operation has failed.

sems_lite_status_t sems_lite_agent_load_package(sems_lite_agent_ctx_t *context, multicast_package_t *multiPkgBuf)

Load Applet package.

This function load an available update package on the SE and assure the tearing safe update of the SE.

Return

Status of the operation

Note

More return codes would be added to request host to either retry or install older package.

Parameters
  • context: Pointer to sems lite agent context.

  • pkgBuf: Pointer to package. It must follow the format defined in multicast_package_t.

Return Value
  • kStatus_SEMS_Lite_Success: The operation has completed successfully.

  • kStatus_SEMS_Lite_ERR_COM: Communication to SE failed.

  • kStatus_SEMS_Lite_ERR_DoReRun: Update not completed please provide update package again.

  • kStatus_SEMS_Lite_ERR_NotApplicable: Update not applicable on this Chip/type.

  • kStatus_SEMS_Lite_ERR_DoRecovery: Update can not be completed. Please provide recovery package, to roll back to last working version.

  • kStatus_SEMS_Lite_ERR_Fatal: Unresolvable error. (This category of errors can only appear in testing of an update package, in the case of NXP updates this is testes before by NXP)

  • kStatus_SEMS_Lite_ERR_NotEnoughNVMemory: Don’t have has enough NV memory for the SEMS Lite Script.

  • kStatus_SEMS_Lite_ERR_NotEnoughTransientMemory: Don’t have enough transient memory for the SEMS Lite Script .

sss_status_t sems_lite_agent_session_close(sems_lite_agent_ctx_t *context)

Close the connection to SEMS Lite Applet.

Return

The api status.

Parameters
  • context: The context

Return Value
  • kStatus_SEMS_Lite_Success: Could close connection 1.

  • kStatus_SEMS_Lite_ERR_General: Could not close connection 1.

sss_status_t sems_lite_agent_session_open(sems_lite_agent_ctx_t *context)

Open a Physical connection to SEMS Lite Applet.

Calling this API opens Locical Connection 1 and selecs the SEMS Lite applet.

Return

The api status.

Parameters
  • context: SEMS Lite Agent Context

Return Value
  • kStatus_SEMS_Lite_Success: Could connect to SEMS Lite Applet.

  • kStatus_SEMS_Lite_ERR_General: Could not connect to SEMS Lite Applet.

sss_status_t sems_lite_check_AppletRecoveryStatus(sems_lite_agent_ctx_t *pContext, sems_lite_recovery_status_t *pRecoveryStatus)

Check Applet Recovery Status.

This API will return the status of applet recovery status

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pRecoveryStatus: Pointer to recovery status.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_check_AppletUpgradeProgress(sems_lite_agent_ctx_t *pContext, sems_lite_upgradeProgress_status_t *pUpgradeStatus)

Check Applet Upgrade Progress.

This API will return the status of applet upgrade progress status

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pUpgradeStatus: Pointer to upgrade status.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_check_Tear(sems_lite_agent_ctx_t *pContext, sems_lite_tearDown_status_t *pTearStatus)

Check Tear during script execution.

This API will check whether there was tear during script execution

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pTearStatus: Pointer to tear status.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_AgentVersion(uint8_t *pRspBuf, size_t *pRspBufLen)

Get the SEMS Lite Agent version.

This API will return the SEMS Lite Agent Version no.

Return

Status of the operation

Parameters
  • pRspBuf: Pointer to response Buffer.

  • pRspBufLen: Pointer to length of the response Buffer

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_AppletVersion(sems_lite_agent_ctx_t *pContext, uint8_t *pRspBuf, size_t *pRspBufLen)

Get the Applet version.

This API will return the SEMS Lite Applet Version no.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pRspBuf: Pointer to response Buffer.

  • pRspBufLen: Pointer to length of the response Buffer

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_available_mem(sems_lite_agent_ctx_t *pContext, uint8_t *pAvailableMem)

{ function_description }

Return

The sss status.

Parameters
  • context: The context

  • pAvailableMem: Availalbe Memory Space Information

sss_status_t sems_lite_get_CA_identifier(sems_lite_agent_ctx_t *pContext, uint8_t *pRspBuf, size_t *pRspBufLen)

Get the CA Identifier.

This API will return the CA Identifier.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pRspBuf: Pointer to response Buffer.

  • pRspBufLen: Pointer to length of the response Buffer

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_ENCIdentifier(sems_lite_agent_ctx_t *pContext, uint8_t *pRspBuf, size_t *pRspBufLen)

Get the ENC Identifier.

This API will return the ENC Identifier.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pRspBuf: Pointer to response Buffer.

  • pRspBufLen: Pointer to length of the response Buffer

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_FIPS_EC_parameter_type(sems_lite_agent_ctx_t *pContext, uint8_t *pParamType)

Get Configured EC domain parameter type.

This API will return Configured EC domain parameter type

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pParamType: Pointer to parameter type.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_FIPS_info(sems_lite_agent_ctx_t *pContext, uint8_t *pFIPSInfo)

Get Configured FIPS Information.

This API will return Configured FIPS Information

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pFIPSInfo: Pointer to FIPS Info.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_Publickey(sems_lite_agent_ctx_t *pContext, uint8_t *pRspBuf, size_t *pRspBufLen)

Read Public Key.

This API will read root certificates public key of the device.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pRspBuf: Pointer to response Buffer.

  • pRspBufLen: Pointer to length of the response Buffer.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_SEAppInfo(sems_lite_agent_ctx_t *pContext, const uint8_t *searchAID, uint8_t searchAidLen, sems_lite_SEAppInfoList_t *pAppInfo, size_t *pAppInfoLen)

Low level API to get App INFO from the SE according to format mentioned in - Table 11-36: GlobalPlatform Registry Data (TLV), GPCardSpc_v2.2.pdf.

This API will read the currently present Applications ELF/ELM AIDs and versions as well as the present instances from the SE.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • [in] searchAID: The search aid

  • [in] searchAidLen: The search aid length

  • pAppInfo: Parsed structures

  • [inout] pAppInfoLen: Length of parsed structures.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_SEAppInfoRAW(sems_lite_agent_ctx_t *pContext, const uint8_t *searchAID, uint8_t searchAidLen, uint8_t *pRspBuf, size_t *pRspBufLen)

Low level API to get Raw App INFO from the SE.

This API will read the currently present Applications ELF/ELM AIDs and versions as well as the present instances from the SE.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • [out] pRspBuf: Pointer to response Buffer.

  • [in] searchAID: The search aid

  • [in] searchAidLen: The search aid length

  • [inout] pRspBufLen: Pointer to length of the response Buffer.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_SEPkgInfo(sems_lite_agent_ctx_t *pContext, const uint8_t *searchAID, uint8_t searchAidLen, sems_lite_SEAppInfoList_t *pAppInfo, size_t *pAppInfoLen)

Low level API to get PKG INFO from the SE according to format mentioned in - Table 11-36: GlobalPlatform Registry Data (TLV), GPCardSpc_v2.2.pdf.

This API will read the currently present Applications ELF/ELM AIDs and versions as well as the present instances from the SE.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • [in] searchAID: The search aid

  • [in] searchAidLen: The search aid length

  • pAppInfo: Parsed structures

  • [inout] pAppInfoLen: Length of parsed structures.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_SEPkgInfoRAW(sems_lite_agent_ctx_t *pContext, const uint8_t *searchAID, uint8_t searchAidLen, uint8_t *pRspBuf, size_t *pRspBufLen)

Low level API to get RAW PKG INFO from the SE.

This API will read the currently present Applications ELF/ELM AIDs and versions as well as the present instances from the SE.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • [in] searchAID: The search aid

  • [in] searchAidLen: The search aid length

  • [out] pRspBuf: Pointer to response Buffer.

  • [inout] pRspBufLen: Pointer to length of the response Buffer.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_SignatureofLastScript(sems_lite_agent_ctx_t *pContext, uint8_t *pRspBuf, size_t *pRspBufLen)

Get the signature of last executed script.

This API will called in case there is tear down

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pRspBuf: Pointer to response Buffer.

  • pRspBufLen: Pointer to length of the response Buffer

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.

sss_status_t sems_lite_get_UUID(sems_lite_agent_ctx_t *pContext, uint8_t *pRspBuf, size_t *pRspBufLen)

Retrieve UUID from SE.

This API read UUID of the SE.

Return

Status of the operation

Parameters
  • pContext: Pointer to sems lite agent context.

  • pRspBuf: Pointer to response Buffer.

  • pRspBufLen: Pointer to length of the response Buffer.

Return Value
  • kStatus_SSS_Success: The operation has completed successfully.

  • kStatus_SSS_Fail: The operation has failed.