Show / Hide Table of Contents

PIV commands

For each possible PIV command, there will be a class that knows how to build the command APDU and parse the data in the response APDU. Each class will know what information is needed from the caller for that command.

According to the PIV standard, there is "Off-Card" and "On-Card". The off-card application is the one calling the YubiKey. The keys, data, and firmware running on the YubiKey is "on-card"

List of PIV commands

  • Get the serial number
  • Get the firmware version number
  • Get metadata
  • Get Bio metadata
  • Verify the PIN
  • Biometric verification
  • Authenticate: management key
  • Set PIN retries
  • Change reference data (change the PIN or PUK)
  • Set the management key (change the management key)
  • Reset retry (recover the PIN)
  • Generate asymmetric key pair
  • Import asymmetric (import a private key)
  • Authenticate: sign
  • Authenticate: decrypt
  • Authenticate: key agreement
  • Create attestation statement
  • Get data
  • Put data
  • Reset

Get the serial number

This gets the YubiKey's serial number.

Available

YubiKey 5 and later.

SDK Classes

GetSerialNumberCommand

GetSerialNumberResponse

Input

None.

Output

int

To see the serial number as a decimal string, use ToString(). For example,

  int serialNumber = serialResponse.GetData();
  string decimalSerial = serialNumber.GetString();
  string hexSerial = serialNumber.GetString("X");

  // Print out the decimalSerial to get something like "11409355"
  // Print out the hexSerial to get something like "00AE17CB"

APDU

Technical APDU Details


Get the firmware version number

This gets the YubiKey firmware version number.

Available

All YubiKeys with the PIV application.

SDK Classes

VersionCommand

VersionResponse

Input

None.

Output

FirmwareVersion

APDU

Technical APDU Details


Get metadata

This gets information about the key in a particular slot.

It is possible to get metadata about public/private key pairs in those slots that hold private keys. It is also possible to get metadata about the symmetric key that is the management key in slot 9B. Finally, it is possible to get metadata about the PIN and PUK, accessed by slots 80 and 81.

There are six possible information elements (described below), but not all keys will report all six elements. Furthermore, if there is no key in a particular slot, there will be no metadata to get. That is, if you execute the Get Metadata command for a slot that has no key, the data retrieved will be "None" or "NoKey".

Available

YubiKey 5.3 and later.

SDK Classes

GetMetadataCommand

GetMetadataResponse

Input

Slot number. See the User's Manual entry on PIV slots and the enum PivSlot for information on the valid PIV slots.

Output

Table 1: List of Metadata Elements

Name Meaning Data Slots
Algorithm Algorithm of the key PIN, PUK, Triple DES, AES-128, AES-192, AES-256,
RSA-1024, RSA-2048, RSA 3072, RSA 4096, ECC-P256, or ECC-P384
all slots
Policy PIN and touch policy PIN: Default, Never, Once, Always
Touch: Default, Never, Always, Cached
9A, 9B, 9C, 9D, 9E, F9, 82 - 95
Origin Imported or generated imported/generated 9A, 9C, 9D, 9E, F9, 82 - 95
Public Pub key partner to the pri key DER encoding of public key 9A, 9C, 9D, 9E, F9, 82 - 95
Default Whether PIN/PUK/Mgmt Key has default value Default or Not Default 80, 81, 9B
Retries Retry count and retries remaining two numbers 80, 81

Another way to look at what is returned is the following table that lists which data elements are returned for each slot.

Table 2: List of PIV slots and the metadata elements returned

Slot Number (hex) Key Data returned
80 PIN Algorithm, Default, Retries
81 PUK Algorithm, Default, Retries
9B Management Algorithm, Policy, Default
82, 83, ..., 95 (20 slots) Retired Keys Algorithm, Policy, Origin, Public
9A Authentication Algorithm, Policy, Origin, Public
9C Signing Algorithm, Policy, Origin, Public
9D Key Management Algorithm, Policy, Origin, Public
9E Card Authentication Algorithm, Policy, Origin, Public
F9 Attestation Algorithm, Policy, Origin, Public

APDU

Technical APDU Details


Get Bio metadata

This gets YubiKey's biometric metadata.

Available

YubiKey Bio Multi-protocol 5.6 and later.

SDK Classes

GetBioMetadataCommand

GetBioMetadataResponse

Output

Table 1: List of Metadata Elements

Name Meaning Data
IsConfigured Whether the device is configured for biometric verification bool
RetriesRemaining Number of remaining retries for biometric verification integer; zero value means the biometric verification is blocked
HasTemporaryPin Whether a temporary PIN is generated bool

APDU

Technical APDU Details


Verify

Verify a PIN.

This is generally used in conjunction with other commands that require PIN entry to work. For example, to sign data using one of the PIV private keys, it is possible the PIN is needed. Use this command to enter the PIN, and if the operation is a success, execute the sign command.

A YubiKey will allow "retry count" incorrect PIN verification attempts in a row, before it blocks the PIN. For example, suppose the retry count is three. That means if you call Verify with an incorrect PIN three times in a row, the PIN will be blocked. Any attempt thereafter to verify the PIN will fail, so any operation that requires the PIN will not run.

There is a "retry count" and a "remaining count". The retry count is the number of tries the YubiKey will allow before locking the PIV application. The remaining count is the current number of tries still left.

Note that when a PIV PIN is blocked, it is only the PIV application that will be unusable. This has no effect on the other applications.

For example, suppose the program sets the retry count to 5. At that point, both the retry and remaining count are 5. Now suppose someone tries to verify the PIN with the wrong value. The remaining count drops to 4. The retry count is still 5, but at the moment there are only 4 tries left before the PIN will be blocked.

If you call Verify with the incorrect PIN, the result will include the remaining count. Once you call Verify with the correct PIN, the remaining count is reset to the retry count.

Note that if the remaining count is more than 15, and the wrong PIN is given, the response to the Verify command will indicate 15 retries remaining. This is because the YubiKey has only 4 bits in its response to return the remaining retry count.

