Class SetMinPinLengthCommand
Set the minimum PIN length, and/or provide a list of relying party IDs that specify which relying parties can see the minimum PIN length, and/or specify whether the PIN must be changed before PIN verification can succeed.
public class SetMinPinLengthCommand : IYubiKeyCommand<Fido2Response>
- Inheritance
-
objectSetMinPinLengthCommand
- Implements
Remarks
The partner Response class is Fido2Response. This command does not return any data, it only returns "success" or "failure", and has some FIDO2-specific error information.
This command is valid only if the "setMinPINLength" option is present and
set to true
.
For any call to this command, it will perform any combination of one,
two, or three of the operations. Each operation is optional, including
setting a new minimum PIN length. For example, if you want to only set
the list of RP Ids, you can do so using this command with a null
newMinPinLength
and a null forceChangePin
.
The YubiKey's FIDO2 application is manufactured with a minimum PIN length. Users that want a different length can call this command. However, it is not possible to set the minimum PIN length to a value less than the current minimum. The only way to possibly set a shorter minimum PIN length is to reset the entire FIDO2 application on the given YubiKey.
The PIN length is measured in code points. See the User's Manual entry on the FIDO2 PIN for more information on PIN composition.
Note that the standard specifies that a PIN cannot be less than 4 Unicode characters and no more than 63 bytes when encoded as UTF-8. Hence, there are limits to the new minimum PIN length.
The list of RP IDs will specify that any RP on the list is allowed to see the minimum PIN length of a YubiKey. That will be visible only during the MakeCredential process. Generally, it is used so that an RP will refuse to provide a credential to an authenticator if the minimum PIN length is too low.
It is possible for a YubiKey to be manufactured with a pre-configured list of RP IDs. That list will never change, even after reset. If RP IDs are added using the SetMinPINLength command, they will be IDs in addition to the pre-configured list.
If RP IDs are added using this command, they will replace any RP IDs that had been added during a previous call to this command. Note that there is no way to get the current list.
If the minimum PIN length is set, and if the current PIN is smaller than
this value, then the YubiKey will require the user to change the PIN. It
will not verify the current PIN and any operation that requires
PIN verification will fail until the PIN is changed to a value that meets
the new requirement. For example, suppose the current minimum PIN length
is 4 and you have a PIN of length 6. You set the minimum PIN length to 7,
but do not set forceChangePin
(you pass in null for that arg). The
YubiKey will still require the user change the PIN.
If forceChangePin
is true, then the caller is requiring the user
to change the PIN, no matter what.
You can know if a PIN must be changed (either because the min PIN length
is now longer than the existing PIN or the forceChangePin
was
set), look at the ForcePinChange property
in the AuthenticatorInfo
.
Constructors
SetMinPinLengthCommand(int?, IReadOnlyList<string>?, bool?, ReadOnlyMemory<byte>, PinUvAuthProtocolBase)
Constructs a new instance of SetMinPinLengthCommand.
public SetMinPinLengthCommand(int? newMinPinLength, IReadOnlyList<string>? relyingPartyIds, bool? forceChangePin, ReadOnlyMemory<byte> pinUvAuthToken, PinUvAuthProtocolBase authProtocol)
Parameters
newMinPinLength
int?The new PIN length, measured in code points. See the User's Manual entry on the FIDO2 PIN for more information on PIN composition. Pass in null to indicate the command should not change the minimum PIN length.
relyingPartyIds
IReadOnlyList<string>A list of strings that are the relying party IDs for those RPs that are allowed to see the minimum PIN length. Pass in null to indicate the command should not add any RP IDs.
forceChangePin
bool?If you want to set the YubiKey to require the user change the PIN before the verification event, pass in
true
. If you pass in null orfalse
, this command will consider the force PIN option not taken.pinUvAuthToken
ReadOnlyMemory<byte>The PIN/UV Auth Token built from the PIN. This is the encrypted token key.
authProtocol
PinUvAuthProtocolBaseThe Auth Protocol used to build the Auth Token.
Remarks
There are up to three elements to set with this command: a new
minimum PIN length, a new list of relying party IDs, and an
indication to require the user change the PIN. All three are
optional, although this command will do nothing if none are set (i.e.
the first three args are null, null, null
).
If you want to set an element, provide a value for the corresponding argument, otherwise, pass in null.
If you want to force a PIN change, pass in true
for the
forceChangePin
arg. If you pass in false
, this class
will consider it the same as null. That is, the forceChangePin
element of this command is optional, meaning the command does not
need to include the element (i.e. leave it blank in the command sent
to the YubiKey). If you pass in false
, this class will send
the command without that element (i.e., it will be left blank).
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 Fido2Response CreateResponseForApdu(ResponseApdu responseApdu)
Parameters
responseApdu
ResponseApduThe ResponseApdu returned by the YubiKey.
Returns
- Fido2Response
The implementation of IYubiKeyResponse that parses and presents ths response APDU.