-
Notifications
You must be signed in to change notification settings - Fork 51
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
Changes from 4 commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
21f2134
updates to PUK docs
equijano21 b0cda9b
changed formatting
equijano21 34beb77
formatting, typo
equijano21 ad75535
changed wording
equijano21 d607889
updated PUK info across multiple pages
equijano21 c399757
added APDU info
equijano21 35602b9
fixed typo
equijano21 9ce6982
fixed length info, added apdu
equijano21 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
|
@@ -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` - | ||||||
`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). | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 | ||||||
|
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.