Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Updates to PIV PUK documentation to reflect new behavior in firmware 5.7 #133

Merged
merged 8 commits into from
Aug 7, 2024
Merged
Changes from 4 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,17 @@ is a 6- to 8-byte value, each of the bytes an ASCII number ('0' to '9', which in
(upper- and lower-case), and even non-alphanumeric characters such as !, %, or # (among
others).

The PUK is used to unblock the PIN (see the section below on Blocking). The standard
specifies that it is to be an 8-byte value, each of the bytes any binary value (`0x00` -
`0xFF`). If your application uses the keyboard to insert the PUK, you might limit the user
to ASCII characters, but the YubiKey will accept any byte value in the PUK. In addition,
the YubiKey will allow the PUK to be 6, 7, or 8 bytes long.
The PUK is used to unblock the PIN (see the section below on [blocking](#blocking)). The standard
specifies that the PUK is to be an 8-byte value, with each of the bytes any binary value from `0x00` to
`0xFF`. The YubiKey, however, will allow the PUK to be 6, 7, or 8 bytes long. For YubiKeys with firmware versions prior to 5.7, the key will accept any value in the `0x00` -
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`0xFF`. The YubiKey, however, will allow the PUK to be 6, 7, or 8 bytes long. For YubiKeys with firmware versions prior to 5.7, the key will accept any value in the `0x00` -
`0xFF`. For YubiKeys with firmware versions prior to 5.7, the key will accept any value in the `0x00` -

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PUK is always 8 characters, the PIN can be 6, 7 or 8 characters.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PUK can actually be 6-8 characters too. Just confirmed the behavior with the authenticator app.

`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-8 byte PUK may be less than 6-8 code points. In order to accomodate keys of varying firmware versions, the SDK maintains a 6-8 byte length requirement when calling [PivSession.TryChangePuk](xref:Yubico.YubiKey.Piv.PivSession.TryChangePuk). 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](xref:TheFido2Pin).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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-8 byte PUK may be less than 6-8 code points. In order to accomodate keys of varying firmware versions, the SDK maintains a 6-8 byte length requirement when calling [PivSession.TryChangePuk](xref:Yubico.YubiKey.Piv.PivSession.TryChangePuk). 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](xref:TheFido2Pin).
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 8 bytes, but for firmware version 5.7 and above, that requirement has changed to 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 8 byte PUK may be less than 8 code points. In order to accommodate keys of varying firmware versions, the SDK maintains a 8 byte length requirement when calling [PivSession.TryChangePuk](xref:Yubico.YubiKey.Piv.PivSession.TryChangePuk). 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](xref:TheFido2Pin).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe my changes to be accurate but probably best to check with the firmware team to be sure.


> [!NOTE]
> If your application uses the keyboard to insert the PUK, you might limit the user
to ASCII characters, regardless of a key's firmware version.

The management key is used to authenticate the entity allowed to perform many YubiKey
management operations, such as generating a key pair. On YubiKeys before version 5.4.2, it
Expand Down