TryRecoverPinOnlyMode Method

TryRecoverPinOnlyMode()

Try to recover the PIN-only state. If successful, this will authenticate the management key and reset the ADMIN DATA and or PRINTED storage locations.

Warning

This can overwrite the contents of ADMIN DATA and/or PRINTED. If some other application relies on that data it will be lost.

C#
public PivPinOnlyMode TryRecoverPinOnlyMode()

Returns

A PivPinOnlyMode, which is an enum indicating the mode or modes the YubiKey is in.

Remarks

See the User's Manual entry on PIV PIN-only mode for a deeper discussion of this operation.

The ADMIN DATA contains information about PIN-only. The PIN-protected management key is stored in PRINTED. Applications should never store information in those locations, only Yubico-supplied products should use them. However, it is possible for an application to overwrite the contents of one or both of these storage locations, making the PIN-only data inaccurate.

This method will obtain the data stored in the two storage locations, and determine if they contain PIN-only data that can be used to authenticate the management key. If it can't, it will return PivPinOnlyMode.None or Unavailable. If it can, it will authenticate and set the ADMIN DATA and PRINTED to contain data compatible with correct PIN-only modes. It will return a PivPinOnlyMode value indicating which mode is set.

For example, suppose the data in both is correct, and it indicates the management key is PIN-protected. After calling this method, the management key will be authenticated, the storage locations will not be changed, and the return will be PivPinOnlyMode.PinProtected.

Another possibility is the ADMIN DATA was overwritten by some application so it is inaccurate, but the PIN-protected data is still in PRINTED. This method will be able to authenticate the management key using that data. It will replace the contents of ADMIN DATA with correct PIN-only information and return PivPinOnlyMode.PinProtected.

If ADMIN DATA and PRINTED contain no data, or if ADMIN DATA contains correct information that indicates the YubiKey is not set to PIN-only mode, then this method will not authenticate the management key, it will not put any data into the storage locations, and it will return PivPinOnlyMode.None.

It is possible this method is not able to recover. For example, suppose the ADMIN DATA is correct and indicates the YubiKey is PIN-protected, but not PIN-derived (there is no salt to use to derive a key), but the data in PRINTED is not correct. In this case, the method will not be able to authenticate the management key as PIN-protected. It will try to authenticate using the default management key, and if that does not work, it will call on the KeyCollector to obtain the it. If that does succeeds, it will set ADMIN DATA to indicate the YubiKey is not PIN-protected, it will clear the contents of PRINTED, and it will return PivPinOnlyMode.None. If the KeyCollector is not able to provide the management key, this method will not be able to reset the ADMIN DATA nor PRINTED (management key authentication is necessary to set a storage location), and will return Unavailable.

This method will require the PIN to be verified. It is possible that the PIN has already been verified and this method will verify it again. If it needs to verify the PIN, it will call on the KeyCollector to obtain it.