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
-
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_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.
-
uint32_t
-
struct
sems_lite_agent_request_ctx_t Public Members
-
int
checkpoint_index
-
int
current_command_index
-
int
retry_count
-
int
-
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
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 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.
-
sss_status_t
