TryAuthenticateManagementKey Method
TryAuthenticateManagementKey(bool)
Try to authenticate the management key.
public bool TryAuthenticateManagementKey(bool mutualAuthentication = true)Parameters
| Type | Name | Description |
|---|---|---|
| bool | mutualAuthentication | If |
Returns
A boolean, true if the management key authenticates,
false if the user cancels.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | There is no |
| MalformedYubiKeyResponseException | The YubiKey returned malformed data and authentication, either single or double, could not be performed. |
| 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>, bool)
Try to authenticate the management key. This method will use the key
data provided, rather than the KeyCollector.
public bool TryAuthenticateManagementKey(ReadOnlyMemory<byte> managementKey, bool mutualAuthentication = true)Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlyMemory<byte> | managementKey | The key to authenticate. |
| bool | mutualAuthentication | If |
Returns
A boolean, true if the management key authenticates,
false if it does not.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | The key provided was not a valid Triple-DES or AES 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. |
| 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(bool) 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.