LOAD KEY instruction

This command loads an authentication key into the reader. The authentication keys are used to implement secure transactions (authentication and ciphered/authenticated communication) with contactless cards (PICC) such as Mifare Classic, Desfire, Mifare Plus or Mifare UltraLight C. Some authentication keys are also involved in host communication.

Command format

Field Value Remark
CLA FF
INS 82
P1 Key Structure See table below
P2 Key Index See details below
Lc Length of DataIn 6, 8, 10, 18, 26 or 61 bytes for plain communication
Padded to a multiple of 16 B + 16 B of Hmac for secure communication
(only the 6-B form, for Mifare Classic keys, is described in the PC/SC standard)
DataIn Key Value (Mifare Classic entry)
or
Key Type || Key Flags || Key Value
or
Raw Key Entry for the SAM AV
Encrypted if secure transmission is chosen
Le -

Key Structure (P1)

Bit Values
7 0 : PICC key
1 : host key
6 0 : plain transmission
1 : secure transmission
5 0 : the key is loaded into the volatile memory
1 : the key is loaded into the SAM AV
4 RFU, must be 0
3-0 If bit 6 is set (secure transmission), index of the host key that been used for the encryption

Using a host key for secure transmission

If bit 6 is set in P1, secure transmission is used. Bits 3-0 select the host key. Only two values are supported:

Bits 3-0 in P1 Refers to Alias
06 Key that protects the communication with the host HostCommUserKey
07 Key that protects the communication with the host and opens administrative access HostCommAdminKey

In this case, the command is protected by a HMAC and an AES cipher:

  1. Invoke the GET CHALLENGE instruction to get a 32-B Nonce: FF B4 00 00 20,
  2. Split Nonce in two 16-B entities:
    • Nonce1 = Nonce [ 0 .. 15 ]
    • Nonce2 = Nonce [ 16..31 ]
  3. Compute Hmac = HMAC-SHA256 ( KHOST , Nonce1 || CLA || INS || P1 || P2 || Lc || DataInPLAIN ),
  4. Truncate Hmac to keep the first 8 bytes of the output only : Hmac = Hmac [ 0..7 ]
  5. Cipher DataInSECURE = AES-CBC ( KHOST , DataInPLAIN || Padding , IV=Nonce2 ) || Hmac where
    • Padding is the 80 byte followed by as many 00s as required to reach a multiple of 16 bytes,
    • The first init vector of the CBC is Nonce2,
  6. Adjust Lc to match the length of DataInSECURE.

Key Index (P2)

Volatile memory

The device has 32 volatile key slots numbered 00 to 1F. The slots are emptied when the device is reset.

Note

Volatile slots can’t be used to store host keys, only PICC keys.

Secure Element

The Secure Element may store up to 128 keys, with some restrictions detailed in SAM AV : Key mapping. These restrictions implies that the type of the key (PICC or host) is correlated to its index, and that not all keys can be loaded by this instruction.

Host keys

If bit 7 is set in P1, this instruction is used to change a host key.

Only the two host keys 06 and 07 are implemented, and must be AES keys (length of the key value = 16).

Key index (P2) Refers to Alias
06 Key that protects the communication with the host HostCommUserKey
07 Key that protects the communication with the host and opens administrative access HostCommAdminKey

Notes

Loading key 06 (HostCommUserKey) and 07 (HostCommAdminKey) is possible only with secure transmission.

Loading key 07 (HostCommAdminKey) is possible only is key 07 itself is used to secure the transmission.

Loading keys with plain transmission or with key 06 can be disabled by configuration.

PICC keys

If bit 7 is not set in P1, this instruction is used to change a PICC key.

Key indexes for PICC keys must comply with the following table:

Key index (P2) Type of PICC key
20 to 2F Mifare Classic
30 to 3F Any PICC key but Mifare Classic
40 to 7F Any PICC key but Mifare Classic

DataIn

The DataIn field may adopt different forms, and different length:

Form Length Description
Key Value 6 Load a Mifare Classic key into the volatile memory or the SE
(only this form is described in the PC/SC standard)
Key Type || Key Flags || Key Value 8 to 26 Load any kind of PICC key into the volatile memory or the SE, or host key into the SE
Key Entry 61 Load a complete Key Entry in the SE - See the documentation of the Secure Element

Key Type field

This 1-byte field tells the device the type of the key. This has an impact on the length of the Key Value field.

Possible values are:

Key Type Description Length of Key Value
00 Mifare Classic key (CRYPTO1) 6
09 Mifare UltraLight C, 3DES2K key 16
10 Mifare Plus, AES-128 key 16
21 Desfire EV0, DES or 3DES2K key 8 or 16
28 Desfire EV1, AES-128 key 16
29 Desfire EV1, DES, 3DES2K or 3DES3K key 8, 16 or 24
30 Desfire EV2, AES-128 key 16
F0 Host key, AES 128 16

Note

If the Key Type field is missing (Lc = 6), it defaults to 00 (PICC key for Mifare Classic).

Key Flags field

This 1-byte field tells the device whether a key diversification algorithm has to be applied to the key, and whether it may be loaded into a PICC (to format it), or not.

Key Flag bits Values
7 0 : this key can be used “as is”
1 : this key must be used after diversification
6-1 RFU, must be 000000
0 0 : this key is for authentication only
1 : this key may be loaded into a PICC

Notes

If the Key Flags field is missing (Lc = 6), it defaults to 00 (no diversification, the key can’t be load into a PICC).

For a host key, this field must by 00.

Key Value field

The length of the Key Value field depends on the cryptographic used.

Key Type Length of the key (Lc) Usable for
Mifare Classic 6 Mifare Classic (CRYPTO1)
DES 8 Desfire EV0, Desfire EV1
3DES2K 16 Desfire EV0, Desfire EV1, Mifare UltraLight C
3DES3K 24 Desfire EV1
AES 16 Desfire EV1, Desfire EV2, Mifare Plus, host key

Response

Field Value Remark
SW 9000 on success See specific error codes below; other values are documented in Status Words

Specific error codes

SW Reason
6300 Secure transmission failed (DataINSECURE is invalid)
6382 PICC key not supported (possible root reason: incompatible entry)
6383 Host key not supported(possible root reason: incompatible entry, key type is not AES)
6384 Plain transmission not supported (possible root reason: secure transmission enforced by configuration)
Plain transmission not allowed for a host key
6385 Secure transmission not supported (possible root reason: the host key index specified in bits 3-0 of P1 is not allowed)
6386 Volatile memory is not available
A host key can’t be loaded into the volatile memory
6387 Non volatile memory is not available (the device does not have a Secure Element)
6388 Key index is not valid
Key index is not allowed for the key type
6389 Key length is not valid
Key length does not match the key type