The PIV PIN, PUK, and management key (2024)

Per the standard, there are three keys/secret values in PIV (Personal IdentityVerification):

• PIN (Personal Identification Number)
• PUK (PIN Unblocking Key)
• Management key

The main purpose of the PIN is to authenticate the user for signing and decrypting,although there are other operations that need it as well. The standard specifies that itis a 6- to 8-byte value, each of the bytes an ASCII number ('0' to '9', which in ASCII is0x30 to 0x39). The YubiKey allows the PIN to be any ASCII character: numbers, letters(upper- and lower-case), and even non-alphanumeric characters such as !, %, or # (amongothers).

The PUK is used to unblock the PIN (see the section below on blocking). The standardspecifies that the PUK is to be an 8-byte value, with each of the bytes any binary value from 0x00 to0xFF. The YubiKey, however, will accept a PUK of 6 to 8 characters. For YubiKeys with firmware versions prior to 5.7, the key will accept any value in the 0x00 -0xFF range in the PUK. For YubiKeys with firmware version 5.7 and above, the key will only accept values in the 0x00 -0x7F range. Values from 0x80 - 0xFF will be considered invalid by the key, and any attempt to change the PUK to a byte array containing one of these values will fail.

These restrictions are due to the YubiKey's PUK length requirements: for firmware versions prior to 5.7, the YubiKey simply requires a PUK length of 6-8 bytes, but for firmware version 5.7 and above, that requirement has changed to 6-8 Unicode code points in length. This is an important change because the byte representation (UTF-8 encoding) of a single code point can be 1-4 bytes in length, which means that a 6-byte PUK may be less than 6 code points. In order to accommodate keys of varying firmware versions, the SDK maintains a 6-8 byte length requirement when calling PivSession.TryChangePuk or Piv.Commands.ChangeReferenceDataCommand. However, keys with firmware 5.7 and above will only accept values that represent single-byte code points, hence the restricted range of 0x00 - 0x7F (the range of 0x80 - 0xFF represents code points of two bytes in length). For additional information on Unicode, UTF-8, and the SDK, see the FIDO2 documentation.

The management key is used to authenticate the entity allowed to perform many YubiKeymanagement operations, such as generating a key pair. On YubiKeys before version 5.4.2, itis a Triple-DES key, which means it is 24 bytes long. Beginning with 5.4.2, the managementkey can be an AES key, either 128, 192, or 256 bits (16, 24, or 32 bytes). The managementkey is binary (each byte is a value from 0x00 to 0xFF). If it is a Triple-DES key, the keydata is 192 bits long, but because of the "parity bits", only 168 bits supply the key'sstrength. In addition, because of certain attacks on Triple-DES, the actual effective bitstrength of a key is 112.

The YubiKey is manufactured with the standard default PIN, PUK, and managment key values:

• PIN: "123456"
• PUK: "12345678"
• Management Key: (Firmware Version 5.6 and below: Triple-DES / 5.7 and above: AES-192),0x010203040506070801020304050607080102030405060708
  0102030405060708 three times

Note that the PIV standard specifies these default/initial values. For firmware 5.4 YubiKeys that allow AES, the defaultmanagement key is Triple-DES. For firmware 5.7 and aboveYubiKeys, the default management key is AES-192.

Upon receipt of the YubiKey, it is a good idea to change the PIN, PUK, and management key from the default values. SeePivSession.TryChangePin, PivSession.TryChangePuk,andPivSession.TryChangeManagementKey.

Entering binary data

If your application takes PIN, PUK, and management key input from the user typing on akeyboard, how do they enter binary data? If the PIN is "stG83C" that's easy to enter at akeyboard. But if the PUK is 0x8F2B00CA716A, how does one type that at a keyboard?

The byte 0x2B is '+', 0x71 is 'q' and 0x6A is 'j', but what about 0x8F, 0x00, and 0xCA?

One solution is to simply limit your application's PUK to be only ASCII characters. Eventhough the standard allows any binary byte, you will allow only keyboard characters. Thiswill likely be acceptable because there is a retry count, which limits the attacker'sability to launch a brute-force attack.

But what about the management key? You could specify only keyboard characters there, 24bytes and 24 keystrokes. But this is very problematic because this severely limits thenumber of possible Triple-DES keys, and there is no retry limit on the management key.

The answer is to simply require the user enter the data as hex. For example, if themanagement key is the default (0x010203...), then the user enters "0102030405060708...".

They enter 48 ASCII characters ('0' '1' '0' '2' ... which is 0x30 31 30 32 ...) but yourapplication reads it as 24 bytes.

