Table of Contents

Class VerifyPinCommand

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

Verify the PIV PIN.

public sealed class VerifyPinCommand : IYubiKeyCommand<VerifyPinResponse>
Inheritance
object
VerifyPinCommand
Implements

Remarks

The partner Response class is VerifyPinResponse.

Some operations require the user enter a PIN. Use this class to build a command to verify the PIN. This will generally be used in conjunction with other commands that require the PIN. But it is possible to simply use this command to verify the PIN only.

The PIN starts out as a default value: "123456", which in ASCII is the 6-byte sequence 0x31 32 33 34 35 36. Generally, the first thing done when a YubiKey is initialized for PIV is to change the PIN (along with the PUK and management key). The PIN must be 6 to 8 bytes. Ultimately the bytes that make up the PIN can be any binary value, but are generally input from a keyboard, so are usually made up of ASCII characters.

The PIN you pass in must be 6 to 8 bytes long. If the actual PIN collected is less than 6 or more than 8 bytes long, it will be invalid.

Note that with PIV there is also a PUK (PIN Unblocking Key). This command cannot verify a PUK.

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

Example: 

/* This example assumes the application has a method to collect a PIN.
 */
byte[] pin;

IYubiKeyConnection connection = key.Connect(YubiKeyApplication.Piv);
pin = CollectPin();
var verifyPinCommand = new VerifyPinCommand(pin);
VerifyPinResponse verifyPinResponse = connection.SendCommand(verifyPinCommand);
if (resetRetryResponse.Status == ResponseStatus.AuthenticationRequired)
{
  int retryCount = resetRetryResponse.GetData();
  /* report the retry count */
}
else if (verifyPinResponse.Status != ResponseStatus.Success)
{
  // Handle error
}

CryptographicOperations.ZeroMemory(pin)

Constructors

VerifyPinCommand(ReadOnlyMemory<byte>)

Initializes a new instance of the VerifyPinCommand class which will use the given PIN.

public VerifyPinCommand(ReadOnlyMemory<byte> pin)

Parameters

pin ReadOnlyMemory<byte>

The bytes that make up the PIN.

Remarks

In order to verify a PIN, the caller must supply the PIN. In this class, the PIN is 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 (not the values. This means that you can overwrite the PIN in your byte array only after this class is done with it. It will no longer need the PIN after calling connection.SendCommand.

A PIN is 6 to 8 bytes long.

Exceptions

ArgumentException

The PIN 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 VerifyPinResponse CreateResponseForApdu(ResponseApdu responseApdu)

Parameters

responseApdu ResponseApdu

The ResponseApdu returned by the YubiKey.

Returns

VerifyPinResponse

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