The default retry count is three, but you can change that using the Set PIN retries command. The retry count can be a value from 1 to 255. You can also get the PIN retry numbers (retry count and remaining count) using the Get metadata command (valid on YubiKeys 5.3 and later).

It is possible that the remaining count is 0 before calling the verify PIN command. This means the PIN has been blocked. If you call verify PIN again, even with the correct PIN, the result will be false and the remaining count will remain 0.

If a PIN is blocked, it is possible to unblock it using the Reset Retry command. If the PUK is blocked as well, the only recovery is to Reset the PIV application.

Available

All YubiKeys with the PIV application.

SDK Classes

VerifyPinCommand

VerifyPinResponse

Input

The PIN to verify. It is six, seven, or eight characters (bytes) long.

Output

An int?. If the PIN verifies, this will be NULL, if it did not verify, this will be the remaining count (number of retries left before the PIN is blocked).

If the PIN is correct, there will be no remaining count (it will be null), and the Status property will be Success.

If the PIN is not correct, the int returned will be the remaining count and the Status property will be AuthenticationRequired. An incorrect PIN is not an (exception-throwing) error. This Command determines if a PIN is correct or not, and if a PIN is incorrect, the command performed its task.

Each time an incorrect PIN is entered, the remaining count is decremented. Once the correct PIN has been entered, the remaining count is restored to the full retry count. See also Set PIN retries.

Note that it is possible to have an error (such as malformed input data), and the PIN could not be verified. In this situation the Status will be set to the appropriate value and GetData will throw an exception.

APDU

Technical APDU Details


Biometric verification

With biometric verification, users can authenticate the PIV session with a successful match of a fingerprint. To execute biometric verification, the YubiKey must have biometrics configured and enabled. Clients can verify these conditions by reading the properties of biometric metadata (see Get Bio metadata).

The YubiKey keeps track of failed biometric matches and will block biometric authentication if there are more than three such failures. In that case, the client should use the PIV PIN verification as soon as possible. The number of remaining biometric verification attempts is returned in the command response's AttemptsRemaining property. The value is present only after a failed match.

Clients can also request to generate a temporary PIN, which can be used with the VerifyTemporaryPinCommand for authentication without the need of a biometric match. The temporary PIN is stored in YubiKey's RAM and is invalidated after the PIV session is closed or an invalid temporary PIN is used. For PIN_OR_MATCH_ALWAYS slot policy, the temporary PIN can be used only once.

Available

YubiKey Bio Multi-Protocol keys.

SDK Classes

VerifyUvCommand

VerifyUvResponse

VerifyTemporaryPinCommand

VerifyTemporaryPinResponse

Input

VerifyUvCommand

Two boolean values:

  • request temporary PIN - if true, the YubiKey will wait for the user to perform biometric verification (match an enrolled fingerprint) and, if verification is successful, generate a temporary PIN.
  • check only - when true, the YubiKey verifies internally that the biometric state is valid. No biometric verification is performed on the YubiKey.

A client application would typically call the command with false, false parameters - this will make the YubiKey request the biometric verification from the users.

VerifyTemporaryPinCommand

The temporary PIN is the only parameter.

Output

VerifyUvResponse

If a temporary PIN was requested and the status is Success, the returned value is the temporary PIN. In case of failure (for example, the fingerprint did not match), the clients should read the AttemptsRemaining property, which contains the number of remaining biometric attempts.

VerifyTemporaryPinResponse

No output. The Status will be Success if the temporary PIN was verified.

APDU

Technical APDU Details for VerifyUvCommand

Technical APDU Details for VerifyTemporaryPinCommand


Authenticate: management key

The Authenticate command can be used to perform several cryptographic operations:

  • Authenticate the Management Key to the YubiKey
  • Sign data using a private key
  • Decrypt data using a private key
  • Perform key agreement using a private key

This section discusses authenticating the management key. See Authenticate: sign, Authenticate: decrypt, and Authenticate: key agreement for information on signing, decrypting, and key agreement.

The primary purpose of this command is to authenticate the client application (off-card application) to the YubiKey. That is, before the YubiKey is able to perform some operations, it must know that the caller has access to the management key. This section will refer to this action as Client Authentication.

It is also possible to authenticate the YubiKey to the client application, so that the app knows it is communicating with the appropriate YubiKey. Maybe the app wants to be sure it will not call on an attacker's YubiKey to perform a sensitive operation. This section will refer to this action as YubiKey Authentication.

Hence, the authenticate management key command can actually perform two different operations: "single authentication" (Client Authentication only), or "mutual authentication" (Client Authentication and YubiKey Authentication). How you call the API determines which operation will be performed.

The authentication is done using "challenge-response". Note that the word "response" is used in "Response APDU" and "Response Class". So to avoid ambiguity, these are the terms we will use in this section.

  • Response APDU
  • Response Class or Response Object (e.g. InitializeAuthenticateManagementKeyResponse is a Response Class and an instantiation of that class is a Response Object)
  • Client Authentication Challenge/Response (the Challenge-Response pair associated with Client Authentication)
  • YubiKey Authentication Challenge/Response (the Challenge-Response pair associated with YubiKey Authenticaiton)

The process is the following:

Single Authentication
Client (Off-Card) Application YubiKey
Step 1
Initiate the process (single auth)
Generate random Client Authentication Challenge
Step 2
Compute the Client Authentication Response based on Client Authentication Challenge
Verify the Client Authentication Response
Return Success or AuthenticationRequired
Mutual Authentication
Client (Off-Card) Application YubiKey
Step 1
Initiate the process (mutual auth)
Generate random Client Authentication Challenge
Step 2
Compute the Client Authentication Response based on Client Authentication Challenge
Generate random YubiKey Authentication Challenge
Verify the Client Authentication Response
Compute the YubiKey Authentication Response based on YubiKey Authentication Challenge
Return Success or AuthenticationRequired
along with YubiKey Authentication Response
Step 3
Verify the YubiKey Authentication Response

