Table of Contents

Class AuthenticateKeyAgreeCommand

Namespace
Yubico.YubiKey.Piv.Commands
Assembly
Yubico.YubiKey.dll

Perform phase 2 of EC Diffie-Hellman key agreement using the private ECC key in one of the PIV slots.

public sealed class AuthenticateKeyAgreeCommand : AuthenticateCommand, IYubiKeyCommand<AuthenticateKeyAgreeResponse>
Inheritance
object
AuthenticateKeyAgreeCommand
Implements
Inherited Members

Remarks

In the PIV standard, there is a command called GENERAL AUTHENTICATE. Although it is one command, it can do four things: authenticate a management key (challenge-response), sign arbitrary data, RSA decryption, and EC Diffie-Hellman. The SDK breaks these four operations into separate classes. This class is how you perform "GENERAL AUTHENTICATE: Key Agree.

The partner Response class is AuthenticateKeyAgreeResponse.

Use this Command class only if the slot selected holds an ECC private key. If the private key in a slot called upon to perform this command is RSA, the YubiKey will return an error. The RSA algorithm can encrypt, decrypt, sign, and verify, but it cannot perform the Diffie-Hellman Key Agreement protocol.

In order to perform key agreement, it is possible you must verify the PIN. The PIN is not part of this command. For information on how to verify a PIN in order to perform operations, see the User's Manual entry on PIV commands access control.

The caller supplies the slot to use. Slot 9D is the "key management" slot, but any PIV slot that holds a private key, other then F9, will be able to decrypt (as long as it contains an ECC private key). That is, any PIV slot other than 80, 81, 9B, or F9 will be able to perform key agreement. Note that slot F9 contains the attestation key, which will sign a certificate it creates, but it cannot perform key agreement, even if it is an ECC key.

The caller supplies the corresponding party's public key. It must be a block encoded as follows. 

04 <x-coordinate> <y-coordinate>
where each coordinate is the same size as the key.
For example, if the slot holds an ECC-P256 key, then each coordinate
must be 32 bytes long (256 bits). Prepend 00 bytes if necessary. The
total length will be 65 bytes.
Note that there is a "compressed" form of a public key, but the YubiKey
does not support it. Hence, you must supply the public key as described.
This class will copy a reference to the data to decrypt, so you should not clear or alter that input data until this class is done with it, which is after the call to SendCommand.

Example: 

IYubiKeyConnection connection = key.Connect(YubiKeyApplication.Piv);
var keyAgreeCommand = new AuthenticateKeyAgreeCommand(pubKeyData, PivSlot.KeyManagement);
AuthenticateDecryptResponse keyAgreeResponse = connection.SendCommand(keyAgreeCommand);
if (keyAgreeResponse.Status != ResponseStatus.Success)
{
  // handle error
}
byte[] sharedSecret = keyAgreeResponse.GetData();

Constructors

AuthenticateKeyAgreeCommand(ReadOnlyMemory<byte>, byte, PivAlgorithm)

Initializes a new instance of the AuthenticateKeyAgreeCommand class. This command takes the slot number and the corresponding party's public key.

public AuthenticateKeyAgreeCommand(ReadOnlyMemory<byte> correspondentPublicKey, byte slotNumber, PivAlgorithm algorithm)

Parameters

correspondentPublicKey ReadOnlyMemory<byte>

The public key that will be used to perform phase 2 of ECDH.

slotNumber byte

The slot holding the private key to use.

algorithm PivAlgorithm

Remarks

The slot number must be for a slot that holds an ECC private key. It cannot be F9 (the attestation key).

If the key that will be used to perform key agreement is ECC-P256, then the correspondent public key data must be 65 bytes long. If the key is ECC-P384, then the data must be 97 bytes long. See also the User's Manual entry on key agreement in the PIV commands page.

Exceptions

ArgumentException

The correspondent public value is not the correct length.

Methods

CreateResponseForApdu(ResponseApdu)

Creates the corresponding IYubiKeyResponse implementation for the current command.

public AuthenticateKeyAgreeResponse CreateResponseForApdu(ResponseApdu responseApdu)

Parameters

responseApdu ResponseApdu

The ResponseApdu returned by the YubiKey.

Returns

AuthenticateKeyAgreeResponse

The implementation of IYubiKeyResponse that parses and presents ths response APDU.