ChangePinAndPukRetryCounts Method

ChangePinAndPukRetryCounts(byte, byte)

Change the retry counts for the PIN and PUK.

Warning

This will reset the PIN and PUK to their default values as well as set the retry counts.

C#
public void ChangePinAndPukRetryCounts(byte newRetryCountPin, byte newRetryCountPuk)

Parameters

Type Name Description
byte newRetryCountPin

The PIN's new retry count.
byte newRetryCountPuk

The PUK's new retry count.

Exceptions

Type Condition
ArgumentException

The new retry count provided is invalid.
InvalidOperationException

There is no KeyCollector loaded, the key provided was not a valid Triple-DES key, or the YubiKey had some other error, such as unreliable connection.
OperationCanceledException

The user canceled management key collection.
SecurityException

Mutual authentication was performed and the YubiKey was not authenticated.

Remarks

See the user's manual entry on changing the retry counts.

The retry count is the number of times a wrong PIN or PUK can be entered before the PIN or PUK is blocked. The YubiKey is manufactured with a retry count of three for both the PIN and PUK.

Call this method to change the retry count of both the PIN and PUK. It is allowed to change the counts to different values. For example, it is acceptable to change the PIN retry count to 7 and the PUK retry count to 4. > [!NOTE] > You must change the retry counts of both the PIN and PUK. There is > no way to change the retry count for only one secret.

Supply the new retry counts in this method. The maximum retry count is 255, hence, the input arguments are bytes. The minimum retry count is 1. If one of the arguments is 0, this method will throw an exception. Note that a retry count of 1 means there are no retries. If the user enters the wrong PIN or PUK just once, the secret is blocked.

After resetting the retry counts, the PIN and PUK will be reset to their default values (PIN: "123456", PUK: "12345678"). Even though you never reset the application (ResetApplication()) or explicitly changed the PIN and PUK (TryChangePin() and TryChangePuk()), after changing the retry counts, the PIN and PUK will be the defaults.

You will likely want to write your application to immediately follow changing the retry counts with setting the PIN and PUK: (TryChangePin() and TryChangePuk(). Another option is to change these counts during the initial user setup before changing the PIN and PUK from their defaults, then never offer the user the option of changing the retry counts again.

In order to perform this operation, the management key must be authenticated and the PIN must be verified during this session. If the have not been authenticated/verified, this method will call AuthenticateManagementKey(bool) and VerifyPin(). That is, your application does not need to authenticate the management key and verify the PIN separately, this method will determine if they have been authenticated/verified or not, and if not, it will make the calls to perform authentication and verification.

The authentication and verification methods will collect the management key and PIN using the KeyCollector delegate. If no such delegate has been set, this method will throw an exception.

The KeyCollector has an option to cancel the operation. That is, the Authenticate and Verify methods will call the KeyCollector requesting the management key or PIN, and it is possible that during the collection operations, the user cancels. The KeyCollector will return to the authentication or verification method noting the cancellation. In that case, this method will throw an exception. If you want the authentication to return false on user cancellation, you must call TryAuthenticateManagementKey(bool) or TryVerifyPin() directly before calling this method.