Available

All YubiKeys with the PIV application.

Beginning with YubiKey 5.4.2, the management key can be an AES key.

SDK Classes

InitializeAuthenticateManagementKeyCommand

InitializeAuthenticateManagementKeyResponse

CompleteAuthenticateManagementKeyCommand

CompleteAuthenticateManagementKeyResponse

Input

Authenticating with the management key requires two calls (send two APDUs). It will be a challenge-response process. The first call will take the algorithm, the second will take in the response APDU from the first call, the management key, and the algorithm.

Output

The output of the YubiKey depends on whether the process is single or mutual authentication, and step 1 or step 2.

  • Single Auth, Step 1: output is Client Authentication Challenge
  • Single Auth, Step 2: output is the result of verifying the Client Authentication Response
  • Mutual Auth, Step 1: output is Client Authentication Challenge
  • Mutual Auth, Step 2: output is YubiKey Authentication Response (to be verified by the client (off-card) application) and the result of Client Authentication

The output of the Response classes is the following.

  • Single Auth, Step 1: output is Client Authentication Challenge
  • Single Auth, Step 2: output is the result of verifying the Client Authentication Response
  • Mutual Auth, Step 1: output is Client Authentication Challenge
  • Mutual Auth, Step 2: output is the result of Client Authentication, and, if Client Authentication was successful, YubiKey Authentication Response

The process is explained in the documentation for CompleteAuthenticateManagementKeyCommand

APDU

Technical APDU Details


Set PIN retries

Set the number of PIN retries allowed before the PIN and PUK are blocked. The default is three. Note that this command will set the retry count for both the PIN and PUK. If you want to set the retry count for only one entity, you must still set the retry count for the other.

Note also that this will reset the PIN and PUK to the default values. For example,

  current PIN: 7777777    retry count: 3
  current PUK: 88888888   retry count: 3

Call this command to set the PIN retry count to 5 and the PUK retry count to 2.
After successful completion of the command, the PIN and PUK are the following.

  current PIN: 123456     retry count: 5
  current PUK: 12345678   retry count: 2

If you don't want to leave the PIN and PUK as the default values, follow this command with the Change reference data command.

Before the YubiKey can set the PIN retries, the caller must have authenticated the management key and verified the PIN. See the User's Manual entry on PIV commands access control for information on how to authenticate with the management key and/or PIN for commands. See also the sections in this page on Authenticate: management key and Verify the PIN.

Available

All YubiKeys with the PIV application.

SDK Classes

SetPinRetriesCommand

SetPinRetriesResponse

Input

The management key, and the number of retries for the PIN and the number of retries for the PUK.

Output

There is no data output, only the status.

If the command was not successful, it will almost certainly be because the management key or PIN supplied was not correct. This command will return an error indicating authentication is required. But it will not report which element (management key or PIN) was incorrect. Generally you will not call this command until you have successfully authenticated the management key and verified the PIN.

APDU

Technical APDU Details


Change Reference Data

Change a PIN or PUK (PIN Unblocking Key). The term "reference data" in this case refers to the "authentication data".

According to NIST 800-73, there are three possible reference data elements that can be changed using this command:

  • Global PIN
  • PIV PIN
  • PUK

However, the YubiKey does not have a global PIN. Hence, the SDK will only support changing the PIV PIN and PUK using this command.

To change reference data, supply the current value and the new value. For example, to change the PIN, provide the current PIN and the new PIN. If the current PIN provided is not correct, the PIN will not be changed.

A YubiKey will allow "retry count" incorrect PIN verification attempts in a row, before it blocks the PIN. For example, suppose the retry count is three. That means if you call change reference data with an incorrect PIN three times in a row, the PIN will be blocked. Any attempt thereafter to verify the PIN will fail, so the change reference data command will fail.

If you call change reference data with the incorrect PIN or PUK, the result will include the remaining count (the number of retries left before it is blocked). Once you call change reference data with the correct PIN or PUK, the remaining count is reset to the full retry count.

For example, suppose the retry count is 5, and no invalid PINs have been tried. Now if you call change reference data with the wrong PIN, the remaining count is 4 (the retry count is still 5). Call change reference data with the correct PIN and the remaining count is 5 again.

Note that if the remaining count is more than 15, and the wrong PIN or PUK is given, the response to the change reference data command will indicate 15 retries remaining. This is because the YubiKey has only 4 bits in its response to return the remaining count.

The default retry count is three, but you can change that using the Set PIN retries command. The retry count can be a value from 1 to 255. You can also get the PIN retry numbers (total count and current remaining) using the Get metadata command (valid on YubiKeys 5.3 and later).

It is possible that the remaining count is 0 before calling the change reference data command. This means the PIN or PUK has been blocked. If you call change reference data again, even with the correct PIN or PUK, the result will be false and the remaining count will remain 0.

If a PIN is blocked, it is possible to unblock it using the Reset Retry command. If the PUK is blocked as well, the only recovery is to Reset the PIV application.

Available

All YubiKeys with the PIV application.

SDK Classes

ChangeReferenceDataCommand

ChangeReferenceDataResponse

Input

Which reference data element to change (PIN or PUK), the current reference value, and the new value.

Both the PIN and the PUK are allowed to be 6 to 8 characters. The PIN can be composed of any ASCII character, but PUK composition depends on the key's firmware. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range.

Output

An int?. If the PIN or PUK was successfully changed, this will be NULL, if the correct, current PIN or PUK was not supplied, this will be the remaining count (the number of retries before the PIN or PUK is blocked).

If the current reference data supplied is correct, there will be no remaining count (the return will be null), and the Status property will be Success,

If the current reference data supplied is not correct, the int returned will be the remaining count and the Status property will be AuthenticationRequired. An incorrect PIN/PUK is not an (exception-throwing) error. This Command determines if a PIN/PUK is correct or not, and if it is correct, changes to the new value. If the PIN/PUK is incorrect, the command will return that information, so it has performed its task.

