11.12.3.4.99. Function Se05x_API_ImportExternalObject¶
Defined in File se05x_APDU_apis.h
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:
The user obtains the SE public key for import via the to get the public key from the device’s key pair. Key ID 0x02 will return the public key of the EC key pair with RESERVED_ID_EXTERNAL_IMPORT. The response is signed by the same key pair.
The user calls with input:
the applet AID (e.g.A0000003965453000000010300000000)
the SCPparameters
1-byte SCP identifier, must equal0xAB
2-byte SCP parameter, must equal 0x01 followed by 1-byte security level (which follows the GlobalPlatform security level definition, see: .
key type, must be 0x88 (AES keytype)
key length, must be 0x10 (AES128key)
host public key (65-byte NIST P-256 publickey)
host public key curve identifier (must be 0x03 (=NIST_P256))
ASN.1 signature over the TLV with tags 0xA6 and0x7F49.
The applet will then calculate the master key by performing SHA256 over a byte array containing (in order):
4-byte counter value being0x00000001
shared secret (ECDH calculation according [IEEE P1363] using the private keyfrom RESERVED_ID_ECKEY_SESSION and the public key provided as input to ECKeySessionInternalAuthenticate. The length depends on the curve used (e.g. 32 byte for NIST P-256 curve).
16-byte random generated by the SE05X.
2-byte SCP parameter, must equal 0x01 followed by 1-byte security level (which follows the GlobalPlatform security level definition, see: .
1-byte keytype
1-byte keylength
The master key will then be the 16 MSB’s of the hash output.
Using the master key, the 3 session keys are derived by following the GlobalPlatform specification to derive session keys, e.g. derivation input:
ENCsession key = CMAC(MK, 00000000000000000000000400008001)
CMACsession key = CMAC(MK, 00000000000000000000000600008001)
RMACsession key = CMAC(MK, 00000000000000000000000700008001)
The Authentication Object ID needs to be passed using TAG_IMPORT_AUTH_KEY_ID, followed by the Write APDU command (using tag TAG_1).
The Write APDU command needs to be constructed as follows:
Encrypt the command encryption counter (starting with 0x00000000000000000000000000000001) using the S_ENC key. This becomes the IV for the encrypted APDU.
Get the APDU command payload and pad it (ISO9797 M2 padding).
Encrypt the payload in AES CBC mode using the S_ENC key.
Set the Secure Messaging bit in the CLA (0x04).
Concatenate the MAC chaining value with the full APDU.
Then calculate the MAC on this byte array and append the 8-byte MAC value to the APDU.
Finally increment the encryption counter for the next command.
A receipt will be generated by doing a CMAC operation on the input from tag 0xA6 and 0x7F49 using the RMAC session key,
Receipt = CMAC(RMAC session key, <input from TLV 0xA6 and TLV 0x7F49>)
There is no need to establish a session; therefore, the ImportExternalObject commands are always sent in the default session. The ImportExternalObject commands are replayable.
The P1 and P2 parameters shall be coded as per the intended operation. For example, to import an EC Key, the P1 and P2 parameters as defined in WriteECKey shall be specified.
Command to Applet
Field
Value
Description
CLA
0x80
INS
INS_IMPORT_EXTERNAL
See
SE05x_INS_t
P1
P1_DEFAULT
See
SE05x_P1_t
P2
P2_DEFAULT
See
SE05x_P2_t
Lc
#(Payload)
Payload
TLV[TAG_IMPORT_AUTH_DATA]
Authentication data
TLV[TAG_IMPORT_AUTH_KEY_ID]
Host public key Identifier
TLV[TAG_1]…
Wraps a complete WriteSecureObject command, protected by ECKey session secure messaging
TLV[TAG_11]
4-byte version [Optional]
R-APDU Body
NA
- Parameters
[in] session_ctx
: Session Context [0:kSE05x_pSession][in] ECKeydata
: ECKeydata [1:kSE05x_TAG_2][in] ECKeydataLen
: Length of ECKeydata[in] serializedObject
: serializedObject [2:kSE05x_TAG_3][in] serializedObjectLen
: Length of serializedObject