SetPinCommand Constructor

SetPinCommand(PinUvAuthProtocolBase, ReadOnlyMemory<Byte>)

Constructs a new instance of SetPinCommand.

C#

public SetPinCommand(PinUvAuthProtocolBase pinProtocol, ReadOnlyMemory<byte> newPin)

Parameters

Type	Name	Description
PinUvAuthProtocolBase	pinProtocol	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.
System.ReadOnlyMemory<System.Byte>	newPin	The PIN to set. This is a byte array with the PIN provided as the UTF-8 encoding of Unicode characters in Normalization Form C.

Exceptions

Type	Condition
System.ArgumentNullException	The pinProtocol arg is null.
System.ArgumentException	The PIN is an incorrect length.
System.ArgumentException	The pinProtocol is in a state indicating Encapsulate has not executed.

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 set the PIN, the caller must supply the new PIN at construction. In this class, the PIN is 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 PIN and will not copy a reference. That means you can overwrite the PIN in your byte array 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.