Note that it is possible to have an error (such as malformed input data), and the operation could not be performed. The Status property in the Response object will be Failed.

APDU

Technical APDU Details


Set management key

Set the management key to a new value.

The YubiKey is manufactured with a default PIV management key: hex 010203040506070801020304050607080102030405060708 (0102030405060708 three times). If you want to change to a different key, use this command.

You can also set the management key to a newer value after changing it from the default. You can use this to change the PIN and touch policies as well. If you supply the same key as before, just new PIN and/or touch policies, this will leave the key the same and change only the PIN and touch policies.

Before the YubiKey can set the management key, the caller must have authenticated the current management key. See the User's Manual entry on PIV commands access control for information on how to authenticate with the management key for commands. See also the section in this page on Authenticate: management key.

Available

All YubiKeys with the PIV application, although require touch is available on only 4 and 5.

Beginning with YubiKey 5.4.2, the management key can be an AES key.

SDK Classes

SetManagementKeyCommand

SetManagementKeyResponse

Input

The new key, a touch policy, and the algorithm. This command must be used in conjunction with the Authenticate command. See "Authenticate: Management Key".

For YubiKeys prior to 5.4.2, the new key must be a Triple-DES key. Beginning with 5.4.2, the managment key can be AES.

If the key is Triple-DES, the new key must be 24 bytes, no more, no less. If the key is AES-128, the new key must be 16 bytes, if AES-192, 24 bytes, and if AES-256, 32 bytes. The touch policy is one of three values: always, cached, or never.

Output

There is no data output, only the status.

If the command was not successful, it will almost certainly be because the current management key was not authenticated. This command will return an error indicating authentication is required. Generally you will not call this command until you have successfully authenticated the management key.

APDU

Technical APDU Details


Reset Retry (Recover the PIN)

Reset the PIN.

This is the command to recover the PIN, using the PUK (PIN Unblocking Key), if the PIN has been lost (the user forgot the PIN).

This is similar to the Change Reference Data command. That command can change the PIN if the current PIN is known. This command can change the PIN (or reset it) if the current PIN is unknown, but the PUK is known.

This can be run no matter what the remaining count of the PIN is.

If you call reset retry with the incorrect PUK, the result will include the PUK's remaining count (the number of retries left before it is blocked). Once you call reset retry with the correct PUK, the remaining count is reset to its full retry count.

For example, suppose the retry count is 5, and no invalid PUKs have been tried. Now if you call reset retry with the wrong PUK, the retry count is still 5, but the remaining count is 4. Call reset retry with the correct PUK and the retry count is still 5, and the remaining count is 5 again.

Note that if the remaining count is more than 15, and the wrong PUK is given, the response to the reset retry command will indicate 15 retries remaining. This is because the YubiKey has only 4 bits in its response to return the remaining count.

The default retry count is three, but you can change that using the Set PIN retries command. The retry count can be a value from 1 to 255. You can also get the PUK retry numbers (total count and current remaining) using the Get metadata command (valid on YubiKeys 5.3 and later).

It is possible that the remaining count is 0 before calling the reset retry command. This means the PUK has been blocked. If you call reset retry again, even with the correct PUK, the result will be false and the remaining count will remain 0.

If the PUK is blocked, the only recovery is to Reset the PIV application.

Available

All YubiKeys with the PIV application.

SDK Classes

ResetRetryCommand

ResetRetryResponse

Input

The PUK and the new PIN.

Output

An int?. If the PUK is correct, the PIN will be changed and this will be NULL. If the PIN was not changed, it will be the remaining count.

If the current reference data supplied is correct, there will be no remaining count (the return will be null), and the Status property will be Success,

If the PUK supplied is not correct, the int returned will be the remaining count and the Status property will be AuthenticationRequired. An incorrect PUK is not an (exception-throwing) error. This Command determines if a PUK is correct or not, and if it is correct, changes the PIN to the new value. If the PUK is incorrect, the command performed its task.

Each time an incorrect PUK is entered, the PUK's remaining count is decremented. Once the correct PUK has been entered, the remaining count is restored to the full retry count. See also Set PIN retries.

Note that it is possible to have an error (such as malformed input data), and the operation could not be performed. The Status property in the Response object will be Failed.

APDU

Technical APDU Details


Generate Asymmetric

Generate a new asymmetric key pair and store it in one of the asymmetric key slots.

If a slot is empty, the new generated key pair goes into that slot. If the slot already contains a key, the new key pair replaces the old one. That old key will be gone and there will be nothing you can do to recover it. There is no way to save the old key pair (e.g. move it to a retired slot) before generating the new key pair, so it will be lost. Hence, use this command with caution.

You can generate a new key pair in any slot that holds asymmetric keys, including the slots described as holding retired keys.

Note that you can generate a new key in slot F9, which holds the attestation key. If you do so, however, you could lose the ability to create an attestation statement, unless you obtain, for the new key in F9, a proper attestation certificate that chains to a supported root.

Available

All YubiKeys with the PIV application.

SDK Classes

GenerateKeyPairCommand

GenerateKeyPairResponse

Input

The management key, slot number, algorithm, key size, PIN policy, and touch policy.

The YubiKey supports RSA 1024, 2048, 3072, and 4096 along with ECC P-256 and P-384.

Output

The public key partner to the private key now residing in the given slot.

APDU

Technical APDU Details


Import Asymmetric

Import an asymmetric key, that was generated outside the YubiKey, into one of the asymmetric key slots.

To load the associated public key and/or cert, use the PUT DATA command.

If a slot is empty, the imported key goes into that slot. If the slot already contains a key, the new key replaces the old one. That old key will be gone and there will be nothing you can do to recover it. There is no way to save the old key (e.g. move it to a retired slot) before importing the new key, so it will be lost. Hence, use this command with caution.

