Updates to PIV PUK documentation to reflect new behavior in firmware 5.7 #133
Conversation
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
equijano21
changed the title
ludwigward
suggested changes
Aug 2, 2024
| 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` - |
There was a problem hiding this comment.
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` - |
There was a problem hiding this comment.
The PUK is always 8 characters, the PIN can be 6, 7 or 8 characters.
There was a problem hiding this comment.
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). |
There was a problem hiding this comment.
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). |
There was a problem hiding this comment.
I believe my changes to be accurate but probably best to check with the firmware team to be sure.
Test Results: Windows 2 files 2 suites 4s ⏱️ Results for commit 9ce6982. ♻️ This comment has been updated with latest results. |
Test Results: Ubuntu 2 files 2 suites 9s ⏱️ Results for commit 9ce6982. ♻️ This comment has been updated with latest results. |
Test Results: MacOS 2 files 2 suites 4s ⏱️ Results for commit 9ce6982. ♻️ This comment has been updated with latest results. |
Minimum allowed line rate is |
DennisDyallo
approved these changes
Aug 7, 2024
ludwigward
reviewed
Aug 9, 2024
| @@ -25,10 +25,14 @@ Which element to change is given in the P2 field of the APDU and the current and | |||
| data (old and new PIN or PUK) are given in the data field. The data is simply the two | |||
| values concatenated. | |||
|
|
|||
| Both the PIN and PUK are allowed to be 6 to 8 characters, but if one is less than 8, it | |||
| will be padded with 0xff. For example, the default PIN is "123456", but on the device, | |||
| Both the PIN and the PUK are allowed to be 6 to 8 characters. If one is less than 8, it | |||
There was a problem hiding this comment.
@equijano21 the PUK has to be 8 characters and 8 characters only. The PIN can be 6-8 characters and will be padded if less than 8.
| @@ -581,7 +581,9 @@ All YubiKeys with the PIV application. | |||
| Which reference data element to change (PIN or PUK), the current reference value, and | |||
| the new value. | |||
|
|
|||
| Both the PIN and PUK are allowed to be 6 to 8 characters. | |||
| 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` - | |||
| 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 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](xref:Yubico.YubiKey.Piv.PivSession.TryChangePuk) or [Piv.Commands.ChangeReferenceDataCommand](xref:Yubico.YubiKey.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](xref:TheFido2Pin). |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Description
Updates to PIV PUK documentation to reflect new behavior in firmware 5.7.
Fixes outdated docs identified by customer.
Type of change
How has this been tested?
Local docs build.