11.12.3.4.99. Function Se05x_API_ImportExternalObject

11.12.3.4.99.1. Function Documentation

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