Table of Contents

Class CreateHostChallengeCommand

Namespace
Yubico.YubiKey.YubiHsmAuth.Commands
Assembly
Yubico.YubiKey.dll

The command class for getting a challenge for credential authentication.

public sealed class CreateHostChallengeCommand : IYubiKeyCommand<CreateHostChallengeResponse>
Inheritance
object
CreateHostChallengeCommand
Implements

Remarks

This command sends the GET_CHALLENGE instruction (0x04) to the YubiKey device to retrieve a challenge based on the credential type.

For symmetric credentials this generates an 8-byte 'Host Challenge', a random value used for authentication with AES-based symmetric key protocols.

For asymmetric credentials this returns 'EPK-OCE', the public part of a newly generated ephemeral ECC SECP256R1 key (65 bytes uncompressed).

The associated response class is CreateHostChallengeResponse.

Constructors

CreateHostChallengeCommand()

Constructs an instance of the CreateHostChallengeCommand class.

public CreateHostChallengeCommand()

Remarks

The CredentialLabel will need to be set before calling CreateCommandApdu().

CreateHostChallengeCommand(CryptographicKeyType, string, ReadOnlyMemory<byte>?)

Constructs an instance of the CreateHostChallengeCommand class with the credential.

public CreateHostChallengeCommand(CryptographicKeyType keytype, string credentialLabel, ReadOnlyMemory<byte>? credentialPassword = null)

Parameters

keytype CryptographicKeyType

The type of cryptographic key.

credentialLabel string

The Credential for which to get the challenge.

credentialPassword ReadOnlyMemory<byte>?

The password for the credential.

Properties

Application

Gets the YubiKeyApplication to which this command belongs.

public YubiKeyApplication Application { get; }

Property Value

YubiKeyApplication

YubiHsmAuth

CredentialLabel

A short name or description of the Credential.

public string CredentialLabel { get; set; }

Property Value

string

Remarks

The string only contains characters that can be encoded with UTF-8, and its UTF-8 byte count is between MinLabelByteCount and MaxLabelByteCount. Non-printing characters are allowed, as long as they can be encoded with UTF-8. For example, null (UTF-8: 0x00) and Right-To-Left Mark U+200F (UTF-8: 0xE2 0x80 0x8F) would be acceptable.

The System.Text.UTF8Encoding class contains methods such as System.Text.UTF8Encoding.GetByteCount(string) which can be used to validate the string prior to attempting to set it here. It is recommended to use the constructor System.Text.UTF8Encoding.UTF8Encoding(bool, bool) so error detection is enabled for invalid characters.

Exceptions

ArgumentNullException

Thrown when the supplied string is null.

ArgumentOutOfRangeException

Thrown when the string's UTF-8 byte count does not meet the length parameters MinLabelByteCount and MaxLabelByteCount.

ArgumentException

Thrown when there is a character that cannot be encoded with UTF-8. The exact exception may be derived from ArgumentException.

KeyType

Cryptographic algorithm used to describe the key(s) associated with a Credential in the YubiHSM Auth application.

public CryptographicKeyType KeyType { get; set; }

Property Value

CryptographicKeyType

Methods

CreateCommandApdu()

Creates a well-formed CommandApdu to send to the YubiKey.

public CommandApdu CreateCommandApdu()

Returns

CommandApdu

A valid CommandApdu that is ready to be sent to the YubiKey, or passed along to additional encoders for further processing.

Remarks

This method will first perform validation on all of the parameters and data provided to it. The CommandAPDU it creates should contain all of the data payload for the command, even if it exceeds 65,535 bytes as specified by the ISO 7816-4 specification. The APDU will be properly chained by the device connection prior to being sent to the YubiKey, and the responses will collapsed into a single result.

CreateResponseForApdu(ResponseApdu)

Creates the corresponding IYubiKeyResponse implementation for the current command.

public CreateHostChallengeResponse CreateResponseForApdu(ResponseApdu responseApdu)

Parameters

responseApdu ResponseApdu

The ResponseApdu returned by the YubiKey.

Returns

CreateHostChallengeResponse

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