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

Public Members

SE05x_ExtendedFeatures_t *extended_features
SE05x_Variant_t variant
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

struct SE05x_ExtendedFeatures_t

Public Members

uint8_t features[30]
struct SE05x_TimeStamp_t

Public Members

uint8_t ts[12]
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
struct Se05xPolicy_t

Public Members

uint8_t *value
size_t value_len
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]

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 length

  • tag: The tag

  • tagLen: 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 id

  • tag: The tag

  • tagLen: 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 length

  • tagData: The tag data

  • tagDataLen: The tag data length

  • outputData: The output data

  • poutputDataLen: 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 length

  • pOutputData: The output data

  • pOutputLen: 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 length

  • outputData: The output data

  • poutputDataLen: 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 id

  • pcurveId: 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 context

  • pappletVersion: The papplet version

  • appletVersionLen: 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 type

  • pfreeMem: 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 size

  • randomData: The random data

  • prandomDataLen: 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 context

  • ptimeStamp: 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 context

  • pappletVersion: The papplet version

  • appletVersionLen: 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 algorithm

  • response: The response

  • presponseLen: The presponse length

  • ptimeStamp: The ptime stamp

  • freshness: The freshness

  • pfreshnessLen: The pfreshness length

  • chipId: The chip identifier

  • pchipIdLen: The pchip identifier length

  • signature: The signature

  • psignatureLen: The psignature length

  • randomAttst: 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:

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

  2. 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 | See SE05x_P1_t | +——-+————+———————————————-+ | P2 | P2_PBKDF | See SE05x_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-byte SetIndicatorRef 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 length

  • data: The data

  • pdataLen: The pdata length

  • attribute: The attribute

  • pattributeLen: The pattribute length

  • ptimeStamp: The ptime stamp

  • outrandom: The outrandom

  • poutrandomLen: The poutrandom length

  • chipId: The chip identifier

  • pchipIdLen: The pchip identifier length

  • signature: The signature

  • psignatureLen: 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 length

  • data: The data

  • pdataLen: The pdata length

  • ptimeStamp: The ptime stamp

  • outrandom: The outrandom

  • poutrandomLen: The poutrandom length

  • chipId: The chip identifier

  • pchipIdLen: The pchip identifier length

  • signature: The signature

  • psignatureLen: 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 length

  • data: The data

  • pdataLen: The pdata length

  • attribute: The attribute

  • pattributeLen: The pattribute length

  • ptimeStamp: The ptime stamp

  • outrandom: The outrandom

  • poutrandomLen: The poutrandom length

  • chipId: The chip identifier

  • pchipIdLen: The pchip identifier length

  • signature: The signature

  • psignatureLen: 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 id

  • psize: 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 id

  • ptype: The ptype

  • pisTransient: 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 result

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

  • [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 length

  • outputData: The output data

  • poutputDataLen: 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 mode

  • result: 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 length

  • result: The result of Self Test

  • ptimeStamp: The ptime stamp

  • outrandom: The outrandom

  • poutrandomLen: The poutrandom length

  • chipId: The chip identifier

  • pchipIdLen: The pchip identifier length

  • signature: The signature

  • psignatureLen: 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_EC

See 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_RSA

See 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

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

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

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

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

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.

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

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

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.

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