TryResetPin Method
TryResetPin()
Try to reset the PIN, using the PUK (PIN Unblocking Key).
public bool TryResetPin()Returns
A boolean, true if the PIN is reset, false if not.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | There is no |
| 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 canceling. 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 int?)
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 int? retriesRemaining)Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlyMemory<byte> | puk | The PIN Unblocking Key. |
| 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 PUK is not correct. If the PIN is reset, this will be set to null. |
Returns
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 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.