TrySetPinConfig Method

TrySetPinConfig(int?, IReadOnlyList<string>?, bool?)

Perform the authenticatorConfig subcommand of setMinPINLength, which will set the minimum PIN length, and/or replace the list of relying parties that are allowed to see the minimum PIN length, and/or specify that the user must change the PIN.

C#

public bool TrySetPinConfig(int? newMinPinLength = null, IReadOnlyList<string>? relyingPartyIds = null, bool? forceChangePin = null)

Parameters

Type	Name	Description
int?	newMinPinLength	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.
IReadOnlyList<string>	relyingPartyIds	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.
bool?	forceChangePin	If you want to set the YubiKey to require the user change the PIN before the next verification event, pass in true. If you pass in null or false, this command will consider the force PIN option not taken.

Returns

bool

A boolean, true if the YubiKey was able to set the YubiKey with the given input data, false if the YubiKey does not support this feature.

Exceptions

Type	Condition
Ctap2DataException	The YubiKey could not perform the operation, even though the set min PIN length feature is supported. For example, if the input newMinPinLength arg is less than the current min PIN length.

Remarks

This method will perform the operation only if the "setMinPINLength" option is present and set to true. Otherwise, it will return false

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 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 method will send the command without that element (i.e., it will be left blank).

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. Even then, after reset, the minimum PIN will be the default length with which the YubiKey was originally manufactured.

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. It will not replace the pre-configured list. 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.

Note that if you pass in null for all three arguments, this method will still check to see if the feature is supported and return false if it is not. If the feature is supported, this method will do nothing.