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
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 contextpAvailableMem
: 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 lengthpAppInfo
: 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 lengthpAppInfo
: 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.
-
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
-
uint32_t
-
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]
-
size_t
-
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]
-
size_t
-
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.
-
uint8_t
-
typedef sems_lite_SEAppInfoList_t