11.12. SE05x MW Types and APIs¶
11.12.1. SE05x Types¶
-
group
se05x_types
SE05x Types.
Defines
-
DO_LOG_A
(TAG, DESCRIPTION, ARRAY, ARRAY_LEN)
-
DO_LOG_V
(TAG, DESCRIPTION, VALUE)
-
kSE05x_INS_I2CM_Attestation
When we want to read I2CM Data with attestation
-
kSE05x_INS_READ_With_Attestation
When we want to read with attestation
-
SE050_INS_MASK_INS_CHAR
3 MSBit for instruction characteristics.
-
SE050_INS_MASK_INSTRUCTION
5 LSBit for instruction
-
SE050_MAX_APDU_PAYLOAD_LENGTH
the maximum APDU payload length will be smaller, depending on which protocol applies, etc.
-
SE050_MAX_I2CM_COMMAND_LENGTH
How many bytes can be used for buffer for I2C Master interface
-
SE050_MAX_NUMBER_OF_SESSIONS
Maximum number of session supported by SE050
-
SE050_OBJECT_IDENTIFIER_SIZE
Maximum number of session supported by SE050
-
SE05x_CryptoObjectID_t
Crypto object identifiers
-
SE05x_KeyID_KEK_NONE
Case when there is no KEK
-
SE05x_KeyID_MFDF_NONE
[Optional: if the authentication key is the same as the key to be replaced, this TAG should not be present].
-
SE05x_MaxAttemps_NA
Identify in code that this is not an AUTH object and hence not applicable
-
SE05x_MaxAttemps_UNLIMITED
Fall back to applet default
-
TLVSET_AttestationAlgo
-
TLVSET_CipherMode
-
TLVSET_CryptoContext
-
TLVSET_CryptoModeSubType
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE)
-
TLVSET_CryptoObjectID
-
TLVSET_DigestMode
-
TLVSET_ECCurve
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE)
-
TLVSET_ECCurveParam
-
TLVSET_ECDAASignatureAlgo
-
TLVSET_ECSignatureAlgo
-
TLVSET_EDSignatureAlgo
-
TLVSET_KeyID
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE)
-
TLVSET_MacOperation
-
TLVSET_MaxAttemps
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE)
-
TLVSET_MemoryType
-
TLVSET_PlatformSCPRequest
-
TLVSET_RSAEncryptionAlgo
-
TLVSET_RSAKeyComponent
-
TLVSET_RSAPubKeyComp
-
TLVSET_RSASignatureAlgo
-
TLVSET_Se05xPolicy
(DESCRIPTION, PBUF, PBUFLEN, TAG, POLICY)
-
TLVSET_Se05xSession
(DESCRIPTION, PBUF, PBUFLEN, TAG, SESSIONID)
-
TLVSET_U16
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE)
-
TLVSET_U16Optional
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE)
-
TLVSET_U32
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE)
-
TLVSET_U64_SIZE
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE, SIZE)
-
TLVSET_U8
(DESCRIPTION, PBUF, PBUFLEN, TAG, VALUE)
-
TLVSET_u8buf
(DESCRIPTION, PBUF, PBUFLEN, TAG, CMD, CMDLEN)
-
TLVSET_u8buf_I2CM
(DESCRIPTION, PBUF, PBUFLEN, TAG, CMD, CMDLEN)
-
TLVSET_u8bufOptional
(DESCRIPTION, PBUF, PBUFLEN, TAG, CMD, CMDLEN)
-
TLVSET_u8bufOptional_ByteShift
(DESCRIPTION, PBUF, PBUFLEN, TAG, CMD, CMDLEN)
-
TLVSET_Variant
Typedefs
-
typedef Se05x_AppletFeatures_t *
pSe05xAppletFeatures_t
-
typedef Se05xPolicy_t *
pSe05xPolicy_t
-
typedef Se05xSession_t *
pSe05xSession_t
-
typedef uint32_t
SE05x_KeyID_t
SE05X’s key IDs
-
typedef SE05x_MACAlgo_t
SE05x_MacOperation_t
HMAC/CMAC Algorithms
-
typedef uint16_t
SE05x_MaxAttemps_t
SE05X key’s max attempts
-
typedef SE05x_SecObjTyp_t
SE05x_SecureObjectType_t
Type of Object
-
typedef SE05x_AppletConfig_t
SE05x_Variant_t
Features which are available / enabled in the Applet
Enums
-
enum
SE05x_AeadAlgo_t
AEAD Algorithms
Values:
-
kSE05x_AeadAlgo_NA
= 0 Invalid
-
kSE05x_AeadGCMAlgo
= 0xB0
-
kSE05x_AeadGCM_IVAlgo
= 0xF3
-
kSE05x_AeadCCMAlgo
= 0xF4
-
-
enum
SE05x_AppletConfig_t
Features which are available / enabled in the Applet
Values:
-
kSE05x_AppletConfig_NA
= 0 Invalid
-
kSE05x_AppletConfig_ECDAA
= 0x0001 Use of curve TPM_ECC_BN_P256
-
kSE05x_AppletConfig_ECDSA_ECDH_ECDHE
= 0x0002 EC DSA and DH support
-
kSE05x_AppletConfig_EDDSA
= 0x0004 Use of curve RESERVED_ID_ECC_ED_25519
Use of curve RESERVED_ID_ECC_MONT_DH_25519
-
kSE05x_AppletConfig_HMAC
= 0x0010 Writing HMACKey objects
-
kSE05x_AppletConfig_RSA_PLAIN
= 0x0020 Writing RSAKey objects
-
kSE05x_AppletConfig_RSA_CRT
= 0x0040 Writing RSAKey objects
Writing AESKey objects
-
kSE05x_AppletConfig_DES
= 0x0100 Writing DESKey objects
-
kSE05x_AppletConfig_PBKDF
= 0x0200 PBKDF2
-
kSE05x_AppletConfig_TLS
= 0x0400 TLS Handshake support commands (see 4.16) in APDU Spec
Mifare DESFire support (see 4.15) in APDU Spec
-
kSE05x_AppletConfig_RFU1
= 0x1000 RFU1
-
kSE05x_AppletConfig_I2CM
= 0x2000 I2C Master support (see 4.17) in APDU Spec
-
kSE05x_AppletConfig_RFU2
= 0x4000 RFU2
-
-
enum
SE05x_AppletResID_t
Reserved idendntifiers of the Applet
Values:
-
kSE05x_AppletResID_NA
= 0 Invalid
-
kSE05x_AppletResID_TRANSPORT
= 0x7FFF0200 An authentication object which allows the user to switch LockState of the applet. The LockState defines whether the applet is transport locked or not.
-
kSE05x_AppletResID_KP_ECKEY_USER
= 0x7FFF0201 A device unique NIST P-256 key pair which contains SK.SE.ECKA and PK.SE.ECKA in ECKey session context.
-
kSE05x_AppletResID_KP_ECKEY_IMPORT
= 0x7FFF0202 A device unique NIST P-256 key pair which contains SK.SE.ECKA and PK.SE.ECKA in ECKey session context; A constant card challenge (all zeroes) is applicable.
-
kSE05x_AppletResID_FEATURE
= 0x7FFF0204 An authentication object which allows the user to change the applet variant.
-
kSE05x_AppletResID_FACTORY_RESET
= 0x7FFF0205 An authentication object which allows the user to delete all objects, except trust provisioned by NXP objects.
-
kSE05x_AppletResID_UNIQUE_ID
= 0x7FFF0206 A BinaryFile Secure Object which holds the device unique ID. This file cannot be overwritten or deleted.
-
kSE05x_AppletResID_PLATFORM_SCP
= 0x7FFF0207 An authentication object which allows the user to change the platform SCP requirements, i.e. make platform SCP mandatory or not, using SetPlatformSCPRequest. Mandatory means full security, i.e. command & response MAC and encryption. Only SCP03 will be sufficient.
An authentication object which grants access to the I2C master feature. If the credential is not present, access to I2C master is allowed in general. Otherwise, a session using this credential shall be established and I2CM commands shall be sent within this session.
-
kSE05x_AppletResID_RESTRICT
= 0x7FFF020A An authentication object which grants access to the SetLockState command
-
kSE05x_AppletResID_SPAKE2P_M_P256_UNCOMPRESSED
= 0x7FFF0210 SPAKE2P_M_P256_UNCOMPRESSED KEY
-
kSE05x_AppletResID_SPAKE2P_N_P256_UNCOMPRESSED
= 0x7FFF0211 SPAKE2P_N_P256_UNCOMPRESSED KEY
-
kSE05x_AppletResID_SPAKE2P_M_P384_UNCOMPRESSED
= 0x7FFF0212 SPAKE2P_M_P384_UNCOMPRESSED KEY
-
kSE05x_AppletResID_SPAKE2P_N_P384_UNCOMPRESSED
= 0x7FFF0213 SPAKE2P_N_P384_UNCOMPRESSED KEY
-
kSE05x_AppletResID_SPAKE2P_M_P521_UNCOMPRESSED
= 0x7FFF0214 SPAKE2P_M_P521_UNCOMPRESSED KEY
-
kSE05x_AppletResID_SPAKE2P_N_P521_UNCOMPRESSED
= 0x7FFF0215 SPAKE2P_N_P521_UNCOMPRESSED KEY
-
-
enum
SE05x_AttestationAlgo_t
Attestation
Values:
-
kSE05x_AttestationAlgo_NA
= 0
-
kSE05x_AttestationAlgo_EC_PLAIN
= kSE05x_ECSignatureAlgo_PLAIN
-
kSE05x_AttestationAlgo_EC_SHA
= kSE05x_ECSignatureAlgo_SHA
-
kSE05x_AttestationAlgo_EC_SHA_224
= kSE05x_ECSignatureAlgo_SHA_224
-
kSE05x_AttestationAlgo_EC_SHA_256
= kSE05x_ECSignatureAlgo_SHA_256
-
kSE05x_AttestationAlgo_EC_SHA_384
= kSE05x_ECSignatureAlgo_SHA_384
-
kSE05x_AttestationAlgo_EC_SHA_512
= kSE05x_ECSignatureAlgo_SHA_512
-
kSE05x_AttestationAlgo_ED25519PURE_SHA_512
= kSE05x_EDSignatureAlgo_ED25519PURE_SHA_512
-
kSE05x_AttestationAlgo_ECDAA
= kSE05x_ECDAASignatureAlgo_ECDAA
-
kSE05x_AttestationAlgo_RSA_SHA1_PKCS1_PSS
= kSE05x_RSASignatureAlgo_SHA1_PKCS1_PSS
-
kSE05x_AttestationAlgo_RSA_SHA224_PKCS1_PSS
= kSE05x_RSASignatureAlgo_SHA224_PKCS1_PSS
-
kSE05x_AttestationAlgo_RSA_SHA256_PKCS1_PSS
= kSE05x_RSASignatureAlgo_SHA256_PKCS1_PSS
-
kSE05x_AttestationAlgo_RSA_SHA384_PKCS1_PSS
= kSE05x_RSASignatureAlgo_SHA384_PKCS1_PSS
-
kSE05x_AttestationAlgo_RSA_SHA512_PKCS1_PSS
= kSE05x_RSASignatureAlgo_SHA512_PKCS1_PSS
-
kSE05x_AttestationAlgo_RSA_SHA_224_PKCS1
= kSE05x_RSASignatureAlgo_SHA_224_PKCS1
-
kSE05x_AttestationAlgo_RSA_SHA_256_PKCS1
= kSE05x_RSASignatureAlgo_SHA_256_PKCS1
-
kSE05x_AttestationAlgo_RSA_SHA_384_PKCS1
= kSE05x_RSASignatureAlgo_SHA_384_PKCS1
-
kSE05x_AttestationAlgo_RSA_SHA_512_PKCS1
= kSE05x_RSASignatureAlgo_SHA_512_PKCS1
-
-
enum
SE05x_AttestationType_t
In case the read is attested
Values:
-
kSE05x_AttestationType_None
= 0
-
kSE05x_AttestationType_AUTH
= kSE05x_INS_AUTH_OBJECT
-
-
enum
SE05x_Cipher_Oper_OneShot_t
One Shot operations helper
Values:
-
kSE05x_Cipher_Oper_OneShot_NA
= 0
-
kSE05x_Cipher_Oper_OneShot_Encrypt
= kSE05x_P2_ENCRYPT_ONESHOT
-
kSE05x_Cipher_Oper_OneShot_Decrypt
= kSE05x_P2_DECRYPT_ONESHOT
-
-
enum
SE05x_Cipher_Oper_t
Cipher Operation.
Encrypt or decrypt
Values:
-
kSE05x_Cipher_Oper_NA
= 0
-
kSE05x_Cipher_Oper_Encrypt
= kSE05x_P2_ENCRYPT
-
kSE05x_Cipher_Oper_Decrypt
= kSE05x_P2_DECRYPT
-
-
enum
SE05x_CipherMode_t
Symmetric cipher modes
Values:
-
kSE05x_CipherMode_NA
= 0 Invalid
-
kSE05x_CipherMode_DES_CBC_NOPAD
= 0x01 Typically using DESKey identifiers
-
kSE05x_CipherMode_DES_CBC_ISO9797_M1
= 0x02 Typically using DESKey identifiers
-
kSE05x_CipherMode_DES_CBC_ISO9797_M2
= 0x03 Typically using DESKey identifiers
-
kSE05x_CipherMode_DES_CBC_PKCS5
= 0x04 NOT SUPPORTED
-
kSE05x_CipherMode_DES_ECB_NOPAD
= 0x05 Typically using DESKey identifiers
-
kSE05x_CipherMode_DES_ECB_ISO9797_M1
= 0x06 NOT SUPPORTED
-
kSE05x_CipherMode_DES_ECB_ISO9797_M2
= 0x07 NOT SUPPORTED
NOT SUPPORTED
-
kSE05x_CipherMode_AES_ECB_NOPAD
= 0x0E Typically using AESKey identifiers
-
kSE05x_CipherMode_AES_CBC_NOPAD
= 0x0D Typically using AESKey identifiers
-
kSE05x_CipherMode_AES_CBC_ISO9797_M1
= 0x16 Typically using AESKey identifiers
-
kSE05x_CipherMode_AES_CBC_ISO9797_M2
= 0x17 Typically using AESKey identifiers
NOT SUPPORTED
-
kSE05x_CipherMode_AES_GCM
= 0xB0 Typically using AEAD GCM mode
-
kSE05x_CipherMode_AES_CTR
= 0xF0 Typically using AESKey identifiers
-
kSE05x_CipherMode_AES_CTR_INT_IV
= 0xF1 Typically using AESKey CTR mode with internal IV Gen Only used by MW. Change to kSE05x_CipherMode_AES_CTR when sending to SE
-
kSE05x_CipherMode_AES_GCM_INT_IV
= 0xF3 Typically using AEAD GCM with internal IV Gen
-
kSE05x_CipherMode_AES_CCM
= 0xF4 Typically using AEAD CCM mode
-
kSE05x_CipherMode_AES_CCM_INT_IV
= 0xF5 Typically using AEAD CCM with internal IV Gen
-
-
enum
SE05x_CryptoContext_t
Cryptographic context for operation
Values:
-
kSE05x_CryptoContext_NA
= 0 Invalid
-
kSE05x_CryptoContext_DIGEST
= 0x01 For DigestInit/DigestUpdate/DigestFinal
-
kSE05x_CryptoContext_CIPHER
= 0x02 For CipherInit/CipherUpdate/CipherFinal
-
kSE05x_CryptoContext_SIGNATURE
= 0x03 For MACInit/MACUpdate/MACFinal
-
kSE05x_CryptoContext_AEAD
= 0x04 For AEADInit/AEADUpdate/AEADFinal
-
kSE05x_CryptoContext_PAKE
= 0x05 For PAKE
-
-
enum
SE05x_CryptoObject_t
Crypto object identifiers
Values:
-
kSE05x_CryptoObject_NA
= 0 Invalid
-
kSE05x_CryptoObject_DIGEST_SHA
-
kSE05x_CryptoObject_DIGEST_SHA224
-
kSE05x_CryptoObject_DIGEST_SHA256
-
kSE05x_CryptoObject_DIGEST_SHA384
-
kSE05x_CryptoObject_DIGEST_SHA512
-
kSE05x_CryptoObject_DES_CBC_NOPAD
-
kSE05x_CryptoObject_DES_CBC_ISO9797_M1
-
kSE05x_CryptoObject_DES_CBC_ISO9797_M2
-
kSE05x_CryptoObject_DES_CBC_PKCS5
-
kSE05x_CryptoObject_DES_ECB_NOPAD
-
kSE05x_CryptoObject_DES_ECB_ISO9797_M1
-
kSE05x_CryptoObject_DES_ECB_ISO9797_M2
-
kSE05x_CryptoObject_DES_ECB_PKCS5
-
kSE05x_CryptoObject_AES_ECB_NOPAD
-
kSE05x_CryptoObject_AES_CBC_NOPAD
-
kSE05x_CryptoObject_AES_CBC_ISO9797_M1
-
kSE05x_CryptoObject_AES_CBC_ISO9797_M2
-
kSE05x_CryptoObject_AES_CBC_PKCS5
-
kSE05x_CryptoObject_AES_CTR
-
kSE05x_CryptoObject_AES_CTR_INT_IV
-
kSE05x_CryptoObject_HMAC_SHA1
-
kSE05x_CryptoObject_HMAC_SHA256
-
kSE05x_CryptoObject_HMAC_SHA384
-
kSE05x_CryptoObject_HMAC_SHA512
-
kSE05x_CryptoObject_CMAC_128
-
kSE05x_CryptoObject_AES_GCM
-
kSE05x_CryptoObject_AES_GCM_INT_IV
-
kSE05x_CryptoObject_AES_CCM
-
kSE05x_CryptoObject_AES_CCM_INT_IV
-
kSE05x_CryptoObject_PAKE_TYPE_A
-
kSE05x_CryptoObject_PAKE_TYPE_B
-
kSE05x_CryptoObject_End
-
-
enum
SE05x_DigestMode_t
Hashing/Digest algorithms
Values:
-
kSE05x_DigestMode_NA
= 0 Invalid
-
kSE05x_DigestMode_NO_HASH
= 0x00
-
kSE05x_DigestMode_SHA
= 0x01
-
kSE05x_DigestMode_SHA224
= 0x07 Not supported
-
kSE05x_DigestMode_SHA256
= 0x04
-
kSE05x_DigestMode_SHA384
= 0x05
-
kSE05x_DigestMode_SHA512
= 0x06
-
-
enum
SE05x_ECCurve_t
ECC Curve Identifiers
Values:
-
kSE05x_ECCurve_NA
= 0x00 Invalid
-
kSE05x_ECCurve_NIST_P192
= 0x01
-
kSE05x_ECCurve_NIST_P224
= 0x02
-
kSE05x_ECCurve_NIST_P256
= 0x03
-
kSE05x_ECCurve_NIST_P384
= 0x04
-
kSE05x_ECCurve_NIST_P521
= 0x05
-
kSE05x_ECCurve_Brainpool160
= 0x06
-
kSE05x_ECCurve_Brainpool192
= 0x07
-
kSE05x_ECCurve_Brainpool320
= 0x0A
-
kSE05x_ECCurve_Brainpool384
= 0x0B
-
kSE05x_ECCurve_Brainpool512
= 0x0C
-
kSE05x_ECCurve_Secp160k1
= 0x0D
-
kSE05x_ECCurve_Secp192k1
= 0x0E
-
kSE05x_ECCurve_Secp224k1
= 0x0F
-
kSE05x_ECCurve_Secp256k1
= 0x10
-
kSE05x_ECCurve_TPM_ECC_BN_P256
= 0x11
-
kSE05x_ECCurve_ECC_ED_25519
= 0x40 Not Weierstrass
-
kSE05x_ECCurve_ECC_MONT_DH_25519
= 0x41
-
kSE05x_ECCurve_ECC_MONT_DH_448
= 0x43 Not Weierstrass
-
-
enum
SE05x_ECCurveParam_t
Parameters while setting the curve
Values:
-
kSE05x_ECCurveParam_NA
= 0 Invalid
-
kSE05x_ECCurveParam_PARAM_A
= 0x01
-
kSE05x_ECCurveParam_PARAM_B
= 0x02
-
kSE05x_ECCurveParam_PARAM_G
= 0x04
-
kSE05x_ECCurveParam_PARAM_PRIME
= 0x10
-
-
enum
SE05x_ECDAASignatureAlgo_t
Different signature algorithms for ECDAA
Values:
-
kSE05x_ECDAASignatureAlgo_NA
= 0 Invalid
-
kSE05x_ECDAASignatureAlgo_ECDAA
= 0xF4 Message input must be pre-hashed (using SHA256)
-
-
enum
SE05x_ECDHAlgo_t
Different ECDH algorithms
Values:
-
kSE05x_ECDHAlgo_NA
= 0 Invalid
-
kSE05x_ECDHAlgo_EC_SVDP_DH
= 0x01 Generates the SHA1 of the X coordinate.
-
kSE05x_ECDHAlgo_EC_SVDP_DH_PLAIN
= 0x03 Generates the X coordinate.
-
-
enum
SE05x_ECPMAlgo_t
ECPMAlgo
Values:
-
kSE05x_ECPMAlgo_PACE_GM
= 0x05
-
kSE05x_ECPMAlgo_SVDP_DH_PLAIN_XY
= 0x06
-
-
enum
SE05x_ECSignatureAlgo_t
Different signature algorithms for EC
Values:
-
kSE05x_ECSignatureAlgo_NA
= 0 Invalid
NOT SUPPORTED
-
kSE05x_ECSignatureAlgo_SHA
= 0x11
-
kSE05x_ECSignatureAlgo_SHA_224
= 0x25
-
kSE05x_ECSignatureAlgo_SHA_256
= 0x21
-
kSE05x_ECSignatureAlgo_SHA_384
= 0x22
-
kSE05x_ECSignatureAlgo_SHA_512
= 0x26
-
-
enum
SE05x_EDSignatureAlgo_t
Different signature algorithms for ED
Values:
-
kSE05x_EDSignatureAlgo_NA
= 0 Invalid
-
kSE05x_EDSignatureAlgo_ED25519PURE_SHA_512
= 0xA3 Message input must be plain Data. Pure EDDSA algorithm
-
-
enum
SE05x_HealthCheckMode_t
Health check
Values:
-
kSE05x_HealthCheckMode_NA
= 0 Invalid
Performs all on-demand self-tests. Can only be done when the module is in FIPS mode. When the test fails, the chip goes into TERMINATED state.
-
kSE05x_HealthCheckMode_CODE_SIGNATURE
= 0xFE01 Performs ROM integrity checks. When the test fails, the chip triggers the attack counter and the chip will reset.
-
kSE05x_HealthCheckMode_DYNAMIC_FLASH_INTEGRITY
= 0xFD02 Performs flash integrity tests. When the test fails, the chip triggers the attack counter and the chip will reset.
-
kSE05x_HealthCheckMode_SHIELDING
= 0xFC03 Performs tests on the active shield protection of the hardware. When the test fails, the chip triggers the attack counter and the chip will reset.
-
kSE05x_HealthCheckMode_SENSOR
= 0xFB04 Performs self-tests on hardware sensors and reports the status.
-
kSE05x_HealthCheckMode_SFR_CHECK
= 0xFA05 Performs self-tests on the hardware registers. When the test fails, the chip triggers the attack counter and the chip will reset.
-
-
enum
SE05x_HkdfMode_t
HKDF Mode
Values:
-
kSE05x_HkdfMode_NA
= 0x00 Invalid
-
kSE05x_HkdfMode_ExtractExpand
= 0x01
-
kSE05x_HkdfMode_ExpandOnly
= 0x02
-
-
enum
SE05x_INS_t
Values for INS in ISO7816 APDU
Values:
-
kSE05x_INS_NA
= 0 Invalid
-
kSE05x_INS_MASK_INS_CHAR
= 0xE0 3 MSBit for instruction characteristics.
-
kSE05x_INS_MASK_INSTRUCTION
= 0x1F 5 LSBit for instruction
Mask for transient object creation, can only be combined with INS_WRITE.
-
kSE05x_INS_AUTH_OBJECT
= 0x40 Mask for authentication object creation, can only be combined with INS_WRITE
-
kSE05x_INS_ATTEST
= 0x20 Mask for getting attestation data.
-
kSE05x_INS_WRITE
= 0x01 Write or create a persistent object.
-
kSE05x_INS_READ
= 0x02 Read the object
-
kSE05x_INS_CRYPTO
= 0x03 Perform Security Operation
-
kSE05x_INS_MGMT
= 0x04 General operation
-
kSE05x_INS_PROCESS
= 0x05 Process session command
-
-
enum
SE05x_KeyPart_t
Part of the asymmetric key
Values:
-
kSE05x_KeyPart_NA
= kSE05x_P1_DEFAULT
-
kSE05x_KeyPart_Pair
= kSE05x_P1_KEY_PAIR Key pair (private key + public key)
-
kSE05x_KeyPart_Private
= kSE05x_P1_PRIVATE Private key
-
kSE05x_KeyPart_Public
= kSE05x_P1_PUBLIC Public key
-
-
enum
SE05x_LockIndicator_t
Transient / Persistent lock
Values:
-
kSE05x_LockIndicator_NA
= 0 Invalid
-
kSE05x_LockIndicator_TRANSIENT_LOCK
= 0x01
-
kSE05x_LockIndicator_PERSISTENT_LOCK
= 0x02
-
-
enum
SE05x_LockState_t
Lock the sample (until unlocked )
Values:
-
kSE05x_LockState_NA
= 0 Invalid
-
kSE05x_LockState_LOCKED
= 0x01
-
-
enum
SE05x_Mac_Oper_t
MAC operations
Values:
-
kSE05x_Mac_Oper_NA
= 0
-
kSE05x_Mac_Oper_Generate
= kSE05x_P2_GENERATE
-
kSE05x_Mac_Oper_Validate
= kSE05x_P2_VALIDATE
-
-
enum
SE05x_MACAlgo_t
HMAC/CMAC Algorithms
Values:
-
kSE05x_MACAlgo_NA
= 0 Invalid
-
kSE05x_MACAlgo_HMAC_SHA384
= 0x1A
-
kSE05x_MACAlgo_HMAC_SHA512
= 0x1B
-
kSE05x_MACAlgo_CMAC_128
= 0x31
-
kSE05x_MACAlgo_DES_CMAC8
= 0x7A
-
-
enum
SE05x_MemoryType_t
Data for available memory
Values:
-
kSE05x_MemoryType_NA
= 0 Invalid
-
kSE05x_MemoryType_PERSISTENT
= 0x01 Persistent memory
-
kSE05x_MemoryType_TRANSIENT_RESET
= 0x02 Transient memory, clear on reset
-
kSE05x_MemoryType_TRANSIENT_DESELECT
= 0x03 Transient memory, clear on deselect
-
-
enum
SE05x_MoreIndicator_t
When there are more entries yet to be fetched from few of the APIs
Values:
-
kSE05x_MoreIndicator_NA
= 0 Invalid
-
kSE05x_MoreIndicator_NO_MORE
= 0x01 No more data available
-
kSE05x_MoreIndicator_MORE
= 0x02 More data available
-
-
enum
SE05x_Origin_t
Where was this object originated
Values:
-
kSE05x_Origin_NA
= 0 Invalid
-
kSE05x_Origin_EXTERNAL
= 0x01 Generated outside the module.
-
kSE05x_Origin_INTERNAL
= 0x02 Generated inside the module.
-
kSE05x_Origin_PROVISIONED
= 0x03 Trust provisioned by NXP
-
-
enum
SE05x_P1_t
Values for P1 in ISO7816 APDU
Values:
-
kSE05x_P1_NA
= 0 Invalid
Highest bit not used
-
kSE05x_P1_MASK_KEY_TYPE
= 0x60 2 MSBit for key type
-
kSE05x_P1_MASK_CRED_TYPE
= 0x1F 5 LSBit for credential type
-
kSE05x_P1_KEY_PAIR
= 0x60 Key pair (private key + public key)
-
kSE05x_P1_PRIVATE
= 0x40 Private key
-
kSE05x_P1_PUBLIC
= 0x20 Public key
-
kSE05x_P1_DEFAULT
= 0x00
-
kSE05x_P1_EC
= 0x01
-
kSE05x_P1_RSA
= 0x02
-
kSE05x_P1_AES
= 0x03
-
kSE05x_P1_DES
= 0x04
-
kSE05x_P1_HMAC
= 0x05
-
kSE05x_P1_BINARY
= 0x06
-
kSE05x_P1_UserID
= 0x07
-
kSE05x_P1_CURVE
= 0x0B
-
kSE05x_P1_SIGNATURE
= 0x0C
-
kSE05x_P1_MAC
= 0x0D
-
kSE05x_P1_CIPHER
= 0x0E
-
kSE05x_P1_TLS
= 0x0F
-
kSE05x_P1_CRYPTO_OBJ
= 0x10
-
kSE05x_P1_AEAD
= 0x11 Applet >= 4.4
-
kSE05x_P1_AEAD_SP800_38D
= 0x12 Applet >= 4.4
-
kSE05x_P1_PAKE
= 0x12
-
-
enum
SE05x_P2_t
Values for P2 in ISO7816 APDU
Values:
-
kSE05x_P2_DEFAULT
= 0x00 Invalid
-
kSE05x_P2_GENERATE
= 0x03
-
kSE05x_P2_CREATE
= 0x04
-
kSE05x_P2_SIZE
= 0x07
-
kSE05x_P2_VERIFY
= 0x0A
-
kSE05x_P2_INIT
= 0x0B
-
kSE05x_P2_UPDATE
= 0x0C
-
kSE05x_P2_FINAL
= 0x0D
-
kSE05x_P2_ONESHOT
= 0x0E
-
kSE05x_P2_DH
= 0x0F
-
kSE05x_P2_DIVERSIFY
= 0x10
-
kSE05x_P2_AUTH_FIRST_PART2
= 0x12
-
kSE05x_P2_AUTH_NONFIRST_PART2
= 0x13
-
kSE05x_P2_DUMP_KEY
= 0x14
-
kSE05x_P2_CHANGE_KEY_PART1
= 0x15
-
kSE05x_P2_CHANGE_KEY_PART2
= 0x16
-
kSE05x_P2_KILL_AUTH
= 0x17
-
kSE05x_P2_SESSION_CREATE
= 0x1B
-
kSE05x_P2_SESSION_CLOSE
= 0x1C
-
kSE05x_P2_SESSION_REFRESH
= 0x1E
-
kSE05x_P2_SESSION_POLICY
= 0x1F
-
kSE05x_P2_VERSION
= 0x20
-
kSE05x_P2_VERSION_EXT
= 0x21
-
kSE05x_P2_MEMORY
= 0x22
-
kSE05x_P2_LIST
= 0x25
-
kSE05x_P2_TYPE
= 0x26
-
kSE05x_P2_EXIST
= 0x27
-
kSE05x_P2_DELETE_ALL
= 0x2A
-
kSE05x_P2_SESSION_UserID
= 0x2C
-
kSE05x_P2_HKDF
= 0x2D
-
kSE05x_P2_PBKDF
= 0x2E
-
kSE05x_P2_HKDF_EXPAND_ONLY
= 0x2F
-
kSE05x_P2_I2CM
= 0x30
-
kSE05x_P2_I2CM_ATTESTED
= 0x31
-
kSE05x_P2_MAC
= 0x32
-
kSE05x_P2_UNLOCK_CHALLENGE
= 0x33
-
kSE05x_P2_CURVE_LIST
= 0x34
-
kSE05x_P2_SIGN_ECDAA
= 0x35
-
kSE05x_P2_ID
= 0x36
-
kSE05x_P2_ENCRYPT_ONESHOT
= 0x37
-
kSE05x_P2_ATTEST
= 0x3A
-
kSE05x_P2_ATTRIBUTES
= 0x3B
-
kSE05x_P2_CPLC
= 0x3C
-
kSE05x_P2_TIME
= 0x3D
-
kSE05x_P2_TRANSPORT
= 0x3E
-
kSE05x_P2_VARIANT
= 0x3F
-
kSE05x_P2_PARAM
= 0x40
-
kSE05x_P2_DELETE_CURVE
= 0x41
-
kSE05x_P2_ENCRYPT
= 0x42
-
kSE05x_P2_DECRYPT
= 0x43
-
kSE05x_P2_VALIDATE
= 0x44
-
kSE05x_P2_GENERATE_ONESHOT
= 0x45
-
kSE05x_P2_VALIDATE_ONESHOT
= 0x46
-
kSE05x_P2_CRYPTO_LIST
= 0x47
-
kSE05x_P2_TLS_PMS
= 0x4A
-
kSE05x_P2_TLS_PRF_CLI_HELLO
= 0x4B
-
kSE05x_P2_TLS_PRF_SRV_HELLO
= 0x4C
-
kSE05x_P2_TLS_PRF_CLI_RND
= 0x4D
-
kSE05x_P2_TLS_PRF_SRV_RND
= 0x4E
-
kSE05x_P2_TLS_PRF_BOTH
= 0x5A
-
kSE05x_P2_RAW
= 0x4F
-
kSE05x_P2_IMPORT_EXT
= 0x51
-
kSE05x_P2_SCP
= 0x52
-
kSE05x_P2_AUTH_FIRST_PART1
= 0x53
-
kSE05x_P2_AUTH_NONFIRST_PART1
= 0x54
-
kSE05x_P2_CM_COMMAND
= 0x55
-
kSE05x_P2_MODE_OF_OPERATION
= 0x56
-
kSE05x_P2_RESTRICT
= 0x57
-
kSE05x_P2_READ_STATE
= 0x5B
-
-
enum
SE05x_PAKEMode_t
PAKE Mode
Values:
-
kSE05x_SPAKE2PLUS_NA
= 0 Invalid
-
kSE05x_SPAKE2PLUS_P256_SHA256_HKDF_HMAC
= 0x01
-
kSE05x_SPAKE2PLUS_P256_SHA512_HKDF_HMAC
= 0x02
-
kSE05x_SPAKE2PLUS_P384_SHA256_HKDF_HMAC
= 0x03
-
kSE05x_SPAKE2PLUS_P384_SHA512_HKDF_HMAC
= 0x04
-
kSE05x_SPAKE2PLUS_P521_SHA512_HKDF_HMAC
= 0x05
-
-
enum
SE05x_PAKEState_t
PAKE State
Values:
-
kSE05x_PAKE_STATE_SETUP
= 0
-
kSE05x_PAKE_STATE_KEY_SHARE_GENERATED
= 0xA5
-
kSE05x_PAKE_STATE_SESSION_KEYS_GENERATED
= 0x5A
-
-
enum
SE05x_PlatformSCPRequest_t
Mandate platform SCP or not
Values:
-
kSE05x_PlatformSCPRequest_NA
= 0 Invalid
-
kSE05x_PlatformSCPRequest_REQUIRED
= 0x01 Platform SCP is required (full enc & MAC)
-
kSE05x_PlatformSCPRequest_NOT_REQUIRED
= 0x02 No platform SCP required.
-
-
enum
SE05x_RestrictMode_t
Applet >= 4.4
See Se05x_API_DisableObjCreation
Values:
-
kSE05x_RestrictMode_NA
= 0
-
kSE05x_RestrictMode_RESTRICT_NEW
= 0x01
-
kSE05x_RestrictMode_RESTRICT_ALL
= 0x02
-
-
enum
SE05x_Result_t
Result of operations
Values:
-
kSE05x_Result_NA
= 0 Invalid
-
kSE05x_Result_SUCCESS
= 0x01
-
kSE05x_Result_FAILURE
= 0x02
-
-
enum
SE05x_RSABitLength_t
Size of RSA Key Objects
Values:
-
kSE05x_RSABitLength_NA
= 0 Invalid
-
kSE05x_RSABitLength_512
= 512
-
kSE05x_RSABitLength_1024
= 1024
-
kSE05x_RSABitLength_1152
= 1152
-
kSE05x_RSABitLength_2048
= 2048
-
kSE05x_RSABitLength_3072
= 3072
-
kSE05x_RSABitLength_4096
= 4096
-
-
enum
SE05x_RSAEncryptionAlgo_t
Different encryption/decryption algorithms for RSA
Values:
-
kSE05x_RSAEncryptionAlgo_NA
= 0 Invalid
-
kSE05x_RSAEncryptionAlgo_NO_PAD
= 0x0C Plain RSA, padding required on host.
-
kSE05x_RSAEncryptionAlgo_PKCS1
= 0x0A RFC8017: RSAES-PKCS1-v1_5
-
kSE05x_RSAEncryptionAlgo_PKCS1_OAEP
= 0x0F RFC8017: RSAES-OAEP
-
-
enum
SE05x_RSAKeyComponent_t
Part of the RSA Key Objects
Values:
-
kSE05x_RSAKeyComponent_NA
= 0xFF Invalid
-
kSE05x_RSAKeyComponent_MOD
= 0x00 Modulus
-
kSE05x_RSAKeyComponent_PUB_EXP
= 0x01 Public key exponent
-
kSE05x_RSAKeyComponent_PRIV_EXP
= 0x02 Private key exponent
-
kSE05x_RSAKeyComponent_P
= 0x03 CRT component p
-
kSE05x_RSAKeyComponent_Q
= 0x04 CRT component q
-
kSE05x_RSAKeyComponent_DP
= 0x05 CRT component dp
-
kSE05x_RSAKeyComponent_DQ
= 0x06 CRT component dq
-
kSE05x_RSAKeyComponent_INVQ
= 0x07 CRT component q_inv
-
-
enum
SE05x_RSAKeyFormat_t
RSA Key format
Values:
-
kSE05x_RSAKeyFormat_CRT
= kSE05x_P2_DEFAULT
-
kSE05x_RSAKeyFormat_RAW
= kSE05x_P2_RAW
-
-
enum
SE05x_RSAPubKeyComp_t
Public part of RSA Keys
Values:
-
kSE05x_RSAPubKeyComp_NA
= 0
-
kSE05x_RSAPubKeyComp_MOD
= kSE05x_RSAKeyComponent_MOD
-
kSE05x_RSAPubKeyComp_PUB_EXP
= kSE05x_RSAKeyComponent_PUB_EXP
-
-
enum
SE05x_RSASignAlgo_t
Algorithms for RSA Signature
Values:
-
kSE05x_RSASignAlgo_NA
= 0 Invalid
-
kSE05x_RSASignAlgo_SHA1_PKCS1_PSS
= 0x15 RFC8017: RSASSA-PSS
-
kSE05x_RSASignAlgo_SHA224_PKCS1_PSS
= 0x2B RFC8017: RSASSA-PSS
-
kSE05x_RSASignAlgo_SHA256_PKCS1_PSS
= 0x2C RFC8017: RSASSA-PSS
-
kSE05x_RSASignAlgo_SHA384_PKCS1_PSS
= 0x2D RFC8017: RSASSA-PSS
-
kSE05x_RSASignAlgo_SHA512_PKCS1_PSS
= 0x2E RFC8017: RSASSA-PSS
-
kSE05x_RSASignAlgo_SHA_224_PKCS1
= 0x27 RFC8017: RSASSA-PKCS1-v1_5
RFC8017: RSASSA-PKCS1-v1_5
RFC8017: RSASSA-PKCS1-v1_5
-
kSE05x_RSASignAlgo_SHA_512_PKCS1
= 0x2A RFC8017: RSASSA-PKCS1-v1_5
-
-
enum
SE05x_RSASignatureAlgo_t
Different signature algorithms for RSA
Values:
-
kSE05x_RSASignatureAlgo_NA
= 0 Invalid
-
kSE05x_RSASignatureAlgo_SHA1_PKCS1_PSS
= 0x15 RFC8017: RSASSA-PSS
-
kSE05x_RSASignatureAlgo_SHA224_PKCS1_PSS
= 0x2B RFC8017: RSASSA-PSS
-
kSE05x_RSASignatureAlgo_SHA256_PKCS1_PSS
= 0x2C RFC8017: RSASSA-PSS
-
kSE05x_RSASignatureAlgo_SHA384_PKCS1_PSS
= 0x2D RFC8017: RSASSA-PSS
-
kSE05x_RSASignatureAlgo_SHA512_PKCS1_PSS
= 0x2E RFC8017: RSASSA-PSS
-
kSE05x_RSASignatureAlgo_SHA1_PKCS1
= 0x0A RFC8017: RSASSA-PKCS1-v1_5
-
kSE05x_RSASignatureAlgo_SHA_224_PKCS1
= 0x27 RFC8017: RSASSA-PKCS1-v1_5
RFC8017: RSASSA-PKCS1-v1_5
RFC8017: RSASSA-PKCS1-v1_5
-
kSE05x_RSASignatureAlgo_SHA_512_PKCS1
= 0x2A RFC8017: RSASSA-PKCS1-v1_5
-
-
enum
SE05x_SecObjTyp_t
Type of Object
Values:
-
kSE05x_SecObjTyp_NA
= 0x00
-
kSE05x_SecObjTyp_EC_KEY_PAIR
= 0x01
-
kSE05x_SecObjTyp_EC_PRIV_KEY
= 0x02
-
kSE05x_SecObjTyp_EC_PUB_KEY
= 0x03
-
kSE05x_SecObjTyp_RSA_KEY_PAIR
= 0x04
-
kSE05x_SecObjTyp_RSA_KEY_PAIR_CRT
= 0x05
-
kSE05x_SecObjTyp_RSA_PRIV_KEY
= 0x06
-
kSE05x_SecObjTyp_RSA_PRIV_KEY_CRT
= 0x07
-
kSE05x_SecObjTyp_DES_KEY
= 0x0A
-
kSE05x_SecObjTyp_BINARY_FILE
= 0x0B
-
kSE05x_SecObjTyp_UserID
= 0x0C
-
kSE05x_SecObjTyp_COUNTER
= 0x0D
-
kSE05x_SecObjTyp_PCR
= 0x0F
-
kSE05x_SecObjTyp_CURVE
= 0x10
-
kSE05x_SecObjTyp_HMAC_KEY
= 0x11
-
-
enum
SE05x_SetIndicator_t
Whether object attribute is set
Values:
-
kSE05x_SetIndicator_NA
= 0 Invalid
-
kSE05x_SetIndicator_NOT_SET
= 0x01
-
kSE05x_SetIndicator_SET
= 0x02
-
-
enum
SE05x_SPAKE2PlusDeviceType_t
SPAKE device type
Values:
-
kSE05x_SPAKE2PLUS_DEVICE_TYPE_UNKNOWN
= 0 Invalid
-
SE05x_SPAKE2PLUS_DEVICE_TYPE_A
= 1 Spake device commionsioner
-
SE05x_SPAKE2PLUS_DEVICE_TYPE_B
= 2 Spake device Node/accessory
-
-
enum
SE05x_SW12_t
Mapping of 2 byte return code
Values:
-
kSE05x_SW12_NA
= 0 Invalid
No Error
Conditions not satisfied
Security status not satisfied.
Wrong data provided.
Data invalid - policy set invalid for the given object
Command not allowed - access denied based on object policy
-
-
enum
SE05x_SymmKeyType_t
Symmetric keys
Values:
-
kSE05x_SymmKeyType_NA
= 0
-
kSE05x_SymmKeyType_AES
= kSE05x_P1_AES
-
kSE05x_SymmKeyType_DES
= kSE05x_P1_DES
-
kSE05x_SymmKeyType_HMAC
= kSE05x_P1_HMAC
-
kSE05x_SymmKeyType_CMAC
= kSE05x_P1_AES
-
-
enum
SE05x_TAG_t
Different TAG Values to talk to SE05X IoT Applet
Values:
-
kSE05x_TAG_NA
= 0 Invalid
-
kSE05x_TAG_SESSION_ID
= 0x10
-
kSE05x_TAG_POLICY
= 0x11
-
kSE05x_TAG_MAX_ATTEMPTS
= 0x12
-
kSE05x_TAG_IMPORT_AUTH_DATA
= 0x13
-
kSE05x_TAG_IMPORT_AUTH_KEY_ID
= 0x14
-
kSE05x_TAG_POLICY_CHECK
= 0x15
-
kSE05x_TAG_1
= 0x41
-
kSE05x_TAG_2
= 0x42
-
kSE05x_TAG_3
= 0x43
-
kSE05x_TAG_4
= 0x44
-
kSE05x_TAG_5
= 0x45
-
kSE05x_TAG_6
= 0x46
-
kSE05x_TAG_7
= 0x47
-
kSE05x_TAG_10
= 0x4A
-
kSE05x_TAG_11
= 0x4B
-
kSE05x_GP_TAG_CONTRL_REF_PARM
= 0xA6
-
kSE05x_GP_TAG_AID
= 0x4F
-
-
enum
SE05x_TLSPerformPRFType_t
TLS Perform PRF
Values:
-
kSE05x_TLS_PRF_NA
= 0
-
kSE05x_TLS_PRF_CLI_HELLO
= kSE05x_P2_TLS_PRF_CLI_HELLO
-
kSE05x_TLS_PRF_SRV_HELLO
= kSE05x_P2_TLS_PRF_SRV_HELLO
-
kSE05x_TLS_PRF_CLI_RND
= kSE05x_P2_TLS_PRF_CLI_RND
-
kSE05x_TLS_PRF_SRV_RND
= kSE05x_P2_TLS_PRF_SRV_RND
-
kSE05x_TLS_PRF_BOTH
= kSE05x_P2_TLS_PRF_BOTH
-
-
enum
SE05x_TransientIndicator_t
Whether object is transient or persistent
Values:
-
kSE05x_TransientIndicator_NA
= 0 Invalid
-
kSE05x_TransientIndicator_PERSISTENT
= 0x01
-
kSE05x_TransientIndicator_TRANSIENT
= 0x02
-
-
enum
SE05x_TransientType_t
Whether key is transient of persistent
Values:
-
kSE05x_TransientType_Persistent
= 0
-
kSE05x_TransientType_Transient
= kSE05x_INS_TRANSIENT
-
Functions
-
smStatus_t
DoAPDUTx_s_Case3
(Se05xSession_t *pSessionCtx, const tlvHeader_t *hdr, uint8_t *cmdBuf, size_t cmdBufLen)
-
smStatus_t
DoAPDUTxRx
(Se05xSession_t *pSessionCtx, uint8_t *cmdBuf, size_t cmdBufLen, uint8_t *rspBuf, size_t *pRspBufLen)
-
smStatus_t
DoAPDUTxRx_s_Case2
(Se05xSession_t *pSessionCtx, const tlvHeader_t *hdr, uint8_t *cmdBuf, size_t cmdBufLen, uint8_t *rspBuf, size_t *pRspBufLen)
-
smStatus_t
DoAPDUTxRx_s_Case4
(Se05xSession_t *pSessionCtx, const tlvHeader_t *hdr, uint8_t *cmdBuf, size_t cmdBufLen, uint8_t *rspBuf, size_t *pRspBufLen)
-
smStatus_t
DoAPDUTxRx_s_Case4_ext
(Se05xSession_t *pSessionCtx, const tlvHeader_t *hdr, uint8_t *cmdBuf, size_t cmdBufLen, uint8_t *rspBuf, size_t *pRspBufLen)
-
smStatus_t
Se05x_API_I2CM_Send
(pSe05xSession_t sessionId, const uint8_t *buffer, size_t bufferLen, uint8_t *result, size_t *presultLen)
-
smStatus_t
se05x_DeCrypt
(struct Se05xSession *pSessionCtx, size_t cmd_cmacLen, uint8_t *rsp, size_t *rspLength, uint8_t hasle)
-
smStatus_t
se05x_Transform
(struct Se05xSession *pSession, const tlvHeader_t *hdr, uint8_t *cmdApduBuf, const size_t cmdApduBufLen, tlvHeader_t *out_hdr, uint8_t *txBuf, size_t *ptxBufLen, uint8_t hasle)
-
smStatus_t
se05x_Transform_scp
(struct Se05xSession *pSession, const tlvHeader_t *hdr, uint8_t *cmdApduBuf, const size_t cmdApduBufLen, tlvHeader_t *outhdr, uint8_t *txBuf, size_t *ptxBufLen, uint8_t hasle)
-
int
tlvGet_Result
(uint8_t *buf, size_t *pBufIndex, size_t bufLen, SE05x_TAG_t tag, SE05x_Result_t *presult)
-
int
tlvGet_Se05xSession
(uint8_t *buf, size_t *pBufIndex, const size_t bufLen, SE05x_TAG_t tag, pSe05xSession_t *pSessionId)
-
int
tlvGet_SecureObjectType
(uint8_t *buf, size_t *pBufIndex, size_t bufLen, SE05x_TAG_t tag, SE05x_SecObjTyp_t *pType)
-
int
tlvGet_TimeStamp
(uint8_t *buf, size_t *pBufIndex, const size_t bufLen, SE05x_TAG_t tag, SE05x_TimeStamp_t *pTs)
-
int
tlvGet_U16
(uint8_t *buf, size_t *pBufIndex, const size_t bufLen, SE05x_TAG_t tag, uint16_t *pRsp)
-
int
tlvGet_U32
(uint8_t *buf, size_t *pBufIndex, const size_t bufLen, SE05x_TAG_t tag, uint32_t *pRsp)
-
int
tlvGet_U8
(uint8_t *buf, size_t *pBufIndex, const size_t bufLen, SE05x_TAG_t tag, uint8_t *pRsp)
-
int
tlvGet_u8buf
(uint8_t *buf, size_t *pBufIndex, const size_t bufLen, SE05x_TAG_t tag, uint8_t *rsp, size_t *pRspLen)
-
int
tlvGet_ValueIndex
(uint8_t *buf, size_t *pBufIndex, const size_t bufLen, SE05x_TAG_t tag)
-
int
tlvSet_ECCurve
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, SE05x_ECCurve_t value)
-
int
tlvSet_KeyID
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, uint32_t keyID)
-
int
tlvSet_MaxAttemps
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, uint16_t maxAttemps)
-
int
tlvSet_Se05xPolicy
(const char *description, uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, Se05xPolicy_t *policy)
-
int
tlvSet_U16
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, uint16_t value)
-
int
tlvSet_U16Optional
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, uint16_t value)
-
int
tlvSet_U32
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, uint32_t value)
-
int
tlvSet_U64_size
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, uint64_t value, uint16_t size)
-
int
tlvSet_U8
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, uint8_t value)
-
int
tlvSet_u8buf
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, const uint8_t *cmd, size_t cmdLen)
-
int
tlvSet_u8buf_features
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, pSe05xAppletFeatures_t appletVariant)
-
int
tlvSet_u8buf_I2CM
(uint8_t **buf, size_t *bufLen, SE05x_I2CM_TAG_t tag, const uint8_t *cmd, size_t cmdLen)
-
int
tlvSet_u8bufOptional
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, const uint8_t *cmd, size_t cmdLen)
-
int
tlvSet_u8bufOptional_ByteShift
(uint8_t **buf, size_t *bufLen, SE05x_TAG_t tag, const uint8_t *cmd, size_t cmdLen)
Variables
-
uint32_t
auth_id
-
SE_AuthType_t
authType
-
void *
conn_ctx
Connection data context
-
uint8_t *
dataToMac
-
size_t
dataToMacLen
-
SE05x_ExtendedFeatures_t *
extended_features
-
uint8_t
features
[30]
-
smStatus_t (*
fp_DeCrypt
)(struct Se05xSession *pSession, size_t prevCmdBufLen, uint8_t *pInRxBuf, size_t *pInRxBufLen, uint8_t hasle)
-
smStatus_t (*
fp_RawTXn
)(void *conn_ctx, struct _sss_se05x_tunnel_context *pChannelCtx, SE_AuthType_t currAuth, const tlvHeader_t *hdr, uint8_t *cmdBuf, size_t cmdBufLen, uint8_t *rsp, size_t *rspLen, uint8_t hasle)
-
smStatus_t (*
fp_Transform
)(struct Se05xSession *pSession, const tlvHeader_t *inHdr, uint8_t *inCmdBuf, size_t inCmdBufLen, tlvHeader_t *outHdr, uint8_t *pTxBuf, size_t *pTxBufLen, uint8_t hasle) API called by fp_TXn. Helps handle UserID/Applet/ECKey to transform buffer.
But this API never sends any data out over any communication link.
-
smStatus_t (*
fp_TXn
)(struct Se05xSession *pSession, const tlvHeader_t *hdr, uint8_t *cmdBuf, size_t cmdBufLen, uint8_t *rsp, size_t *rspLen, uint8_t hasle) Meta Funciton
Internall first calls fp_Transform Then calls fp_RawTXn Then calls fp_DeCrypt
-
uint8_t
hasSession
-
struct _sss_se05x_tunnel_context *
pChannelCtx
-
NXSCP03_DynCtx_t *
pdynScp03Ctx
-
uint8_t *
se05xCmd
-
const tlvHeader_t *
se05xCmd_hdr
-
size_t
se05xCmdLC
-
size_t
se05xCmdLCW
-
size_t
se05xCmdLen
-
uint8_t *
se05xTxBuf
-
size_t
se05xTxBufLen
-
uint8_t
ts
[12]
-
uint8_t
value
[8]
-
uint8_t *
value
-
size_t
value_len
-
SE05x_Variant_t
variant
-
size_t
ws_LC
-
size_t
ws_LCW
-
uint8_t *
wsSe05x_cmd
-
size_t
wsSe05x_cmdLen
-
uint8_t *
wsSe05x_tag1Cmd
-
size_t
wsSe05x_tag1CmdLen
-
size_t
wsSe05x_tag1Len
-
size_t
wsSe05x_tag1W
-
struct
Se05x_AppletFeatures_t
-
union
SE05x_CryptoModeSubType_t
- #include <se05x_enums.h>
Cyrpto module subtype
Public Members
-
SE05x_AeadAlgo_t
aead
In case it’s aead
-
SE05x_CipherMode_t
cipher
In case it’s cipher
-
SE05x_DigestMode_t
digest
In case it’s digest
-
SE05x_MACAlgo_t
mac
In case it’s mac
-
SE05x_PAKEMode_t
pakeMode
In case it’s pake
-
uint8_t
union_8bit
Accessing 8 bit value for APDUs
-
SE05x_AeadAlgo_t
-
struct
SE05x_ExtendedFeatures_t
Public Members
-
uint8_t
features
[30]
-
uint8_t
-
struct
SE05x_TimeStamp_t
Public Members
-
uint8_t
ts
[12]
-
uint8_t
-
struct
Se05xApdu_t
Public Members
-
uint8_t *
dataToMac
-
size_t
dataToMacLen
-
uint8_t *
se05xCmd
-
const tlvHeader_t *
se05xCmd_hdr
-
size_t
se05xCmdLC
-
size_t
se05xCmdLCW
-
size_t
se05xCmdLen
-
uint8_t *
se05xTxBuf
-
size_t
se05xTxBufLen
-
size_t
ws_LC
-
size_t
ws_LCW
-
uint8_t *
wsSe05x_cmd
-
size_t
wsSe05x_cmdLen
-
uint8_t *
wsSe05x_tag1Cmd
-
size_t
wsSe05x_tag1CmdLen
-
size_t
wsSe05x_tag1Len
-
size_t
wsSe05x_tag1W
-
uint8_t *
-
struct
Se05xPolicy_t
Public Members
-
uint8_t *
value
-
size_t
value_len
-
uint8_t *
-
struct
Se05xSession
Public Members
-
uint32_t
auth_id
-
SE_AuthType_t
authType
-
void *
conn_ctx
Connection data context
-
smStatus_t (*
fp_DeCrypt
)(struct Se05xSession *pSession, size_t prevCmdBufLen, uint8_t *pInRxBuf, size_t *pInRxBufLen, uint8_t hasle)
-
smStatus_t (*
fp_RawTXn
)(void *conn_ctx, struct _sss_se05x_tunnel_context *pChannelCtx, SE_AuthType_t currAuth, const tlvHeader_t *hdr, uint8_t *cmdBuf, size_t cmdBufLen, uint8_t *rsp, size_t *rspLen, uint8_t hasle)
-
smStatus_t (*
fp_Transform
)(struct Se05xSession *pSession, const tlvHeader_t *inHdr, uint8_t *inCmdBuf, size_t inCmdBufLen, tlvHeader_t *outHdr, uint8_t *pTxBuf, size_t *pTxBufLen, uint8_t hasle) API called by fp_TXn. Helps handle UserID/Applet/ECKey to transform buffer.
But this API never sends any data out over any communication link.
-
smStatus_t (*
fp_TXn
)(struct Se05xSession *pSession, const tlvHeader_t *hdr, uint8_t *cmdBuf, size_t cmdBufLen, uint8_t *rsp, size_t *rspLen, uint8_t hasle) Meta Funciton
Internall first calls fp_Transform Then calls fp_RawTXn Then calls fp_DeCrypt
-
uint8_t
hasSession
-
struct _sss_se05x_tunnel_context *
pChannelCtx
-
NXSCP03_DynCtx_t *
pdynScp03Ctx
-
uint8_t
value
[8]
-
uint32_t
-
11.12.2. SE05x APIs¶
-
group
se05x_apis
SE05x APIs.
Defines
-
ENABLE_DEPRECATED_API_WritePCR
-
Se05x_API_ECGenSharedSecret
Wrapper for Se05x_API_ECDHGenerateSharedSecret
-
Se05x_API_SHAOneShot
Wrapper for Se05x_API_DigestOneShot
-
Se05x_API_WriteECKey_with_version
Functions
-
smStatus_t
Se05x_API_AeadCCMFinal
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, uint8_t *pOutputData, size_t *pOutputLen, uint8_t *pTag, size_t *pTagLen, const SE05x_Cipher_Oper_t operation) Se05x_API_AeadCCMFinal
Finish a sequence of AES_CCM AEAD operations.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_AEAD
See
SE05x_P1_t
P2
P2_FINAL
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_6]
Byte array containing tag to verify [Conditional] When the mode is decrypt and verify (i.e. AEADInit has been called with P2 = P2_DECRYPT).
Le
0x00
Expected returned data.
R-APDU Body
Value
Description
TLV[TAG_1]
Output data
TLV[TAG_2]
Byte array containing tag (if P2 = P2_ENCRYPT) or byte array containing Result (if P2 = P2_DECRYPT)
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] cryptoObjectID
: The crypto object id[out] pOutputData
: The output data[out] pOutputLen
: The output lengthtag
: The tagtagLen
: The tag length[in] operation
: The operation
-
smStatus_t
Se05x_API_AeadCCMInit
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_CipherMode_t cipherMode, SE05x_CryptoObjectID_t cryptoObjectID, uint8_t *pIV, size_t IVLen, size_t aadLen, size_t payloadLen, size_t tagLen, const SE05x_Cipher_Oper_t operation) Se05x_API_AeadCCMInit
Initialize an authentication encryption or decryption with associated data. The Crypto Object keeps the state of the AEAD operation until it’s finalized or deleted. Once the AEADFinal function is executed successfully, the Crypto Object state returns to the state immediately after the previous AEADInit function.AEAD in CCM mode.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_AEAD
See
SE05x_P1_t
P2
P2_ENCRYPT or P2_DECRYPT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the AESKey Secure object.
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_5]
Byte array containing the initialization vector [12 bytes until 60 bytes] or a 2-byte value containing the initialization vector length, depending on the AEADMode of the Crypto Object.
TLV[TAG_6]
Byte array containing 2-byte AAD length. [Conditional: needed if AEADMode equals AES_CCM]
TLV[TAG_7]
Byte array containing 2-byte message length. [Conditional: needed if AEADMode equals AES_CCM]
TLV[TAG_8]
Byte array containing 2-byte tag size. [Conditional: needed if AEADMode equals AES_CCM].
Le
R-APDU Body
NA R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object id[in] cryptoObjectID
: The crypto object id[in] pIV
: { parameter_description }[in] IVLen
: The iv length[in] aadLen
: The aad length[in] payloadLen
: The payloadLen length[in] tagLen
: The tag length[in] operation
: The operation
-
smStatus_t
Se05x_API_AeadCCMLastUpdate
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, const uint8_t *pInputData, size_t inputDataLen) Se05x_API_AeadCCMLastUpdate.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_AEAD
See
SE05x_P1_t
P2
P2_UPDATE
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_3]
Byte array containing input data [Conditional: only when TLV[TAG_4] is not present] [Optional]
Le
0x00
Expecting returned data.
R-APDU Body
NA R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
R-APDU Trailer
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] cryptoObjectID
: The crypto object id[in] pInputData
: The input data[in] inputDataLen
: The input data length
-
smStatus_t
Se05x_API_AeadFinal
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, uint8_t *tag, size_t *tagLen, const SE05x_Cipher_Oper_t operation) Se05x_API_AeadFinal
Finish a sequence of AEAD operations. The AEADFinal command provides the computed GMAC or indicates whether the GMAC is correct depending on the P2 parameters passed during AEADInit. The length of the GMAC is always 16 bytes when P2 equals P2_ENCRYPT. When P2 equals P2_DECRYPT, the minimum tag length to pass is 4 bytes.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_AEAD
See
SE05x_P1_t
P2
P2_FINAL
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_6]
Byte array containing tag to verify [Conditional] When the mode is decrypt and verify (i.e. AEADInit has been called with P2 = P2_DECRYPT).
Le
0x00
Expected returned data.
R-APDU Body
Value
Description
TLV[TAG_2]
Byte array containing tag (if P2 = P2_ENCRYPT) or byte array containing Result (if P2 = P2_DECRYPT)
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] cryptoObjectID
: The crypto object idtag
: The tagtagLen
: The tag length[in] operation
: The operation
-
smStatus_t
Se05x_API_AeadInit
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_CipherMode_t cipherMode, SE05x_CryptoObjectID_t cryptoObjectID, uint8_t *pIV, size_t IVLen, const SE05x_Cipher_Oper_t operation) Se05x_API_AeadInit
Initialize an authentication encryption or decryption with associated data. The Crypto Object keeps the state of the AEAD operation until it’s finalized or deleted. Once the AEADFinal function is executed successfully, the Crypto Object state returns to the state immediately after the previous AEADInit function.
When P1 equals P1_AEAD_INT_IV and P2 equals P1_ENCRYPT, TLV[TAG_5] must includes the length of the initialization vector. In that case, the initialization vector is generated internally and passed back in the response command. When the device is in FIPS mode (see FIPS Compliance), P1 equal to P1_AEAD will result in SW_CONDITIONS_NOT_SATISFIED.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_AEAD or P1_AEAD_INT_IV
See
SE05x_P1_t
P2
P2_ENCRYPT or P2_DECRYPT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the AESKey Secure object.
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_5]
Byte array containing the initialization vector (if P1 equals P1_AEAD or P1 equals P1_AEAD and P2 equals P2_DECRYPT) or 2-byte value containing the initialization vector length (if P1 equals P1_AEAD_INT_IV and P2 equals P2_ENCRYPT) [Optional] [Conditional: required when P1 equals P1_AEAD_INT_IV and P2 equals P2_ENCRYPT]
Le
R-APDU Body
Value
Description
TLV[TAG_3]
Byte array containing the used initialization vector. It remains valid until deselect, AEADInit, AEADFinal or AEADOneShot is called. [Conditional: Only when P1 equals P1_AEAD_INT_IV and P2 equals P2_ENCRYPT]
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object id[in] cryptoObjectID
: The crypto object id[in] pIV
: { parameter_description }[in] IVLen
: The iv length[in] operation
: The operation
-
smStatus_t
Se05x_API_AeadOneShot
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_CipherMode_t cipherMode, const uint8_t *inputData, size_t inputDataLen, const uint8_t *aad, size_t aadLen, uint8_t *IV, size_t IVLen, uint8_t *tagData, size_t *tagDataLen, uint8_t *outputData, size_t *poutputDataLen, const SE05x_Cipher_Oper_OneShot_t operation) Se05x_API_AeadOneShot
Authenticated encryption or decryption with associated data in one shot mode.
The key object must be either an AES key or DES key.
The AEADOneShot command returns the computed GMAC (when P2 equals P2_ENCRYPT_ONESHOT) or indicates whether the GMAC is correct (when P2 equals P2_DECRYPT_ONESHOT). The length of the GMAC is always 16 bytes when P2 equals P2_ENCRYPT_ONESHOT.
When P2 equals P2_DECRYPT_ONESHOT:
the minimum tag length to pass is 4 bytes.
when the GMAC tag is not correct, only the result will be returned, no output data will be present.
Note: on applet v4.4.0, the maximum lengths are not yet enforced and might differ from the values listed in the C-APDU.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_AEAD or P1_AEAD_INT_IV
See
SE05x_P1_t
P2
P2_ENCRYPT_ONESHOT or P2_DECRYPT_ONESHOT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the AESKey Secure object.
TLV[TAG_2]
1-byte AEADMode
TLV[TAG_3]
Byte array containing input data. Maximum length = 256 bytes. [Optional]
TLV[TAG_4]
Byte array containing Additional Authenticated Data. Maximum length = 64 bytes. [Optional]
TLV[TAG_5]
Byte array containing an initialization vector (if P1 equals P1_AEAD) or 2-byte value containing the initialization vector length (if P1 equals P1_AEAD_SP800_108). Maximum IV length = 60 bytes. [Optional] [Conditional: required when P1 equals P1_AEAD_INT_IV]
TLV[TAG_6]
Byte array containing the GMAC tag to verify. [Conditional: when P2 equals P2_DECRYPT_ONESHOT]
Le
0x00
Expecting return data.
R-APDU Body
Value
Description
TLV[TAG_1]
Byte array containing output data.
TLV[TAG_2]
Byte array containing tag (if P2 = P2_ENCRYPT_ONESHOT) or byte array containing Result (if P2 = P2_DECRYPT_ONESHOT)
TLV[TAG_3]
Byte array containing the initialization vector (if P1 = P1_AEAD_INT_IV and P2 = P2_ENCRYPT_ONESHOT).
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object id[in] cipherMode
: The cipher mode[in] inputData
: The input data[in] inputDataLen
: The input data length[in] aad
: The aad[in] aadLen
: The aad length[in] IV
: The iv[in] IVLen
: The iv lengthtagData
: The tag datatagDataLen
: The tag data lengthoutputData
: The output datapoutputDataLen
: The poutput data length[in] operation
: The operation
-
smStatus_t
Se05x_API_AeadUpdate
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, const uint8_t *pInputData, size_t inputDataLen, uint8_t *pOutputData, size_t *pOutputLen) Se05x_API_AeadUpdate.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_AEAD
See
SE05x_P1_t
P2
P2_UPDATE
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_3]
Byte array containing input data [Conditional: only when TLV[TAG_4] is not present] [Optional]
Le
0x00
Expecting returned data.
R-APDU Body
Value
Description
TLV[TAG_1]
Output data [Conditional: only when TLV[TAG_3] is passed as input]
R-APDU Trailer
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] cryptoObjectID
: The crypto object id[in] pInputData
: The input data[in] inputDataLen
: The input data lengthpOutputData
: The output datapOutputLen
: The output length
-
smStatus_t
Se05x_API_AeadUpdate_aad
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, const uint8_t *pAadData, size_t aadDataLen) Se05x_API_AeadUpdate_aad
Update a Crypto Object of type CC_AEAD.
The user either needs to send input data or Additional Authenticated Data (AAD), but not both at once.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_AEAD
See
SE05x_P1_t
P2
P2_UPDATE
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_4]
Byte array containing Additional Authenticated Data. [Conditional: only when TLV[TAG_3] is not present] [Optional]
Le
0x00
Expecting returned data.
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] cryptoObjectID
: The crypto object id[in] pAadData
: The aad data[in] aadDataLen
: The aad data length
-
smStatus_t
Se05x_API_CheckObjectExists
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_Result_t *presult) Se05x_API_CheckObjectExists
Check if a Secure Object with a certain identifier exists or not.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_EXIST
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte existing Secure Object identifier.
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
1-byte
SE05x_Result_t
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1][out] presult
: [0:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_CipherFinal
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, const uint8_t *inputData, size_t inputDataLen, uint8_t *outputData, size_t *poutputDataLen) Se05x_API_CipherFinal
Finish a sequence of cipher operations.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_CIPHER
See
SE05x_P1_t
P2
P2_FINAL
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_3]
Input data
Le
0x00
Expected returned data.
R-APDU Body
Value
Description
TLV[TAG_1]
Output data
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] cryptoObjectID
: cryptoObjectID [1:kSE05x_TAG_2][in] inputData
: inputData [2:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] outputData
: [0:kSE05x_TAG_1][inout] poutputDataLen
: Length for outputData
-
smStatus_t
Se05x_API_CipherInit
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_CryptoObjectID_t cryptoObjectID, uint8_t *IV, size_t IVLen, const SE05x_Cipher_Oper_t operation) Se05x_API_CipherInit
Initialize a symmetric encryption or decryption. The Crypto Object keeps the state of the cipher operation until it’s finalized or deleted. Once the CipherFinal function is executed successfully, the Crypto Object state returns to the state immediately after the previous CipherInit function.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_CIPHER
See
SE05x_P1_t
P2
P2_ENCRYPT or P2_DECRYPT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the key object.
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_4]
Initialization Vector [Optional] [Conditional: only when the Crypto Object type equals CC_CIPHER and subtype is not including ECB]
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] cryptoObjectID
: cryptoObjectID [2:kSE05x_TAG_2][in] IV
: IV [3:kSE05x_TAG_4][in] IVLen
: Length of IV[in] operation
: See SE05x_Cipher_Oper_t
-
smStatus_t
Se05x_API_CipherOneShot
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_CipherMode_t cipherMode, const uint8_t *inputData, size_t inputDataLen, uint8_t *IV, size_t IVLen, uint8_t *outputData, size_t *poutputDataLen, const SE05x_Cipher_Oper_OneShot_t operation) Se05x_API_CipherOneShot.
Encrypt or decrypt data in one shot mode.
The key object must be either an AES key or DES key.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_CIPHER
See
SE05x_P1_t
P2
P2_ENCRYPT_ONESHOT or P2_DECRYPT_ONESHOT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the key object.
TLV[TAG_2]
1-byte CipherMode
TLV[TAG_3]
Byte array containing input data.
TLV[TAG_4]
Byte array containing an initialization vector. [Optional] [Conditional: only when the Crypto Object type equals CC_CIPHER and subtype is not including ECB]
Le
0x00
Expecting return data.
R-APDU Body
Value
Description
TLV[TAG_1]
Output data
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object id[in] cipherMode
: The cipher mode[in] inputData
: The input data[in] inputDataLen
: The input data length[in] IV
: Initial vector[in] IVLen
: The iv lengthoutputData
: The output datapoutputDataLen
: The poutput data length[in] operation
: The operation
-
smStatus_t
Se05x_API_CipherUpdate
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, const uint8_t *inputData, size_t inputDataLen, uint8_t *outputData, size_t *poutputDataLen) Se05x_API_CipherUpdate
Update a cipher context.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_CIPHER
See
SE05x_P1_t
P2
P2_UPDATE
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_3]
Byte array containing input data
Le
0x00
Expecting returned data.
R-APDU Body
Value
Description
TLV[TAG_1]
Output data
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] cryptoObjectID
: cryptoObjectID [1:kSE05x_TAG_2][in] inputData
: inputData [2:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] outputData
: [0:kSE05x_TAG_1][inout] poutputDataLen
: Length for outputData
-
smStatus_t
Se05x_API_CloseSession
(pSe05xSession_t session_ctx) Se05x_API_CloseSession
Closes a running session.
When a session is closed, it cannot be reopened.
All session parameters are transient.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SESSION_CLOSE
See
SE05x_P2_t
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The session is closed successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession]
-
smStatus_t
Se05x_API_CreateCounter
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t objectID, uint16_t size) Se05x_API_CreateCounter
Creates a new counter object.
Counters can only be incremented, not decremented.
When a counter reaches its maximum value (e.g., 0xFFFFFFFF for a 4-byte counter), they cannot be incremented again.
An input value (TAG_3) must always have the same length as the existing counter (if it exists); otherwise the command will return an error.
Command to Applet
Field
Value
Description
P1
P1_COUNTER
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Payload
TLV[TAG_POLICY]
Byte array containing the object policy. [Optional: default policy applies] [Conditional: only when the object identifier is not in use yet]
TLV[TAG_1]
4-byte counter identifier.
TLV[TAG_2]
2-byte counter size (1 up to 8 bytes). [Conditional: only if object doesn’t exist yet and TAG_3 is not given]
TLV[TAG_3]
Counter value [Optional: - if object doesn’t exist: must be present if TAG_2 is not given. - if object exists: if not present, increment by 1. if present, set counter to value.]
R-APDU Body
NA
R-APDU Trailer
NA
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] policy
: policy [1:kSE05x_TAG_POLICY][in] objectID
: object id [2:kSE05x_TAG_1][in] size
: size [3:kSE05x_TAG_2]
-
smStatus_t
Se05x_API_CreateCryptoObject
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, SE05x_CryptoContext_t cryptoContext, SE05x_CryptoModeSubType_t subtype) Se05x_API_CreateCryptoObject
Creates a Crypto Object on the SE05X . Once the Crypto Object is created, it is bound to the user who created the Crypto Object.
A CryptoObject is a 2-byte value consisting of a CryptoContext in MSB and one of the following in LSB:
DigestMode in case CryptoContext = CC_DIGEST
CipherMode in case CryptoContext = CC_CIPHER
MACAlgo in case CryptoContext = CC_SIGNATURE
AEADMode in case CryptoContext = CC_AEAD
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_WRITE
See
SE05x_INS_t
P1
P1_CRYPTO_OBJ
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Lc
#(Payload)
Payload length
Payload
TLV[TAG_1]
2-byte Crypto Object identifier
TLV[TAG_2]
1-byte
SE05x_CryptoObject_t
TLV[TAG_3]
1-byte Crypto Object subtype, either from
DigestModeRef
, CipherMode, MACAlgo (depending on TAG_2) or AEADMode.R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The file is created or updated successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] cryptoObjectID
: cryptoObjectID [1:kSE05x_TAG_1][in] cryptoContext
: cryptoContext [2:kSE05x_TAG_2][in] subtype
: 1-byte Crypto Object subtype, either from DigestMode, CipherMode or MACAlgo (depending on TAG_2). [3:kSE05x_TAG_3]
-
smStatus_t
Se05x_API_CreateECCurve
(pSe05xSession_t session_ctx, SE05x_ECCurve_t curveID) Se05x_API_CreateECCurve
Create an EC curve listed in ECCurve.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_WRITE
See
SE05x_INS_t
P1
P1_CURVE
See
SE05x_P1_t
P2
P2_CREATE
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
1-byte curve identifier (from
SE05x_ECCurve_t
).Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] curveID
: curve id [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_CreateSession
(pSe05xSession_t session_ctx, uint32_t authObjectID, uint8_t *sessionId, size_t *psessionIdLen) Se05x_API_CreateSession
Creates a session on SE05X .
Depending on the authentication object being referenced, a specific method of authentication applies. The response needs to adhere to this authentication method.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SESSION_CREATE
See
SE05x_P2_t
Lc
#(Payload)
Payload length.
Payload
TLV[TAG_1]
4-byte authentication object identifier.
Le
0x0A
Expecting TLV with 8-byte session ID.
R-APDU Body
Value
Description
TLV[TAG_1]
8-byte session identifier.
R-APDU Trailer
SW_NO_ERROR:
The command is handled successfully.
SW_CONDITIONS_NOT_SATISFIED:
The authenticator does not exist
The provided input data are incorrect.
The session is invalid.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] authObjectID
: auth [1:kSE05x_TAG_1][out] sessionId
: [0:kSE05x_TAG_1][inout] psessionIdLen
: Length for sessionId
-
smStatus_t
Se05x_API_DeleteAll
(pSe05xSession_t session_ctx) Se05x_API_DeleteAll
Delete all Secure Objects, delete all curves and Crypto Objects. Secure Objects that are trust provisioned by NXP are not deleted (i.e., all objects that have Origin set to ORIGIN_PROVISIONED, including the objects with reserved object identifiers listed in Object attributes).
This command can only be used from sessions that are authenticated using the credential with index RESERVED_ID_FACTORY_RESET.
Important : if a secure messaging session is up & running (e.g., AESKey or ECKey session) and the command is sent within this session, the response of the DeleteAll command will not be wrapped (i.e., not encrypted and no R-MAC), so this will also break down the secure channel protocol (as the session is closed by the DeleteAll command itself).
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_DELETE_ALL
See
SE05x_P2_t
Lc
0x00
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession]
-
smStatus_t
Se05x_API_DeleteAll_Iterative
(pSe05xSession_t session_ctx) Se05x_API_DeleteAll_Iterative
Go through each object and delete it individually.
This API does not use the Applet API Se05x_API_DeleteAll. It does not delete ALL objects and purposefully skips few objects.
Instead, this API uses Se05x_API_ReadIDList and Se05x_API_ReadCryptoObjectList to first fetch list of objects to host, and selectitvely deletes.
For e.g. It does not kill objects from:
The range SE05X_OBJID_SE05X_APPLET_RES_START to SE05X_OBJID_SE05X_APPLET_RES_END. This range is used by applet.
The range EX_SSS_OBJID_DEMO_AUTH_START to EX_SSS_OBJID_DEMO_AUTH_END, which is used by middleware DEMOS for authentication.
And others.
Kindly see the Implementation of is API Se05x_API_DeleteAll_Iterative to see the list of ranges that are skipped.
- Return
The status of API.
- Parameters
[in] session_ctx
: Session Context
-
smStatus_t
Se05x_API_DeleteCryptoObject
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID) Se05x_API_DeleteCryptoObject
Deletes a Crypto Object on the SE05X .
Note: when a Crypto Object is deleted, the memory (as mentioned in ) is de- allocated, but the transient memory is only freed when de-selecting the applet!
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_CRYPTO_OBJ
See
SE05x_P1_t
P2
P2_DELETE_OBJECT
See
SE05x_P2_t
Lc
#(Payload)
Payload length
Payload
TLV[TAG_1]
2-byte Crypto Object identifier
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The file is created or updated successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] cryptoObjectID
: cryptoObjectID [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_DeleteECCurve
(pSe05xSession_t session_ctx, SE05x_ECCurve_t curveID) Se05x_API_DeleteECCurve
Deletes an EC curve.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_CURVE
See
SE05x_P1_t
P2
P2_DELETE_OBJECT
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
1-byte curve identifier (from
SE05x_ECCurve_t
)R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] curveID
: curve id [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_DeleteSecureObject
(pSe05xSession_t session_ctx, uint32_t objectID) Se05x_API_DeleteSecureObject
Deletes a Secure Object.
If the object origin = ORIGIN_PROVISIONED, an error will be returned and the object is not deleted.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_DELETE_OBJECT
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte existing Secure Object identifier.
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The file is created or updated successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_DFAuthenticateFirstPart1
(pSe05xSession_t session_ctx, uint32_t objectID, const uint8_t *inputData, size_t inputDataLen, uint8_t *outputData, size_t *poutputDataLen) Se05x_API_DFAuthenticateFirstPart1
MIFARE DESFire support
MIFARE DESFire EV2 Key derivation (S-mode). This is limited to AES128 keys only.
The SE05X can be used by a card reader to setup a session where the SE05X stores the master key(s) and the session keys are generated and passed to the host.
The SE05X keeps an internal state of MIFARE DESFire authentication data during authentication setup. This state is fully transient, so it is lost on deselect of the applet.
The MIFARE DESFire state is owned by 1 user at a time; i.e., the user who calls DFAuthenticateFirstPart1 owns the MIFARE DESFire context until DFAuthenticateFirstPart1 is called again or until DFKillAuthentication is called.
The SE05X can also be used to support a ChangeKey command, either supporting ChangeKey or ChangeKeyEV2. To establish a correct use case, policies need to be applied to the keys to indicate keys can be used for ChangeKey or not, etc. (to be detailed)
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_AUTH_FIRST_PART1
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte key identifier.
TLV[TAG_2]
16-byte encrypted card challenge: E(Kx,RndB)
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
32-byte output data: E(Kx, RandA || RandB’)
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] inputData
: inputData [2:kSE05x_TAG_2][in] inputDataLen
: Length of inputData[out] outputData
: [0:kSE05x_TAG_1][inout] poutputDataLen
: Length for outputData
-
smStatus_t
Se05x_API_DFAuthenticateFirstPart2
(pSe05xSession_t session_ctx, const uint8_t *inputData, size_t inputDataLen, uint8_t *outputData, size_t *poutputDataLen) Se05x_API_DFAuthenticateFirstPart2
For First part 2, the key identifier is implicitly set to the identifier used for the First authentication. DFAuthenticateFirstPart1 needs to be called before; otherwise an error is returned.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_AUTH_FIRST_PART2
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
32 byte input: E(Kx,TI||RndA’||PDcap2||PCDcap2)
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
12-byte array returning PDcap2||PCDcap2.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
SW_WRONG_DATA
SW_CONDITIONS_NOT_SATISFIED
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] inputData
: inputData [1:kSE05x_TAG_1][in] inputDataLen
: Length of inputData[out] outputData
: [0:kSE05x_TAG_1][inout] poutputDataLen
: Length for outputData
-
smStatus_t
Se05x_API_DFAuthenticateNonFirstPart1
(pSe05xSession_t session_ctx, uint32_t objectID, const uint8_t *inputData, size_t inputDataLen, uint8_t *outputData, size_t *poutputDataLen) Se05x_API_DFAuthenticateNonFirstPart1
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_AUTH_NONFIRST_PART1
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte key identifier.
TLV[TAG_2]
16-byte encrypted card challenge: E(Kx,RndB)
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
32-byte output data: E(Kx, RandA || RandB’)
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] inputData
: inputData [2:kSE05x_TAG_2][in] inputDataLen
: Length of inputData[out] outputData
: [0:kSE05x_TAG_1][inout] poutputDataLen
: Length for outputData
-
smStatus_t
Se05x_API_DFAuthenticateNonFirstPart2
(pSe05xSession_t session_ctx, const uint8_t *inputData, size_t inputDataLen) Se05x_API_DFAuthenticateNonFirstPart2
For NonFirst part 2, the key identifier is implicitly set to the identifier used for the NonFirst part 1 authentication. DFAuthenticateNonFirstPart1 needs to be called before; otherwise an error is returned.
If authentication fails, SW_WRONG_DATA will be returned.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_AUTH_NONFIRST_PART2
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
16-byte E(Kx, RndA’)
Le
0x00
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] inputData
: inputData [1:kSE05x_TAG_1][in] inputDataLen
: Length of inputData
-
smStatus_t
Se05x_API_DFChangeKeyPart1
(pSe05xSession_t session_ctx, uint32_t oldObjectID, uint32_t newObjectID, uint8_t keySetNr, uint8_t keyNoDESFire, uint8_t keyVer, uint8_t *KeyData, size_t *pKeyDataLen) Se05x_API_DFChangeKeyPart1
The DFChangeKeyPart1 command is supporting the function to change keys on the DESFire PICC. The command generates the cryptogram required to perform such operation.
The new key and, if used, the current (or old) key must be stored in the SE05X and have the POLICY_OBJ_ALLOW_DESFIRE_AUTHENTICATION associated to execute this command. This means the new PICC key must have been loaded into the SE05X prior to issuing this command.
The 1-byte key set number indicates whether DESFire ChangeKey or DESFire ChangeKeyEV2 is used. When key set equals 0xFF, ChangeKey is used.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_CHANGE_KEY_PART1
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte identifier of the old key. [Optional: if the authentication key is the same as the key to be replaced, this TAG should not be present].
TLV[TAG_2]
4-byte identifier of the new key.
TLV[TAG_3]
1-byte key set number [Optional: default = 0xC6]
TLV[TAG_4]
1-byte DESFire key number to be targeted.
TLV[TAG_5]
1-byte key version
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
Cryptogram holding key data
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] oldObjectID
: oldObjectID [1:kSE05x_TAG_1][in] newObjectID
: newObjectID [2:kSE05x_TAG_2][in] keySetNr
: keySetNr [3:kSE05x_TAG_3][in] keyNoDESFire
: keyNoDESFire [4:kSE05x_TAG_4][in] keyVer
: keyVer [5:kSE05x_TAG_5][out] KeyData
: [0:kSE05x_TAG_1][inout] pKeyDataLen
: Length for KeyData
-
smStatus_t
Se05x_API_DFChangeKeyPart2
(pSe05xSession_t session_ctx, const uint8_t *MAC, size_t MACLen, uint8_t *presult) Se05x_API_DFChangeKeyPart2
The DFChangeKeyPart2 command verifies the MAC returned by ChangeKey or ChangeKeyEV2. Note that this function only needs to be called if a MAC is returned (which is not the case if the currently authenticated key is changed on the DESFire card).
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_CHANGE_KEY_PART2
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
MAC
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
1-byte
SE05x_Result_t
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] MAC
: MAC [1:kSE05x_TAG_1][in] MACLen
: Length of MAC[out] presult
: [0:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_DFDiversifyKey
(pSe05xSession_t session_ctx, uint32_t masterKeyID, uint32_t diversifiedKeyID, const uint8_t *divInputData, size_t divInputDataLen) Se05x_API_DFDiversifyKey
Create a Diversified Key. Input is divInput 1 up to 31 bytes.
Note that users need to create the diversified key object before calling this function.
Both the master key and the diversified key need the policy POLICY_OBJ_ALLOW_DESFIRE_AUTHENTICATION to be set.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_DIVERSIFY
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte master key identifier.
TLV[TAG_2]
4-byte diversified key identifier.
TLV[TAG_3]
Byte array containing divInput (up to 31 bytes).
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
SW_CONDITIONS_NOT_SATISFIED
No master key found.
Wrong length for divInput.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] masterKeyID
: masterKeyID [1:kSE05x_TAG_1][in] diversifiedKeyID
: diversifiedKeyID [2:kSE05x_TAG_2][in] divInputData
: divInputData [3:kSE05x_TAG_3][in] divInputDataLen
: Length of divInputData
-
smStatus_t
Se05x_API_DFDumpSessionKeys
(pSe05xSession_t session_ctx, uint8_t *sessionData, size_t *psessionDataLen) Se05x_API_DFDumpSessionKeys
Dump the Transaction Identifier and the session keys to the host.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_DUMP_KEY
See
SE05x_P2_t
Lc
#(Payload)
Le
0x28
Expecting TLV with 38 bytes data.
R-APDU Body
Value
Description
TLV[TAG_1]
38 bytes: KeyID.SesAuthENCKey || KeyID.SesAuthMACKey || TI || Cmd-Ctr
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][out] sessionData
: 38 bytes: KeyID.SesAuthENCKey || KeyID.SesAuthMACKey || TI || Cmd-Ctr [0:kSE05x_TAG_1][inout] psessionDataLen
: Length for sessionData
-
smStatus_t
Se05x_API_DFKillAuthentication
(pSe05xSession_t session_ctx) Se05x_API_DFKillAuthentication
DFKillAuthentication invalidates any authentication and clears the internal DESFire state. Keys used as input (master keys or diversified keys) are not touched.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_KILL_AUTH
See
SE05x_P2_t
Lc
#(Payload)
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession]
-
smStatus_t
Se05x_API_DigestFinal
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, const uint8_t *inputData, size_t inputDataLen, uint8_t *cmacValue, size_t *pcmacValueLen) Se05x_API_DigestFinal
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_FINAL
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_3]
Data to be encrypted or decrypted.
Le
0x00
Expecting TLV with hash value.
R-APDU Body
Value
Description
TLV[TAG_1]
CMAC value
R-APDU Trailer
SW
Description
SW_NO_ERROR
The hash is created successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] cryptoObjectID
: cryptoObjectID [1:kSE05x_TAG_2][in] inputData
: inputData [2:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] cmacValue
: [0:kSE05x_TAG_1][inout] pcmacValueLen
: Length for cmacValue
-
smStatus_t
Se05x_API_DigestInit
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID) Se05x_API_DigestInit
Open a digest operation. The state of the digest operation is kept in the Crypto Object until the Crypto Object is finalized or deleted.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_INIT
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_2]
2-byte Crypto Object identifier
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] cryptoObjectID
: cryptoObjectID [1:kSE05x_TAG_2]
-
smStatus_t
Se05x_API_DigestOneShot
(pSe05xSession_t session_ctx, uint8_t digestMode, const uint8_t *inputData, size_t inputDataLen, uint8_t *hashValue, size_t *phashValueLen) Se05x_API_DigestOneShot
Performs a hash operation in one shot (without context).
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_ONESHOT
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
1-byte DigestMode (except DIGEST_NO_HASH)
TLV[TAG_2]
Data to hash.
Le
0x00
TLV expecting hash value
R-APDU Body
Value
Description
TLV[TAG_1]
Hash value.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The hash is created successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] digestMode
: digestMode [1:kSE05x_TAG_1][in] inputData
: inputData [2:kSE05x_TAG_2][in] inputDataLen
: Length of inputData[out] hashValue
: [0:kSE05x_TAG_1][inout] phashValueLen
: Length for hashValue
-
smStatus_t
Se05x_API_DigestUpdate
(pSe05xSession_t session_ctx, SE05x_CryptoObjectID_t cryptoObjectID, const uint8_t *inputData, size_t inputDataLen) Se05x_API_DigestUpdate
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_UPDATE
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_3]
Data to be hashed.
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] cryptoObjectID
: cryptoObjectID [1:kSE05x_TAG_2][in] inputData
: inputData [2:kSE05x_TAG_3][in] inputDataLen
: Length of inputData
-
smStatus_t
Se05x_API_DisableObjCreation
(pSe05xSession_t session_ctx, SE05x_LockIndicator_t lockIndicator, SE05x_RestrictMode_t restrictMode) Se05x_API_DisableObjCreation
Command to Applet
R-APDU Body
NA
R-APDU Trailer
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] lockIndicator
: [1:kSE05x_TAG_1][in] restrictMode
: [2:kSE05x_TAG_2]
-
smStatus_t
Se05x_API_EC_CurveGetId
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_ECCurve_t *pcurveId) Get the Curve ID for existing Key.
This API is functionally same as Se05x_API_GetECCurveId but uses SE05x_ECCurve_t as a type instead of uint8_t.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object idpcurveId
: The pcurve identifier
-
smStatus_t
Se05x_API_ECDAASign
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_ECDAASignatureAlgo_t ecdaaSignAlgo, const uint8_t *inputData, size_t inputDataLen, const uint8_t *randomData, size_t randomDataLen, uint8_t *signature, size_t *psignatureLen) Se05x_API_ECDAASign
The ECDAASign command signs external data using the indicated key pair or private key. This is performed according to ECDAA. The generated signature is:
r = random mod n
s = (r + T.ds) mod n where d is the private key
The ECDAASignatureAlgo indicates the applied algorithm.
This APDU command should be used with a key identifier linked to TPM_ECC_BN_P256 curve.
Note: The applet allows the random input to be 32 bytes of zeroes; the user must take care that this is not considered as valid input. Only input in the interval [1, n-1] must be considered as valid.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_SIGNATURE
See
SE05x_P1_t
P2
P2_SIGN
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte identifier of EC key pair or private key.
TLV[TAG_2]
1-byte ECDAASignatureAlgo
TLV[TAG_3]
T = 32-byte array containing hashed input data.
TLV[TAG_4]
r = 32-byte array containing random data, must be in the interval [1, n-1] where n is the order of the curve.
Le
0x00
Expecting signature
R-APDU Body
Value
Description
TLV[TAG_1]
ECDSA Signature (r concatenated with s).
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] ecdaaSignAlgo
: ecdaaSignAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[in] randomData
: randomData [4:kSE05x_TAG_4][in] randomDataLen
: Length of randomData[out] signature
: [0:kSE05x_TAG_1][inout] psignatureLen
: Length for signature
-
smStatus_t
Se05x_API_ECDHGenerateSharedSecret
(pSe05xSession_t session_ctx, uint32_t objectID, const uint8_t *pubKey, size_t pubKeyLen, uint8_t *sharedSecret, size_t *psharedSecretLen) Se05x_API_ECDHGenerateSharedSecret
The ECDHGenerateSharedSecret command generates a shared secret ECC point on the curve using an EC private key on SE05X and an external public key provided by the caller. The output shared secret is returned to the caller.
All curves from ECCurve are supported, except ECC_ED_25519.
Note that ECDHGenerateSharedSecret commands with EC keys using curve ID_ECC_MONT_DH_25519 or ID_ECC_MONT_DH_448 cause NVM write operations for each call. This is not the case for the other curves.
When CONFIG_FIPS_MODE_DISABLED is not set, this function will always return SW_CONDTIONS_NOT_SATISFIED.
The shared secret can only be received when the Secure Object containing the key pair or private key (TLV[TAG_1]) does not contain the policy POLICY_OBJ_FORBID_DERIVED_OUTPUT. If that is the case, the user must provide TLV[TAG_7} to store the shared secret in an HMACKey object. The user is responsible to assign the correct size of the HMACKey object: this must equal the size of the shared secret exactly.
On applet 4.4.0, the policy POLICY_OBJ_FORBID_DERIVED_OUTPUT is not yet verified for this function. It will always be allowed.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_EC
See
SE05x_P1_t
P2
P2_DH
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the key pair or private key.
TLV[TAG_2]
External public key (see
ECKeyRef
).TLV[TAG_7]
4-byte HMACKey identifier to store output. [Optional]
Le
0x00
Expected shared secret length.
R-APDU Body
Value
Description
TLV[TAG_1]
The returned shared secret. [Conditional: only when the input does not contain TLV[TAG_7].}
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] pubKey
: pubKey [2:kSE05x_TAG_2][in] pubKeyLen
: Length of pubKey[out] sharedSecret
: [0:kSE05x_TAG_1][inout] psharedSecretLen
: Length for sharedSecret
-
smStatus_t
Se05x_API_ECDHGenerateSharedSecret_InObject
(pSe05xSession_t session_ctx, uint32_t objectID, const uint8_t *pubKey, size_t pubKeyLen, uint32_t sharedSecretID, uint8_t invertEndianness) Se05x_API_ECDHGenerateSharedSecret_InObject
See Se05x_API_ECDHGenerateSharedSecret
-
smStatus_t
Se05x_API_ECDHGenerateSharedSecret_InObject_extended
(pSe05xSession_t session_ctx, uint32_t objectID, const uint8_t *pubKey, size_t pubKeyLen, SE05x_ECDHAlgo_t ecdhAlgo, uint32_t sharedSecretID, uint8_t invertEndianness) Se05x_API_ECDHGenerateSharedSecret_InObject_extended
See Se05x_API_ECDHGenerateSharedSecret_InObject_extended. New ECDH api with support for ECDH algo input (EC_SVDP_DH and EC_SVDP_DH_PLAIN).
- Parameters
[in] session_ctx
: The session context[in] objectID
: Private key or key pair identifier[in] pubKey
: External EC public key[in] pubKeyLen
: External EC public key length[in] ecdhAlgo
: ECDH Algorithm[in] sharedSecretID
: Identifier to store derived key[in] invertEndianness
: Option to invert endianness of derived key
-
smStatus_t
Se05x_API_ECDSASign
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_ECSignatureAlgo_t ecSignAlgo, const uint8_t *inputData, size_t inputDataLen, uint8_t *signature, size_t *psignatureLen) Se05x_API_ECDSASign
The ECDSASign command signs external data using the indicated key pair or private key.
The ECSignatureAlgo indicates the ECDSA algorithm that is used, but the hashing of data always must be done on the host. E.g., if ECSignatureAlgo = SIG_ ECDSA_SHA256, the user must have applied SHA256 on the input data already.
The user must take care of providing the correct input length; i.e., the data input length (TLV[TAG_3]) must match the digest indicated in the signature algorithm (TLV[TAG_2]).
In any case, the APDU payload must be smaller than MAX_APDU_PAYLOAD_LENGTH.
This is performed according to the ECDSA algorithm as specified in [ANSI X9.62]. The signature (a sequence of two integers ‘r’ and ‘s’) as returned in the response adheres to the ASN.1 DER encoded formatting rules for integers.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_SIGNATURE
See
SE05x_P1_t
P2
P2_SIGN
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte identifier of EC key pair or private key.
TLV[TAG_2]
1-byte ECSignatureAlgo.
TLV[TAG_3]
Byte array containing input data.
Le
0x00
Expecting ASN.1 signature
R-APDU Body
Value
Description
TLV[TAG_1]
ECDSA Signature in ASN.1 format.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] ecSignAlgo
: ecSignAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] signature
: [0:kSE05x_TAG_1][inout] psignatureLen
: Length for signature
-
smStatus_t
Se05x_API_ECDSAVerify
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_ECSignatureAlgo_t ecSignAlgo, const uint8_t *inputData, size_t inputDataLen, const uint8_t *signature, size_t signatureLen, SE05x_Result_t *presult) Se05x_API_ECDSAVerify
The ECDSAVerify command verifies whether the signature is correct for a given (hashed) data input using an EC public key or EC key pair’s public key.
The ECSignatureAlgo indicates the ECDSA algorithm that is used, but the hashing of data must always be done on the host. E.g., if ECSignatureAlgo = SIG_ ECDSA_SHA256, the user must have applied SHA256 on the input data already.
The key cannot be passed externally to the command directly. In case users want to use the command to verify signatures using different public keys or the public key value regularly changes, the user should create a transient key object to which the key value is written and then the identifier of that transient secure object can be used by this ECDSAVerify command.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_SIGNATURE
See
SE05x_P1_t
P2
P2_VERIFY
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte identifier of the key pair or public key.
TLV[TAG_2]
1-byte ECSignatureAlgo.
TLV[TAG_3]
Byte array containing ASN.1 signature
TLV[TAG_5]
Byte array containing hashed data to compare.
Le
0x03
Expecting TLV with
SE05x_Result_t
R-APDU Body
Value
Description
TLV[TAG_1]
Result of the signature verification (
SE05x_Result_t
).R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
SW_CONDITIONS_NOT_SATISFIED
Incorrect data
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] ecSignAlgo
: ecSignAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[in] signature
: signature [4:kSE05x_TAG_5][in] signatureLen
: Length of signature[out] presult
: [0:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_ECPointMultiply_InputObj
(pSe05xSession_t session_ctx, uint32_t objectID, uint32_t pubKeyID, uint32_t sharedSecretID, uint8_t *sharedSecretOuput, size_t *psharedSecretOuputLen, SE05x_ECPMAlgo_t ECPMAlgo)
-
smStatus_t
Se05x_API_EdDSASign
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_EDSignatureAlgo_t edSignAlgo, const uint8_t *inputData, size_t inputDataLen, uint8_t *signature, size_t *psignatureLen) Se05x_API_EdDSASign
The EdDSASign command signs external data using the indicated key pair or private key (using a Twisted Edwards curve). This is performed according to the EdDSA algorithm as specified in [RFC8032].
The input data need to be the plain data (not hashed).
The signature as returned in the response is a 64-byte array, being the concatenation of the signature r and s component (without leading zeroes for sign indication).
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_SIGNATURE
See
SE05x_P1_t
P2
P2_SIGN
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte identifier of EC key pair or private key.
TLV[TAG_2]
1-byte EDSignatureAlgo
TLV[TAG_3]
Byte array containing plain input data.
Le
0x00
Expecting signature
R-APDU Body
Value
Description
TLV[TAG_1]
EdDSA Signature (r concatenated with s).
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] edSignAlgo
: edSignAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] signature
: [0:kSE05x_TAG_1][inout] psignatureLen
: Length for signature
-
smStatus_t
Se05x_API_EdDSAVerify
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_EDSignatureAlgo_t edSignAlgo, const uint8_t *inputData, size_t inputDataLen, const uint8_t *signature, size_t signatureLen, SE05x_Result_t *presult) Se05x_API_EdDSAVerify
The EdDSAVerify command verifies whether the signature is correct for a given data input (hashed using SHA512) using an EC public key or EC key pair’s public key. The signature needs to be given as concatenation of r and s.
The data needs to be compared with the plain message without being hashed.
Note : See chapter 7 for correct byte order as both r and s need to be byte swapped.
This is performed according to the EdDSA algorithm as specified in [RFC8032].
The key cannot be passed externally to the command directly. In case users want to use the command to verify signatures using different public keys or the public key value regularly changes, the user should create a transient key object to which the key value is written and then the identifier of that transient secure object can be used by this EdDSAVerify command.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_SIGNATURE
See
SE05x_P1_t
P2
P2_VERIFY
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte identifier of the key pair or public key.
TLV[TAG_2]
1-byte
EDSignatureAlgoRef
.TLV[TAG_3]
64-byte array containing the signature (concatenation of r and s).
TLV[TAG_5]
Byte array containing plain data to compare.
Le
0x03
Expecting TLV with
SE05x_Result_t
R-APDU Body
Value
Description
TLV[TAG_1]
Result of the signature verification (
SE05x_Result_t
).R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
SW_CONDITIONS_NOT_SATISFIED
Incorrect data
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] edSignAlgo
: edSignAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[in] signature
: signature [4:kSE05x_TAG_5][in] signatureLen
: Length of signature[out] presult
: [0:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_ExchangeSessionData
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy) Se05x_API_ExchangeSessionData
Sets session policies for the current session.
Command to Applet
Field
Value
Description
CLA
0x80 or 0x84
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SESSION_POLICY
See P2
Lc
#(Payload)
Payload length.
Payload
TLV[TAG_1]
Session policies
C-MAC
If applicable
Le
0x00
R-APDU Body
Value
Description
R-MAC
Optional, depending on established security level
SW
Description
SW_NO_ERROR
The command is handled successfully.
SW_CONDITIONS_NOT_SATISFIED
Invalid policies
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] policy
: Check pdf [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_ExportObject
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_RSAKeyComponent_t rsaKeyComp, uint8_t *data, size_t *pdataLen) Se05x_API_ExportObject
Reads a transient Secure Object from SE05X.
Secure Objects can be serialized so the Secure Object can be represented as a byte array. The byte array contains all attributes of the Secure Object, as well as the value (including the secret part!) of the object.
The purpose of the serialization is to be able to allow export and import of Secure Objects. Serialized Secure Objects can be reconstructed so they can be used as a (normal) Secure Object. Any operation like key or file management and crypto operation can only be done on a deserialized Secure Object.
Users can export transient Secure Objects to a non-trusted environment (e.g., host controller). The object must be AESKey, DESKey, RSAKey or ECCKey.
Exported credentials are always encrypted and MAC’ed.
The following steps are taken:
The secure element holds a randomly generated persistent 256-bit AES cipher and an 128-bit AES CMAC key. Both keys do not require user interaction, they are internal to the SE05X .
A Secure Object that is identified for export is serialized. This means the key value as well as all Secure Object attributes are stored as byte array (see Object attributes for attribute details).
The serialized Secure Object is encrypted using AES CBC (no padding) and using the default IV.
A CMAC is applied to the serialized Secure Object + metadata using the AES CMAC key.
The byte array is exported.
An object may only be imported into the store if the SecureObject ID and type are the same as the exported object. Therefore, it is not possible to import if the corresponding object in the applet has been deleted.
NOTES:
The exported object is not deleted automatically.
The timestamp has a 100msec granularity, so it is possible to export multiple times with the same timestamp. The freshness (user input) should avoid duplicate attestation results as the user has to provide different freshness input.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
.P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_EXPORT
See
SE05x_P2_t
Lc
#(Payload)
Payload Length.
TLV[TAG_1]
4-byte object identifier
TLV[TAG_2]
1-byte
SE05x_RSAKeyComponent_t
(only applies to Secure Objects of type RSAKey).Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
Byte array containing exported Secure Object data.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The file is created or updated successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1][in] rsaKeyComp
: rsaKeyComp [2:kSE05x_TAG_2][out] data
: [0:kSE05x_TAG_1][inout] pdataLen
: Length for data
-
smStatus_t
Se05x_API_GetECCurveId
(pSe05xSession_t session_ctx, uint32_t objectID, uint8_t *pcurveId) Se05x_API_GetECCurveId
Get the curve associated with an EC key.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
P1
P1_CURVE
See
SE05x_P1_t
P2
P2_ID
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
1-byte curve identifier (from
SE05x_ECCurve_t
)R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1][out] pcurveId
: [0:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_GetExtVersion
(pSe05xSession_t session_ctx, uint8_t *pappletVersion, size_t *appletVersionLen) Se05x_API_GetExtVersion
Gets the applet extended version information.
This will return 37-byte VersionInfo (including major, minor and patch version of the applet, supported applet features and secure box version).
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_VERSION or P2_VERSION_EXT
See
SE05x_P2_t
Lc
#(Payload)
Le
0x00
Expecting TLV with 7-byte data (when P2 = P2_VERSION) or a TLV with 37 byte data (when P2= P2_VERSION_EXT).
R-APDU Body
Value
Description
TLV[TAG_1]
7-byte
VersionInfoRef
(if P2 = P2_VERSION) or 7-byte VersionInfo followed by 30 bytes extendedFeatureBits (if P2 = P2_VERSION_EXT)R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session contextpappletVersion
: The papplet versionappletVersionLen
: The applet version length
-
smStatus_t
Se05x_API_GetFreeMemory
(pSe05xSession_t session_ctx, SE05x_MemoryType_t memoryType, uint16_t *pfreeMem) Se05x_API_GetFreeMemory
Gets the amount of free memory. MemoryType indicates the type of memory.
The result indicates the amount of free memory. Note that behavior of the function might not be fully linear and can have a granularity of 16 bytes where the applet will typically report the “worst case” amount. For example, when allocating 2 bytes a time, the first report will show 16 bytes being allocated, which remains the same for the next 7 allocations of 2 bytes.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_MEMORY
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
SE05x_MemTyp_t
Le
0x04
Expecting TLV with 2-byte data.
R-APDU Body
Value
Description
TLV[TAG_1]
2 bytes indicating the amount of free memory of the requested memory type. 0x7FFF as response means at least 32768 bytes are available.
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] memoryType
: The memory typepfreeMem
: The pfree memory
-
smStatus_t
Se05x_API_GetRandom
(pSe05xSession_t session_ctx, uint16_t size, uint8_t *randomData, size_t *prandomDataLen) Se05x_API_GetRandom
Gets random data from the SE05X .
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_RANDOM
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
2-byte requested size.
Le
0x00
Expecting random data
R-APDU Body
Value
Description
TLV[TAG_1]
Random data.
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] size
: The sizerandomData
: The random dataprandomDataLen
: The prandom data length
-
smStatus_t
Se05x_API_GetTimestamp
(pSe05xSession_t session_ctx, SE05x_TimeStamp_t *ptimeStamp) Se05x_API_GetTimestamp
Gets a monotonic counter value (time stamp) from the operating system of the device (both persistent and transient part). See TimestampFunctionality for details on the timestamps.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_TIME
See
SE05x_P2_t
Lc
#(Payload)
Le
0x2C
Expecting TLV with timestamp.
R-APDU Body
Value
Description
TLV[TAG_1]
TLV containing a 12-byte operating system timestamp.
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session contextptimeStamp
: The ptime stamp
-
smStatus_t
Se05x_API_GetVersion
(pSe05xSession_t session_ctx, uint8_t *pappletVersion, size_t *appletVersionLen) Se05x_API_GetVersion
Gets the applet version information.
This will return 7-byte VersionInfo (including major, minor and patch version of the applet, supported applet features and secure box version).
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_VERSION or P2_VERSION_EXT
See
SE05x_P2_t
Lc
#(Payload)
Le
0x00
Expecting TLV with 7-byte data (when P2 = P2_VERSION) or a TLV with 37 byte data (when P2= P2_VERSION_EXT).
R-APDU Body
Value
Description
TLV[TAG_1]
7-byte
VersionInfoRef
(if P2 = P2_VERSION) or 7-byte VersionInfo followed by 30 bytes extendedFeatureBits (if P2 = P2_VERSION_EXT)R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session contextpappletVersion
: The papplet versionappletVersionLen
: The applet version length
-
smStatus_t
Se05x_API_HKDF
(pSe05xSession_t session_ctx, uint32_t hmacID, SE05x_DigestMode_t digestMode, const uint8_t *salt, size_t saltLen, const uint8_t *info, size_t infoLen, uint16_t deriveDataLen, uint8_t *hkdfOuput, size_t *phkdfOuputLen) Se05x_API_HKDF
Note that this KDF is equal to the KDF in Feedback Mode described in [NIST SP800-108] with the PRF being HMAC with SHA256 and with an 8-bit counter at the end of the iteration variable.
The full HKDF algorithm is executed, i.e. Extract-And-Expand.
The caller must provide a salt length (0 up to 64 bytes). If salt length equals 0 or salt is not provided as input, the default salt will be used.
The output of the HKDF functions can be either:
send back to the caller => precondition : none of the input Secure Objects -if present- shall have a policy POLICY_OBJ_FORBID_DERIVED_OUTPUT set.
be stored in a Secure Object => precondition : the Secure Object must be created upfront and the size must exactly match the expected length.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_HKDF
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte HMACKey identifier (= IKM)
TLV[TAG_2]
1-byte DigestMode (except DIGEST_NO_HASH)
TLV[TAG_3]
Byte array (0-64 bytes) containing salt. [Optional] [Conditional: only when TLV[TAG_6] is absent.]
TLV[TAG_4]
Info: The context and information to apply (1 to 80 bytes). [Optional]
TLV[TAG_5]
2-byte requested length (L): 1 up to MAX_APDU_PAYLOAD_LENGTH
TLV[TAG_6]
4-byte HMACKey identifier containing salt. [Optional] [Conditional: only when TLV[TAG_3] is absent]
TLV[TAG_7]
4-byte HMACKey identifier to store output. [Optional]
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
HKDF output. [Conditional: only when the input does not contain TLV[TAG-7]]
R-APDU Trailer
SW
Description
SW_NO_ERROR
The HKDF is executed successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] hmacID
: hmacID [1:kSE05x_TAG_1][in] digestMode
: digestMode [2:kSE05x_TAG_2][in] salt
: salt [3:kSE05x_TAG_3][in] saltLen
: Length of salt[in] info
: info [4:kSE05x_TAG_4][in] infoLen
: Length of info[in] deriveDataLen
: 2-byte requested length (L) [5:kSE05x_TAG_5][out] hkdfOuput
: [0:kSE05x_TAG_1][inout] phkdfOuputLen
: Length for hkdfOuput
-
smStatus_t
Se05x_API_I2CM_ExecuteCommandSet
(pSe05xSession_t session_ctx, const uint8_t *inputData, size_t inputDataLen, uint32_t attestationID, uint8_t attestationAlgo, uint8_t *response, size_t *presponseLen, SE05x_TimeStamp_t *ptimeStamp, uint8_t *freshness, size_t *pfreshnessLen, uint8_t *chipId, size_t *pchipIdLen, uint8_t *signature, size_t *psignatureLen, uint8_t *randomAttst, size_t randomAttstLen) Se05x_API_I2CM_ExecuteCommandSet
Execute one or multiple I2C commands in master mode. Execution is conditional to the presence of the authentication object identified by RESERVED_ID_I2CM_ACCESS. If the credential is not present in the eSE, access is allowed in general. Otherwise, a session shall be established before executing this command. In this case, the I2CM_ExecuteCommandSet command shall be sent within the mentioned session.
The I2C command set is constructed as a sequence of instructions described in with the following rules:
The length should be limited to MAX_I2CM_COMMAND_LENGTH.
The data to be read cannot exceed MAX_I2CM_COMMAND_LENGTH, including protocol overhead.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
See
SE05x_INS_t
, in addition to INS_CRYPTO, users can set the INS_ATTEST flag. In that case, attestation applies.P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_I2CM
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
Byte array containing I2C Command set as TLV array.
TLV[TAG_2]
4-byte attestation object identifier. [Optional] [Conditional: only when INS_ATTEST is set]
TLV[TAG_3]
1-byte
SE05x_AttestationAlgo_t
[Optional] [Conditional: only when INS_ATTEST is set]TLV[TAG_7]
16-byte freshness random [Optional] [Conditional: only when INS_ATTEST is set]
Le
0x00
Expecting TLV with return data.
R-APDU Body
Value
Description
TLV[TAG_1]
Read response, a bytestring containing a sequence of: * CONFIGURE (0x01), followed by 1 byte of return code (0x5A = SUCCESS). * WRITE (0x03), followed by 1 byte of return code * READ (0x04), followed by - Length: 2 bytes in big endian encoded without TLV length encoding - Read bytes * 0xFF followed by the error return code in case of a structural error of the incoming buffer (too long, for example)
TLV[TAG_3]
TLV containing 12-byte timestamp
TLV[TAG_4]
TLV containing 16-byte freshness (random)
TLV[TAG_5]
TLV containing 18-byte chip unique ID
TLV[TAG_6]
TLV containing signature over the concatenated values of TLV[TAG_1], TLV[TAG_3], TLV[TAG_4] and TLV[TAG_5].
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] inputData
: The input data[in] inputDataLen
: The input data length[in] attestationID
: The attestation id[in] attestationAlgo
: The attestation algorithmresponse
: The responsepresponseLen
: The presponse lengthptimeStamp
: The ptime stampfreshness
: The freshnesspfreshnessLen
: The pfreshness lengthchipId
: The chip identifierpchipIdLen
: The pchip identifier lengthsignature
: The signaturepsignatureLen
: The psignature lengthrandomAttst
: The random attst[in] randomAttstLen
: The random attst length
-
smStatus_t
Se05x_API_ImportExternalObject
(pSe05xSession_t session_ctx, const uint8_t *ECKeydata, size_t ECKeydataLen, const uint8_t *ECAuthKeyID, size_t ECAuthKeyIDLen, const uint8_t *serializedObject, size_t serializedObjectLen) Se05x_API_ImportExternalObject
Combined with the INS_IMPORT_EXTERNAL mask, enables users to send a WriteSecureObject APDU (WriteECKey until WritePCR) protected by a secure channel.
Secure Objects can be imported into the SE05X through a secure channel which does not require the establishment of a session. This feature is also referred to single side import and can only be used to create or update objects.
The mechanism is based on ECKey session to protect the Secure Object content and is summarized in the following figure.
External import flow
The flow above can be summarized in the following steps:
The user obtains the SE public key for import via the to get the public key from the device’s key pair. Key ID 0x02 will return the public key of the EC key pair with RESERVED_ID_EXTERNAL_IMPORT. The response is signed by the same key pair.
The user calls with input:
the applet AID (e.g.A0000003965453000000010300000000)
the SCPparameters
1-byte SCP identifier, must equal0xAB
2-byte SCP parameter, must equal 0x01 followed by 1-byte security level (which follows the GlobalPlatform security level definition, see: .
key type, must be 0x88 (AES keytype)
key length, must be 0x10 (AES128key)
host public key (65-byte NIST P-256 publickey)
host public key curve identifier (must be 0x03 (=NIST_P256))
ASN.1 signature over the TLV with tags 0xA6 and0x7F49.
The applet will then calculate the master key by performing SHA256 over a byte array containing (in order):
4-byte counter value being0x00000001
shared secret (ECDH calculation according [IEEE P1363] using the private keyfrom RESERVED_ID_ECKEY_SESSION and the public key provided as input to ECKeySessionInternalAuthenticate. The length depends on the curve used (e.g. 32 byte for NIST P-256 curve).
16-byte random generated by the SE05X.
2-byte SCP parameter, must equal 0x01 followed by 1-byte security level (which follows the GlobalPlatform security level definition, see: .
1-byte keytype
1-byte keylength
The master key will then be the 16 MSB’s of the hash output.
Using the master key, the 3 session keys are derived by following the GlobalPlatform specification to derive session keys, e.g. derivation input:
ENCsession key = CMAC(MK, 00000000000000000000000400008001)
CMACsession key = CMAC(MK, 00000000000000000000000600008001)
RMACsession key = CMAC(MK, 00000000000000000000000700008001)
The Authentication Object ID needs to be passed using TAG_IMPORT_AUTH_KEY_ID, followed by the Write APDU command (using tag TAG_1).
The Write APDU command needs to be constructed as follows:
Encrypt the command encryption counter (starting with 0x00000000000000000000000000000001) using the S_ENC key. This becomes the IV for the encrypted APDU.
Get the APDU command payload and pad it (ISO9797 M2 padding).
Encrypt the payload in AES CBC mode using the S_ENC key.
Set the Secure Messaging bit in the CLA (0x04).
Concatenate the MAC chaining value with the full APDU.
Then calculate the MAC on this byte array and append the 8-byte MAC value to the APDU.
Finally increment the encryption counter for the next command.
A receipt will be generated by doing a CMAC operation on the input from tag 0xA6 and 0x7F49 using the RMAC session key,
Receipt = CMAC(RMAC session key, <input from TLV 0xA6 and TLV 0x7F49>)
There is no need to establish a session; therefore, the ImportExternalObject commands are always sent in the default session. The ImportExternalObject commands are replayable.
The P1 and P2 parameters shall be coded as per the intended operation. For example, to import an EC Key, the P1 and P2 parameters as defined in WriteECKey shall be specified.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_IMPORT_EXTERNAL
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_IMPORT_AUTH_DATA]
Authentication data
TLV[TAG_IMPORT_AUTH_KEY_ID]
Host public key Identifier
TLV[TAG_1]…
Wraps a complete WriteSecureObject command, protected by ECKey session secure messaging
TLV[TAG_11]
4-byte version [Optional]
R-APDU Body
NA
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] ECKeydata
: ECKeydata [1:kSE05x_TAG_2][in] ECKeydataLen
: Length of ECKeydata[in] serializedObject
: serializedObject [2:kSE05x_TAG_3][in] serializedObjectLen
: Length of serializedObject
-
smStatus_t
Se05x_API_ImportObject
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_RSAKeyComponent_t rsaKeyComp, const uint8_t *serializedObject, size_t serializedObjectLen) Se05x_API_ImportObject
Writes a serialized Secure Object to the SE05X (i.e., “import”)
Command to Applet
Field
Value
Description
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_IMPORT
See
SE05x_P2_t
Payload
TLV[TAG_1]
4-byte identifier.
TLV[TAG_2]
1-byte
SE05x_RSAKeyComponent_t
[Conditional: only when the identifier refers to an RSAKey object]TLV[TAG_3]
Serialized object (encrypted).
R-APDU Body
NA
R-APDU Trailer
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1][in] rsaKeyComp
: rsaKeyComp [2:kSE05x_TAG_2][in] serializedObject
: serializedObject [3:kSE05x_TAG_3][in] serializedObjectLen
: Length of serializedObject
-
smStatus_t
Se05x_API_IncCounter
(pSe05xSession_t session_ctx, uint32_t objectID) Se05x_API_IncCounter
See Se05x_API_CreateCounter
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_MACFinal
(pSe05xSession_t session_ctx, const uint8_t *inputData, size_t inputDataLen, SE05x_CryptoObjectID_t cryptoObjectID, const uint8_t *macValidateData, size_t macValidateDataLen, uint8_t *macValue, size_t *pmacValueLen) Se05x_API_MACFinal
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_MAC
See
SE05x_P1_t
P2
P2_FINAL
See
SE05x_P2_t
Payload
TLV[TAG_1]
Byte array containing data to be taken as input to MAC.
TLV[TAG_2]
2-byte Crypto Object identifier
TLV[TAG_3]
Byte array containing MAC to validate. [Conditional: only applicable the crypto object is set for validating (MACInit P2 = P2_VALIDATE)]
Le
0x00
Expecting MAC or result.
R-APDU Body
Value
Description
TLV[TAG_1]
MAC value (when MACInit had P2 = P2_GENERATE) or
SE05x_Result_t
(when MACInit had P2 = P2_VERIFY).R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] inputData
: inputData [1:kSE05x_TAG_1][in] inputDataLen
: Length of inputData[in] cryptoObjectID
: cryptoObjectID [2:kSE05x_TAG_2][in] macValidateData
: macValidateData [3:kSE05x_TAG_3][in] macValidateDataLen
: Length of macValidateData[out] macValue
: [0:kSE05x_TAG_1][inout] pmacValueLen
: Length for macValue
-
smStatus_t
Se05x_API_MACInit
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_CryptoObjectID_t cryptoObjectID, const SE05x_Mac_Oper_t mac_oper) Se05x_API_MACInit
Initiate a MAC operation. The state of the MAC operation is kept in the Crypto Object until it’s finalized or deleted.
The 4-byte identifier of the key must refer to an AESKey, DESKey or HMACKey.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_MAC
See
SE05x_P1_t
P2
P2_GENERATE or P2_VALIDATE
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the MAC key.
TLV[TAG_2]
2-byte Crypto Object identifier
Le
0x00
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] cryptoObjectID
: cryptoObjectID [2:kSE05x_TAG_2][in] mac_oper
: The Operation
-
smStatus_t
Se05x_API_MACOneShot_G
(pSe05xSession_t session_ctx, uint32_t objectID, uint8_t macOperation, const uint8_t *inputData, size_t inputDataLen, uint8_t *macValue, size_t *pmacValueLen) Se05x_API_MACOneShot_G
Generate. See Se05x_API_MACOneShot_V for Verfiication.
Performs a MAC operation in one shot (without keeping state).
The 4-byte identifier of the key must refer to an AESKey, DESKey or HMACKey.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_MAC
See
SE05x_P1_t
P2
P2_GENERATE_ONESHOT or P2_VALIDATE_ONESHOT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the key object.
TLV[TAG_2]
1-byte
MACAlgoRef
TLV[TAG_3]
Byte array containing data to be taken as input to MAC.
TLV[TAG_5]
MAC to verify (when P2=P2_VALIDATE_ONESHOT)
Le
0x00
Expecting MAC or Result.
R-APDU Body
Value
Description
TLV[TAG_1]
MAC value (P2=P2_GENERATE_ONESHOT) or
SE05x_Result_t
(when p2=P2_VALIDATE_ONESHOT).R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] macOperation
: macOperation [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] macValue
: [0:kSE05x_TAG_1][inout] pmacValueLen
: Length for macValue
-
smStatus_t
Se05x_API_MACOneShot_V
(pSe05xSession_t session_ctx, uint32_t objectID, uint8_t macOperation, const uint8_t *inputData, size_t inputDataLen, const uint8_t *MAC, size_t MACLen, uint8_t *result, size_t *presultLen) Se05x_API_MACOneShot_V
Validate. See Se05x_API_MACOneShot_G for Generation.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] macOperation
: macOperation [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[in] MAC
: MAC to verify (when P2=P2_VALIDATE_ONESHOT) [4:kSE05x_TAG_5][in] MACLen
: Length of MAC[out] result
: [0:kSE05x_TAG_1][inout] presultLen
: Length for result
-
smStatus_t
Se05x_API_MACUpdate
(pSe05xSession_t session_ctx, const uint8_t *inputData, size_t inputDataLen, SE05x_CryptoObjectID_t cryptoObjectID) Se05x_API_MACUpdate
Update MAC
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_MAC
See
SE05x_P1_t
P2
P2_UPDATE
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
Byte array containing data to be taken as input to MAC.
TLV[TAG_2]
2-byte Crypto Object identifier
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] inputData
: inputData [1:kSE05x_TAG_1][in] inputDataLen
: Length of inputData[in] cryptoObjectID
: cryptoObjectID [2:kSE05x_TAG_2]
-
smStatus_t
Se05x_API_PBKDF2
(pSe05xSession_t session_ctx, uint32_t objectID, const uint8_t *salt, size_t saltLen, uint16_t count, uint16_t requestedLen, uint8_t *derivedSessionKey, size_t *pderivedSessionKeyLen) Se05x_API_HKDF_Extended
Only step 2 of the algorithm is executed, i.e. Expand only.
Using an IV as input parameter results in a FIPS compliant SP800-108 KDF in Feedback Mode where K[0] is the provided IV. This KDF is then using a 8-bit counter, AFTER_FIXED counter location.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_HKDF_EXPAND_ONLY
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte HMACKey identifier (= PRK)
TLV[TAG_2]
1-byte DigestMode (except DIGEST_NO_HASH)
TLV[TAG_3]
Byte array (0-64 bytes) containing IV. [Optional] [Conditional: only when TLV[TAG_6] is absent.]
TLV[TAG_4]
Info: The context and information to apply (1 to 80 bytes). [Optional]
TLV[TAG_5]
2-byte requested length (L): 1 up to MAX_APDU_PAYLOAD_LENGTH
TLV[TAG_6]
4-byte HMACKey identifier containing IV. [Optional] [Conditional: only when TLV[TAG_3] is absent]
TLV[TAG_7]
4-byte HMACKey identifier to store output. [Optional]
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
HKDF output. [Conditional: only when the input does not contain TLV[TAG-7]]
R-APDU Trailer
SW
Description
SW_NO_ERROR
The HKDF is executed successfully.
/
- smStatus_t Se05x_API_HKDF_Extended(pSe05xSession_t session_ctx,
uint32_t hmacID, SE05x_DigestMode_t digestMode, SE05x_HkdfMode_t hkdfMode, const uint8_t salt, size_t saltLen, uint32_t saltID, const uint8_t info, size_t infoLen, uint32_t derivedKeyID, uint16_t deriveDataLen, uint8_t hkdfOuput, size_t phkdfOuputLen);
/ * Se05x_API_PBKDF2
Password Based Key Derivation Function 2 (PBKDF2) according [RFC8018].
The password is an input to the KDF and must be stored inside the .
The output is returned to the host.
# Command to Applet
verbatim embed:rst:leading-asterisk +——-+————+———————————————-+ | Field | Value | Description | +=======+============+==============================================+ | CLA | 0x80 | | +——-+————+———————————————-+ | INS | INS_CRYPTO |
SE05x_INS_t
| +——-+————+———————————————-+ | P1 | P1_DEFAULT | SeeSE05x_P1_t
| +——-+————+———————————————-+ | P2 | P2_PBKDF | SeeSE05x_P2_t
| +——-+————+———————————————-+ | Lc | #(Payload) | | +——-+————+———————————————-+ | | TLV[TAG_1] | 4-byte password identifier (object type must | | | | be HMACKey) | +——-+————+———————————————-+ | | TLV[TAG_2] | Salt (0 to 64 bytes) [Optional] | +——-+————+———————————————-+ | | TLV[TAG_3] | 2-byte Iteration count: 1 up to 0x7FFF. | +——-+————+———————————————-+ | | TLV[TAG_4] | 2-byte Requested length: 1 up to 512 bytes. | +——-+————+———————————————-+ | Le | 0x00 | Expecting derived key material. | +——-+————+———————————————-+R-APDU Body
Value
Description
TLV[TAG_1]
Derived key material (session key).
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: 4-byte password identifier (object type must be HMACKey) [1:kSE05x_TAG_1][in] salt
: salt [2:kSE05x_TAG_2][in] saltLen
: Length of salt[in] count
: count [3:kSE05x_TAG_3][in] requestedLen
: requestedLen [4:kSE05x_TAG_4][out] derivedSessionKey
: [0:kSE05x_TAG_1][inout] pderivedSessionKeyLen
: Length for derivedSessionKey
-
smStatus_t
Se05x_API_PBKDF2_extended
(pSe05xSession_t session_ctx, uint32_t objectID, const uint8_t *salt, size_t saltLen, uint32_t saltID, uint16_t count, SE05x_MACAlgo_t macAlgo, uint16_t requestedLen, uint32_t derivedSessionKeyID, uint8_t *derivedSessionKey, size_t *pderivedSessionKeyLen) Se05x_API_PBKDF2_extended
See Se05x_API_PBKDF2_extended. New PBKDF2 api with optional salt object id and optional derived Session key id. This api also supports additional mac algorithms.
- Parameters
[in] session_ctx
: The session context[in] objectID
: HMAC key object id[in] salt
: Salt data[in] saltLen
: Salt length[in] saltID
: Object id with salt data[in] macAlgo
: MAC Algorithm[in] requestedLen
: Requested derived session key length[inout] derivedSessionKeyID
: HMAC object id to store output derived session key[inout] derivedSessionKey
: Buffer to store derived session key on host[inout] pderivedSessionKeyLen
: DerivedSessionKey buffer length
-
smStatus_t
Se05x_API_ReadCryptoObjectList
(pSe05xSession_t session_ctx, uint8_t *idlist, size_t *pidlistLen) Se05x_API_ReadCryptoObjectList
Get the list of allocated Crypto Objects indicating the identifier, the CryptoContext and the sub type of the CryptoContext.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
P1
P1_CRYPTO_OBJ
See
SE05x_P1_t
P2
P2_LIST
See
SE05x_P2_t
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
Byte array containing a list of 2-byte Crypto Object identifiers, followed by 1-byte CryptoContext and 1-byte subtype for each Crypto Object (so 4 bytes for each Crypto Object).
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][out] idlist
: If more ids are present [0:kSE05x_TAG_1][inout] pidlistLen
: Length for idlist
-
smStatus_t
Se05x_API_ReadECCurveList
(pSe05xSession_t session_ctx, uint8_t *curveList, size_t *pcurveListLen) Se05x_API_ReadECCurveList
Get a list of (Weierstrass) EC curves that are instantiated.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
P1
P1_CURVE
See
SE05x_P1_t
P2
P2_LIST
See
SE05x_P2_t
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
Byte array listing all curve identifiers in
SE05x_ECCurve_t
(excluding UNUSED) where the curve identifier < 0x40; for each curve, a 1-byteSetIndicatorRef
is returned.R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][out] curveList
: [0:kSE05x_TAG_1][inout] pcurveListLen
: Length for curveList
-
smStatus_t
Se05x_API_ReadIDList
(pSe05xSession_t session_ctx, uint16_t outputOffset, uint8_t filter, uint8_t *pmore, uint8_t *idlist, size_t *pidlistLen) Se05x_API_ReadIDList
Get a list of present Secure Object identifiers.
The offset in TAG_1 is an 0-based offset in the list of object. As the user does not know how many objects would be returned, the offset needs to be based on the return values from the previous ReadIDList. If the applet only returns a part of the result, it will indicate that more identifiers are available (by setting TLV[TAG_1] in the response to 0x01). The user can then retrieve the next chunk of identifiers by calling ReadIDList with an offset that equals the amount of identifiers listed in the previous response.
Example 1: first ReadIDList command TAG_1=0, response TAG_1=0, TAG_2=complete list
Example 2: first ReadIDList command TAG_1=0, response TAG_1=1, TAG_2=first chunk (m entries) second ReadIDList command TAG_1=m, response TAG_1=1, TAG_2=second chunk (n entries) thirst ReadIDList command TAG_1=(m+n), response TAG_1=0, TAG_2=third last chunk
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_LIST
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
2-byte offset
TLV[TAG_2]
1-byte type filter: 1 byte from
SE05x_SecObjTyp_t
or 0xFF for all types.Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
1-byte
MoreIndicatorRef
TLV[TAG_2]
Byte array containing 4-byte identifiers.
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] outputOffset
: output offset [1:kSE05x_TAG_1][in] filter
: filter [2:kSE05x_TAG_2][out] pmore
: If more ids are present [0:kSE05x_TAG_1][out] idlist
: Byte array containing 4-byte identifiers [1:kSE05x_TAG_2][inout] pidlistLen
: Length for idlist
-
smStatus_t
Se05x_API_ReadObject
(pSe05xSession_t session_ctx, uint32_t objectID, uint16_t offset, uint16_t length, uint8_t *data, size_t *pdataLen) Se05x_API_ReadObject
Reads the content of a Secure Object.
If the object is a key pair, the command will return the key pair’s public key.
If the object is a public key, the command will return the public key.
If the object is a private key or a symmetric key or a userID, the command will return SW_CONDITIONS_NOT_SATISFIED.
If the object is a binary file, the file content is read, giving the offset in TLV[TAG_2] and the length to read in TLV[TAG_3]. Both TLV[TAG_2] and TLV[TAG_3] are bound together; i.e.. either both tags are present, or both are absent. If both are absent, the whole file content is returned.
If the object is a monotonic counter, the counter value is returned.
If the object is a PCR, the PCR value is returned.
If TLV[TAG_4] is filled, only the modulus or public exponent of an RSA key pair or RSA public key is read. It does not apply to other Secure Object types.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
, in addition to INS_READ, users can set the INS_ATTEST flag. In that case, attestation applies.P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Lc
#(Payload)
Payload Length.
TLV[TAG_1]
4-byte object identifier
TLV[TAG_2]
2-byte offset [Optional: default 0] [Conditional: only when the object is a BinaryFile object]
TLV[TAG_3]
2-byte length [Optional: default 0] [Conditional: only when the object is a BinaryFile object]
TLV[TAG_4]
1-byte
SE05x_RSAKeyComponent_t
: either RSA_COMP_MOD or RSA_COMP_PUB_EXP. [Optional] [Conditional: only for RSA key components]Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
Data read from the secure object.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The read is done successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1][in] offset
: offset [2:kSE05x_TAG_2][in] length
: length [3:kSE05x_TAG_3][out] data
: [0:kSE05x_TAG_1][inout] pdataLen
: Length for data
-
smStatus_t
Se05x_API_ReadObject_W_Attst
(pSe05xSession_t session_ctx, uint32_t objectID, uint16_t offset, uint16_t length, uint32_t attestID, SE05x_AttestationAlgo_t attestAlgo, const uint8_t *random, size_t randomLen, uint8_t *data, size_t *pdataLen, uint8_t *attribute, size_t *pattributeLen, SE05x_TimeStamp_t *ptimeStamp, uint8_t *outrandom, size_t *poutrandomLen, uint8_t *chipId, size_t *pchipIdLen, uint8_t *signature, size_t *psignatureLen)
-
smStatus_t
Se05x_API_ReadObject_W_Attst_V2
(pSe05xSession_t session_ctx, uint32_t objectID, uint16_t offset, uint16_t length, uint32_t attestID, SE05x_AttestationAlgo_t attestAlgo, const uint8_t *random, size_t randomLen, uint8_t *data, size_t *pdataLen, uint8_t *attribute, size_t *pattributeLen, SE05x_TimeStamp_t *ptimeStamp, uint8_t *chipId, size_t *pchipIdLen, uint8_t *pCmd, size_t *pCmdLen, uint8_t *pObj, size_t *pObjLen, uint8_t *signature, size_t *psignatureLen) Se05x_API_ReadObject_W_Attst
Read with attestation.
See Se05x_API_ReadObject
When INS_ATTEST is set in addition to INS_READ, the secure object is read with attestation. In addition to the response in TLV[TAG_1], there are additional tags:
TLV[TAG_2] will hold the object attributes (see ObjectAttributes).
TLV[TAG_3] relative timestamp when the object has been retrieved
TLV[TAG_4] will hold freshness random data
TLV[TAG_5] will hold the unique ID of the device.
TLV[TAG_6] will hold the signature over all concatenated Value fields tags of the response (TAG_1 until and including TAG_5).
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
, in addition to INS_READ, users can set the INS_ATTEST flag. In that case, attestation applies.P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Lc
#(Payload)
Payload Length.
TLV[TAG_1]
4-byte object identifier
TLV[TAG_2]
2-byte offset [Optional: default 0] [Conditional: only when the object is a BinaryFile object]
TLV[TAG_3]
2-byte length [Optional: default 0] [Conditional: only when the object is a BinaryFile object]
TLV[TAG_4]
1-byte
SE05x_RSAKeyComponent_t
: either RSA_COMP_MOD or RSA_COMP_PUB_EXP. [Optional] [Conditional: only for RSA key components]TLV[TAG_5]
4-byte attestation object identifier. [Optional] [Conditional: only when INS_ATTEST is set]
TLV[TAG_6]
1-byte
SE05x_AttestationAlgo_t
[Optional] [Conditional: only when INS_ATTEST is set]TLV[TAG_7]
16-byte freshness random [Optional] [Conditional: only when INS_ATTEST is set]
Le
0x00
Value
Description
TLV[TAG_1]
Data read from the secure object.
TLV[TAG_2]
(only when INS_ATTEST is set) Byte array containing the attributes (see
ObjectAttributesRef
).TLV[TAG_3]
(only when INS_ATTEST is set) 12-byte timestamp
TLV[TAG_4]
(only when INS_ATTEST is set) 16-byte freshness random
TLV[TAG_5]
(only when INS_ATTEST is set) 18-byte Chip unique ID
TLV[TAG_6]
(only when INS_ATTEST is set) Signature applied over the value of TLV[TAG_1], TLV[TAG_2], TLV[TAG_3], TLV[TAG_4] and TLV[TAG_5].
R-APDU Body
Value
Description
TLV[TAG_1]
Data read from the secure object.
TLV[TAG_2]
(only when INS_ATTEST is set) Byte array containing the attributes (see
ObjectAttributesRef
).TLV[TAG_3]
(only when INS_ATTEST is set) 12-byte timestamp
TLV[TAG_4]
(only when INS_ATTEST is set) 16-byte freshness random
TLV[TAG_5]
(only when INS_ATTEST is set) 18-byte Chip unique ID
TLV[TAG_6]
(only when INS_ATTEST is set) Signature applied over the value of TLV[TAG_1], TLV[TAG_2], TLV[TAG_3], TLV[TAG_4] and TLV[TAG_5].
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object id[in] offset
: The offset[in] length
: The length[in] attestID
: The attest id[in] attestAlgo
: The attest algorithm[in] random
: The random[in] randomLen
: The random lengthdata
: The datapdataLen
: The pdata lengthattribute
: The attributepattributeLen
: The pattribute lengthptimeStamp
: The ptime stampoutrandom
: The outrandompoutrandomLen
: The poutrandom lengthchipId
: The chip identifierpchipIdLen
: The pchip identifier lengthsignature
: The signaturepsignatureLen
: The psignature length
-
smStatus_t
Se05x_API_ReadObjectAttributes
(pSe05xSession_t session_ctx, uint32_t objectID, uint8_t *data, size_t *pdataLen) Se05x_API_ReadObjectAttributes
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1][out] data
: [0:kSE05x_TAG_2][inout] pdataLen
: Length for data
-
smStatus_t
Se05x_API_ReadObjectAttributes_W_Attst
(pSe05xSession_t session_ctx, uint32_t objectID, uint32_t attestID, SE05x_AttestationAlgo_t attestAlgo, const uint8_t *random, size_t randomLen, uint8_t *data, size_t *pdataLen, SE05x_TimeStamp_t *ptimeStamp, uint8_t *outrandom, size_t *poutrandomLen, uint8_t *chipId, size_t *pchipIdLen, uint8_t *signature, size_t *psignatureLen) Se05x_API_ReadObjectAttributes_W_Attst
Reads the attributes of a Secure Object (without the value of the Secure Object).
Each Secure Object has a number of attributes assigned to it. These attributes are listed in for Authentication Objects and in for non-Authentication Objects.
Authentication Object attributes
Attribute
Size (bytes)
Description
Object identifier
4
See
identifiersRef
Object type
1
One of SecureObjectType
Authentication attribute
1
One of
SetIndicatorRef
Object counter
2
Number of failed attempts for an authentication object if the Maximum Authentication Attempts has been set.
Authentication object identifier
4
”Owner” of the secure object; i.e., the identifier of the session authentication object when the object has been created.
Maximum authentication attempts
2
Maximum number of authentication attempts. 0 means unlimited.
Policy
Variable
Policy attached to the object
Origin
1
One of
OriginRef
; indicates the origin of the Secure Object, either externally set, internally generated or trust provisioned by NXP.Version
1
The Secure Object version. Default = 0. See FIPS compliance for details about versioning of Secure Objects.
Non-Authentication Objects
Attribute
Size (bytes)
Description
Object identifier
4
See Object identifiers
Object type
1
One of SecureObjectType
Authentication attribute
1
One of
SetIndicatorRef
Tag length
2
Set to 0x0000, except for AESKey objects: for AESKey objects, this indicates the GMAC length that applies when doing AEAD operations. If the value is set to 0 and AEAD operations are done, the GMAC length shall be 128 bit.
Authentication object identifier
4
”Owner” of the secure object; i.e., the identifier of the session authentication object when the object has been created.
RFU
2
Set to 0x0000.
Policy
Variable
Policy attached to the object
Origin
1
One of
OriginRef
; indicates the origin of the Secure Object, either externally set, internally generated or trust provisioned by NXP.Version
1
The Secure Object version. Default = 0. See FIPS compliance for details about versioning of Secure Objects.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
, in addition to INS_READ, users can set the INS_ATTEST flag. In that case, attestation applies.P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_ATTRIBUTES
See
SE05x_P2_t
Lc
#(Payload)
Payload Length.
TLV[TAG_1]
4-byte object identifier
TLV[TAG_5]
4-byte attestation object identifier. [Optional] [Conditional: only when INS_ATTEST is set]
TLV[TAG_6]
1-byte AttestationAlgo [Optional] [Conditional: only when INS_ATTEST is set]
TLV[TAG_7]
16-byte freshness random [Optional] [Conditional: only when INS_ATTEST is set]
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_2]
Byte array containing the attributes (see Object Attributes).
TLV[TAG_3]
(only when INS_ATTEST is set) 12-byte timestamp
TLV[TAG_4]
(only when INS_ATTEST is set) 16-byte freshness random
TLV[TAG_5]
(only when INS_ATTEST is set) 18-byte Chip unique ID
TLV[TAG_6]
(only when INS_ATTEST is set) Signature applied over the value of TLV[TAG_2], TLV[TAG_2], TLV[TAG_3], TLV[TAG_4] and TLV[TAG_5].
R-APDU Trailer
SW
Description
SW_NO_ERROR
The read is done successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object id[in] attestID
: The attest id[in] attestAlgo
: The attest algorithm[in] random
: The random[in] randomLen
: The random lengthdata
: The datapdataLen
: The pdata lengthptimeStamp
: The ptime stampoutrandom
: The outrandompoutrandomLen
: The poutrandom lengthchipId
: The chip identifierpchipIdLen
: The pchip identifier lengthsignature
: The signaturepsignatureLen
: The psignature length
-
smStatus_t
Se05x_API_ReadRSA
(pSe05xSession_t session_ctx, uint32_t objectID, uint16_t offset, uint16_t length, SE05x_RSAPubKeyComp_t rsa_key_comp, uint8_t *data, size_t *pdataLen) Se05x_API_ReadRSA
See Se05x_API_ReadObject
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1][in] offset
: offset [2:kSE05x_TAG_2][in] length
: length [3:kSE05x_TAG_3][in] rsa_key_comp
: rsa_key_comp [4:kSE05x_TAG_4][out] data
: [0:kSE05x_TAG_1][inout] pdataLen
: Length for data
-
smStatus_t
Se05x_API_ReadRSA_W_Attst
(pSe05xSession_t session_ctx, uint32_t objectID, uint16_t offset, uint16_t length, SE05x_RSAPubKeyComp_t rsa_key_comp, uint32_t attestID, SE05x_AttestationAlgo_t attestAlgo, const uint8_t *random, size_t randomLen, uint8_t *data, size_t *pdataLen, uint8_t *attribute, size_t *pattributeLen, SE05x_TimeStamp_t *ptimeStamp, uint8_t *outrandom, size_t *poutrandomLen, uint8_t *chipId, size_t *pchipIdLen, uint8_t *signature, size_t *psignatureLen) Se05x_API_ReadRSA_W_Attst
See Se05x_API_ReadObject_W_Attst
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object id[in] offset
: The offset[in] length
: The length[in] rsa_key_comp
: The rsa key component[in] attestID
: The attest id[in] attestAlgo
: The attest algorithm[in] random
: The random[in] randomLen
: The random lengthdata
: The datapdataLen
: The pdata lengthattribute
: The attributepattributeLen
: The pattribute lengthptimeStamp
: The ptime stampoutrandom
: The outrandompoutrandomLen
: The poutrandom lengthchipId
: The chip identifierpchipIdLen
: The pchip identifier lengthsignature
: The signaturepsignatureLen
: The psignature length
-
smStatus_t
Se05x_API_ReadSize
(pSe05xSession_t session_ctx, uint32_t objectID, uint16_t *psize) Se05x_API_ReadSize
ReadSize
Get the size of a Secure Object (in bytes):
For EC keys: the size of the curve is returned.
For RSA keys: the key size is returned.
For AES/DES/HMAC keys, the key size is returned.
For binary files: the file size is returned
For userIDs: nothing is returned (SW_CONDITIONS_NOT_SATISFIED).
For counters: the counter length is returned.
For PCR: the PCR length is returned.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SIZE
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte object identifier.
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
Byte array containing size.
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object idpsize
: The psize
-
smStatus_t
Se05x_API_ReadState
(pSe05xSession_t session_ctx, uint8_t *pstateValues, size_t *pstateValuesLen) Se05x_API_ReadState
Command to Applet
R-APDU Body
NA
R-APDU Trailer
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][out] pstateValues
: [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_ReadType
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_SecureObjectType_t *ptype, uint8_t *pisTransient, const SE05x_AttestationType_t attestation_type) Se05x_API_ReadType
Get the type of a Secure Object.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_READ
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_TYPE
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte object identifier.
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
Type of the Secure Object: one of
SE05x_SecObjTyp_t
TLV[TAG_2]
TransientIndicatorRef
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object idptype
: The ptypepisTransient
: The pis transient[in] attestation_type
: The attestation type
-
smStatus_t
Se05x_API_RefreshSession
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy) Se05x_API_RefreshSession
Refreshes a session on , the policy of the running session can be updated; the rest of the session state remains.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SESSION_REFRESH
See
SE05x_P2_t
Lc
#(Payload)
Payload length.
TLV[TAG_POLICY]
Byte array containing the policy to attach to the session. [Optional]
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] policy
: policy [1:kSE05x_TAG_POLICY]
-
smStatus_t
Se05x_API_RSADecrypt
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_RSAEncryptionAlgo_t rsaEncryptionAlgo, const uint8_t *inputData, size_t inputDataLen, uint8_t *decryptedData, size_t *pdecryptedDataLen) Se05x_API_RSADecrypt
The RSADecrypt command decrypts data.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_RSA
See
SE05x_P1_t
P2
P2_DECRYPT_ONESHOT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the key pair or private key.
TLV[TAG_2]
1-byte
SE05x_RSAEncryptionAlgo_t
TLV[TAG_3]
Byte array containing data to be decrypted.
Le
0x00
Expected TLV with decrypted data.
R-APDU Body
Value
Description
TLV[TAG_1]
Encrypted data
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] rsaEncryptionAlgo
: rsaEncryptionAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] decryptedData
: [0:kSE05x_TAG_1][inout] pdecryptedDataLen
: Length for decryptedData
-
smStatus_t
Se05x_API_RSAEncrypt
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_RSAEncryptionAlgo_t rsaEncryptionAlgo, const uint8_t *inputData, size_t inputDataLen, uint8_t *encryptedData, size_t *pencryptedDataLen) Se05x_API_RSAEncrypt
The RSAEncrypt command encrypts data.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_RSA
See
SE05x_P1_t
P2
P2_ENCRYPT_ONESHOT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the key pair or public key.
TLV[TAG_2]
1-byte
SE05x_RSAEncryptionAlgo_t
TLV[TAG_3]
Byte array containing data to be encrypted.
Le
0x00
Expected TLV with encrypted data.
R-APDU Body
Value
Description
TLV[TAG_1]
Encrypted data
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] rsaEncryptionAlgo
: rsaEncryptionAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] encryptedData
: [0:kSE05x_TAG_1][inout] pencryptedDataLen
: Length for encryptedData
-
smStatus_t
Se05x_API_RSASign
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_RSASignatureAlgo_t rsaSigningAlgo, const uint8_t *inputData, size_t inputDataLen, uint8_t *signature, size_t *psignatureLen) Se05x_API_RSASign
The RSASign command signs the input message using an RSA private key.
Name
Value
Description
RSA_SHA1_PKCS1_PSS
0x15
RFC8017: RSASSA-PSS
RSA_SHA224_PKCS1_PSS
0x2B
RFC8017: RSASSA-PSS
RSA_SHA256_PKCS1_PSS
0x2C
RFC8017: RSASSA-PSS
RSA_SHA384_PKCS1_PSS
0x2D
RFC8017: RSASSA-PSS
RSA_SHA512_PKCS1_PSS
0x2E
RFC8017: RSASSA-PSS
RSA_SHA1_PKCS1
0x0A
RFC8017: RSASSA-PKCS1-v1_5
RSA_SHA_224_PKCS1
0x27
RFC8017: RSASSA-PKCS1-v1_5
RSA_SHA_256_PKCS1
0x28
RFC8017: RSASSA-PKCS1-v1_5
RSA_SHA_384_PKCS1
0x29
RFC8017: RSASSA-PKCS1-v1_5
RSA_SHA_512_PKCS1
0x2A
RFC8017: RSASSA-PKCS1-v1_5
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_SIGNATURE
See
SE05x_P1_t
P2
P2_SIGN
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte identifier of the key pair or private key.
TLV[TAG_2]
1-byte
SE05x_RSASignAlgo_t
TLV[TAG_3]
Byte array containing input data.
Le
0x00
Expecting ASN.1 signature.
R-APDU Body
Value
Description
TLV[TAG_1]
RSA signature in ASN.1 format.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] rsaSigningAlgo
: rsaSigningAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[out] signature
: [0:kSE05x_TAG_1][inout] psignatureLen
: Length for signature
-
smStatus_t
Se05x_API_RSAVerify
(pSe05xSession_t session_ctx, uint32_t objectID, SE05x_RSASignatureAlgo_t rsaSigningAlgo, const uint8_t *inputData, size_t inputDataLen, const uint8_t *signature, size_t signatureLen, SE05x_Result_t *presult) Se05x_API_RSAVerify
The RSAVerify command verifies the given signature and returns the result.
The key cannot be passed externally to the command directly. In case users want to use the command to verify signatures using different public keys or the public key value regularly changes, the user should create a transient key object to which the key value is written and then the identifier of that transient secure object can be used by this RSAVerify command.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
SE05x_INS_t
P1
P1_SIGNATURE
See
SE05x_P1_t
P2
P2_VERIFY
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
4-byte identifier of the key pair or public key.
TLV[TAG_2]
1-byte
SE05x_RSASignAlgo_t
TLV[TAG_3]
Byte array containing data to be verified.
TLV[TAG_5]
Byte array containing ASN.1 signature.
Le
0x03
Expecting Result in TLV
R-APDU Body
Value
Description
TLV[TAG_1]
SE05x_Result_t
: Verification resultR-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: objectID [1:kSE05x_TAG_1][in] rsaSigningAlgo
: rsaSigningAlgo [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData[in] signature
: signature [4:kSE05x_TAG_5][in] signatureLen
: Length of signature[out] presult
: [0:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_SendCardManagerCmd
(pSe05xSession_t session_ctx, uint8_t *pCmdData, size_t cmdDataLen, uint8_t *pOutputData, size_t *pOutputDataLen) Se05x_API_SendCardManagerCmd
Sends a command to the Card Manager.
This APDU will send command to Card Manager
Command to Card Manager
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_CM_COMMAND
See
SE05x_P2_t
Lc
#(Payload)
Payload length
Payload
TLV[TAG_1]
APDU to be sent to the Card Manager.
Le
0x00
Expected response length
R-APDU Body
Value
Description
TLV[TAG_1]
Byte array containing the Card Manager response.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] pCmdData
: The command input data[in] cmdDataLen
: The command input data length[out] pOutputData
: The response data[out] pOutputDataLen
: The response data length
-
smStatus_t
Se05x_API_SetAppletFeatures
(pSe05xSession_t session_ctx, pSe05xAppletFeatures_t appletVariant) Se05x_API_SetAppletFeatures
Sets the applet features that are supported. To successfully execute this command, the session must be authenticated using the RESERVED_ID_FEATURE.
The 2-byte input value is a pre-defined AppletConfig value.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_VARIANT
See
SE05x_P2_t
Lc
#(Payload)
Payload length
Payload
TLV[TAG_1]
2-byte Variant from
SE05x_AppletConfig_t
R-APDU Body
NA
R-APDU Trailer
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] variant
: variant [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_SetCounterValue
(pSe05xSession_t session_ctx, uint32_t objectID, uint16_t size, uint64_t value) Se05x_API_SetCounterValue
See Se05x_API_CreateCounter
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] objectID
: object id [1:kSE05x_TAG_1][in] size
: size [3:kSE05x_TAG_2][in] value
: value [4:kSE05x_TAG_3]
-
smStatus_t
Se05x_API_SetECCurveParam
(pSe05xSession_t session_ctx, SE05x_ECCurve_t curveID, SE05x_ECCurveParam_t ecCurveParam, const uint8_t *inputData, size_t inputDataLen) Se05x_API_SetECCurveParam
Set a curve parameter. The curve must have been created first by CreateEcCurve.
All parameters must match the expected value for the listed curves. If the curve parameters are not correct, the curve cannot be used.
Users have to set all 5 curve parameters for the curve to be usable. Once all curve parameters are given, the secure element will check if all parameters are correct and return SW_NO_ERROR..
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_WRITE
See
SE05x_INS_t
P1
P1_CURVE
See
SE05x_P1_t
P2
P2_PARAM
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
1-byte curve identifier, from
SE05x_ECCurve_t
TLV[TAG_2]
1-byte
SE05x_ECCurveParam_t
TLV[TAG_3]
Bytestring containing curve parameter value.
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
Data is returned successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] curveID
: curve id [1:kSE05x_TAG_1][in] ecCurveParam
: ecCurveParam [2:kSE05x_TAG_2][in] inputData
: inputData [3:kSE05x_TAG_3][in] inputDataLen
: Length of inputData
-
smStatus_t
Se05x_API_SetLockState
(pSe05xSession_t session_ctx, uint8_t lockIndicator, uint8_t lockState) Se05x_API_SetLockState
Sets the applet transport lock (locked or unlocked). There is a Persistent lock and a Transient Lock. If the Persistent lock is UNLOCKED, the device is unlocked (regardless of the Transient lock). If the Persistent lock is LOCKED, the device is only unlocked when the Transient lock is UNLOCKED and the device will be locked again after deselect of the applet.
Note that regardless of the lock state, the credential RESERVED_ID_TRANSPORT allows access to all features. For example, it is possible to write/update objects within the session opened by RESERVED_ID_TRANSPORT, even if the applet is locked.
The default TRANSIENT_LOCK state is LOCKED; there is no default PERSISTENT_LOCK state (depends on product configuration).
This command can only be used in a session that used the credential with identifier RESERVED_ID_TRANSPORT as authentication object.
PERSISTENT_LOCK
TRANSIENT_LOCK
Behavior
UNLOCKED
UNLOCKED
Unlocked until PERSISTENT_LOCK set to LOCKED.
UNLOCKED
LOCKED
Unlocked until PERSISTENT_LOCK set to LOCKED.
LOCKED
UNLOCKED
Unlocked until deselect or TRANSIENT_LOCK set to LOCKED.
LOCKED
LOCKED
Locked until PERSISTENT_LOCK set to UNLOCKED.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_TRANSPORT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
1-byte
LockIndicatorRef
TLV[TAG_2]
1-byte
LockStateRef
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] lockIndicator
: lock indicator [1:kSE05x_TAG_1][in] lockState
: lock state [2:kSE05x_TAG_2]
-
smStatus_t
Se05x_API_SetPlatformSCPRequest
(pSe05xSession_t session_ctx, SE05x_PlatformSCPRequest_t platformSCPRequest) Se05x_API_SetPlatformSCPRequest
Sets the required state for platform SCP (required or not required). This is a persistent state.
If platform SCP is set to SCP_REQUIRED, any applet APDU command will be refused by the applet when platform SCP is not enabled. Enabled means full encryption and MAC, both on C-APDU and R-APDU. Any other level is not sufficient and will not be accepted. SCP02 will not be accepted (as there is no response MAC and encryption).
If platform SCP is set to “not required,” any applet APDU command will be accepted by the applet.
This command can only be used in a session that used the credential with identifier RESERVED_ID_PLATFORM_SCP as authentication object.
Note that the default state is SCP_NOT_REQUIRED.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SCP
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_1]
1-byte
SE05x_PlatformSCPRequest_t
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] platformSCPRequest
: platf scp req [1:kSE05x_TAG_1]
-
smStatus_t
Se05x_API_TLSCalculatePreMasterSecret
(pSe05xSession_t session_ctx, uint32_t keyPairId, uint32_t pskId, uint32_t hmacKeyId, const uint8_t *inputData, size_t inputDataLen) Se05x_API_TLSCalculatePreMasterSecret
The command TLSCalculatePreMasterSecret will compute the pre-master secret for TLS according [RFC5246]. The pre-master secret will always be stored in an HMACKey object (TLV[TAG_3]). The HMACKey object must be created before; otherwise the calculation of the pre-master secret will fail.
It can use one of these algorithms: - - - -
PSK Key Exchange algorithm as defined in [RFC4279]
RSA_PSK Key Exchange algorithm as defined in [RFC4279]
ECDHE_PSK Key Exchange algorithm as defined in [RFC5489]
EC Key Exchange algorithm as defined in [RFC4492]
RSA Key Exchange algorithm as defined in [RFC5246]
TLV[TAG_1] needs to be an (existing) HMACKey identifier containing the pre- shared Key.
Input data in TLV[TAG_4] are:
An EC public key when TLV[TAG_2] refers to an EC key pair.
An RSA encrypted secret when TLV[TAG_2] refers to an RSA key pair.
Empty when TLV[TAG_2] is absent or empty.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
See
SE05x_INS_t
P1
P1_TLS
See
SE05x_P1_t
P2
P2_PMS
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte PSK identifier referring to a 16, 32, 48 or 64-byte Pre Shared Key. [Optional]
TLV[TAG_2]
4-byte key pair identifier. [Optional]
TLV[TAG_3]
4-byte target HMACKey identifier.
TLV[TAG_4]
Byte array containing input data.
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] keyPairId
: keyPairId [1:kSE05x_TAG_1][in] pskId
: pskId [2:kSE05x_TAG_2][in] hmacKeyId
: hmacKeyId [3:kSE05x_TAG_3][in] inputData
: inputData [4:kSE05x_TAG_4][in] inputDataLen
: Length of inputData
-
smStatus_t
Se05x_API_TLSCalculateRsaPreMasterSecret
(pSe05xSession_t session_ctx, uint32_t keyPairId, uint32_t pskId, uint32_t hmacKeyId, const uint8_t *inputData, size_t inputDataLen, const uint8_t *clientVersion, size_t clientVersionLen) Se05x_API_TLSCalculateRsaPreMasterSecret
- Parameters
[in] session_ctx
: Session Context[0:kSE05x_pSession][in] keyPairId
: keyPairId[1:kSE05x_TAG_1][in] pskId
: pskId[2:kSE05x_TAG_2][in] hmacKeyId
: hmacKeyId[3:kSE05x_TAG_3][in] inputData
: inputData[4:kSE05x_TAG_4][in] inputDataLen
: Length of inputData[in] clientVersion
: client version[6:kSE05x_TAG_6][in] clientVersionLen
: Length of client version
-
smStatus_t
Se05x_API_TLSGenerateRandom
(pSe05xSession_t session_ctx, uint8_t *randomValue, size_t *prandomValueLen) Se05x_API_TLSGenerateRandom
Generates a random that is stored in the SE05X and used by TLSPerformPRF.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
See
SE05x_INS_t
P1
P1_TLS
See
SE05x_P1_t
P2
P2_RANDOM
See
SE05x_P2_t
Lc
#(Payload)
Le
0x22
Expecting TLV with 32 bytes data.
R-APDU Body
Value
Description
TLV[TAG_1]
32-byte random value
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][out] randomValue
: [0:kSE05x_TAG_1][inout] prandomValueLen
: Length for randomValue
-
smStatus_t
Se05x_API_TLSPerformPRF
(pSe05xSession_t session_ctx, uint32_t objectID, uint8_t digestAlgo, const uint8_t *label, size_t labelLen, const uint8_t *random, size_t randomLen, uint16_t reqLen, uint8_t *outputData, size_t *poutputDataLen, const SE05x_TLSPerformPRFType_t tlsprf) Se05x_API_TLSPerformPRF
The command TLSPerformPRF will compute either:
the master secret for TLS according [RFC5246], section 8.1
key expansion data from a master secret for TLS according [RFC5246], section 6.3
Each time before calling this function, TLSGenerateRandom must be called. Executing this function will clear the random that is stored in the SE05X .
The function can be called as client or as server and either using the pre- master secret or master secret as input, stored in an HMACKey. The input length must be either 16, 32, 48 or 64 bytes.
This results in P2 having 4 possibilities:
P2_TLS_PRF_CLI_HELLO: pass the clientHelloRandom to calculate a master secret, the serverHelloRandom is in SE05X , generated by TLSGenerateRandom.
P2_TLS_PRF_SRV_HELLO: pass the serverHelloRandom to calculate a master secret, the clientHelloRandom is in SE05X , generated by TLSGenerateRandom.
P2_TLS_PRF_CLI_RANDOM: pass the clientRandom to generate key expansion data, the serverRandom is in SE05X , generated by TLSGenerateRandom.
P2_TLS_PRF_SRV_RANDOM: pass the serverRandom to generate key expansion data, the clientRandom is in SE05X
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_CRYPTO
See
SE05x_INS_t
P1
P1_TLS
See
SE05x_P1_t
P2
See description above.
See
SE05x_P2_t
Lc
#(Payload)
TLV[TAG_1]
4-byte HMACKey identifier.
TLV[TAG_2]
1-byte
SE05x_DigestMode_t
, except DIGEST_NO_HASH.TLV[TAG_3]
Label (1 to 64 bytes)
TLV[TAG_4]
32-byte random
TLV[TAG_5]
2-byte requested length
Le
0x00
R-APDU Body
Value
Description
TLV[TAG_1]
Byte array containing requested output data.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] objectID
: The object id[in] digestAlgo
: The digest algorithm[in] label
: The label[in] labelLen
: The label length[in] random
: The random[in] randomLen
: The random length[in] reqLen
: The request lengthoutputData
: The output datapoutputDataLen
: The poutput data length[in] tlsprf
: The tlsprf
-
smStatus_t
Se05x_API_TriggerSelfTest
(pSe05xSession_t session_ctx, SE05x_HealthCheckMode_t healthCheckMode, uint8_t *result) Se05x_API_TriggerSelfTest
Trigger a system health check for the system. When calling this command, a self-test is triggered in the operating system. When the test fails, the device might not respond with a R-APDU as the chip is reset. If HealthCheckMode is set to HCM_FIPS, the test will only work if the device is running in FIPS approved mode of operation.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
. In addition to INS_CRYPTO, users can set the INS_ATTEST flag. In that case, attestation applies.P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SANITY
See
SE05x_P2_t
Lc
#(Payload)
Payload length
Payload
TLV[TAG_1]
2-byte value from HealthCheckMode
Le
0x00
2-byte response + attested data (if INS_ATTEST is set).
R-APDU Body
Value
Description
TLV[TAG_1]
TLV containing 1-byte Result.
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] HealthCheckMode
: The health check moderesult
: The result of Self Test
-
smStatus_t
Se05x_API_TriggerSelfTest_W_Attst
(pSe05xSession_t session_ctx, SE05x_HealthCheckMode_t healthCheckMode, uint32_t attestID, SE05x_AttestationAlgo_t attestAlgo, const uint8_t *random, size_t randomLen, uint8_t *result, SE05x_TimeStamp_t *ptimeStamp, uint8_t *outrandom, size_t *poutrandomLen, uint8_t *chipId, size_t *pchipIdLen, uint8_t *signature, size_t *psignatureLen) Se05x_API_TriggerSelfTest_W_Attst
Trigger a system health check for the system. When calling this command, a self-test is triggered in the operating system. When the test fails, the device might not respond with a R-APDU as the chip is reset. If HealthCheckMode is set to HCM_FIPS, the test will only work if the device is running in FIPS approved mode of operation.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
. In addition to INS_CRYPTO, users can set the INS_ATTEST flag. In that case, attestation applies.P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SANITY
See
SE05x_P2_t
Lc
#(Payload)
Payload length
Payload
TLV[TAG_1]
2-byte value from HealthCheckMode
TLV[TAG_5]
4-byte attestation object identifier. [Optional] [Conditional: only when INS_ATTEST is set]
TLV[TAG_6]
1-byte AttestationAlgo [Optional] [Conditional: only when INS_ATTEST is set]
TLV[TAG_7]
16-byte freshness random [Optional] [Conditional: only when INS_ATTEST is set]
Le
0x00
2-byte response + attested data (if INS_ATTEST is set).
R-APDU Body
Value
Description
TLV[TAG_1]
TLV containing 1-byte Result.
TLV[TAG_3]
TLV containing 12-byte timestamp [Conditional: only when C-APDU contains INS_ATTEST]
TLV[TAG_4]
TLV containing 16-byte freshness (random) [Conditional: only when C-APDU contains INS_ATTEST]
TLV[TAG_5]
TLV containing 18-byte chip unique ID [Conditional: only when C-APDU contains INS_ATTEST]
TLV[TAG_6]
TLV containing signature over the concatenated values of TLV[TAG_1], TLV[TAG_3], TLV[TAG_4] and TLV[TAG_5]. [Conditional: only when C-APDU contains INS_ATTEST]
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] HealthCheckMode
: The health check mode[in] attestID
: The attest id[in] attestAlgo
: The attest algorithm[in] random
: The random[in] randomLen
: The random lengthresult
: The result of Self TestptimeStamp
: The ptime stampoutrandom
: The outrandompoutrandomLen
: The poutrandom lengthchipId
: The chip identifierpchipIdLen
: The pchip identifier lengthsignature
: The signaturepsignatureLen
: The psignature length
-
smStatus_t
Se05x_API_UpdateBinary_Ver
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t objectID, uint16_t offset, uint16_t length, const uint8_t *inputData, size_t inputDataLen, uint32_t version) Se05x_API_UpdateBinary_Ver
See Se05x_API_WriteBinary. Also allows to set key version (4 bytes). Called to update the value of already existing object. If policy is passed, it should match with existing policy on object.
-
smStatus_t
Se05x_API_UpdateCounter
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t objectID, uint16_t size, uint64_t value) Se05x_API_UpdateCounter
See Se05x_API_SetCounterValue. Called to update the value of already existing object. If policy is passed, it should match with existing policy on object.
-
smStatus_t
Se05x_API_UpdateECKey_Ver
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, SE05x_MaxAttemps_t maxAttempt, uint32_t objectID, SE05x_ECCurve_t curveID, const uint8_t *privKey, size_t privKeyLen, const uint8_t *pubKey, size_t pubKeyLen, const SE05x_INS_t ins_type, const SE05x_KeyPart_t key_part, uint32_t version) Se05x_API_UpdateECKey_Ver
See Se05x_API_WriteECKey. Also allows to set key version (4 bytes). Called to update the value of already existing object. If policy is passed, it should match with existing policy on object.
-
smStatus_t
Se05x_API_UpdatePCR
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t pcrID, const uint8_t *inputData, size_t inputDataLen) Se05x_API_UpdatePCR
See Se05x_API_WritePCR. Called to update the value of already existing object. If policy is passed, it should match with existing policy on object.
-
smStatus_t
Se05x_API_UpdateRSAKey_Ver
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t objectID, uint16_t size, const uint8_t *p, size_t pLen, const uint8_t *q, size_t qLen, const uint8_t *dp, size_t dpLen, const uint8_t *dq, size_t dqLen, const uint8_t *qInv, size_t qInvLen, const uint8_t *pubExp, size_t pubExpLen, const uint8_t *priv, size_t privLen, const uint8_t *pubMod, size_t pubModLen, const SE05x_INS_t ins_type, const SE05x_KeyPart_t key_part, const SE05x_RSAKeyFormat_t rsa_format, uint32_t version) Se05x_API_UpdateRSAKey_Ver
See Se05x_API_WriteRSAKey. Also allows to set key version (4 bytes). Called to update the value of already existing object. If policy is passed, it should match with existing policy on object.
-
smStatus_t
Se05x_API_UpdateSymmKey_Ver
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, SE05x_MaxAttemps_t maxAttempt, uint32_t objectID, SE05x_KeyID_t kekID, const uint8_t *keyValue, size_t keyValueLen, const SE05x_INS_t ins_type, const SE05x_SymmKeyType_t type, uint32_t version) Se05x_API_UpdateSymmKey_Ver
See Se05x_API_WriteSymmKey. Also allows to set key version (4 bytes). Called to update the value of already existing object. If policy is passed, it should match with existing policy on object.
-
smStatus_t
Se05x_API_VerifySessionUserID
(pSe05xSession_t session_ctx, const uint8_t *userId, size_t userIdLen) Se05x_API_VerifySessionUserID
Verifies the session user identifier (UserID) in order to allow setting up a session. If the UserID is correct, the session establishment is successful; otherwise the session cannot be opened (SW_CONDITIONS_NOT_SATISFIED is returned).
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_MGMT
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_SESSION_USERID
See
SE05x_P2_t
Lc
#(Payload)
Payload length.
TLV[TAG_1]
UserID value
Le
R-APDU Body
NA
R-APDU Trailer
SW
Description
SW_NO_ERROR
The command is handled successfully.
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] userId
: userId [1:kSE05x_TAG_1][in] userIdLen
: Length of userId
-
smStatus_t
Se05x_API_WriteBinary
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t objectID, uint16_t offset, uint16_t length, const uint8_t *inputData, size_t inputDataLen) Se05x_API_WriteBinary
Creates or writes to a binary file object. Data are written to either the start of the file or (if specified) to the offset passed to the function.
Command to Applet
Field
Value
Description
P1
P1_BINARY
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Payload
TLV[TAG_POLICY]
Byte array containing the object policy. [Optional: default policy applies] [Conditional: only when the object identifier is not in use yet]
TLV[TAG_1]
4-byte object identifier
TLV[TAG_2]
2-byte file offset [Optional: default = 0]
TLV[TAG_3]
2-byte file length (up to 0x7FFF). [Conditional: only when the object identifier is not in use yet]
TLV[TAG_4]
Data to be written [Optional: if not given, TAG_3 must be filled]
TLV[TAG_11]
4-byte version [Optional]
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] policy
: policy [1:kSE05x_TAG_POLICY][in] objectID
: object id [2:kSE05x_TAG_1][in] offset
: offset [3:kSE05x_TAG_2][in] length
: length [4:kSE05x_TAG_3][in] inputData
: input data [5:kSE05x_TAG_4][in] inputDataLen
: Length of inputData
-
smStatus_t
Se05x_API_WriteBinary_Ver
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t objectID, uint16_t offset, uint16_t length, const uint8_t *inputData, size_t inputDataLen, uint32_t version) Se05x_API_WriteBinary_Ver
See Se05x_API_WriteBinary. Also allows to set key version (4 bytes).
-
smStatus_t
Se05x_API_WriteECKey
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, SE05x_MaxAttemps_t maxAttempt, uint32_t objectID, SE05x_ECCurve_t curveID, const uint8_t *privKey, size_t privKeyLen, const uint8_t *pubKey, size_t pubKeyLen, const SE05x_INS_t ins_type, const SE05x_KeyPart_t key_part) Se05x_API_WriteECKey
Write or update an EC key object.
P1KeyPart indicates the key type to be created (if the object does not yet exist).
If P1KeyPart = P1_KEY_PAIR, Private Key Value (TLV[TAG_3]) and Public Key Value (TLV[TAG_4) must both be present, or both be absent. If absent, the key pair is generated in the SE05X .
If the object already exists, P1KeyPart is ignored.
Field
Value
Description
P1
SE05x_P1_t
| P1_ECSee
SE05x_P1_t
, P1KeyType should only be set for new objects.P2
P2_DEFAULT
See P2
Payload
TLV[TAG_POLICY]
Byte array containing the object policy. [Optional: default policy applies] [Conditional - only when the object identifier is not in use yet]
TLV[TAG_MAX_ATTEMPTS]
2-byte maximum number of attempts. If 0 is given, this means unlimited. [Optional: default unlimited] [Conditional: only when the object identifier is not in use yet and INS includes INS_AUTH_OBJECT; see AuthenticationObjectPolicies ]
TLV[TAG_1]
4-byte object identifier
TLV[TAG_2]
1-byte curve identifier, see ECCurve [Conditional: only when the object identifier is not in use yet; ]
TLV[TAG_3]
Private key value (see
ECKeyRef
) [Conditional: only when the private key is externally generated and P1KeyType is either P1_KEY_PAIR or P1_PRIVATE]TLV[TAG_4]
Public key value (see
ECKeyRef
) [Conditional: only when the public key is externally generated and P1KeyType is either P1_KEY_PAIR or P1_PUBLIC]TLV[TAG_11]
4-byte version [Optional]
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] policy
: The policy[in] maxAttempt
: The maximum attempt[in] objectID
: The object id[in] curveID
: The curve id[in] privKey
: The priv key[in] privKeyLen
: The priv key length[in] pubKey
: The pub key[in] pubKeyLen
: The pub key length[in] ins_type
: The insert type[in] key_part
: The key part
-
smStatus_t
Se05x_API_WriteECKey_Ver
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, SE05x_MaxAttemps_t maxAttempt, uint32_t objectID, SE05x_ECCurve_t curveID, const uint8_t *privKey, size_t privKeyLen, const uint8_t *pubKey, size_t pubKeyLen, const SE05x_INS_t ins_type, const SE05x_KeyPart_t key_part, uint32_t version) Se05x_API_WriteECKey_Ver
See Se05x_API_WriteECKey. Also allows to set key version (4 bytes).
-
smStatus_t
Se05x_API_WritePCR
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t pcrID, const uint8_t *initialValue, size_t initialValueLen, const uint8_t *inputData, size_t inputDataLen) Se05x_API_WritePCR
Creates or writes to a PCR object.
A PCR is a hash to which data can be appended; i.e., writing data to a PCR will update the value of the PCR to be the hash of all previously inserted data concatenated with the new input data.
A PCR will always use DigestMode = DIGEST_SHA256; no other configuration possible.
If TAG_2 and TAG_3 is not passed, the PCR is reset to its initial value (i.e., the value set when the PCR was created).
This reset is controlled under the POLICY_OBJ_ALLOW_DELETE policy, so users that can delete the PCR can also reset the PCR to initial value.
Command to Applet
Field
Value
Description
P1
P1_PCR
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Payload
TLV[TAG_POLICY]
Byte array containing the object policy. [Optional: default policy applies] [Conditional: only when the object identifier is not in use yet]
TLV[TAG_1]
4-byte PCR identifier.
TLV[TAG_2]
Initial hash value [Conditional: only when the object identifier is not in use yet]
TLV[TAG_3]
Data to be extended to the existing PCR. [Conditional: only when the object identifier is already in use] [Optional: not present if a Reset is requested]
R-APDU Body
NA
R-APDU Trailer
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] policy
: policy [1:kSE05x_TAG_POLICY][in] pcrID
: object id [2:kSE05x_TAG_1][in] initialValue
: initialValue [3:kSE05x_TAG_2][in] initialValueLen
: Length of initialValue[in] inputData
: inputData [4:kSE05x_TAG_3][in] inputDataLen
: Length of inputData
-
smStatus_t
Se05x_API_WritePCR_WithType
(pSe05xSession_t session_ctx, const SE05x_INS_t ins_type, pSe05xPolicy_t policy, uint32_t pcrID, const uint8_t *initialValue, size_t initialValueLen, const uint8_t *inputData, size_t inputDataLen)
-
smStatus_t
Se05x_API_WriteRSAKey
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t objectID, uint16_t size, const uint8_t *p, size_t pLen, const uint8_t *q, size_t qLen, const uint8_t *dp, size_t dpLen, const uint8_t *dq, size_t dqLen, const uint8_t *qInv, size_t qInvLen, const uint8_t *pubExp, size_t pubExpLen, const uint8_t *priv, size_t privLen, const uint8_t *pubMod, size_t pubModLen, const SE05x_INS_t transient_type, const SE05x_KeyPart_t key_part, const SE05x_RSAKeyFormat_t rsa_format) Se05x_API_WriteRSAKey
Creates or writes an RSA key or a key component.
Supported key sizes are listed in RSABitLength. Other values are not supported.
An RSA key creation requires multiple ADPUs to be sent:
The first APDU must contain:
Policy (optional, so only if non-default applies)
Object identifier
Key size
1 of the key components.
Each next APDU must contain 1 of the key components.
The policy applies only once all key components are set.
Once an RSAKey object has been created, its format remains fixed and cannot be updated (so CRT or raw mode, no switch possible).
If the object already exists, P1KeyType is ignored.
For key pairs, if no component is present (TAG_3 until TAG_9), the key pair will be generated on chip; otherwise the key pair will be constructed starting with the given component.
For private keys or public keys, there should always be exactly one of the tags TAG_3 until TAG_10.
TLV[TAG_8] and TLV[TAG_10] must only contain a value if the key pair is to be set to a known value and P1KeyType is either P1_KEY_PAIR or P1_PUBLIC; otherwise the value must be absent and the length must be equal to 0.
TLV[TAG_9] must only contain a value it the key is to be set in raw mode to a known value and P1KeyType is either P1_KEY_PAIR or P1_PRIVATE; otherwise the value must be absent and the length must be equal to 0.
If TLV[TAG_3] up to TLV[TAG_10] are absent (except TLV[TAG_8]), the RSA key will be generated on chip in case the object does not yet exist; otherwise it will be regenerated. This only applies to RSA key pairs.
Keys can be set by setting the different components of a key; only 1 component can be set at a time in this case.
Field
Value
Description
P1
SE05x_KeyPart_t
| P1_RSASee
SE05x_P1_t
P2
P2_DEFAULT or P2_RAW
See
SE05x_P2_t
; P2_RAW only in case P1KeyPart = P1_KEY_PAIR and TLV[TAG_3] until TLV[TAG_10] is empty and the must generate a raw RSA key pair; all other cases: P2_DEFAULT.Payload
TLV[TAG_POLICY]
Byte array containing the object policy. [Optional: default policy applies] [Conditional: only when the object identifier is not in use yet]
TLV[TAG_1]
4-byte object identifier
TLV[TAG_2]
2-byte key size in bits (
SE05x_RSABitLength_t
) [Conditional: only when the object identifier is not in use yet]TLV[TAG_3]
P component [Conditional: only when the object identifier is in CRT mode and the key is generated externally and P1KeyPart is either P1_KEY_PAIR or P1_PRIVATE]
TLV[TAG_4]
Q component [Conditional: only when the object identifier is in CRT mode and the key is generated externally and P1KeyPart is either P1_KEY_PAIR or P1_PRIVATE]
TLV[TAG_5]
DP component [Conditional: only when the object identifier is in CRT mode and the key is generated externally and P1KeyPart is either P1_KEY_PAIR or P1_PRIVATE]
TLV[TAG_6]
DQ component [Conditional: only when the object identifier is in CRT mode and the key is generated externally and P1KeyPart is either P1_KEY_PAIR or P1_PRIVATE]
TLV[TAG_7]
INV_Q component [Conditional: only when the object identifier is in CRT mode and the key is generated externally and P1KeyPart is either P1_KEY_PAIR or P1_PRIVATE]
TLV[TAG_8]
Public exponent
TLV[TAG_9]
Private Key (non-CRT mode only)
TLV[TAG_10]
Public Key (Modulus)
TLV[TAG_11]
4-byte version [Optional]
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] policy
: The policy[in] objectID
: The object id[in] size
: The size[in] p
: The part p[in] pLen
: The p length[in] q
: The quarter[in] qLen
: The quarter length[in] dp
: The part dp[in] dpLen
: The dp length[in] dq
: The part dq[in] dqLen
: The dq length[in] qInv
: The quarter inv[in] qInvLen
: The quarter inv length[in] pubExp
: The pub exponent[in] pubExpLen
: The pub exponent length[in] priv
: The priv[in] privLen
: The priv length[in] pubMod
: The pub modifier[in] pubModLen
: The pub modifier length[in] transient_type
: The transient type[in] key_part
: The key part[in] rsa_format
: The rsa format
-
smStatus_t
Se05x_API_WriteRSAKey_Ver
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, uint32_t objectID, uint16_t size, const uint8_t *p, size_t pLen, const uint8_t *q, size_t qLen, const uint8_t *dp, size_t dpLen, const uint8_t *dq, size_t dqLen, const uint8_t *qInv, size_t qInvLen, const uint8_t *pubExp, size_t pubExpLen, const uint8_t *priv, size_t privLen, const uint8_t *pubMod, size_t pubModLen, const SE05x_INS_t ins_type, const SE05x_KeyPart_t key_part, const SE05x_RSAKeyFormat_t rsa_format, uint32_t version) Se05x_API_WriteRSAKey_Ver
See Se05x_API_WriteRSAKey. Also allows to set key version (4 bytes).
-
smStatus_t
Se05x_API_WriteSymmKey
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, SE05x_MaxAttemps_t maxAttempt, uint32_t objectID, SE05x_KeyID_t kekID, const uint8_t *keyValue, size_t keyValueLen, const SE05x_INS_t ins_type, const SE05x_SymmKeyType_t type) Se05x_API_WriteSymmKey
Creates or writes an AES key, DES key or HMAC key, indicated by P1:
P1_AES
P1_DES
P1_HMAC
Users can pass RFC3394 wrapped keys by indicating the KEK in TLV[TAG_2]. Note that RFC3394 required 8-byte aligned input, so this can only be used when the key has an 8-byte aligned length.
Command to Applet
Field
Value
Description
P1
See above
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Payload
TLV[TAG_POLICY]
Byte array containing the object policy. [Optional: default policy applies] [Conditional: only when the object identifier is not in use yet]
TLV[TAG_MAX_ATTEMPTS]
2-byte maximum number of attempts. If 0 is given, this means unlimited. [Optional: default unlimited] [Conditional: only when the object identifier is not in use yet and INS includes INS_AUTH_OBJECT; see AuthenticationObjectPolicies]
TLV[TAG_1]
4-byte object identifier
TLV[TAG_2]
4-byte KEK identifier [Conditional: only when the key value is RFC3394 wrapped]
TLV[TAG_3]
Key value, either plain or RFC3394 wrapped.
TLV[TAG_4]
Tag length for GCM/GMAC. Will only be used if the object is an AESKey. [Optional]
TLV[TAG_11]
4-byte version [Optional]
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] policy
: The policy[in] maxAttempt
: The maximum attempt[in] objectID
: The object id[in] kekID
: The kek id[in] keyValue
: The key value[in] keyValueLen
: The key value length[in] ins_type
: The insert type[in] type
: The type
-
smStatus_t
Se05x_API_WriteSymmKey_Ver
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, SE05x_MaxAttemps_t maxAttempt, uint32_t objectID, SE05x_KeyID_t kekID, const uint8_t *keyValue, size_t keyValueLen, const SE05x_INS_t ins_type, const SE05x_SymmKeyType_t type, uint32_t version) Se05x_API_WriteSymmKey_Ver
See Se05x_API_WriteSymmKey. Also allows to set key version (4 bytes).
-
smStatus_t
Se05x_API_WriteSymmKey_Ver_extended
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, SE05x_MaxAttemps_t maxAttempt, uint32_t objectID, SE05x_KeyID_t kekID, const uint8_t *keyValue, size_t keyValueLen, const SE05x_INS_t ins_type, const SE05x_SymmKeyType_t type, uint32_t version, uint16_t min_aead_tag_len) Se05x_API_WriteSymmKey_Ver_extended
See Extension of Se05x_API_WriteSymmKey_Ver api. Allows to set minimum tag length for AEAD (2 bytes).
-
smStatus_t
Se05x_API_WriteUserID
(pSe05xSession_t session_ctx, pSe05xPolicy_t policy, SE05x_MaxAttemps_t maxAttempt, uint32_t objectID, const uint8_t *userId, size_t userIdLen, const SE05x_AttestationType_t attestation_type) Se05x_API_WriteUserID
Creates a UserID object, setting the user identifier value. The policy defines the maximum number of attempts that can be performed as comparison.
Command to Applet
Field
Value
Description
P1
P1_USERID
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
TLV[TAG_POLICY]
Byte array containing the object policy. [Optional: default policy applies] [Conditional: only when the object identifier is not in use yet]
TLV[TAG_MAX_ATTEMPTS]
2-byte maximum number of attempts. If 0 is given, this means unlimited. For pins, the maximum number of attempts must be smaller than 256. [Optional: default = 0] [Conditional: only when the object identifier is not in use yet and INS includes INS_AUTH_OBJECT; see
-
]TLV[TAG_1]
4-byte object identifier.
TLV[TAG_2]
Byte array containing 4 to 16 bytes user identifier value.
- Return
The sm status.
- Parameters
[in] session_ctx
: The session context[in] policy
: The policy[in] maxAttempt
: The maximum attempt[in] objectID
: The object id[in] userId
: The user identifier[in] userIdLen
: The user identifier length[in] attestation_type
: The attestation type
-
11.12.3. SE05x SCP03 Types and APIs¶
-
group
se05x_scp03
SE05x SCP03 types and API reference.
Enums
-
enum
SE_AuthType_t
Values:
-
kSSS_AuthType_None
= 0
-
kSSS_AuthType_SCP03
= 1 Global platform SCP03
-
kSSS_AuthType_ID
= 2 (e.g. SE05X) UserID based connection
-
kSSS_AuthType_AESKey
= 3 (e.g. SE05X) Use AESKey for user authentication
Earlier this was called kSSS_AuthType_AppletSCP03
-
kSSS_AuthType_ECKey
= 4 (e.g. SE05X) Use ECKey for user authentication
Earlier this was called kSSS_AuthType_FastSCP
-
kSSS_AuthType_INT_ECKey_Counter
= 0x14 Used internally, not to be set/used by user.
For the versions of the applet where we have to add the a counter during KDF.
-
kSSS_SIZE
= 0x7FFFFFFF
-
-
struct
_SE_AuthCtx
- #include <nxScp03_Types.h>
Authentication mechanims
Public Members
-
SM_SECURE_SCP03_KEYOBJ
a71chAuthKeys
Legacy, only for A71CH with Host Crypto
-
SE_AuthType_t
authType
How exactly we are going to authenticat ot the system.
Since
ctx
is a union, this is needed to know exactly how we are going to authenticate.
-
union _SE_AuthCtx::[anonymous]
ctx
Depending on
authType
, the input and output parameters.This has both input and output parameters.
Input is for Keys that are used to initiate the connection. While connecting, session keys/parameters are generated and they are also part of this context.
In any case, we connect to only one type
-
uint8_t
data
[SSS_AUTH_MAX_CONTEXT_SIZE
]
-
SE05x_AuthCtx_ECKey_t
eckey
For ECKey
-
struct _SE_AuthCtx::[anonymous]::[anonymous]
extension
Reserved memory for implementation specific extension
-
SE05x_AuthCtx_ID_t
idobj
For UserID/PIN based based Authentication
-
NXSCP03_AuthCtx_t
scp03
For PlatformSCP / Applet SCP.
Same SCP context will be used for platform and applet scp03
-
SM_SECURE_SCP03_KEYOBJ
-
struct
NXECKey03_StaticCtx_t
- #include <nxScp03_Types.h>
Static part of keys for FAST SCP
Public Members
-
sss_object_t
HostEcdsaObj
Host ECDSA Private key
-
sss_object_t
HostEcKeypair
Host ephemeral ECC key pair
-
sss_object_t
masterSec
Host master Secret
-
sss_object_t
SeEcPubKey
SE ECC public key
-
sss_object_t
-
struct
NXSCP03_AuthCtx_t
- #include <nxScp03_Types.h>
Static and Dynamic Context in one Context.
Depending on system, these objects may point to keys inside other security system.
Public Members
-
NXSCP03_DynCtx_t *
pDyn_ctx
session keys data
-
NXSCP03_StaticCtx_t *
pStatic_ctx
.static keys data
-
NXSCP03_DynCtx_t *
-
struct
NXSCP03_DynCtx_t
- #include <nxScp03_Types.h>
Dynamic SCP03 Context.
This structure is filled after establishing an SCP03 session.
Public Members
-
SE_AuthType_t
authType
Handle differnt types of auth.. PlatformSCP / AppletSCP
-
uint8_t
cCounter
[16] command counter
-
sss_object_t
Enc
session channel encryption key
-
sss_object_t
Mac
session command authentication key
-
uint8_t
MCV
[16] MAC chaining value.
-
sss_object_t
Rmac
session response authentication key
-
uint8_t
SecurityLevel
security level set
-
SE_AuthType_t
-
struct
NXSCP03_StaticCtx_t
- #include <nxScp03_Types.h>
Static SCP03 Context.
This structure is filled before establishing an SCP03 session.
Depending on system, these objects may point to keys inside other security system.
Public Members
-
sss_object_t
Dek
data encryption key obj
-
sss_object_t
Enc
Encryption key object
-
uint8_t
keyVerNo
Key version no to use for chanel authentication in SCP03
-
sss_object_t
Mac
static secure channel authentication key obj
-
sss_object_t
-
struct
SE05x_AuthCtx_ECKey_t
- #include <nxScp03_Types.h>
Keys to connect for a ECKey Connection
Public Members
-
NXSCP03_DynCtx_t *
pDyn_ctx
The Dynamic part of the ECKey Authentication
We derive/compute the session keys based on the
pStatic_ctx
.
-
NXECKey03_StaticCtx_t *
pStatic_ctx
The Input/Static part of the ECKey Authentication
We start/initiate a session with the keys here.
-
NXSCP03_DynCtx_t *
-
struct
SE05x_AuthCtx_ID_t
- #include <nxScp03_Types.h>
UseID / PIN baed authentication object
This is required to open an UserID / PIN based session to the SE.
Public Members
-
sss_object_t *
pObj
The corresponding authentication object on the Host
-
sss_object_t *
-
struct
SE_Connect_Ctx_t
- #include <nxScp03_Types.h>
When connecting to a secure element,
Extension of sss_connect_ctx_t
Public Members
-
SE_AuthCtx_t
auth
If we need to authenticate, add required objects for authentication
-
SSS_Conn_Type_t
connType
How exactly are we going to connect physically
-
U32
i2cAddress
12C address on embedded devices.
-
const char *
portName
Connection port name for Socket names, etc.
-
uint8_t
refresh_session
If we need to refresh session, SE050 specific
-
sss_policy_session_u *
session_policy
If some policy restrictions apply when we connect, point it here
-
uint8_t
sessionResume
Set to 1 if we should resume a session already open with SE
-
uint16_t
sizeOfStucture
to support binary compatibility/check, sizeOfStucture helps
-
uint8_t
skip_select_applet
In the case of Key Rotation, and other use cases where we do not select the IoT Applet and skip the selection of the IoT Applet.
One of the use cases is to do platform SCP key rotation.
When set to 0: Do not skip IoT Applet selection and run as-is.
When set to 1: Skip selection of card manager. Skip selection of Applet.
Internally, if there is platform SCP selected as Auth mechanism during compile time, the internal logic would Select the card manager. But, skip selection of the Applet.
-
sss_tunnel_t *
tunnelCtx
If we connect logically, via some software layer
-
SE_AuthCtx_t
-
struct
SM_SECURE_SCP03_KEYOBJ
- #include <nxScp03_Types.h>
Legacy, only for A71CH with Host Crypto
Public Members
-
sss_object_t
pKeyDek
SSS AES Dek Key object.
-
sss_object_t
pKeyEnc
SSS AES Enc Key object.
-
sss_object_t
pKeyMac
SSS AES Mac Key object.
-
sss_object_t
-
struct
sss_connect_ctx_t
- #include <nxScp03_Types.h>
Wrapper strucutre sss_connect_ctx_t
Public Members
-
SE_AuthCtx_t
auth
If we need to authenticate, add required objects for authentication
-
uint8_t
data
[SSS_CONNECT_MAX_CONTEXT_SIZE
]
-
struct sss_connect_ctx_t::[anonymous]
extension
Reserved memory for implementation specific extension
-
sss_policy_session_u *
session_policy
If some policy restrictions apply when we connect, point it here
-
uint16_t
sizeOfStucture
To support binary compatibility/check, sizeOfStucture helps
-
SE_AuthCtx_t
-
enum