SetPinOnlyMode Method

SetPinOnlyMode(PivPinOnlyMode)

Set the YubiKey's PIV application to be PIN-only with a PIN-derived and/or PIN-Protected management key. The default management key algorithm will be used (AES-192 for YubiKeys with firmware 5.7.x and later, TDES for keys with firmware 5.6.x and earlier). This sets the YubiKey to either

PivPinOnlyMode.PinProtected
PivPinOnlyMode.PinDerived
PivPinOnlyMode.PinProtected | PivPinOnlyMode.PinDerived
PivPinOnlyMode.None

If the YubiKey is set to PinProtected, PinDerived, or both, the PUK will also be blocked.

Warning

You should not set a YubiKey for PIN-derived, this feature is provided only for backwards compatibility.

public void SetPinOnlyMode(PivPinOnlyMode pinOnlyMode)

Parameters

Type	Name	Description
PivPinOnlyMode	pinOnlyMode	The mode to which the YubiKey is to be set.

Exceptions

Type	Condition
InvalidOperationException	There is no `KeyCollector` loaded, one of the keys provided was not of a valid key algorithm type (Firmware 5.7.x and later: AES-192. Firmware 5.6.x and earlier: TDES.), the data stored on the YubiKey is incompatible with PIN-only, or the YubiKey had some other error, such as unreliable connection.
OperationCanceledException	The user canceled management key or PIN collection.
SecurityException	Mutual authentication was performed and the YubiKey was not authenticated, or the remaining retries count indicates the PIN is blocked.

Remarks

PIN-only mode means that the application does not need to enter the management key in order to perform PIV operations that normally require it, only the PIN is needed.

See the documentation for SetPinOnlyMode(PivPinOnlyMode, PivAlgorithm) and the User's Manual entry on PIV PIN-only mode for a deeper discussion of this feature.

Note that this sets the PIV application on the specific YubiKey to a PIN-only mode, it has nothing to do with OATH, FIDO, or OpenPGP.

Note also that this will make sure that the management key algorithm will be default management key algorithm (Firmware 5.7.x and later: AES-192. Firmware 5.6.x and earlier: TDES.), even if the current management key is a different algorithm. This behavior matches how this method operated in previous versions of the SDK.

SetPinOnlyMode(PivPinOnlyMode, PivAlgorithm)

Set the YubiKey's PIV application to be PIN-only with a PIN-derived and/or PIN-Protected management key of the specified algorithm. This sets the YubiKey to either

PivPinOnlyMode.PinProtected
PivPinOnlyMode.PinDerived
PivPinOnlyMode.PinProtected | PivPinOnlyMode.PinDerived
PivPinOnlyMode.None

If the YubiKey is set to PinProtected, PinDerived, or both, the PUK will also be blocked.

Warning

You should not set a YubiKey for PIN-derived, this feature is provided only for backwards compatibility.

public void SetPinOnlyMode(PivPinOnlyMode pinOnlyMode, PivAlgorithm mgmtKeyAlgorithm)

Parameters

Type	Name	Description
PivPinOnlyMode	pinOnlyMode	The mode to which the YubiKey is to be set.
PivAlgorithm	mgmtKeyAlgorithm	The algorithm to which the management key will be set.

Exceptions

Type	Condition
InvalidOperationException	There is no `KeyCollector` loaded, one of the keys provided was not of a valid key algorithm type, the data stored on the YubiKey is incompatible with PIN-only, or the YubiKey had some other error, such as unreliable connection.
OperationCanceledException	The user canceled management key or PIN collection.
SecurityException	Mutual authentication was performed and the YubiKey was not authenticated, or the remaining retries count indicates the PIN is blocked.

Remarks

PIN-only mode means that the application does not need to enter the management key in order to perform PIV operations that normally require it, only the PIN is needed.

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

Note that this sets the PIV application on the specific YubiKey to a PIN-only mode, it has nothing to do with OATH, FIDO, or OpenPGP.

Upon successful completion of this method, the PUK will be blocked.

The management key derived and/or stored in PRINTED will be for the specified algorithm. For all YubiKeys, TripleDes is a valid algorithm. For YubiKeys 5.4.2 and later, it is possible to set the management key to an AES key. For YubiKeys 5.7 and later, AES192 is the default. Before setting the mgmtKeyAlgorithm arg to an AES algorithm, make sure it is allowed on the YubiKey. You can use the HasFeature call. For example,

