ImportPrivateKey Method

ImportPrivateKey(byte, PivPrivateKey, PivPinPolicy, PivTouchPolicy)

Import a private key into the given slot.

C#

[Obsolete("Usage of PivEccPublic/PivEccPrivateKey is deprecated. Use IPublicKey, IPrivateKey instead", false)]
public void ImportPrivateKey(byte slotNumber, PivPrivateKey privateKey, PivPinPolicy pinPolicy = PivPinPolicy.Default, PivTouchPolicy touchPolicy = PivTouchPolicy.Default)

Parameters

Type	Name	Description
byte	slotNumber	The slot into which the key will be imported.
PivPrivateKey	privateKey	The private key to import into the YubiKey.
PivPinPolicy	pinPolicy	The PIN policy the key will have. If no argument is given, the policy will be Default.
PivTouchPolicy	touchPolicy	The touch policy the key will have. If no argument is given, the policy will be Default.

Exceptions

Type	Condition
ArgumentNullException	The privateKey argument is null.
ArgumentException	The slot specified is not valid for generating a key pair, or the privateKey object is empty.
InvalidOperationException	There is no KeyCollector loaded, the key provided was not a valid Triple-DES key, or the YubiKey had some other error, such as unreliable connection.
OperationCanceledException	The user canceled management key collection.
SecurityException	Mutual authentication was performed and the YubiKey was not authenticated.
NotSupportedException	If the specified PivAlgorithm is not supported by the provided IYubiKeyDevice.

Remarks

When you import a key, you specify which slot will hold this key. If there is a key in that slot already, this method will replace it. That old key will be gone and there will be nothing you can do to recover it. Hence, use this method with caution.

This method will not return to you the public key partner to the private key imported into the slot. For YubiKeys before version 5.3, you will not have the opportunity to obtain the public key, so make sure your application manages it right from the start. Beginning with version 5.3, it is possible to get a public key out of a slot at any time.

You also have the opportunity to specify the PIN and touch policies of the private key generated. These policies describe what will be required when using the key. For example, if the PIN policy is Always, then every time the key is used (to sign, decrypt, or perform key agreement), it will be necessary to verify the PIV PIN. With the touch policy, for instance, setting it to Always will require touch every time the key is used. This method has the policies as optional arguments. If you do not specify these arguments, the key pair will be generated with the policies set to Default. Currently for all YubiKeys, the default PIN policy is Once, and the default touch policy is Never.

In order to perform this operation, the management key must be authenticated during this session. If it has not been authenticated, this method will call AuthenticateManagementKey(bool). That is, your application does not need to authenticate the management key separately (i.e., call TryAuthenticateManagementKey or AuthenticateManagementKey), this method will determine if the management key has been authenticated or not, and if not, it will make the call to perform mutual authentication.

The authentication method will collect the management key using the KeyCollector delegate. If no such delegate has been set, it will throw an exception.

The KeyCollector has an option to cancel the operation. That is, the AuthenticateManagementKey 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 the authentication method noting the cancellation. In that case, it will throw an exception. If you want the authentication to return false on user cancellation, you must call TryAuthenticateManagementKey(bool) directly before calling this method.

ImportPrivateKey(byte, IPrivateKey, PivPinPolicy, PivTouchPolicy)

Import a private key into the given slot.

C#

public void ImportPrivateKey(byte slotNumber, IPrivateKey privateKey, PivPinPolicy pinPolicy = PivPinPolicy.Default, PivTouchPolicy touchPolicy = PivTouchPolicy.Default)

Parameters

Type	Name	Description
byte	slotNumber	The slot into which the key will be imported.
IPrivateKey	privateKey	The private key parameters and values to import into the YubiKey.
PivPinPolicy	pinPolicy	The PIN policy the key will have. If no argument is given, the policy will be Default.
PivTouchPolicy	touchPolicy	The touch policy the key will have. If no argument is given, the policy will be Default.

Exceptions

Type	Condition
ArgumentNullException	The privateKey argument is null.
ArgumentException	The slot specified is not valid for generating a key pair, or the privateKey object is empty.
InvalidOperationException	There is no KeyCollector loaded, the key provided was not a valid Triple-DES key, or the YubiKey had some other error, such as unreliable connection.
OperationCanceledException	The user canceled management key collection.
SecurityException	Mutual authentication was performed and the YubiKey was not authenticated.
NotSupportedException	If the specified PivAlgorithm is not supported by the provided IYubiKeyDevice.

Remarks

When you import a key, you specify which slot will hold this key. If there is a key in that slot already, this method will replace it. That old key will be gone and there will be nothing you can do to recover it. Hence, use this method with caution.

This method will not return to you the public key partner to the private key imported into the slot. For YubiKeys before version 5.3, you will not have the opportunity to obtain the public key, so make sure your application manages it right from the start. Beginning with version 5.3, it is possible to get a public key out of a slot at any time.

You also have the opportunity to specify the PIN and touch policies of the private key generated. These policies describe what will be required when using the key. For example, if the PIN policy is Always, then every time the key is used (to sign, decrypt, or perform key agreement), it will be necessary to verify the PIV PIN. With the touch policy, for instance, setting it to Always will require touch every time the key is used. This method has the policies as optional arguments. If you do not specify these arguments, the key pair will be generated with the policies set to Default. Currently for all YubiKeys, the default PIN policy is Once, and the default touch policy is Never.

In order to perform this operation, the management key must be authenticated during this session. If it has not been authenticated, this method will call AuthenticateManagementKey(bool). That is, your application does not need to authenticate the management key separately (i.e., call TryAuthenticateManagementKey or AuthenticateManagementKey), this method will determine if the management key has been authenticated or not, and if not, it will make the call to perform mutual authentication.

The authentication method will collect the management key using the KeyCollector delegate. If no such delegate has been set, it will throw an exception.

The KeyCollector has an option to cancel the operation. That is, the AuthenticateManagementKey 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 the authentication method noting the cancellation. In that case, it will throw an exception. If you want the authentication to return false on user cancellation, you must call TryAuthenticateManagementKey(bool) directly before calling this method.