Introduction

This documents the PIV extensions that are shipped by Yubico.

For more information on PIV APDUs, see the guidance provided by Special Publication (SP) 800-73-4, Interfaces for Personal Identity Verification from the US government’s National Institute of Standards and Technology (NIST) Computer Security Resource Centre: https://csrc.nist.gov/publications/detail/sp/800-73/4/final.

Instructions

Name	Code
Set management key	0xff
Import asymmetric key	0xfe
Get version	0xfd
Reset	0xfb
Set PIN retries	0xfa
Attest	0xf9
Get serial	0xf8
Get metadata	0xf7

SET MANAGEMENT KEY

Set a new management key. For this authentication with management key is required. Require touch is only available on YubiKey 4 & 5.

Syntax

CLA	0x00
INS	0xff
P1	0xff
P2	0xff for no touch, 0xfe for require touch

Data

Algorithm	0x03
Key ID	0x9b
Key Length	24
Key Data

IMPORT ASYMMETRIC KEY

Import a new asymmetric key. For this authentication with management key is required.

Syntax

CLA	0x00
INS	0xfe
P1	Algorithm
P2	Key ID

Data

Tag P	0x01	P Value for RSA Key
Tag Q	0x02	Q Value for RSA Key
Tag dP	0x03	dP Value for RSA Key
Tag dQ	0x04	dQ Value for RSA Key
Tag Qinv	0x05	Qinv Value for RSA Key
Tag S	0x06	S Value for EC Key

GET VERSION

Get the version of the PIV implementation.

Syntax

CLA	0x00
INS	0xfd
P1	0x00
P2	0x00

RESET

Reset to default state. Only available if both PIN and PUK is blocked.

Syntax

CLA	0x00
INS	0xfb
P1	0x00
P2	0x00

SET PIN RETRIES

Set the PIN retries for PIN and PUK. Both PIN and PUK will be reset to default values when this is executed. For this authentication in management mode is required and PIN has to be validated.

Syntax

CLA	0x00
INS	0xfa
P1	PIN retries
P2	PUK retries

PIN POLICY

Set PIN policy to be used for a key, valid for generate and import. Only available in YubiKey 4 & 5.

Syntax

The tag used is 0xaa and possible values are:

Default	0x00	The default behaviour for that key is used
Never	0x01	PIN is never checked for operations
Once	0x02	PIN is checked once for the session
Always	0x03	PIN is verified just before operation

TOUCH POLICY

Set touch policy to be used for a key, valid for generate and import. Only available in YubiKey 4 & 5.

Syntax

The tag used is 0xab and possible values are:

Default	0x00	The default behaviour for that key is used
Never	0x01	Touch is never required for operations
Always	0x02	Touch is always required for operations
Cached	0x03	Touch is cached for 15s after use (valid from 4.3).

ATTESTATION

Get an attestation certificate for a slot where the key has been generated on device. Only available in YubiKey 4.3 & 5.

The output is a DER encoded X.509 certificate.

Syntax

CLA	0x00
INS	0xf9
P1	Slot
P2	0x00

GET SERIAL

Get the serial number of the device. Only available in YubiKey 5.

Syntax

CLA	0x00
INS	0xf8
P1	0x00
P2	0x00

Encoded as a four-bytes Big-Endian number: 0001e240 for serial number 123456.

GET METADATA

Get information about a specific key. Only available in YubiKey 5.3.

Syntax

CLA	0x00
INS	0xf7
P1	0x00
P2	Slot

The following TLVs will be returned if the key is present:

Algorithm	0x01	Algorithm/type of the key
Policy	0x02	PIN and Touch policy of the key (keys only)
Origin	0x03	Origin of the key: imported or generated
Public key	0x04	Public key associated with the private key
Default value	0x05	Whether the PIN/key has a default value (PIN, PUK and Mgmt key only)
Retries	0x06	Number of retries left (PIN and PUK only)

Use slot 0x80 for PIN, slot 0x81 for PUK and slot 0x9b for the Management key.

Only the TLV that apply to an object will be returned.

Answer To Reset (ATR) and Answer To Select (ATS)

Note: The YubiKey 5 Series ATR card issuer’s data has been changed from Yubikey 4 to YubiKey.

YubiKey 5 Series USB	ATR	0x3b, 0xfd, 0x13, 0x00, 0x00, 0x81, 0x31, 0xfe, 0x15, 0x80, 0x73, 0xc0, 0x21, 0xc0, 0x57, 0x59, 0x75, 0x62, 0x69, 0x4b, 0x65, 0x79, 0x40
YubiKey 5 Series NFC	ATR	0x3b, 0x8d, 0x80, 0x01, 0x80, 0x73, 0xc0, 0x21, 0xc0, 0x57, 0x59, 0x75, 0x62, 0x69, 0x4b, 0x65, 0x79, 0xf9
YubiKey 5 Series USB	ATS	0x12, 0x78, 0xb3, 0x84, 0x00, 0x80, 0x73, 0xc0, 0x21, 0xc0, 0x57, 0x59, 0x75, 0x62, 0x69, 0x4b, 0x65, 0x79
YubiKey 4 Series USB	ATR	0x3b, 0xf8, 0x13, 0x00, 0x00, 0x81, 0x31, 0xfe, 0x15, 0x59, 0x75, 0x62, 0x69, 0x6b, 0x65, 0x79, 0x34, 0xd4
YubiKey NEO USB	ATR	0x3b, 0xfc, 0x13, 0x00, 0x00, 0x81, 0x31, 0xfe, 0x15, 0x59, 0x75, 0x62, 0x69, 0x6b, 0x65, 0x79, 0x4e, 0x45, 0x4f, 0x72, 0x33, 0xe1
YubiKey NEO NFC	ATR	0x3b, 0x8c, 0x80, 0x01, 0x59, 0x75, 0x62, 0x69, 0x6b, 0x65, 0x79, 0x4e, 0x45, 0x4f, 0x72, 0x33, 0x58