AuthenticateKeyAgreeCommand Class

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.

C#
public sealed class AuthenticateKeyAgreeCommand : AuthenticateCommand, IYubiKeyCommand<AuthenticateKeyAgreeResponse>
Inheritance System.Object AuthenticateCommand AuthenticateKeyAgreeCommand

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

Name Description
AuthenticateKeyAgreeCommand(ReadOnlyMemory<Byte>, Byte)

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

Methods

Name Description
CreateResponseForApdu(ResponseApdu)

Creates the corresponding IYubiKeyResponse implementation for the current command.