From 21f21342bb4cb13c9636aec4a29bcf8afc4f551d Mon Sep 17 00:00:00 2001 From: Elena Quijano Date: Thu, 1 Aug 2024 13:45:23 -0700 Subject: [PATCH 1/8] updates to PUK docs --- .../application-piv/pin-puk-mgmt-key.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md index 41df9852..c3ed5c7f 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md @@ -32,11 +32,15 @@ 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 (`0x00` - +`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 not equal 6-8 code points. In order to accomodate keys of varrying 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#unicode-characters). + +> [!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 From b0cda9b85a6f67a2143639ea6e83972fbc1d6b4e Mon Sep 17 00:00:00 2001 From: Elena Quijano Date: Thu, 1 Aug 2024 13:55:30 -0700 Subject: [PATCH 2/8] changed formatting --- .../docs/users-manual/application-piv/pin-puk-mgmt-key.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md index c3ed5c7f..498b9b98 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md @@ -36,7 +36,9 @@ The PUK is used to unblock the PIN (see the section below on [blocking](#blockin specifies that the PUK is to be an 8-byte value, with each of the bytes any binary value (`0x00` - `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 not equal 6-8 code points. In order to accomodate keys of varrying 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#unicode-characters). +`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 not equal 6-8 code points. In order to accomodate keys of varrying 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). > [!NOTE] > If your application uses the keyboard to insert the PUK, you might limit the user From 34beb775d09268f654b285788e143d8ef0a234c8 Mon Sep 17 00:00:00 2001 From: Elena Quijano Date: Thu, 1 Aug 2024 14:29:35 -0700 Subject: [PATCH 3/8] formatting, typo --- .../docs/users-manual/application-piv/pin-puk-mgmt-key.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md index 498b9b98..1051aab1 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md @@ -33,12 +33,12 @@ is a 6- to 8-byte value, each of the bytes an ASCII number ('0' to '9', which in others). 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 (`0x00` - -`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` - +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 not equal 6-8 code points. In order to accomodate keys of varrying 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 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 not equal 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). > [!NOTE] > If your application uses the keyboard to insert the PUK, you might limit the user From ad75535f2bb3320ba380359f1deeb524a1975023 Mon Sep 17 00:00:00 2001 From: Elena Quijano Date: Thu, 1 Aug 2024 14:33:54 -0700 Subject: [PATCH 4/8] changed wording --- .../docs/users-manual/application-piv/pin-puk-mgmt-key.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md index 1051aab1..7e528b8f 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md @@ -38,7 +38,7 @@ specifies that the PUK is to be an 8-byte value, with each of the bytes any bina `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 not equal 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 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). > [!NOTE] > If your application uses the keyboard to insert the PUK, you might limit the user From d6078894974eed3928a60f872ec1944736cadfae Mon Sep 17 00:00:00 2001 From: Elena Quijano Date: Tue, 6 Aug 2024 15:25:19 -0700 Subject: [PATCH 5/8] updated PUK info across multiple pages --- .../docs/users-manual/application-piv/apdu/change-ref.md | 8 ++++++-- .../docs/users-manual/application-piv/commands.md | 4 +++- .../docs/users-manual/application-piv/pin-puk-mgmt-key.md | 4 ++-- .../YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs | 8 ++++---- Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs | 5 ++--- 5 files changed, 17 insertions(+), 12 deletions(-) diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md b/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md index 916d7da7..84022cd2 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md @@ -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, +The PIN is allowed to be 6 to 8 ASCII characters. If it is less than 8, it +will be padded with 0xff to reach 8 bytes in length. For example, the default PIN is "123456", but on the device, it is represented as `31 32 33 34 34 36 FF FF`. +The PUK is allowed to be 8 characters. For YubiKeys with firmware versions prior to 5.7, the key will accept any value in the `0x00` - +`0xFF` range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the key will only accept values in the `0x00` - +`0x7F` range for a total length of 8 Unicode code points. + The data is therefore 16 bytes, current value (possibly padded) followed by the new value (possibly padded). diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/commands.md b/Yubico.YubiKey/docs/users-manual/application-piv/commands.md index 4a17db05..77879780 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/commands.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/commands.md @@ -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. +The PIN is allowed to be 6 to 8 ASCII characters (6 to 8 bytes in length). For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the `0x00` - +`0xFF` range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the `0x00` - +`0x7F` range for a total length of 8 Unicode code points. ### Output diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md index 7e528b8f..15a040da 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md @@ -34,11 +34,11 @@ others). 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`. 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). +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 an 8-byte PUK may be less than 8 code points. In order to accomodate keys of varying firmware versions, the SDK maintains an 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). > [!NOTE] > If your application uses the keyboard to insert the PUK, you might limit the user diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs index f371c294..fc909f58 100644 --- a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs +++ b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs @@ -30,9 +30,9 @@ namespace Yubico.YubiKey.Piv.Commands /// starts out as a default value as well: "12345678", which in ASCII is the /// 8-byte sequence 0x31 32 33 34 35 36 37 38. Generally, the first /// thing done when a YubiKey is initialized for PIV is to change the PIN and - /// PUK (along with the management key). The PUK must be 6 to 8 bytes. - /// Ultimately the bytes that make up the PIN or PUK can be any binary value, - /// but are generally input from a keyboard, so are usually made up of ASCII + /// PUK (along with the management key). + /// The PIN is allowed to be 6 to 8 ASCII characters (6 to 8 bytes in length). The PUK must be 8 characters. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 8 Unicode code points. + /// Since the PIN and PUK are generally input from a keyboard, they are usually made up of ASCII /// characters. /// /// @@ -150,7 +150,7 @@ private ChangeReferenceDataCommand() /// or PUK after calling connection.SendCommand. /// /// - /// Both the PIN and PUK are 6 to 8 bytes long. + /// The PIN is allowed to be 6 to 8 ASCII characters (6 to 8 bytes in length). The PUK must be 8 characters. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 8 Unicode code points. /// /// /// diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs index c47f7fb7..f4846705 100644 --- a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs +++ b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs @@ -834,9 +834,8 @@ public bool TryChangePin(ReadOnlyMemory currentPin, ReadOnlyMemory n /// during the initial YubiKey setup to change from the default PUK, or /// later, to change it again. /// - /// The PUK is six to eight bytes byte long. Although most PUKs will be - /// characters, the YubiKey allows any binary data to be a PUK. The - /// default is the ASCII string "12345678" which is the byte array + /// The PUK must be 8 characters. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 8 Unicode code points. The + /// default PUK is the ASCII string "12345678", which is the byte array /// /// 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38 /// From c399757ea4ff406470dcc3fb82517171cfacf3b5 Mon Sep 17 00:00:00 2001 From: Elena Quijano Date: Tue, 6 Aug 2024 18:51:33 -0700 Subject: [PATCH 6/8] added APDU info --- .../users-manual/application-piv/apdu/change-ref.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md b/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md index 84022cd2..674769a3 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md @@ -71,6 +71,17 @@ Data Length: 0 The PIN or PUK entered might or might not be correct, however, authentication was denied because the number of retries have been exhausted. +#### Response APDU for CHANGE REFERENCE DATA (PIN or PUK failed length and/or complexity requirements) + +Total Length: 2\ +Data Length: 0 + +| Data | SW1 | SW2 | +|:---------:|:---:|:---:| +| (no data) | 69 | 85 | + +The new PIN or PUK did not meet the specified length requirements, an invalid character/byte was used, and/or the PIN/PUK violated the key's [PIN complexity policy](xref:UsersManualPinComplexityPolicy). + ### Examples ```C From 35602b94c329f1cd39bec6827fffec32e028f710 Mon Sep 17 00:00:00 2001 From: Elena Quijano Date: Tue, 6 Aug 2024 18:53:22 -0700 Subject: [PATCH 7/8] fixed typo --- .../docs/users-manual/application-piv/pin-puk-mgmt-key.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md index 15a040da..cbba29a0 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md @@ -38,7 +38,7 @@ specifies that the PUK is to be an 8-byte value, with each of the bytes any bina `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 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 an 8-byte PUK may be less than 8 code points. In order to accomodate keys of varying firmware versions, the SDK maintains an 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). +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 an 8-byte PUK may be less than 8 code points. In order to accommodate keys of varying firmware versions, the SDK maintains an 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). > [!NOTE] > If your application uses the keyboard to insert the PUK, you might limit the user From 9ce69825662b5a4b6cc8566de405925b2b55e563 Mon Sep 17 00:00:00 2001 From: Elena Quijano Date: Wed, 7 Aug 2024 12:11:49 -0700 Subject: [PATCH 8/8] fixed length info, added apdu --- .../application-piv/apdu/change-ref.md | 32 ++++++++++++++++--- .../users-manual/application-piv/commands.md | 6 ++-- .../application-piv/pin-puk-mgmt-key.md | 4 +-- .../Commands/ChangeReferenceDataCommand.cs | 4 +-- .../src/Yubico/YubiKey/Piv/PivSession.Pin.cs | 2 +- 5 files changed, 35 insertions(+), 13 deletions(-) diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md b/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md index 674769a3..603a5e7e 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/apdu/change-ref.md @@ -25,13 +25,13 @@ 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. -The PIN is allowed to be 6 to 8 ASCII characters. If it is less than 8, it -will be padded with 0xff to reach 8 bytes in length. 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 +will be padded with 0xff to reach 8 characters/bytes in length. For example, the default PIN is "123456", but on the device, it is represented as `31 32 33 34 34 36 FF FF`. -The PUK is allowed to be 8 characters. For YubiKeys with firmware versions prior to 5.7, the key will accept any value in the `0x00` - -`0xFF` range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the key will only accept values in the `0x00` - -`0x7F` range for a total length of 8 Unicode code points. +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 key will accept any value in the `0x00` - +`0xFF` range for the PUK. For YubiKeys with firmware version 5.7 and above, the key will only accept values in the `0x00` - +`0x7F` range (not including the padding). The data is therefore 16 bytes, current value (possibly padded) followed by the new value (possibly padded). @@ -82,6 +82,28 @@ Data Length: 0 The new PIN or PUK did not meet the specified length requirements, an invalid character/byte was used, and/or the PIN/PUK violated the key's [PIN complexity policy](xref:UsersManualPinComplexityPolicy). +#### Response APDU for CHANGE REFERENCE DATA (input data failed the length requirement) + +Total Length: 2\ +Data Length: 0 + +| Data | SW1 | SW2 | +|:---------:|:---:|:---:| +| (no data) | 6a | 80 | + +The total data length did not match the 16-byte requirement. + +#### Response APDU for CHANGE REFERENCE DATA (invalid P1 and/or P2) + +Total Length: 2\ +Data Length: 0 + +| Data | SW1 | SW2 | +|:---------:|:---:|:---:| +| (no data) | 6a | 88 | + +The P1 or P2 parameter was not valid given the instruction code. + ### Examples ```C diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/commands.md b/Yubico.YubiKey/docs/users-manual/application-piv/commands.md index 77879780..78866699 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/commands.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/commands.md @@ -581,9 +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. -The PIN is allowed to be 6 to 8 ASCII characters (6 to 8 bytes in length). For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the `0x00` - -`0xFF` range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the `0x00` - -`0x7F` range for a total length of 8 Unicode code points. +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 diff --git a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md index cbba29a0..f92ef72b 100644 --- a/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md +++ b/Yubico.YubiKey/docs/users-manual/application-piv/pin-puk-mgmt-key.md @@ -34,11 +34,11 @@ others). 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`. For YubiKeys with firmware versions prior to 5.7, the key will accept any value in the `0x00` - +`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 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 an 8-byte PUK may be less than 8 code points. In order to accommodate keys of varying firmware versions, the SDK maintains an 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). +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). > [!NOTE] > If your application uses the keyboard to insert the PUK, you might limit the user diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs index fc909f58..13578c49 100644 --- a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs +++ b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/Commands/ChangeReferenceDataCommand.cs @@ -31,7 +31,7 @@ namespace Yubico.YubiKey.Piv.Commands /// 8-byte sequence 0x31 32 33 34 35 36 37 38. Generally, the first /// thing done when a YubiKey is initialized for PIV is to change the PIN and /// PUK (along with the management key). - /// The PIN is allowed to be 6 to 8 ASCII characters (6 to 8 bytes in length). The PUK must be 8 characters. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 8 Unicode code points. + /// The PIN and PUK are both allowed to be 6 to 8 characters/bytes. The PIN can be any ASCII character. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 6-8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 6-8 Unicode code points. /// Since the PIN and PUK are generally input from a keyboard, they are usually made up of ASCII /// characters. /// @@ -150,7 +150,7 @@ private ChangeReferenceDataCommand() /// or PUK after calling connection.SendCommand. /// /// - /// The PIN is allowed to be 6 to 8 ASCII characters (6 to 8 bytes in length). The PUK must be 8 characters. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 8 Unicode code points. + /// The PIN and PUK are both allowed to be 6 to 8 characters/bytes. The PIN can be any ASCII character. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 6-8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 6-8 Unicode code points. /// /// /// diff --git a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs index f4846705..23c6e0b7 100644 --- a/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs +++ b/Yubico.YubiKey/src/Yubico/YubiKey/Piv/PivSession.Pin.cs @@ -834,7 +834,7 @@ public bool TryChangePin(ReadOnlyMemory currentPin, ReadOnlyMemory n /// during the initial YubiKey setup to change from the default PUK, or /// later, to change it again. /// - /// The PUK must be 8 characters. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 8 Unicode code points. The + /// The PUK must be 6-8 characters. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 6-8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 6-8 Unicode code points. The /// default PUK is the ASCII string "12345678", which is the byte array /// /// 0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38