TryChangePuk Method

TryChangePuk()

Try to change the PUK (PIN Unblocking Key).

public bool TryChangePuk()

Returns

bool

A boolean, true if the PUK 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 PUK is blocked.

Remarks

Upon manufacture of a YubiKey, the PIV application begins with a default PUK (see the User's Manual entry on the PUK). 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 PUK, or later, to change it again.

The PUK must be 6-8 characters. For YubiKeys with firmware versions prior to 5.7, the PUK is allowed to be any character in the 0x00 - 0xFF range for a total length of 6-8 bytes. For YubiKeys with firmware version 5.7 and above, the PUK is allowed to be any character in the 0x00 - 0x7F range for a total length of 6-8 Unicode code points. The default PUK is the ASCII string "12345678", which is the byte array

0x31 0x32 0x33 0x34 0x35 0x36 0x37 0x38

In order to change the PUK, both the the current PUK and new PUK must be provided. This method will call the KeyCollector delegate with the Request of KeyEntryRequest.ChangePivPuk. The KeyCollector provides both the current and new PUK.

The KeyCollector has an option to cancel the operation. That is, this TryChangePuk method will call the KeyCollector requesting the PUK, 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 PUK 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.

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

Try to change the PUK. This method will use the currentPuk and newPuk provided.

public bool TryChangePuk(ReadOnlyMemory<byte> currentPuk, ReadOnlyMemory<byte> newPuk, out int? retriesRemaining)

Parameters

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

Returns

bool

A boolean, true if the PUK 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 PUK is blocked.

Remarks

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

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

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

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