Class ChangePinCommand

Namespace

Yubico.YubiKey.Fido2.Commands

Assembly

Yubico.YubiKey.dll

Change the YubiKey's FIDO2 application PIN.

public class ChangePinCommand : IYubiKeyCommand<ChangePinResponse>

Inheritance

object

ChangePinCommand

Implements

IYubiKeyCommand<ChangePinResponse>

Remarks

Upon manufacture, the YubiKey's FIDO2 application has no PIN set as there is no default PIN defined. Many FIDO2 operations are possible by simply inserting the YubiKey and possibly touching the contact. However, it is possible to set the application to require a PIN to perform many of the operations. Use SetPinCommand to set the PIN.

Use this command to change the PIN to a new value. Note that this command is possible only if a PIN is currently set. Note that it is not possible to remove a PIN, other than by resetting the entire application, which will mean losing all credentials as well as removing the PIN.

Constructors

ChangePinCommand(PinUvAuthProtocolBase, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>)

Constructs a new instance of ChangePinCommand.

public ChangePinCommand(PinUvAuthProtocolBase pinProtocol, ReadOnlyMemory<byte> currentPin, ReadOnlyMemory<byte> newPin)

Parameters

pinProtocol PinUvAuthProtocolBase

An object defining the PIN protocol the command will use. The Encapsulate(CoseKey) method must have been successfully executed before passing it to this constructor.

currentPin ReadOnlyMemory<byte>

The current PIN that is to be changed. This is a byte array with the PIN provided as the UTF-8 encoding of Unicode characters in Normalization Form C.

newPin ReadOnlyMemory<byte>

The PIN to change to. This is a byte array with the PIN provided as the UTF-8 encoding of Unicode characters in Normalization Form C.

Remarks

The caller must specify which PIN protocol the command will use. This is done by passing in a subclass of PinUvAuthProtocolBase. This constructor requires the Encapsulate(CoseKey) method to have been called before passing it in. Note that the Encapsulate method requires the YubiKey's public key, which is obtained by executing the GetKeyAgreementCommand.

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

The standard specifies that the PIN must be "the UTF-8 representation of" the "Unicode characters in Normalization Form C." This constructor expects the PIN to already be in that representation. See the User's Manual entry on the FIDO2 PIN for more information on what this means and how to build the PIN into the appropriate form. While this constructor will verify that the PIN is not too long, it will not verify the PIN is in the correct form. If it is invalid, the YubiKey might reject it and the response will indicate a failure.

This class will encrypt the PINs and will not copy references. That means you can overwrite the PINs in your byte arrays after calling the constructor.

The PIN is at least 4 unicode code points. If the YubiKey supports the "Set Minimum PIN Length" feature, it is possible to change this minimum to a bigger number, but never smaller than 4.

Note that the minimum length is given in code points, not bytes. The PIN must be converted to a sequence of bytes representing the Unicode characters in Normalization Form C, then UTF-8 encoded.

The maximum length is 63 bytes. This limit is in bytes, not code points. The standard also specifies that the last byte cannot be zero. Because the PIN must be UTF-8 encoded, this should never be an issue.

Exceptions

ArgumentNullException

The pinProtocol arg is null.

ArgumentException

A PIN is an incorrect length.

ArgumentException

The pinProtocol is in a state indicating Encapsulate has not executed.

Properties

Application

Gets the YubiKeyApplication (e.g. PIV, OATH, etc.) to which this command applies.

public YubiKeyApplication Application { get; }

Property Value

YubiKeyApplication

YubiKeyApplication.Otp, YubiKeyApplication.Piv, etc.

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

Parameters

responseApdu ResponseApdu

The ResponseApdu returned by the YubiKey.

Returns

ChangePinResponse

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