Note that you can import a new key in slot F9, which holds the attestation key. If you do so, however, you could lose the ability to create an attestation statement, unless you obtain, for the key in F9, a proper attestation certificate that chains to a supported root.

Available

All YubiKeys with the PIV application.

SDK Classes

ImportAsymmetricKeyCommand

ImportAsymmetricKeyResponse

Input

The management key, the slot number, PIN policy, touch policy, and the new key.

Output

bool: was the private key successfully imported?

APDU

Technical APDU Details


Authenticate: sign

The Authenticate command can be used to perform several cryptographic operations:

  • Authenticate the Management Key to the YubiKey
  • Sign data using a private key
  • Decrypt data using a private key
  • Perform key agreement using a private key

This section discusses signing using a private key. See Authenticate: management key, Authenticate: decrypt, and Authenticate: key agreement for information on authenticating the management key, decrypting, and key agreement.

This command signs arbitrary data. The signature process generally involves digesting the data to sign and then computing a signature based on that digest and the private key. This command does not perform the digest, only the private key operations.

Available

All YubiKeys with the PIV application.

SDK Classes

AuthenticateSignCommand

AuthenticateSignResponse

Input

The PIN (maybe), the slot number, and the digest of the data to sign, possibly formatted. The data to sign is digested outside the YubiKey.

Whether the PIN or touch is required before the YubiKey will sign is dependent on the PIN and touch policies specified when the key pair was generated or imported. See the sections on generating key pairs and importing keys, along with PIV PIN and touch policies. For example, if a key pair was generated with the PIN policy of "Never", then no PIN will be required to sign. However, most applications will likely set the policy to "Always" or "Once".

Slot 9C is the digital signature slot, although the YubiKey will sign using any slot holding a private key, other than F9 (F9 holds the attestation key, which can sign a a certificate it creates, so it can sign, however, it cannot sign arbitrary data, only).

For RSA signatures, the digest must be formatted into a block. The block will be the same size as the key. The two block formats allowed are PKCS 1 v 1.5 or PKCS 1 PSS.

For example, if using PKCS 1 v 1.5, before calling, build the following block.

  formatted digest = 00 01 FF FF ... FF 00 \<DER of DigestInfo\>

  For a 2048-bit key, the block is 256 bytes long (the leading 00 byte is one of the 256).

  If the digest algorithm is SHA-256, the DER of the DigestInfo will be 49 bytes long:

  30 2f
     30 0b
        06 09
           60 86 48 01 65 03 04 02 01
     04 20
        <32-byte digest>

  The block to pass to the YubiKey will be

  00 01 FF FF ... FF 00 \<49-byte DER of DigestInfo\>
        ^          ^
        |          |
        -------------- 204 bytes of 0xFF

PSS (Probabilistic Signature Scheme) is much more complicated. If you want to learn how to build a PSS block, see RFC 8017. The formatted digest will appear to be simply random bytes.

For ECC signatures, simply provide the digest. No DER encoding, just the digest.

If the key is EccP256, the digest must be 256 bits (32 bytes) or shorter. You will generally use SHA-256.

If the key is EccP384, the digest must be 384 bits (48 bytes) or shorter. You will generally use SHA-384.

The actual APDU will format the data you provide even further:

  7C len1 82 00 81 len2 \<digest block\>

However, you will not need to worry about this.

Output

The signature.

APDU

Technical APDU Details


Authenticate: decrypt

The Authenticate command can be used to perform several cryptographic operations:

  • Authenticate the Management Key to the YubiKey
  • Sign data using a private key
  • Decrypt data using a private key
  • Perform key agreement using a private key

This section discusses decrypting arbitrary data. See Authenticate: management key, Authenticate: sign, and Authenticate: key agreement for information on authenticating the management key, signing, and key agreement.

Decryption with a private key is possible only if the key in the slot is RSA.

If the key in the slot is ECC, calling this command will produce an exception.

Available

All YubiKeys with the PIV application.

SDK Classes

AuthenticateDecryptCommand

AuthenticateDecryptResponse

Input

The PIN (maybe), the slot number, and the corresponding party's public key.

Whether the PIN or touch is required before the YubiKey will perform key agreement is dependent on the PIN and touch policies specified when the key pair was generated or imported. See the sections on generating key pairs and importing keys, along with PIV PIN and touch policies. For example, if a key pair was generated with the PIN policy of "Never", then no PIN will be required to sign. However, most applications will likely set the policy to "Always" or "Once".

Slot 9D is the Key Management slot, although the YubiKey will perform key agreement using any slot holding a private key, other than F9 (the attestation key, which can only sign a certificate it creates).

The input data must be the same size as the key. For example, if the key is RSA-2048, the input data (the data to decrypt) must be 256 bytes. If the data is shorter than the key, prepend as many 00 bytes as needed to make it the correct size.

Output

The decrypted data. The result will likely be formatted following PKCS 1 v. 1.5 or OAEP. It is the responsibility of the caller to extract the actual plaintext from the formatted result.

APDU

Technical APDU Details


Authenticate: key agreement

The Authenticate command can be used to perform several cryptographic operations:

  • Authenticate the Management Key to the YubiKey
  • Sign data using a private key
  • Decrypt data using a private key
  • Perform key agreement using a private key

This section discusses performing key agreement using a private key. See Authenticate: management key, Authenticate: sign, and Authenticate: decrypt, for information on authenticating the management key, signing, and decrypting.

Key agreement is possible only if the key in the slot is ECC. If so, this command will perform the EC Diffie-Hellman Key Agreement protocol, phase 2.

If the key in the slot is RSA, calling this command will produce an exception.

Available

All YubiKeys with the PIV application.

SDK Classes

AuthenticateKeyAgreeCommand

AuthenticateKeyAgreeResponse

Input

The PIN (maybe), the slot number, and the corresponding party's public key.

