Show / Hide Table of Contents

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.)

C#
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 PivTouchPolicy.Default.

Returns

bool

A boolean, true if the management key is changed, false if not.

Exceptions

Type Condition
InvalidOperationException

There is no KeyCollector loaded, 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

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.

C#
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

bool

A boolean, true if the management key is changed, false if not.

Exceptions

Type Condition
InvalidOperationException

There is no KeyCollector loaded, one of the keys provided was not a valid key for the specified algorithm, 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

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.

C#
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 PivTouchPolicy.Default.

Returns

bool

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.

C#
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

bool

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.

In this article
Back to top Generated by DocFX