AuthenticateSignCommand Class

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

Build a digital signature using the private key in one of the PIV slots.

C#

public sealed class AuthenticateSignCommand : AuthenticateCommand, IYubiKeyCommand<AuthenticateSignResponse>

Inheritance System.Object AuthenticateCommand AuthenticateSignCommand

Implements

IYubiKeyCommand<AuthenticateSignResponse>

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: Sign".

The partner Response class is AuthenticateSignResponse.

In order to create a signature, 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 9C is the "digital signature" slot, but any PIV slot that holds a private key, other then F9, will be able to create a signature. That is, any PIV slot other than 80, 81, 9B, or F9 will be able to sign. Note that slot F9 contains the attestation key, which will sign a certificate it creates, so it can sign. It simply cannot sign arbitrary data, only attestation statements.

The caller also supplies the digest of the data to sign. For RSA signatures, the digest must be formatted following PKCS 1 version 1.5, or PKCS 1 PSS (Probabilistic Signature Scheme). See RFC 8017 for details on these formats. For ECC signatures, the digest provided is not formatted further. For example, if you digest the data to sign using SHA-256, the digest is 32 bytes and you provide 32 bytes to this command. See also the User's Manual entry on signing in the PIV commands page.

If the key is ECC-P256, the digest must be 256 bits (32 bytes). If the key is ECC-P384, the digest must be 384 bits (48 bytes).

You should know which algorithm (and size) the key in the requested slot is, because if you provide the wrong format (or size) of digest, the YubiKey will return an error.

This class will copy a reference to the digest data, 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:

  /* This example assumes there is some code that will digest the data. */
  byte[] sha384Digest = DigestDataToSign(SHA384, dataToSign);

  IYubiKeyConnection connection = key.Connect(YubiKeyApplication.Piv);

  var signCommand = new AuthenticateSignCommand(sha384Digest, PivSlot.Signing);
  AuthenticateSignResponse signResponse = connection.SendCommand(signCommand);

  if (signResponse.Status != ResponseStatus.Success)
  {
    // handle error
  }
  byte[] signature = signResponse.GetData();

Constructors

Name	Description
AuthenticateSignCommand(ReadOnlyMemory<Byte>, Byte)	Initializes a new instance of the AuthenticateSignCommand class. This command takes the slot number and the (possibly formatted) digest of the data to sign.

Methods

Name	Description
CreateResponseForApdu(ResponseApdu)	Creates the corresponding IYubiKeyResponse implementation for the current command.