The YKOATH protocol is used to manage and use OATH credentials with a YubiKey NEO, YubiKey 4, or YubiKey 5. It can be accessed over USB (when the CCID transport is enabled) or over NFC, using ISO 7816-4 commands as defined in this document.
Instructions marked as Require Auth require a successful VALIDATE command to be performed before they are available, if a validation code is set.
| Name | Code | Require Auth |
|---|---|---|
PUT |
0x01 |
Y |
DELETE |
0x02 |
Y |
SET CODE |
0x03 |
Y |
RESET |
0x04 |
N |
LIST |
0xa1 |
Y |
CALCULATE |
0xa2 |
Y |
VALIDATE |
0xa3 |
N |
CALCULATE ALL |
0xa4 |
Y |
SEND REMAINING |
0xa5 |
Y |
HMAC-SHA1 |
0x01 |
HMAC-SHA256 |
0x02 |
HMAC-SHA512 |
0x03 |
|
Note
|
HMAC-SHA512 requires YubiKey 4.3.1 or later. |
HOTP |
0x10 |
TOTP |
0x20 |
Only increasing |
0x01 |
Enforces that a challenge is always higher than the previous |
Require touch |
0x02 |
Require button press to generate OATH codes |
|
Note
|
Require touch requires YubiKey 4.2.4 or later. |
Selects the application for use and returns version, ID and a challenge if authentication is configured (see the validate instruction below).
CLA |
0x00 |
INS |
0xa4 |
P1 |
0x04 |
P2 |
0x00 |
Lc |
Length of AID (7) |
Data |
AID (0xa0 0x00 0x00 0x05 0x27 0x21 0x01) |
A challenge is returned if the authentication object is set. In that case an authentication is required for all commands except VALIDATE and RESET.
Version tag |
0x79 |
Version length |
Length of version |
Version data |
Version |
Name tag |
0x71 |
Name length |
Length of name |
Name data |
Name |
Challenge tag |
0x74 |
Challenge length |
Length of challenge |
Challenge data |
Challenge |
Algorithm tag |
0x7b |
Algorithm length |
Length of algorithm (1) |
Algorithm |
What algorithm to use |
Adds a new (or overwrites) OATH credential.
CLA |
0x00 |
INS |
0x01 |
P1 |
0x00 |
P2 |
0x00 |
Lc |
Length of Data |
Data |
Put Data |
Name tag |
0x71 |
Name length |
Length of name data, max 64 bytes |
Name data |
Name |
Key tag |
0x73 |
Key length |
Length of key data + 2 |
Key algorithm |
High 4 bits is type, low 4 bits is algorithm |
Digits |
Number of digits in OATH code |
Key data |
Key |
Property tag(o) |
0x78 |
Property(o) |
Property byte |
IMF tag(o) |
0x7a (only valid for HOTP) |
IMF length(o) |
Length of imf data, always 4 bytes |
IMF data(o) |
Imf |
Success |
0x9000 |
No space |
0x6a84 |
Auth required |
0x6982 |
Wrong syntax |
0x6a80 |
Deletes an existing credential.
CLA |
0x00 |
INS |
0x02 |
P1 |
0x00 |
P2 |
0x00 |
Lc |
Length of Data |
Data |
Delete Data |
Name tag |
0x71 |
Name length |
Length of name data |
Name data |
Name |
Success |
0x9000 |
No such object |
0x6984 |
Auth required |
0x6982 |
Wrong syntax |
0x6a80 |
Configures Authentication. If length 0 is sent, authentication is removed. The key to be set is expected to be a user-supplied UTF-8 encoded password passed through 1000 rounds of PBKDF2 with the ID from select used as salt. 16 bytes of that are used. When configuring authentication you are required to send an 8 byte challenge and one authentication-response with that key, in order to confirm that the application and the host software can calculate the same response for that key.
CLA |
0x00 |
INS |
0x03 |
P1 |
0x00 |
P2 |
0x00 |
Lc |
Length of Data |
Data |
Set Code Data |
Key tag |
0x73 |
Key length |
Length of key data + 1 |
Key algorithm |
Algorithm |
Key data |
Key |
Challenge tag |
0x74 |
Challenge length |
Length of challenge data |
Challenge data |
Challenge |
Response tag |
0x75 |
Response length |
Length of response data |
Response data |
Response |
Success |
0x9000 |
Response doesn’t match |
0x6984 |
Auth required |
0x6982 |
Wrong syntax |
0x6a80 |
Resets the application to just-installed state.
CLA |
0x00 |
INS |
0x04 |
P1 |
0xde |
P2 |
0xad |
Success |
0x9000 |
Lists configured credentials.
CLA |
0x00 |
INS |
0xa1 |
P1 |
0x00 |
P2 |
0x00 |
Response will be a continual list of objects looking like:
Name list tag |
0x72 |
Name length |
Length of name + 1 |
Algorithm |
High 4 bits is type, low 4 bits is algorithm |
Name data |
Name |
Success |
0x9000 |
More data available |
0x61xx |
Auth required |
0x6982 |
Generic error |
0x6581 |
Performs CALCULATE for one named credential.
CLA |
0x00 |
INS |
0xa2 |
P1 |
0x00 |
P2 |
0x00 for full response 0x01 for truncated |
Lc |
Length of data |
Data |
Calculate data |
Name tag |
0x71 |
Name length |
Length of name data |
Name data |
Name |
Challenge tag |
0x74 |
Challenge length |
Length of challenge |
Challenge data |
Challenge |
Response tag |
0x75 for full response, 0x76 for truncated |
Response length |
Length of response + 1 |
Digits |
Number of digits in the OATH code |
Response data |
Response |
Success |
0x9000 |
No such object |
0x6984 |
Auth required |
0x6982 |
Wrong syntax |
0x6a80 |
Generic error |
0x6581 |
Validates authentication (mutually). The challenge for this comes from the SELECT command. The response if computed by performing the correct HMAC function of that challenge with the correct key. A new challenge is then sent to the application, together with the response. The application will then respond with a similar calculation that the host software can verify.
CLA |
0x00 |
INS |
0xa3 |
P1 |
0x00 |
P2 |
0x00 |
Lc |
Length of data |
Data |
Validate data |
Response tag |
0x75 |
Response length |
Length of response |
Response data |
Response |
Challenge tag |
0x74 |
Challenge length |
Length of challenge |
Challenge data |
Challenge |
Response tag |
0x75 |
Response length |
Length of response |
Response data |
Response |
Success |
0x9000 |
Auth not enabled |
0x6984 |
Wrong syntax |
0x6a80 |
Generic error |
0x6581 |
Performs CALCULATE for all available credentials, returns name + response for TOTP and just name for HOTP and credentials requiring touch.
CLA |
0x00 |
INS |
0xa4 |
P1 |
0x00 |
P2 |
0x00 for full response 0x01 for truncated |
Lc |
Length of data |
Data |
Calculate all data |
Challenge tag |
0x74 |
Challenge length |
Length of challenge |
Challenge data |
Challenge |
For HOTP the response tag is 0x77 (No response) For credentials requiring touch the response tag is 0x7c (No response) The response will be a list of the following objects:
Name tag |
0x71 |
Name length |
Length of name |
Name data |
Name |
Response tag |
0x77 for HOTP, 0x7c for touch, 0x75 for full response or 0x76 for truncated response |
Response len |
Length of response + 1 |
Digits |
Number of digits in the OATH code |
Response data |
Response |
Success |
0x9000 |
More data available |
0x61xx |
Auth required |
0x6982 |
Wrong syntax |
0x6a80 |
Generic error |
0x6581 |
Gets remaining data if everything didn’t fit in previous response (response code was 61xx).
CLA |
0x00 |
INS |
0xa5 |
P1 |
0x00 |
P2 |
0x00 |
Data |
Continued data where previous command left off |