SetPinRetriesCommand Class

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

Set the number of retries for the PIN and PUK.

C#

public sealed class SetPinRetriesCommand : Object, IYubiKeyCommand<SetPinRetriesResponse>

Inheritance System.Object SetPinRetriesCommand

Implements

IYubiKeyCommand<SetPinRetriesResponse>

Remarks

The partner Response class is SetPinRetriesResponse.

Note that this command will reset the PIN and PUK to their default values ("123456" for the PIN and "12345678" for the PUK), as well as changing the retry count. You will likely want to follow up this command with a call to ChangeReferenceDataCommand

In order to set the retry count, you must authenticate the management key and verify the PIN. Those two elements are not part of this command. See the User's Manual entry on PIV commands access control For information on how to provide authentication for a command that does not include the authentication information in the command.

The number of retries refers to how many times in a row the wrong value can be entered until the element is blocked. For example, suppose the PIN retry count is three. If you perform an operation or command that requires the PIN, and you provide the wrong PIN, the operation or command will not succeed. The retry count will drop to two. If you enter the wrong PIN two more times, the PIN is blocked. Any operation or command that requires the PIN will not work, even if you supply the correct PIN.

The YubiKey is manufactured with the default PIN and PUK counts of 3.

Note that if a PIN is blocked, it is possible to unblock it using the PUK and the ResetRetryCommand. If that command is performed with the wrong PUK, the retry count for the PUK will be decremented. After too many wrong PUKs, it can also be blocked. In that case, the only possible recovery is to reset the entire PIV application.

The Set Retries command will set the retry count for both the PIN and PUK. If you want to reset the retry count for one, not the other, you still have to set the count for both.

The retry count must be a value from 1 to 255. Note that if you set the retry count to one, that means that after one wrong entry, the PIN or PUK is blocked.

Example:

  IYubiKeyConnection connection = key.Connect(YubiKeyApplication.Piv);

  var setPinRetriesCommand = new SetPinRetriesCommand (5, 5);
  SetPinRetriesResponse setPinRetriesResponse =
      connection.SendCommand(setPinRetriesCommand);

  if (setPinRetriesResponse.Status != ResponseStatus.Success)
  {
    // Handle error
  }

Constructors

Name	Description
SetPinRetriesCommand()	Initializes a new instance of the SetPinRetriesCommand class. This command will set the PinRetryCount and PukRetryCount to the default count of 3.
SetPinRetriesCommand(Byte, Byte)	Initializes a new instance of the SetPinRetriesCommand class. This command takes the PIN and PUK retry counts as input.

Properties

Name	Description
Application	Gets the YubiKeyApplication to which this command belongs. For this command it's PIV.
PinRetryCount	The number of retries before the PIN will be blocked.
PukRetryCount	The number of retries before the PUK will be blocked.

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.