But whatever you do, please document it. Don't simply put a box into the UI and say,"Enter PUK" or "Enter management key". Let the user know they must enter the data as hexvalues. Or if the PUK is limited to keyboard characters, let them know. Even for the PIN,you can document that the input can be letters, numbers, or even some set of specialcharacters.

Otherwise the user might enter something that is incorrect, get an error message ("invalidPUK" or "management key not 24 bytes") and have to figure it out through trial and error.

Blocking

A PIN or PUK can be blocked. This happens when the wrong value is entered too many timesin a row. How many is too many? Upon manufacture, the number (the "retry count") is 3 forboth the PIN and PUK. It is possible to change the retry count usingSet PIN retries. The retry count can be any number from1 to 255 (inclusive).

When a PIN is blocked, any operation that requires the PIN will not work, even if yousupply the correct PIN. You can unblock the PIN using the PUK (PIN Unblocking Key) in thePivSession.TryResetPin method.

If you try to reset the PIN using the PUK, and provide the wrong PUK its retry count timesin a row, the PUK will be blocked. At that point, you cannot unblock the PIN, even if yousupply the correct PUK. There is no way to unblock the PUK, not even with the managementkey.

When both the PIN and PUK are blocked, there is not much useful work you can do with theYubiKey's PIV application. At this point, all you can do is reset the PIV application:PivSession.Reset. Thisdeletes the keys in all PIV slots and resets the PIN, PUK, and management key to theirdefaults. Note that this has no effect on the other YubiKey applications (OTP, FIDO,etc.).

The management key cannot be blocked. If an attacker wants to try to break your managementkey, they can try a brute-force attack (with a Triple-DES it is a modified brute-forceattack), which means trying every possible key until "stumbling" onto the correct one.That will take thousands of years for a Triple-DES key and trillions of years with an AESkey.

Changing the retry counts

The YubiKey is manufactured with a retry count of three for both the PIN and PUK. If youwould like to change that, call theChange retry countsmethod. This call will change the retry counts for both the PIN and PUK.

The minimum retry count is one, and the maximum retry count is 255. A retry count of onemeans there are no retries. If the user enters the wrong PIN or PUK just once, the secretis blocked.

Because changing the retry count will reset the PIN and PUK to their default values, it isa good idea to combine this operation with changing the PIN and PUK. That is, instead ofthree options or menu items of "change retry count", "change PIN", and "change PUK", yourapplication could have one option or menu item that changes the PIN, PUK, and retry countall at once. Alternatively, your application could set the retry count once during userinitiation, when the PIN, PUK, and management key are first changed from the default. Thennever offer the option of changing the retry count again.

Operations that require the management key

• Put data
• Generate a new key pair
• Import a private key
• Import a certificate
• Change the retry counts
  also requires the PIN
• Change the management key

Operations that require the PIN

• Verify the PIN
• Change the PIN
• Change the retry counts
  also requires the management key
• Sign
• Decrypt
• Key Agreement
• Get data for some data objects: Get data

Note that it is possible, on YubiKey 4.0 and later, to change the PIN policy of the signand decrypt operations, so that the PIN is not required. See the user's manual entry onPin and touch policies.

Operations that require the PUK

• Change the PUK
• Reset the PIN

Examples

Suppose the "retry count" for the PIN is 4. You try to sign but enter the wrong PIN. Theoperation fails and the "remaining count" is decremented to 3. The retry count is still 4,but you have only 3 tries remaining. Try again with the correct PIN, the operationsucceeds, and the remaining count is restored to 4.

The PIN retry count (and remaining count) is 4, but you know you have forgotten the PIN,so you don't even try to verify it. You simply use the PUK to reset/unblock the PIN. Thisworks, because it is not necessary for the remaining count to go to zero before you usethe PUK to reset the PIN.

You changed the PIN and PUK when you first got the YubiKey. Now, you decide you want tochange the PIN again. This is certainly allowed, simply call theChange Reference Data command.

PIN only

It is possible to set a YubiKey to be PIN only. This means the YubiKey is configured torequire he PIN only when performing operations, even those functions that normally requiremanagement key authentication.

There are two ways to achieve this: PIN-protected and PIN-derived. It is possible to haveboth methods active for a YubiKey.

Yubico recommends that if you must set a YubiKey to PIN only, you set it to use onlyPIN-protected.

Minidriver compatibility

The Yubico minidriver will configure a YubiKey to PIN-protected mode. Hence, if you knowthat your application will be running alongside Microsoft Windows machines using theYubiKey Minidriver, you should strongly consider adding support for setting YubiKeys toPIN-protected mode. See the User's manual entry on PIN-only.