Whether the PIN or touch is required before the YubiKey will perform key agreement is dependent on the PIN and touch policies specified when the key pair was generated or imported. See the sections on generating key pairs and importing keys, along with PIV PIN and touch policies. For example, if a key pair was generated with the PIN policy of "Never", then no PIN will be required to sign. However, most applications will likely set the policy to "Always" or "Once".

Slot 9D is the Key Management slot, although the YubiKey will perform key agreement using any slot holding a private key, other than F9 (the attestation key, which can only sign a certificate it creates).

The input data must be the other party's public point, and must include both the x- and y-coordinates. It will be in the form

  04 || x-coordinate || y-coordinate

  where each coordinate is the same size as the key. For example, if the key
  in the slot is ECC-P256, then each coordinate must be 32 bytes. Prepend 00
  bytes if necessary. The total length will be 65 bytes.

Output

The result of ECDH phase 2, which is the shared secret.

The result will be the same size as the key. For example, if the key is ECC-P384, the result will be 48 bytes, possibly with leading 00 bytes. It happens to be the x-coordinate of the point result of ECC scalar multiplication, which is phase 2 of ECDH. It is the shared secret itself, no tag or length octets.

APDU

Technical APDU Details


Create attestation statement

Create an attestation statement for a key that had been generated by the YubiKey. See the article on attestation.

This command will instruct the YubiKey to build and return an attestation statement. An attestation statement is an X.509 certificate. This certificate is signed by the attestation key.

The cert returned will affirm that a private key was generated on the YubiKey, and not imported. The private keys that can be attested are those in slots 9A, 9C, 9D, 9E and 82 - 95.

Note

In version 1.0.0 of the SDK, it was not possible to create an attestation statement for keys in slots 82 - 95 (retired key slots). Beginning with version 1.0.1 of the SDK it is possible to create an attestation statement for the keys in those slots.

The private key that will sign this newly-created certificate (the attestation statement) is the attestation key in slot F9. This slot also contains the attestation certificate.

The attestation key is generated at the time of manufacture. The same attestation key is loaded onto many YubiKeys. At the same time it is generated and loaded onto YubiKeys, a certificate for it is built, signed by the YubiKey PIV Certificate Authority. The CA cert is signed by the YubiKey root.

To obtain the YubiKey CA and root certs, visit the Yubico Developer's PIV Attestation website.

So to verify that a private key is indeed attested, extract the public key from the attestation statement and verify that it is the appropriate public key (this is generally done by verifying a signature), extract the serial number (if part of the attestation statement) and verify it is the serial number of the YubiKey in question, and finally, verify the certificate. To verify the certificate, use the attestation cert (acquired by using the GET DATA command), the YubiKey PIV CA cert, and the YubiKey root cert.

      Yubico Root Cert
             |
             |
     Yubico PIV CA Cert
             |
             |
      Attestation Cert
         (Slot F9)
   (from Get Data command)
             |
             |
   Attestation Statement
   (an X.509 certificate)

Note that each time this command is executed, a new cert will be created.

Available

YubiKey 4.3 and later.

SDK Classes

CreateAttestationStatementCommand

CreateAttestationStatementResponse

Input

Slot number.

Output

The DER encoding of an X.509 certificate signed by the attestation key, asserting that the key in the given slot was generated by a YubiKey.

The public key in the certificate is the public key partner to the private key in the specified slot, and an extension in the certificate is the serial number of the YubiKey itself. Therefore, it is possible to attest that the specific private key was generated by the specific YubiKey.

APDU

Technical APDU Details


Get Data

Get a data element from the YubiKey.

There are a number of data elements that are retrievable using a command specifically for that element (e.g. serial number). However, for other elements, it is necessary to use the GET DATA command.

GET DATA is general purpose (i.e. it is not unique to the PIV application). In fact, you will likely find GET DATA commands in other areas (FIDO commands, Inter-Industry commands, etc.). However, for the PIV command namespace, there is a set of classes that represent a GET DATA command that gets specific PIV info. That is, this class will be able to construct a specific subset of GET DATA APDUs related to PIV, but not an "arbitrary" GET DATA command.

See also the User's Manual entry on the GET and PUT DATA commands.

Available

All YubiKeys with the PIV application.

SDK Classes

GetDataCommand

GetDataResponse

Input

A "tag" specifying which data element to get. Tables 4x list which data objects will be supported in the PIV GET DATA command class. It also contains links to descriptions of the data returned.

Some tags require PIN authentication as well. The tags that do are listed in tables 4x.

Output

Data elements based on the input tag. The SDK returns the data as a byte array. It is the responsibility of the caller to further parse that result.

Table 4A lists PIV standard elements that the YubiKey will possess upon manufacture (as long as the PIV application is initialized).

Table 4B lists PIV standard elements that the YubiKey will not possess upon manufacture. Requesting these elements using GET DATA will return "NoData". If you want these elements to contain data, you will have to load them using PUT DATA.

Table 4A: PIV GET DATA elements available upon manufacture

Name Tag Meaning Authentication
Required
Data Returned
DISCOVERY 7E PIV AID plus
PIN usage policy
PUT: not allowed
GET: none
Encoded discovery

Table 4B: PIV GET DATA elements empty upon manufacture

