Table of Contents

Class SetPinRetriesCommand

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

Set the number of retries for the PIN and PUK.

public sealed class SetPinRetriesCommand : IYubiKeyCommand<SetPinRetriesResponse>
Inheritance
object
SetPinRetriesCommand
Implements

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

SetPinRetriesCommand()

Initializes a new instance of the SetPinRetriesCommand class. This command will set the PinRetryCount and PukRetryCount to the default count of 3.

public SetPinRetriesCommand()

Remarks

This constructor is provided for those developers who want to use the object initializer pattern. For example:

var command = new SetPinRetriesCommand()
{
    PinRetryCount = 5,
    PukRetryCount = 2,
};

SetPinRetriesCommand(byte, byte)

Initializes a new instance of the SetPinRetriesCommand class. This command takes the PIN and PUK retry counts as input.

public SetPinRetriesCommand(byte pinRetryCount, byte pukRetryCount)

Parameters

pinRetryCount byte

The new number of retries for the PIN (minimum 1, maximum 255).

pukRetryCount byte

The new number of retries for the PUK (minimum 1, maximum 255).

Remarks

The retry count must be a value from 1 to 255 (inclusive).

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

PinRetryCount

The number of retries before the PIN will be blocked.

public byte PinRetryCount { get; set; }

Property Value

byte

Exceptions

ArgumentException

The PIN retry count is invalid.

PukRetryCount

The number of retries before the PUK will be blocked.

public byte PukRetryCount { get; set; }

Property Value

byte

Exceptions

ArgumentException

The PUK retry count is invalid.

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 SetPinRetriesResponse CreateResponseForApdu(ResponseApdu responseApdu)

Parameters

responseApdu ResponseApdu

The ResponseApdu returned by the YubiKey.

Returns

SetPinRetriesResponse

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