PivAlgorithm mgmtKeyAlgorithm = yubiKey.HasFeature(YubiKeyFeature.PivAesManagementKey) ?
        PivAlgorithm.Aes192 : PivAlgorithm.TripleDes;
    pivSession.SetPinOnlyMode(PivPinOnlyMode.PinProtected, mgmtKeyAlgorithm);

If the algorithm is not supported by the YubiKey, this method will throw an exception. It will not change the YubiKey, it will not set it to PIN-only.

If the YubiKey is already set to the specified PIN-protected mode and algorithm, this will not reset the YubiKey, but will simply authenticate the management key.

If the YubiKey is already set to PIN-only, but not the specified mode, this method will make sure the YubiKey is set to both PIN-only modes.

If the YubiKey is already set to PIN-only, but not the specified algorithm, this method will change to a new management key of the specified algorithm.

If the requested pinOnlyMode is both, then this will make sure the YubiKey is both PIN-protected and PIN-derived.

If the input pinOnlyMode is None, and the YubiKey is currently set to PIN-only (and neither PinProtected nor PinDerived is Unavailable), this method will remove the contents of the storage locations ADMIN DATA and PRINTED, and reset the management key to the default management key. In this case, the mgmtKeyAlgorithm arg will be ignored, the management key's algorithm after removing PIN-only status will be the default management key algorithm (Firmware 5.7.x and later: AES-192. Firmware 5.6.x and earlier: TDES.). The touch policy of the management key will also be set to the default (Never). Note that the management key must be authenticated and the PIN verified in order to perform this task. This method will authenticate the management key using the PIN-only mode to which the YubiKey is currently set, then clear the contents. It will then change the management key to the default value. Hence, after setting the YubiKey out of PIN-only mode, you should change the management key. Note also that the PUK will still be blocked. The only way to unblock the PUK is to reset the retry counts. This will set both the PIN and PUK to their default values. Resetting the retry counts requires management key authentication.

If the input pinOnlyMode is None, and the YubiKey is currently set to one PIN-only mode, but the other is Unavailable, this method will clear the one that is set but leave the one that is Unavailable as is. For example, suppose the current mode is PinProtected | PinDerivedUnavailable, then after setting to None, the PRINTED storage area will be empty and the ADMIN DATA storage area will be left as is.

If the input pinOnlyMode is None, and the YubiKey is currently NOT set to either PIN-only modes, this method will do nothing. It will not remove anything from ADMIN DATA or PRINTED, it will not try to authenticate the management key, nor will it try to verify the PIN. It will not change the management to the default. It will ignore the mgmtKeyAlgorithm argument.

If a YubiKey is currently set to both modes, and you call this method with only one of the modes, this method will NOT "remove" the other mode.

If a YubiKey is currently set to both PIN-only modes and you want to "remove" one of them, call this method and set the YubiKey to None, then call this method a second time and set the YubiKey to the desired mode.

In order to set the YubiKey to be PIN-only, this method must authenticate the management key. Even if the management key is already authenticated, this method will authenticate. It will try to authenticate using the PIN-only techniques, and if that does not work, it will try to authenticate using the default management key. If either of those techniques works, the user will not have to enter the management key. But if the YubiKey is not PIN-only, and the default management key does not authenticate, the method will call on the KeyCollector to obtain the correct value.

If the mode to set is PIN-protected, then this method will use the existing mgmt key, unless it is the default. In that case, this method will generate a new, random mgmt key, set the YubiKey with this new value, and PIN-protect the new key.

This method also requires the PIN to be verified. If setting to PIN-derived, even if the PIN is already verified, this method will call on the KeyCollector to obtain the PIN. If setting to PIN-protected, this method will verify the PIN only if it has not yet been verified.

Note that this method will throw an exception if the current contents of ADMIN DATA and/or PRINTED are not compatible with PIN-only mode. If there are no current contents, then this method will set one or both of those storage locations with appropriate data. But if there is already something in one or both, and it is not PIN-only information, then this method will not replace that data, it will throw an exception.