Class ResetRetryCommand

Namespace

Yubico.YubiKey.Piv.Commands

Assembly

Yubico.YubiKey.dll

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

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);

Note: YubiKey Bio Multi-protocol Edition (MPE) keys do not have a PUK.

Constructors

ResetRetryCommand(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>)

Build a new Command object to reset the PIN using the PUK (PIN Unblocking Key).

public ResetRetryCommand(ReadOnlyMemory<byte> puk, ReadOnlyMemory<byte> newPin)

Parameters

puk ReadOnlyMemory<byte>

The current PUK.

newPin ReadOnlyMemory<byte>

The new PIN.

Remarks

To reset the PIN is to set the PIN to a new value, even if you don't know what the old value is. This is possible if you know what the PUK is. This command is similar to ChangeReferenceDataCommand. That command changes the PIN if you know the current PIN.

In order to reset the PIN, the caller must supply the PUK and the new PIN. In this class, the PINs and PUKs are supplied as ReadOnlyMemory<byte>. It is possible to pass a byte[], because it will be automatically cast.

This class will copy references to the PIN and PUK (not the values). This means that you can overwrite the PIN and PUK in your byte arrays only after this class is done with it. It will no longer need the PIN or PUK after calling connection.SendCommand.

Both the PIN and PUK are 6 to 8 bytes long.

Exceptions

ArgumentException

The PIN or PUK is an invalid length.

Properties

Application

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

public YubiKeyApplication Application { get; }

Property Value

YubiKeyApplication

YubiKeyApplication.Piv

Methods

CreateCommandApdu()

Creates a well-formed CommandApdu to send to the YubiKey.

public CommandApdu CreateCommandApdu()

Returns

CommandApdu

A valid CommandApdu that is ready to be sent to the YubiKey, or passed along to additional encoders for further processing.

Remarks

This method will first perform validation on all of the parameters and data provided to it. The CommandAPDU it creates should contain all of the data payload for the command, even if it exceeds 65,535 bytes as specified by the ISO 7816-4 specification. The APDU will be properly chained by the device connection prior to being sent to the YubiKey, and the responses will collapsed into a single result.

CreateResponseForApdu(ResponseApdu)

Creates the corresponding IYubiKeyResponse implementation for the current command.

public ResetRetryResponse CreateResponseForApdu(ResponseApdu responseApdu)

Parameters

responseApdu ResponseApdu

The ResponseApdu returned by the YubiKey.

Returns

ResetRetryResponse

The implementation of IYubiKeyResponse that parses and presents ths response APDU.