TryChangeManagementKey Method

TryChangeManagementKey(PivTouchPolicy)

Try to change the management key. This will assume the new key is to be Triple-DES.

C#

public bool TryChangeManagementKey(PivTouchPolicy touchPolicy)

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

System.Boolean

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

Exceptions

Type	Condition
System.InvalidOperationException	There is no KeyCollector loaded, one of the keys 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

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

System.Boolean

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

Exceptions

Type	Condition
System.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.
System.Security.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. The new key's algorithm will be Triple-DES.

C#

public bool TryChangeManagementKey(ReadOnlyMemory<byte> currentKey, ReadOnlyMemory<byte> newKey, PivTouchPolicy touchPolicy)

Parameters

Type	Name	Description
System.ReadOnlyMemory<System.Byte>	currentKey	The current management key.
System.ReadOnlyMemory<System.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

System.Boolean

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

Exceptions

Type	Condition
System.InvalidOperationException	One of the keys 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 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
System.ReadOnlyMemory<System.Byte>	currentKey	The current management key.
System.ReadOnlyMemory<System.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

System.Boolean

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

Exceptions

Type	Condition
System.InvalidOperationException	One of the keys 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 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.