TryAuthenticateManagementKey Method

TryAuthenticateManagementKey(Boolean)

Try to authenticate the management key.

C#

public bool TryAuthenticateManagementKey(bool mutualAuthentication = true)

Parameters

Type	Name	Description
System.Boolean	mutualAuthentication	If true the method will perform mutual authentication, if false, only the application will authenticate to the YubiKey.

Returns

System.Boolean

A boolean, true if the management key authenticates, false if the user cancels.

Exceptions

Type	Condition
System.InvalidOperationException	There is no KeyCollector loaded, the key provided was not a valid key, or the YubiKey had some other error, such as unreliable connection.
MalformedYubiKeyResponseException	The YubiKey returned malformed data and authentication, either single or double, could not be performed.
System.Security.SecurityException	Mutual authentication was performed and the YubiKey was not authenticated.

Remarks

You need to authenticate the management key only once per session. But if you have already authenticated, and you call this method, it will perform the authentication again. If the authentication fails the second time, the previous auth will be nullified.

See the ManagementKeyAuthenticated property for the current state of management key authentication.

This method will determine if the YubiKey is set for PIN-only. If so, it will collect the management key using the PIN and authenticate. If not, it will use the KeyCollector to obtain the management key. The ADMIN DATA and PRINTED storage locations contain information about PIN-only (PIN-protected, PIN-derived, or both). If that information is inaccurate (some other application overwrote the data in one or both locations, PIN-only authentication might fail and this method will use the KeyCollector.

If the YubiKey is not set for PIN-only, this method will collect the management key using the KeyCollector delegate. If no such delegate has been set, this method will throw an exception.

Beginning with YubiKey 5.4.2, the management key can be AES as well as Triple-DES. When the SDK calls the KeyCollector delegate, it will not specify the expected algorithm or length of the management key. If you need to know which algorithm the management keys is, look at the property PivSession.ManagementKeyAlgorithm. Maybe your Key Collector is an object and you can let it know which algorithm the management key is so when the management key is requested, the user will know how many bytes to provide. For example,

   KeyCollectorClass.ManagementKeyAlgorithm = pivSession.ManagementKeyAlgorithm;
   pivSession.KeyCollector = KeyCollectorClass.KeyCollectorDelegate;

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

It is possible to perform single or mutual authentication. In single, only the "off-card" application authenticates itself to the YubiKey. In mutual authentication, both the off-card application and the YubiKey authenticate each other. If the bool argument mutualAuthentication is true, this method will perform mutual authentication. If false, it will perform single. The default is true, so if no argument is given, this method will perform mutual authentication.

This method will also set the ManagementKeyAuthenticated and ManagementKeyAuthenticationResult properties. The "Result" is an AuthenticateManagementKeyResult enum, listing the possible results. For example, if you call for mutual authentication and it fails, the property will be set to AuthenticateManagementKeyResult.MutualOffCardAuthenticationFailed or MutualYubiKeyAuthenticationFailed, depending on what went wrong.

If the management key authenticates, the method will return true. If not, and the KeyCollector cancels the process, the method will return false and set the ManagementKeyAuthenticationResult property to the failure reason.

If the call is for mutual authentication, and the off-card application authenticates but the YubiKey does not, this method will set the ManagementKeyAuthenticationResult property to MutualYubiKeyAuthenticationFailed and throw an exception. This can happen when the there is an unreliable connection with the YubiKey, but it is also possible the device is a fraudulent YubiKey. In this case it is still possible to call on the connected device to perform operations, after all, the device trusts the off-card application. Generally, however, an application will not want to use the device if this happens. Nonetheless, an application could catch the exception and continue, either try again or use the device knowing it is untrusted.

The method will call the KeyCollector delegate to obtain the management key. If the management key obtained authenticates, the method will call the KeyCollector again with the Request of Release. Upon the return from this release call to the KeyCollector, the method will return true and set the ManagementKeyAuthenticated property to true and the ManagementKeyAuthenticationResult property to SingleAuthenticated or MutualFullyAuthenticated. Note that this method ignores the return from the KeyCollector when the request is Release. That is, this method will return true or false depending on what happened before the Release. Note also that the KeyCollector MUST NEVER throw an exception when the request is Release.

If the off-card application authentication fails, the method will call the KeyCollector delegate again, this time indicating the previous management key provided failed to authenticate (KeyEntryRequest.IsRetry will be set to true). The method will continue to call the KeyCollector and try to authenticate as long as the returned management key does not authenticate, and the return from the KeyCollector is true. If you want to cancel the authentication process after some number of failed attempts, build your KeyCollector to allow the user to cancel or keep track of the failures and return false after the limit has been reached.

Note that there is no limit on the number of tries to authenticate the management key. That is, the management key will never be blocked.

Note also that if the call is for mutual authentication and the YubiKey fails to authenticate, then the method will not call the KeyCollector again, it will set the ManagementKeyAuthenticated property to false, the ManagementKeyAuthenticationResult property to MutualYubiKeyAuthenticationFailed, and throw an exception.

If there is an error during the process, this method will simply call the KeyCollector with Release, set the ManagementKeyAuthenticated property to false, the ManagementKeyAuthenticationResult property to Unauthenticated, and throw an exception.

TryAuthenticateManagementKey(ReadOnlyMemory<Byte>, Boolean)

Try to authenticate the management key. This method will use the key data provided, rather than the KeyCollector.

C#

public bool TryAuthenticateManagementKey(ReadOnlyMemory<byte> managementKey, bool mutualAuthentication = true)

Parameters

Type	Name	Description
System.ReadOnlyMemory<System.Byte>	managementKey	The key to authenticate.
System.Boolean	mutualAuthentication	If true the method will perform mutual authentication, if false, only the application will authenticate to the YubiKey. The default is true.

Returns

System.Boolean

A boolean, true if the management key authenticates, false if it does not.

Exceptions

Type	Condition
System.InvalidOperationException	The key provided was not a valid Triple-DES key, or the YubiKey had some other error, such as unreliable connection.
MalformedYubiKeyResponseException	The YubiKey returned malformed data and authentication, either single or double, could not be performed.
System.Security.SecurityException	Mutual authentication was performed and the YubiKey was not authenticated.

Remarks

Normally, an application will not call any AuthenticateManagementKey method. Under the covers, the SDK determines when the management key needs to be verified and calls the KeyCollector. It is only at that point the application needs to supply the key. The SDK will call the application-supplied KeyCollector, indicating what it needs (PIN, PUK, management key), and the KeyCollector does what it needs to obtain the value requested. This system also contains a mechanism to report if the previous value was incorrect. If the management key is never needed, the key is never provided.

See the User's Manual entry on the Key Collector for a more detailed explanation of this process.

With this method, however, the caller provides the management key and the KeyCollector is never contacted.

See the TryAuthenticateManagementKey(Boolean) method for further documentation on this method.

Generally, it is necessary to authenticate a management key once per session. Once the key is authenticated, any operation that required the key in order to execute, called during that session, will work. The exceptions include changing the management key, and setting a YubiKey to PIN-only.

Some applications would like to avoid using a KeyCollector. For such situations, this method is provided. As long as the application does not perform an operation that requires the management key even if it has been authenticated in the session, the KeyCollector is not needed.

Note that if the management key is needed during the session even after the key is authenticated using this method (see exceptions above), and no KeyCollector is provided, the SDK will throw an exception.

The management key is provided to this method as a ReadOnlyMemory<byte>. It is possible to pass a byte[], because it will be automatically cast. The management key is 24 bytes, no more, no less.

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