ResetRetryCommand Class

Namespace: Yubico.YubiKey.Piv.Commands Assembly: Yubico.YubiKey.dll

Reset the PIN, using the PUK (PIN Unblocking Key).

C#

public sealed class ResetRetryCommand : IYubiKeyCommand<ResetRetryResponse>

Inheritance object ResetRetryCommand

Implements

IYubiKeyCommand<ResetRetryResponse>

Remarks

The partner Response class is ResetRetryResponse.

This command is what the PUK is for. You can change the PUK, or reset the retry count on a PUK, but the only really useful operation you can do with the PUK is to reset a PIN.

The PIN starts out as a default value: "123456", which in ASCII is the 6-byte sequence 0x31 32 33 34 35 36. The PUK (PIN Unblocking Key) 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 PIN and PUK must each 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 characters.

If the user forgets the PIN, or if an incorrect PIN value has been entered too many times in a row (exhausted the retry count), it is possible to reset the PIN if the PUK is known.

When you pass the PIN and PUK to this class, it will copy a reference to the object passed in, it will not copy the value. Because of this, you cannot overwrite the PIN and PUK until this object is done with it. It will be safe to overwrite the PIN and PUK after calling connection.SendCommand. See the User's Manual entry on sensitive data for more information on this topic.

Example:

using System.Security.Cryptography;
/* This example assumes the application has a method to collect a
 * PIN/PUK.
 */
byte[] puk;
byte[] newPin;

IYubiKeyConnection connection = key.Connect(YubiKeyApplication.Piv);
puk = CollectPuk();
newPin = CollectNewPin();
var resetRetryCommand = new ResetRetryCommand(puk, newPin);
ResetRetryResponse resetRetryResponse = connection.SendCommand(resetRetryCommand);
if (resetRetryResponse.Status != ResponseStatus.Success)
{
  if (resetRetryResponse.Status == ResponseStatus.AuthenticationRequired)
  {
      int retryCount = resetRetryResponse.GetData();
      /* report the retry count */
  }
  else
  {
      // Handle error
  }
}

CryptographicOperations.ZeroMemory(puk);
CryptographicOperations.ZeroMemory(newPin);

Constructors

Name	Description
ResetRetryCommand(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>)	Build a new Command object to reset the PIN using the PUK (PIN Unblocking Key).

Properties

Name	Description
Application	Gets the YubiKeyApplication to which this command belongs. For this command it's PIV.

Methods

Name	Description
CreateCommandApdu()	Creates a well-formed CommandApdu to send to the YubiKey.
CreateResponseForApdu(ResponseApdu)	Creates the corresponding IYubiKeyResponse implementation for the current command.