7.6. APIs

group sems_lite_agent

API to load an available update package on the SE.

Typedefs

typedef sems_lite_SEAppInfoList_t sems_lite_PKGInfoList_t

Same as sems_lite_SEAppInfoList_t for for list of installed packages

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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