TryChangeManagementKey Method
TryChangeManagementKey(PivTouchPolicy)
Try to change the management key. The default management key algorithm will be used. (Firmware 5.7.x and later: AES-192. Firmware 5.6.x and earlier: TDES.)
public bool TryChangeManagementKey(PivTouchPolicy touchPolicy = PivTouchPolicy.Default)Parameters
| Type | Name | Description |
|---|---|---|
| PivTouchPolicy | touchPolicy | The touch policy for the new management key. If no argument is given,
the policy will be |
Returns
A boolean, true if the management key is changed, false
if not.
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
Upon manufacture of a YubiKey, the PIV application begins with a default management key (see the User's Manual entry on the management key). 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 management key, or later, to change it again.
If the YubiKey is set for PIN-only, this method will throw an exception.
Beginning with YubiKey 5.4.2, the management key can be either
Triple-DES or AES. When changing the management key, the SDK can
obtain the metadata for the management key slot to determine the
algorithm of the current key. However, the caller must supply the
algorithm of the new key (if it is 24 bytes, is it Triple-DES or
AES-192?). There is a Try method for changing the management
key that has an input argument for the algorithm. This method does
not have such an arg. This one will set the new key to Triple-DES.
The Triple-DES management key is 24 byte long, no more, no less. It is binary. That's 192 bits. But note that because of "parity" bits, the actual bit strength of a Triple-DES key is 124 bits. And then further, there are attacks on Triple-DES that leave its effective bit strength at 112 bits.
In order to change it, the current management key must be
authenticated. If it has already been authenticated in this session,
this method will still make the appropriate calls to authenticate (it
will perform mutual authentication). That is, if you want to change
the management key, it is not necessary to call
TryAuthenticateManagementKey or
AuthenticateManagementKey first. You can, but it doesn't
matter, because this method will call it again.
This method will collect the current and new management keys using
the KeyCollector delegate. If no such delegate has been set,
this method will throw an exception.
The KeyCollector has an option to cancel the operation. That
is, this TryAuthenticateManagementKey method will call the
KeyCollector requesting the current 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.
Along with the key data itself, a management key has a touch policy. See the User's Manual entry on the PIV touch policy.
This method takes in a touch policy argument, but the argument has a
default value, so it is valid to pass no argument to this method. The
default argument value is the Default touch policy.
Note: touch policy for the management key is available only on YubiKey 4 and later. A YubiKey prior to 4 will ignore the touch policy and simply set the touch policy of the management key to the default.
The touch policy refers to whether use of the management key will
require touch or not, and if so, always or cached. The policy is
specified using the PivTouchPolicy enum. If the input is
None or Never, the YubiKey will not require touch to
complete an operation that requires the management key. Always
means every operation requires touch, even if the YubiKey had been
touched for an operation shortly before. If Cached, one touch
will last for 15 seconds. That is, touch for an operation, and if a
second operation requires the management key, and it is executing
less than 15 seconds after the first, touch is not required.
Default will use the YubiKey's default touch policy.
After this method is called, the management key will be authenticated for this session. That is, in order to change the key, the current management key must be authenticated. After changing, the new management key will be considered authenticated, and any subsequent operation that requires management key authentication in order to execute (e.g. generate a key pair) will work.
TryChangeManagementKey(PivTouchPolicy, PivAlgorithm)
Try to change the management key. The new key will be the specified algorithm.
public bool TryChangeManagementKey(PivTouchPolicy touchPolicy, PivAlgorithm newKeyAlgorithm)Parameters
| Type | Name | Description |
|---|---|---|
| PivTouchPolicy | touchPolicy | The touch policy for the new management key. |
| PivAlgorithm | newKeyAlgorithm | The new management key's algorithm. |
Returns
A boolean, true if the management key is changed, false
if not.
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
Upon manufacture of a YubiKey, the PIV application begins with a default management key (see the User's Manual entry on the management key). 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 management key, or later, to change it again.
If the YubiKey is set for PIN-only, this method will throw an exception.
Beginning with YubiKey 5.4.2, the management key can be either Triple-DES or AES. When changing the management key, the SDK can obtain the metadata for the management key slot to determine the algorithm of the current key. However, the caller must supply the algorithm of the new key (if it is 24 bytes, is it Triple-DES or AES-192?).
Note that a Triple-DES key is 24 byte long, no more, no less. It is binary. That's 192 bits. But because of "parity" bits, the actual bit strength of a Triple-DES key is 124 bits. Furthermore, there are attacks on Triple-DES that leave its effective bit strength at 112 bits.
In order to change it, the current management key must be
authenticated. If it has already been authenticated in this session,
this method will still make the appropriate calls to authenticate (it
will perform mutual authentication). That is, if you want to change
the management key, it is not necessary to call
TryAuthenticateManagementKey or
AuthenticateManagementKey first. You can, but it doesn't
matter, because this method will call it again.
This method will collect the current and new management keys using
the KeyCollector delegate. If no such delegate has been set,
this method will throw an exception.
The KeyCollector has an option to cancel the operation. That
is, this TryAuthenticateManagementKey method will call the
KeyCollector requesting the current 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.
Along with the key data itself, a management key has a touch policy. See the User's Manual entry on the PIV touch policy. This method requires a touch policy argument, it does not have a default.
Note: touch policy for the management key is available only on YubiKey 4 and later. A YubiKey prior to 4 will ignore the touch policy and simply set the touch policy of the management key to the default.
The touch policy refers to whether use of the management key will
require touch or not, and if so, always or cached. The policy is
specified using the PivTouchPolicy enum. If the input is
None or Never, the YubiKey will not require touch to
complete an operation that requires the management key. Always
means every operation requires touch, even if the YubiKey had been
touched for an operation shortly before. If Cached, one touch
will last for 15 seconds. That is, touch for an operation, and if a
second operation requires the management key, and it is executing
less than 15 seconds after the first, touch is not required.
Default will use the YubiKey's default touch policy.
After this method is called, the management key will be authenticated for this session. That is, in order to change the key, the current management key must be authenticated. After changing, the new management key will be considered authenticated, and any subsequent operation that requires management key authentication in order to execute (e.g. generate a key pair) will work.
TryChangeManagementKey(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, PivTouchPolicy)
Try to change the management key. This method will use the
currentKey and newKey provided.
public bool TryChangeManagementKey(ReadOnlyMemory<byte> currentKey, ReadOnlyMemory<byte> newKey, PivTouchPolicy touchPolicy = PivTouchPolicy.Default)Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlyMemory<byte> | currentKey | The current management key. |
| ReadOnlyMemory<byte> | newKey | What the management key will be changed to. |
| PivTouchPolicy | touchPolicy | The touch policy for the new management key. If no argument is given,
the policy will be |
Returns
A boolean, true if the management key is changed, false
if not.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | One of the keys 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 would call the
TryChangeManagementKey(PivTouchPolicy) method and the SDK
would call on the loaded KeyCollector to retrieve the current
and new keys. With this method, the caller provides the keys and the
KeyCollector is never contacted.
Some applications would like to avoid using a KeyCollector.
For such situations, this method is provided.
See the TryChangeManagementKey(PivTouchPolicy) method for further documentation on this method.
If the wrong current key is provided, this method will return
false.
TryChangeManagementKey(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>, PivTouchPolicy, PivAlgorithm)
Try to change the management key. This method will use the
currentKey and newKey provided. The new key's algorithm
will be as specified.
public bool TryChangeManagementKey(ReadOnlyMemory<byte> currentKey, ReadOnlyMemory<byte> newKey, PivTouchPolicy touchPolicy, PivAlgorithm newKeyAlgorithm)Parameters
| Type | Name | Description |
|---|---|---|
| ReadOnlyMemory<byte> | currentKey | The current management key. |
| ReadOnlyMemory<byte> | newKey | What the management key will be changed to. |
| PivTouchPolicy | touchPolicy | The touch policy for the new management key. |
| PivAlgorithm | newKeyAlgorithm | The algorithm the new management key will be. |
Returns
A boolean, true if the management key is changed, false
if not.
Exceptions
| Type | Condition |
|---|---|
| InvalidOperationException | One of the keys 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 would call the
TryChangeManagementKey(PivTouchPolicy) method and the SDK
would call on the loaded KeyCollector to retrieve the current
and new keys. With this method, the caller provides the keys and the
KeyCollector is never contacted.
Some applications would like to avoid using a KeyCollector.
For such situations, this method is provided.
See the TryChangeManagementKey(PivTouchPolicy, PivAlgorithm) method for further documentation on this method.
Note that with this method, a touch policy argument is required, there is no default value.
If the wrong current key is provided, this method will return
false.