Name Tag Meaning Authentication
Required
Data Returned
AUTHENTICATION 5F C1 05 Cert for key in slot 9A PUT: mgmt key
GET: none
Encoded certificate
SIGNATURE 5F C1 0A Cert for key in slot 9C PUT: mgmt key
GET: none
Encoded certificate
KEY MANAGEMENT 5F C1 0B Cert for key in slot 9D PUT: mgmt key
GET: none
Encoded certificate
CARD AUTH 5F C1 01 Cert for key in slot 9E PUT: mgmt key
GET: none
Encoded certificate
RETIRED1 to
RETIRED20
5F C1 0D
through
5F C1 20
Retired certs PUT: mgmt key
GET: none
Encoded certificate
CHUID 5F C1 02 Cardholder Unique
Identifier
PUT: mgmt key
GET: none
Encoded CHUID
CAPABILITY 5F C1 07 Card Capability
Container (CCC)
PUT: mgmt key
GET: none
Encoded CCC
PRINTED 5F C1 09 Information printed
on the card
PUT: mgmt key
GET: PIN
Encoded printed
SECURITY 5F C1 06 Security object PUT: mgmt key
GET: none
Encoded security
KEY HISTORY 5F C1 0C Info about retired keys PUT: mgmt key
GET: none
Encoded key history
IRIS 5F C1 21 Cardholder iris images PUT: mgmt key
GET: PIN
Encoded iris images
FACIAL IMAGE 5F C1 08 Cardholder facial image PUT: mgmt key
GET: PIN
Encoded facial image
FINGERPRINTS 5F C1 03 Cardholder fingerprints PUT: mgmt key
GET: PIN
Encoded fingerprints
BITGT 7F 61 Biometric Information
Group Template
PUT: not supported
GET: none
Encoded BITGT
SM SIGNER 5F C1 22 Secure Messaging
Certificate Signer
PUT: mgmt key
GET: none
Encoded SM cert signer
PC REF DATA 5F C1 23 Pairing Code
Reference Data
PUT: mgmt key
GET: none
Encoded PC Ref

All the tags supported are one, two, or three bytes long. The APDU data contains the tag, each constructed as a TLV itself. That is, there is a DER TLV with a T of 5C, and a V of the GET DATA tag. Unfortunately, that is the terminology used in the standard. There is a tag for TLV and a value that is itself called a "tag".

 5C 01 7E
 5C 02 7F 61
 5C 03 5F C1 xx

Encoded certificate

If the certificate retrieved is the attestation statement, it is returned encoded as follows.

  53 L1
     70 L2
        --X.509 certificate--

The X.509 certificate is the DER encoding of the ASN.1 definition "Certificate"
from the X.509 standard (see RFC 5280).

All other certificates are returned as specified in the PIV standard:

  53 L1
     70 L2
        --X.509 certificate--
     71 01
        00 (compression)
     FE 00 (LRC)

The X.509 certificate is the DER encoding of the ASN.1 definition "Certificate"
from the X.509 standard (see RFC 5280).

The 71 01 00 means the certificate itself is uncompressed. If it were 71 01 01, it would
mean the certificate were gzipped.

The "LRC" is an error detection code. While it is mandatory according to
one smart card standard, the PIV standard does not use it and therefore its
length is zero.

Encoded CHUID

As specified in the PIV standard:

53 3B
   30 19
      --FASC-N, fixed at 25 bytes--
   34 10
      --GUID, fixed at 16 bytes--
   35 08
      --expiration data, ASCII YYYYMMDD, fixed at 8 bytes--
   3E 00 (Issuer Asymmetric Signature, max 2816 bytes, unused in YubiKey)
   FE 00 (LRC, unused in PIV)

The FASC-N is a value generated following the TIG SCEPACS standard (a smart card
standard).

The GUID is a value generated following RFC 4122.

The "LRC" is an error detection code. While it is mandatory according to
one smart card standard, the PIV standard does not use it and therefore its
length is zero.

Encoded CCC

As specified in the PIV standard:

53 33
   F0 15 (card identifier, fixed at 21 bytes)
      A0 00 00 01 16 FF 02
      --14 random bytes--
   F1 01
      21 (container version number)
   F2 01
      21 (grammar version number)
   F3 00 (unused by YubiKey)
   F4 01
      00 (PKCS 15 support, YubiKey does not support)
   F5 01
      10 (Data model number)
   F6 00 (unused by YubiKey)
   F7 00 (unused by YubiKey)
   FA 00 (unused by YubiKey)
   FB 00 (unused by YubiKey)
   FC 00 (unused by YubiKey)
   FD 00 (unused by YubiKey)
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

Encoded discovery

As specified in the PIV standard:

7E 12
   4F 0B
      A0 00 00 03 08 00 00 10 00 01 00 (Application AID, fixed)
   5F 2F 02
      40 00 (PIN Usage Policy, the only policy YubiKey supports)

Encoded printed

As specified in the PIV standard:

53 L1
   01 len
      --Name, ASCII text, up to 125 bytes--
   02 len
      --Employee afiliation, ASCII text, up to 20 bytes--
   04 len
      --Expiration date, ASCII numbers YYYYMMMDD, fixed at 9 bytes--
   05 len
      --Agency Card Serial Number, ASCII text, up to 20 bytes--
   06 len
      --Issuer Id, ASCII text, up to 15 bytes--
   07 len
      --Org affiliation, line 1, ASCII text, up to 20 bytes--
   08 len
      --Org affiliation, line 2, ASCII text, up to 20 bytes--
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

Note that the SDK does not allow putting data into the Printed tag. However, Yubico uses this tag to store information. If you GET DATA with this tag, you will likely see either no data or data that does not follow this format.

You should never overwrite the information in the Printed tag. If you do, it could make your YubiKey unusable.

Encoded security object

As specified in the PIV standard:

53 L1
   BA len
      --Mapping of DG (Data Group, see PIV standard) to ContainerID, up to 30 bytes--
   BB len
      --Security object (See MRTD standard), up to 1298 bytes--
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

Encoded key history

As specified in the PIV standard:

53 L1
   C1 01
      --number of keys with on card certs--
   C2 01
      --number of keys with off card certs--
   F3 len
      --off card cert URL, only if C2 value is > 0, up to 118 bytes--
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

Encoded iris images

As specified in the PIV standard:

53 L1
   BC len
      --image for verification, up to 7,100 bytes--
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

Encoded facial image

As specified in the PIV standard:

53 L1
   BC len
      --image for verification, up to 12,704 bytes--
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

Encoded fingerprints

As specified in the PIV standard:

53 L1
   BC len
      --Fingerprint I and II, up to 4,000 bytes--
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

