TryChangePin Method

TryChangePin()

Try to change the PIN.

public bool TryChangePin()

Returns

bool

A boolean, true if the PIN is changed, false if not.

Exceptions

Type	Condition
InvalidOperationException	There is no `KeyCollector` loaded, or the YubiKey had some other error, such as unreliable connection.
SecurityException	The remaining retries count indicates the PIN is blocked.

Remarks

Upon manufacture of a YubiKey, the PIV application begins with a default PIN (see the User's Manual entry on the PIN). This method changes it. Note that this method can be run at any time, either during the initial YubiKey setup to change from the default PIN, or later, to change it again.

The PIN is six to eight bytes byte long. Although most PINs will be characters, the YubiKey allows any binary data to be a PIN. The default is the ASCII string "123456" which is the byte array

0x31 0x32 0x33 0x34 0x35 0x36

In order to change the PIN, both the current PIN and new PIN must be provided. Even if the current PIN had been verified already (using one of the methods TryVerifyPin or VerifyPin), the current PIN must be provided again. This method will call the KeyCollector delegate with the Request of KeyEntryRequest.ChangePivPin. The KeyCollector must then provide to this method both the current and new PIN.

The KeyCollector has an option to cancel the operation. That is, this TryChangePin method will call the KeyCollector requesting the PIN, and it is possible that during the collection operations, the user cancels. The KeyCollector will return to this method noting the cancellation. In that case, this method will return false.

Note that this is the only way to get a false return. Any other error and this method will throw an exception. In other words, a false return from this method means the user canceled.

An incorrect current PIN will decrement the remaining tries count. Hence, trying to change the PIN with the wrong current PIN too many times (retry count times) will cause the PIN to be blocked.

If the wrong current PIN is provided, and the remaining retries count is not zero, the method will call the KeyCollector again with KeyEntryData.IsRetry set to true and KeyEntryData.RetriesRemaining set to the number of tries remaining until the PIN is blocked. The KeyCollector can try to collect the PIN again, but will likely report the retries remaining to the user and offer the option of canceling. If the KeyCollector returns false, this method will call the KeyCollector with Release and return false.

If the wrong current PIN is provided, and the remaining retries count is zero, the method will call the KeyCollector again, indicating Release and then throw an exception. That is, once the remaining retries count goes to zero the PIN is blocked. At this point, this method will not try to collect the PIN any more and will throw an exception.

If there is an error during the process, this method will simply call the KeyCollector with Release and throw an exception.

Note that when this method calls the KeyCollector with Release, the return from the KeyCollector is ignored, this method will return true or false depending on what happened before the Release.

Changing the PIN does not affect the status of the Session's PIN verification. That is, the PinVerified property will not change after this method completes. If the status is false (unverified), and the PIN is successfully changed, the PIN will still be unverified and any operation that requires the PIN (such as signing), will need the PIN verified (with the new PIN). If the status is true (verified) and this method succeeds, the PIN will still be considered verified (the previous PIN), even though there is a new PIN. If the status is true (verified) and this method fails, the PIN will still be considered verified (the current PIN).

TryChangePin(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, out int?)

Try to change the PIN. This method will use the currentPin and newPin provided.

public bool TryChangePin(ReadOnlyMemory<byte> currentPin, ReadOnlyMemory<byte> newPin, out int? retriesRemaining)

Parameters

Type	Name	Description
ReadOnlyMemory<byte>	currentPin	The current PIN, the PIN that is to be changed.
ReadOnlyMemory<byte>	newPin	The new PIN, what the PIN will be changed to.
int?	retriesRemaining	An output, it will be set to the number of retries remaining if the current PIN is not verified. If the current PIN is verified and the PIN is changed, this will be set to null.

Returns

bool

A boolean, true if the PIN is changed, false if not.

Exceptions

Type	Condition
InvalidOperationException	The YubiKey had some error, such as unreliable connection.
SecurityException	The remaining retries count indicates the PIN is blocked.

Remarks

Normally, an application would call the TryChangePin() method (no arguments) and the SDK would call on the loaded KeyCollector to retrieve the PINs. With this method, the caller provides the PINs and the KeyCollector is never contacted.

Some applications would like to avoid using a KeyCollector. For such situations, this method is provided.

See the TryChangePin() method for further documentation on this method.

If the wrong current PIN is provided, this method will return false.

If the YubiKey is configured for PIN-derived, this method will update the management key, so that it is derived from the new PIN. Note that if the ADMIN DATA and/or PRINTED storage locations have been overwritten, this method might not be able to correctly update the management key. It is a good idea to call TryRecoverPinOnlyMode() before changing the PIN. See also the User's Manual entry on PIN-only modes.