ChangePin Method

ChangePin()

For a version 4 FIPS series YubiKey that has a PIN set on the U2F application, this will call on the KeyCollector to obtain the current and a new PIN and use them to change the U2F PIN.

C#

public void ChangePin()

Exceptions

Type	Condition
SecurityException	The YubiKey is not version 4 FIPS series, or the PIN is blocked.
OperationCanceledException	The user cancelled. This happens when this method calls the KeyCollector and it returns false.

Remarks

A version 4 FIPS series YubiKey is manufactured with no PIN set on the U2F application. At this point, the YubiKey is not in FIPS mode. Once the PIN is set, it is in FIPS mode See SetPin(). After it has been set, it is possible to change the PIN to a new value.

Once a PIN is set, however, the only way to remove a PIN is to reset the entire U2F application. After reset, the YubiKey's U2F application is no longer in FIPS mode, and furthermore, it can never be put into FIPS mode again. It can be set with a PIN again, but that will not put a reset YubiKey into FIPS mode.

The current PIN must be entered, even if the PIN has been verified in the current session. If the wrong current PIN is entered, the YubiKey will decrement the retries remaining count, and this method will call on the KeyCollector for the current and new PIN again (the KeyEntryData.IsRetry property will be true). See the user's manual entry on FIDO U2F FIPS mode retries for more information.

The PIN is binary data and must be at least 6 and no more than 32 bytes long. If the user enters a value too short or too long, this method will not change the PIN, but it will call the KeyCollector again requesting the user enter a new PIN.

While the PIN can be any binary value, most PINs will be letters, numbers, and other characters entered from a keyboard. It is the responsibility of the app to determine how a character typed at a keyboard is represented as a byte. Almost certainly the best encoding will be UTF-8. In UTF-8, each ASCII character ie encoded with the single byte that is the ASCII character. For example, the character "5" in ASCII is 0x35. In UTF-8, it is 0x35. The character "C" is 0x43 in both ASCII and UTF-8.

Note that if the SDK calls the KeyCollector to try again, it will not specify what the problem is, wrong current PIN or invalid new PIN. Hence, it would be a good idea if your KeyCollector checked the length of the new PIN and reject it before passing it on to the SDK. If so, then you know a retry means incorrect current PIN.

Note that a PIN is needed to perform U2F registration, but not authentication.