Encoded BITGT

As specified in the PIV standard:

7F 61 L1
   02 01
      --number of fingers--
   7F 60 len
      --BIT for first finger, up to 28 bytes--
   7F 60 len (Optional)
      --BIT for second finger, up to 28 bytes--

Encoded SM cert signer

As specified in the PIV standard:

53 L1
   70 len
      --X.509 cert, up to 3,048 bytes--
   71 01
      --compression--
   7F 21 len (Optional)
      --intermediate CVC (see PIV standard), uncompressed, up to 3,048 bytes--
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

The YubiKey will allow for up to a combined 3,048 bytes for the cert and CVC. That is, even though the maximum length of each element is 3,048 bytes, the length of the two combined must be 3,048 bytes or fewer. So a cert of 3,048 bytes with no CVC (length 0) is acceptable, but a cert of length 2,500 bytes combined with a CVC of 600 bytes would not be allowed.

Encoded PC Ref

As specified in the PIV standard:

53 0C
   99 08
      --Pairing code, Ascii text, fixed at 8 bytes--
   FE 00 (LRC, unused in PIV)

The "LRC" is an error detection code. While it is mandatory according to one smart card standard, the PIV standard does not use it and therefore its length is zero.

APDU

Technical APDU Details


Put data

Put the given data into a data element on the card.

See also the User's Manual entry on the GET and PUT DATA commands.

Available

All YubiKeys with the PIV application.

SDK Classes

PutDataCommand

PutDataResponse

Input

In order to put data, the management key must be authenticated. See the User's Manual entry on PIV commands access control for information on how to authenticate with the management key for commands. See also the section in this page on Authenticate: management key.

The input data will be a "tag" specifying where the data is to go, along with the data to PUT. Tables 4x in the Get Data command section above lists all possible tags. The "Data Returned" in that table is the data to put. Note that the SDK requires the data be formatted as defined in the PIV standard, described above.

Note that the YubiKey will not allow putting data for the following tags.

  • Printed
  • Discovery
  • Biometric Information Group Template

You should never overwrite the information in the Printed tag. If you do, it could make your YubiKey unusable.

Output

bool: was the data element successfully put?

APDU

Technical APDU Details


Get and Put Vendor Data

The SDK also contains the ability to get and put data into tags not defined by the PIV standard. These are vendor-defined tags. The tag must be of the form 0x5FFFxx. Using this feature, a caller can also store arbitrary data into a tag, data that is not necessarily encoded following the PIV specification.

This feature, however, is not publicly available. It is only callable from inside the SDK.

Table 5A lists Yubico-defined elements that the YubiKey will possess upon manufacture (as long as the PIV application is initialized).

Table 5B lists Yubico-defined elements that the YubiKey will not possess upon manufacture. Requesting these elements using GET DATA will return "NoData". If you want these elements to contain data, you will have to load them using PUT DATA.

Table 5A: Yubico-defined GET DATA elements available upon manufacture

Name Tag Meaning Authentication
Required
Data Returned
ATTESTATION 5F FF 01 Attestation cert PUT: mgmt key
GET: none
Encoded certificate

Table 5B: Yubico-defined GET DATA elements empty upon manufacture

Name Tag Meaning Authentication
Required
Data Returned
ADMIN DATA 5F FF 00 PIV manager application
administrative data
PUT: mgmt key
GET: none
Encoded admin data
MSCMAP 5F FF 10 Microsoft container map PUT: mgmt key
GET: none
MSCMAP
MSROOTS1 to
MSROOTS5
5F FF 11
through
5F FF 15
Microsoft root certs PUT: mgmt key
GET: none
MSROOTS

Encoded Admin Data

The GET DATA element ADMIN DATA is used by the PIV manager application to store data about the PIV application and the data in the PIV portion of the YubiKey. The information is generally not used by the YubiKey anymore and is retained only for backwards compatibility. It is safe to ignore this element.

80 L1
   81 01 (optional)
      --bit field, PUK blocked, Mgmt Key stored in protected data--
   82 L2 (optional)
      --salt, deprecated--
   83 L3 (optional)
      --time the PIN was last updated--

The bit field contains up to two bits: 1 is PUK blocked and 2 is PIN-protected.

It is permissible to have no salt (either no TLV for tag 82, or 82 00 as the TLV) or a 16-byte value.

The "PIN last updated" field is the UNIX time of seconds since 1970, in little endian order. For example, some time in Jan. 14, 2022 is 0x61E1B870. It would be encoded as

   83 04
      70 B8 E1 61

It will generally be a 4-byte value until sometime in January, 2038, when it will be 5 bytes.

MSROOTS

These tags were created so that Yubico libraries (minidriver, SDK) can better interface with the Microsoft Smart Card Base Crypto Service Provider (CSP). There will likely never be a scenario where an application will need to use the data the SDK will PUT into and GET from these objects. If your application uses the Base CSP, and you use a YubiKey, any necessary operations with the MSROOTS will be handled by the SDK.

MSCMAP

This tag was created so that Yubico libraries (minidriver, SDK) can better interface with the Microsoft Smart Card Base Crypto Service Provider (CSP). There will likely never be a scenario where an application will need to use the data the SDK will PUT into and GET from these objects. If your application uses the Base CSP, and you use a YubiKey, any necessary operations with the MSCMAP will be handled by the SDK.


Reset the PIV Application

Delete all the credentials and keys, and set the PIN, PUK, and management key to the default values:

PIN:       123456
PUK:       12345678
Mgmt Key:  hex 010203040506070801020304050607080102030405060708
               0102030405060708 three times

This command will be accepted only if the PIN and PUK are both blocked.

Available

All YubiKeys with the PIV application.

SDK Classes

ResetPivCommand

ResetPivResponse

Input

None.

Output

There is no data output, only the status.

APDU

Technical APDU Details


  • Improve this Doc
In this article
Back to top Generated by DocFX