Get AES-128 session keys
Get the SCP03 session keys from an AES-128 credential.
Available
All YubiKeys with the YubiHSM Auth application (included in firmware version 5.4.3 and later).
Note
Use the .NET API's HasFeature() method to check if a key has the YubiHSM Auth application.
SDK classes
Input
Before calling this operation, the host needs to generate an 8-byte challenge (the host challenge). The host challenge is typically generated using a random or pseudorandom method. The host sends the host challenge to the HSM device, which returns its own 8-byte challenge (the HSM device challenge). See YubiHSM Shell for ways to communicate with the HSM device.
To call GetAes128SessionKeysCommand, you must pass it the label and password of the AES-128 credential that will be used to calculate the SCP03 session keys as well as the host challenge and HSM device challenge from the initial step. There is a limit of 8 attempts to authenticate with the password before the credential is deleted. Once the credential is deleted, it cannot be recovered. Supplying the correct password before the credential is deleted will reset the retry counter to 8.
The credential may require proof of user presence. This is configured when the credential is added ( see AddCredentialCommand). In this case, the user must touch the YubiKey in order to complete the authentication procedure. Otherwise, the command will fail (though the credential password retry counter does not change).
Output
An array which contains the ENC, MAC, and R-MAC session keys. Each key is exactly 16-bytes long.
In the case of a failure, the status word in the response may include further information. For example, the credential was configured to require touch, but the user did not touch the YubiKey.
Command APDU
| CLA | INS | P1 | P2 | Lc | Data | Le |
|---|---|---|---|---|---|---|
| 00 | 03 | 00 | 00 | variable | (TLV, see below) | (absent) |
Data
The data is sent as concatenated TLV-formatted elements, as follows:
| Tag (hexadecimal) | Length (decimal) | Value | Notes |
|---|---|---|---|
| 0x71 | 1-64 | label | UTF-8 encoded string |
| 0x77 | 16 | {host challenge, HSM device challenge} | challenges as byte arrays, concatenated together |
| 0x73 | 16 | password | byte array |
Response APDU
Total Length: 50
Data Length: 48
| Data | SW1 | SW2 |
|---|---|---|
| {ENC, MAC, R-MAC} | 90 | 00 |