PIN complexity policy

PIN complexity is an optional feature available on YubiKeys with firmware version 5.7 or later. If PIN complexity is enabled, the YubiKey will block the usage of non-trivial PINs, such as 11111111, password, or 12345678.

YubiKeys can also be programmed during the pre-registration process to refuse other specific values. For more information on PIN complexity and the full PIN blocklist, see the YubiKey Technical Manual.

Note

PIN complexity policy is derived from the current Revision 3 of NIST SP 800-63 (specifically SP 800-63B-3), with additional consideration of Revision 4 of SP 800-63 (specifically SP 800-63B-4).

For the SDK, PIN complexity enablement means that the YubiKey will refuse to set or change the following values if they violate the policy:

Managing PIN complexity with the SDK

PIN complexity can be managed by the SDK in two ways:

  1. Reading the current PIN complexity status of a key.
  2. Handling PIN complexity-related errors.

Reading the current PIN complexity status

To verify whether PIN complexity is enabled for a particular YubiKey, check the IsPinComplexityEnabled property, which is part of the IYubiKeyDeviceInfo interface.

Handling PIN complexity errors

Applications that support setting or changing PINs should be able to handle the situation when a YubiKey refuses the user value because it violates the PIN complexity policy.

The SDK communicates PIN complexity violations by throwing specific exceptions.

PivSession exceptions

During a PivSession, PIN complexity violations result in a System.Security.SecurityException with the message, ExceptionMessages.PinComplexityViolation.

If the application uses a KeyCollector, the violation is reported through the KeyEntryData.IsViolatingPinComplexity property.

PIN complexity violations are reported for following PIV operations:

Fido2Session exceptions

During a Fido2Session, PIN complexity violations result in a Fido2Exception object with a Status of CtapStatus.PinPolicyViolation.

If the application uses a KeyCollector, the violation is reported through the KeyEntryData.IsViolatingPinComplexity property.

PIN complexity violations are reported for following FIDO2 operations:

Example code

For code samples demonstrating how to handle PIN complexity violations, see the PivSampleCode, Fido2SampleCode, and PinComplexityTests integration tests.