TryResetPin Method

TryResetPin()

Try to reset the PIN, using the PUK (PIN Unblocking Key).

public bool TryResetPin()

Returns

System.Boolean

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

Exceptions

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

Remarks

If a user loses (or forgets) the PIN, it is possible to reset it using the PUK. Whether the PIN has been blocked (the wrong value was entered too many times in calls to TryVerifyPin or TryChangePin, and the retry count was exhausted) or not, it is possible to reset the PIN to a new value. That is, if the PIN is blocked, use this method to unblock it. But even if the PIN is not blocked, you can use this method to reset it.

This is essentially the same operation as TryChangePin, except instead of using the current PIN to provide permission to change the PIN, it uses the PUK.

If the PUK is blocked, this method will not execute. Note that if a YubiKey is configured PIN-only, the PUK will be blocked.

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.

In order to change the PUK, both the the current PUK and a new PIN must be provided. This method will call the KeyCollector delegate with the Request of KeyEntryRequest.ResetPivPinWithPuk. The KeyCollector provides both the current PUK and a new PIN. Once it has both the PUK and a new PIN, this method will try to reset the PIN. That is, this method will not verify the current PUK in a separate step, the current PUK will only be verified for the reset with the new PIN.

The KeyCollector has an option to cancel the operation. That is, this TryResetPin method will call the KeyCollector requesting the PUK and 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 PUK will decrement the remaining tries count. Hence, trying to change the PIN with the wrong current PUK too many times (retry count times) will cause the PUK to be blocked.

If the wrong current PUK 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 PUK is blocked. The KeyCollector can try to collect the PUK again, but will likely report the retries remaining to the user and offer the option of cancelling. If the KeyCollector returns false, this method will call the KeyCollector with Release and return false.

If the wrong current PUK 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 PUK is blocked. At this point, this method will not try to collect the PUK 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.

Resetting 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 reset, 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).

TryResetPin(ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, out Nullable<Int32>)

Try to reset the PIN using the PUK (PIN Unblocking Key). This method will use the puk and pin provided.

public bool TryResetPin(ReadOnlyMemory<byte> puk, ReadOnlyMemory<byte> newPin, out Nullable<int> retriesRemaining)

Parameters

Type	Name	Description
System.ReadOnlyMemory<System.Byte>	puk	The PIN Unblocking Key.
System.ReadOnlyMemory<System.Byte>	newPin	The new PIN, what the PIN will be changed to.
System.Nullable<System.Int32>	retriesRemaining	An output, it will be set to the number of retries remaining if the PUK is not correct. If the PIN is reset, this will be set to null.

Returns

System.Boolean

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

Exceptions

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

Remarks

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

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

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

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

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).

If the PUK is blocked, this method will not execute. Note that if a YubiKey is configured PIN-only, the PUK will be blocked.