Introduction

This documents the extensions to PIV that is shipped by Yubico.

Instructions

Name Code

Set management key

0xff

Import asymmetric key

0xfe

Get version

0xfd

Reset

0xfb

Set PIN retries

0xfa

Attest

0xf9

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 & 5.3+.

The output is a DER encoded X.509 certificate.

Syntax

CLA

0x00

INS

0xf9

P1

Slot

P2

0x00

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 & 5” to “YubiKey”.

YubiKey 5 Series

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

ATS

0x12, 0x78, 0xb3, 0x84, 0x00, 0x80, 0x73, 0xc0, 0x21, 0xc0, 0x57, 0x59, 0x75, 0x62, 0x69, 0x4b, 0x65, 0x79

YubiKey 4 & 5 Series

ATR

0x3b, 0xf8, 0x13, 0x00, 0x00, 0x81, 0x31, 0xfe, 0x15, 0x59, 0x75, 0x62, 0x69, 0x6b, 0x65, 0x79, 0x34, 0xd4

YubiKey NEO

ATR

0x3b, 0xfc, 0x13, 0x00, 0x00, 0x81, 0x31, 0xfe, 0x15, 0x59, 0x75, 0x62, 0x69, 0x6b, 0x65, 0x79, 0x4e, 0x45, 0x4f, 0x72, 0x33, 0xe1