Class ConfigureChallengeResponse

Namespace

Yubico.YubiKey.Otp.Operations

Assembly

Yubico.YubiKey.dll

Configures a YubiKey's OTP slot to perform challenge-response using either the Yubico OTP or the HMAC-SHA1 algorithm.

public class ConfigureChallengeResponse : OperationBase<ConfigureChallengeResponse>

Inheritance

object

OperationBase<ConfigureChallengeResponse>

ConfigureChallengeResponse

Inherited Members

OperationBase<ConfigureChallengeResponse>.CurrentAccessCode

OperationBase<ConfigureChallengeResponse>.NewAccessCode

OperationBase<ConfigureChallengeResponse>.OtpSlot

OperationBase<ConfigureChallengeResponse>.Session

OperationBase<ConfigureChallengeResponse>.Version

OperationBase<ConfigureChallengeResponse>.Connection

OperationBase<ConfigureChallengeResponse>.Execute()

OperationBase<ConfigureChallengeResponse>.UseCurrentAccessCode(SlotAccessCode)

OperationBase<ConfigureChallengeResponse>.SetNewAccessCode(SlotAccessCode)

Remarks

This class is not to be instantiated by non-SDK code. Instead, you will get a reference to an instance of this class by calling ConfigureChallengeResponse(Slot).

Once you have a reference to an instance, the member methods of this class can be used to chain together configurations using a builder pattern.

Challenge-response mode needs to either have the UseHmacSha1ChallengeResponseMode(bool) or the UseYubicoOtpChallengeResponseMode(bool) setting selected.

Fields

HmacSha1KeySize

The key for an HMAC-SHA1 operation is 20 bytes.

public const int HmacSha1KeySize = 20

Field Value

int

YubiOtpKeySize

The key for a Yubico OTP operation is 16 bytes.

public const int YubiOtpKeySize = 16

Field Value

int

Methods

ExecuteOperation()

Execute the operation here.

protected override void ExecuteOperation()

Remarks

This method is called after pre-launch code has run. Everything that could be validated should have been before this method is called.

The only validation could that should be in this method are things that could not be checked in the PreLaunchOperation() method. For example, if an operation must be completed in multiple steps, and subsequent steps depend on the success of previous steps, then it must be in this method by necessity.

GenerateKey(Memory<byte>)

Generates a cryptographically random series of bytes as the key for the credential.

public ConfigureChallengeResponse GenerateKey(Memory<byte> key)

Parameters

key Memory<byte>

Returns

ConfigureChallengeResponse

The current ConfigureChallengeResponse instance.

Remarks

Generating a key is not compatible with setting an explicit byte collection as the key. Specifying both will result in an exception.

Exceptions

InvalidOperationException

This will be thrown if the caller called UseKey(ReadOnlyMemory<byte>) before calling this method.

PreLaunchOperation()

Validate all settings and choices here.

protected override void PreLaunchOperation()

Remarks

All possible validation should be done here. The point of this method is to simplify the ExecuteOperation() method that each operation must implement.

Conflicting choices that could not be checked by the OtpSettings<T> methods should be checked here.

Many of the operation classes use nullable fields (bool?) for choices. This allows the PreLaunchOperation() implementation to verify that a choice has been made. In the ExecuteOperation() method, the field has already been validated, and an exception thrown if it was not set, so null-forgiving operators are used when accessing those fields in ExecuteOperation().

SetAllowUpdate(bool)

Allows certain non-security related settings to be modified after the configuration has been written.

public ConfigureChallengeResponse SetAllowUpdate(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureChallengeResponse

The current ConfigureChallengeResponse instance.

Remarks

The list below is of all settings that can be updated when this setting is set. However, some of the options are not compatible with all settings, so it's important to use care when choosing settings to apply later.

• AllowUpdate(bool)
• SetDormant(bool)
  Allows a configuration to be stored without being accessible.
• UseFastTrigger(bool)
  Causes the trigger action of the YubiKey button to become faster.
• SetInvertLed(bool)
  Inverts the configured state of the LED.
• SetSerialNumberApiVisible(bool)
  Allows the serial number to be read by proprietary means, including being visible to the Yubico.YubiKey SDK.
• SetSerialNumberButtonVisible(bool)
  Allows the serial number to be retrieved by holding down the touch button while inserting the device into the USB port.
• SetSerialNumberUsbVisible(bool)
  Makes the serial number appear in the YubiKey's USB descriptor's iSerialNumber field.
• UseNumericKeypad(bool)
  Causes numeric characters to be sent as keystrokes from the numeric keypad rather than the normal numeric keys on an 84-key keyboard.
• SendTabFirst(bool)
  Sends a tab character before the fixed string.
• AppendTabToFixed(bool)
  Sends a tab character after the fixed string.
• SetAppendTabToOtp(bool)
  Sends a tab character after the OTP string.
• AppendDelayToFixed(bool)
  Adds a 500ms delay after sending the fixed string.
• AppendDelayToOtp(bool)
  Adds a 500ms delay after sending the OTP string.
• AppendCarriageReturn(bool)
  Sends a carriage return [Enter Key] after all characters have been sent.
• Use10msPacing(bool)
  Adds an inter-character pacing time of 10ms between each keystroke.
• Use20msPacing(bool)
  Adds an inter-character pacing time of 20ms between each keystroke.

UseButton(bool)

Require user acceptance by touching the YubiKey button for challenge-response operations

public ConfigureChallengeResponse UseButton(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureChallengeResponse

The current ConfigureChallengeResponse instance.

Remarks

This setting must be used with either UseYubicoOtpChallengeResponseMode(bool) or UseHmacSha1ChallengeResponseMode(bool).

UseHmacSha1()

Configures the challenge-response to use the HMAC-SHA1 algorithm.

public ConfigureChallengeResponse UseHmacSha1()

Returns

ConfigureChallengeResponse

The current ConfigureChallengeResponse instance.

Exceptions

InvalidOperationException

You must choose either Yubico OTP or HMAC-SHA1, but not both.

UseKey(ReadOnlyMemory<byte>)

Explicitly sets the key of the credential.

public ConfigureChallengeResponse UseKey(ReadOnlyMemory<byte> bytes)

Parameters

bytes ReadOnlyMemory<byte>

A collection of bytes to use for the key.

Returns

ConfigureChallengeResponse

The current ConfigureChallengeResponse instance.

Remarks

Setting an explicit key is not compatible with generating a key. Specifying both will result in an exception.

Exceptions

InvalidOperationException

This is thrown when GenerateKey(Memory<byte>) has been called before this.

UseSmallChallenge(bool)

Set when the HMAC challenge will be less than 64-bytes.

public ConfigureChallengeResponse UseSmallChallenge(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureChallengeResponse

The current ConfigureChallengeResponse instance.

Remarks

The traditional HMAC challenge is exactly 64-bytes. The YubiKey has a setting that indicates a key of less than 64 bytes.

Warning: It's important to choose this setting correctly. If you set this setting and submit a full 64-byte challenge to the YubiKey, then the last byte will be truncated, resulting in a different response.

This setting is only valid if configuring for an HMAC challenge. If you set this for a Yubico OTP challenge, an System.InvalidOperationException will be thrown when you call Execute().

UseYubiOtp()

Configures the challenge-response to use the Yubico OTP algorithm.

public ConfigureChallengeResponse UseYubiOtp()

Returns

ConfigureChallengeResponse

The current ConfigureChallengeResponse instance.

Exceptions

InvalidOperationException

You must choose either Yubico OTP or HMAC-SHA1, but not both.