Class AuthenticateDecryptCommand

Namespace

Yubico.YubiKey.Piv.Commands

Assembly

Yubico.YubiKey.dll

Decrypt data using the private RSA key in one of the PIV slots.

public sealed class AuthenticateDecryptCommand : AuthenticateCommand, IYubiKeyCommand<AuthenticateDecryptResponse>

Inheritance

object

AuthenticateCommand

AuthenticateDecryptCommand

Implements

IYubiKeyCommand<AuthenticateDecryptResponse>

Inherited Members

AuthenticateCommand.Application

AuthenticateCommand.SlotNumber

AuthenticateCommand.CreateCommandApdu()

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: RSA Decryption".

The partner Response class is AuthenticateDecryptResponse.

Use this Command class only if the slot selected holds an RSA private key. If the private key in a slot called upon to perform this command is ECC, the YubiKey will return an error. While there is an algorithm known as "EC Encryption Scheme" (aka "EC El Gamal"), the YubiKey does not support it. Hence, this command will not be able to decrypt using an EC key. Therefore, you should know which algorithm (and size) the key in the requested slot is before calling on this class.

In order to decrypt, 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 RSA private key). That is, any PIV slot other than 80, 81, 9B, or F9 will be able to decrypt. Note that slot F9 contains the attestation key, which will sign a certificate it creates, but it cannot decrypt.

The caller supplies the data to decrypt. It must be a block the same size as the key. For an RSA-1024 key, the block must be 128 bytes, for an RSA-2048 key, the block must be 256 bytes, for an RSA-3072 key, the block must be 384 bytes, and for an RSA-4096 key, the block must be 512 bytes. If the actual data to decrypt is shorter, it must be provided with as many prepended 00 bytes as needed to make sure the block is the appropriate length.

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 decryptCommand = new AuthenticateDecryptCommand(dataToDecrypt, PivSlot.KeyManagement);
AuthenticateDecryptResponse decryptResponse = connection.SendCommand(decryptCommand);
if (decryptResponse.Status != ResponseStatus.Success)
{
  // handle error
}
byte[] decryptedData = decryptResponse.GetData();

Constructors

AuthenticateDecryptCommand(ReadOnlyMemory<byte>, byte)

Initializes a new instance of the AuthenticateDecryptCommand class. This command takes the slot number and the data to decrypt.

public AuthenticateDecryptCommand(ReadOnlyMemory<byte> dataToDecrypt, byte slotNumber)

Parameters

dataToDecrypt ReadOnlyMemory<byte>

The data to decrypt.

slotNumber byte

The slot holding the private key to use.

Remarks

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

If the key that will be used to decrypt is RSA-1024, then the data to decrypt must be 128 (1024 bits) bytes long. If the key is RSA-2048, then the data must be 256 bytes (2048 bits) long. If the key is RSA-3072, then the data must be 384 bytes (3072 bits) long. If the key is RSA-4096, then the data must be 512 bytes (4096 bits) long. See also the User's Manual entry on decrypting in the PIV commands page.

Exceptions

ArgumentException

The ciphertext is not the correct length.

Methods

CreateResponseForApdu(ResponseApdu)

Creates the corresponding IYubiKeyResponse implementation for the current command.

public AuthenticateDecryptResponse CreateResponseForApdu(ResponseApdu responseApdu)

Parameters

responseApdu ResponseApdu

The ResponseApdu returned by the YubiKey.

Returns

AuthenticateDecryptResponse

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