Class ConfigureYubicoOtp

Namespace

Yubico.YubiKey.Otp.Operations

Assembly

Yubico.YubiKey.dll

Configures a YubiKey's OTP slot to perform OTP using the Yubico OTP protocol.

public class ConfigureYubicoOtp : OperationBase<ConfigureYubicoOtp>

Inheritance

object

OperationBase<ConfigureYubicoOtp>

ConfigureYubicoOtp

Inherited Members

OperationBase<ConfigureYubicoOtp>.CurrentAccessCode

OperationBase<ConfigureYubicoOtp>.NewAccessCode

OperationBase<ConfigureYubicoOtp>.OtpSlot

OperationBase<ConfigureYubicoOtp>.Session

OperationBase<ConfigureYubicoOtp>.Version

OperationBase<ConfigureYubicoOtp>.Connection

OperationBase<ConfigureYubicoOtp>.Execute()

OperationBase<ConfigureYubicoOtp>.UseCurrentAccessCode(SlotAccessCode)

OperationBase<ConfigureYubicoOtp>.SetNewAccessCode(SlotAccessCode)

Remarks

Once configured, pressing the button on the YubiKey will cause it to emit the standard Yubico OTP challenge string.

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 ConfigureYubicoOtp(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.

Fields

KeySize

The key size of the Yubico OTP credential.

public const int KeySize = 16

Field Value

int

PrivateIdentifierSize

The count of bytes used as the private identifier for the Yubico OTP credential.

public const int PrivateIdentifierSize = 6

Field Value

int

PublicIdentifierMaxLength

The count of bytes that are prepended to the Yubico OTP challenge.

public const int PublicIdentifierMaxLength = 16

Field Value

int

Methods

AppendCarriageReturn(bool)

Sends a carriage return [Enter Key] after all characters have been sent.

public ConfigureYubicoOtp AppendCarriageReturn(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

AppendDelayToFixed(bool)

Adds a 500ms delay after sending the fixed string.

public ConfigureYubicoOtp AppendDelayToFixed(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

AppendDelayToOtp(bool)

Adds a 500ms delay after sending the OTP string.

public ConfigureYubicoOtp AppendDelayToOtp(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

AppendTabToFixed(bool)

Sends a tab character after the fixed string.

public ConfigureYubicoOtp AppendTabToFixed(bool setConfig)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

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 Yubico OTP credential.

public ConfigureYubicoOtp GenerateKey(Memory<byte> key)

Parameters

key Memory<byte>

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp 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(Memory<byte>) before calling this method.

GeneratePrivateId(Memory<byte>)

Generates a cryptographically random series of bytes as the private ID for the Yubico OTP credential.

public ConfigureYubicoOtp GeneratePrivateId(Memory<byte> privateId)

Parameters

privateId Memory<byte>

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

Remarks

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

Exceptions

InvalidOperationException

This will be thrown if the caller called UsePrivateId(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().

SendReferenceString(bool)

Sends a reference string of the ModHex characters for 0-15 before the fixed or OTP data.

public ConfigureYubicoOtp SendReferenceString(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

Remarks

This can be used by the verifying application to verify the mapping of the modhex characters.

For all YubiKeys with a firmware version of 2.0 or later, if set in combination with UseAlphaNumericPassword(bool), this string will be replaced with a shifted character '1' (typically '!' on most keyboard layouts). This can be used to meet strong password requirements where at least one character is required to be a "special character".

SendTabFirst(bool)

Sends a tab character before the fixed string.

public ConfigureYubicoOtp SendTabFirst(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

SetAllowUpdate(bool)

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

public ConfigureYubicoOtp SetAllowUpdate(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp 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.

Use10msPacing(bool)

Adds an inter-character pacing time of 10ms between each keystroke.

public ConfigureYubicoOtp Use10msPacing(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

Remarks

This setting is not compatible with UseYubicoOtpChallengeResponseMode(bool) nor UseHmacSha1ChallengeResponseMode(bool).

Use20msPacing(bool)

Adds an inter-character pacing time of 20ms between each keystroke.

public ConfigureYubicoOtp Use20msPacing(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

Remarks

This setting is not compatible with UseYubicoOtpChallengeResponseMode(bool) nor UseHmacSha1ChallengeResponseMode(bool).

UseFastTrigger(bool)

Causes the trigger action of the YubiKey button to become faster.

public ConfigureYubicoOtp UseFastTrigger(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

Remarks

This only applies when one configuration is written. If both configurations are active, this setting has no effect.

UseKey(Memory<byte>)

Explicitly sets the key of the Yubico OTP credential.

public ConfigureYubicoOtp UseKey(Memory<byte> key)

Parameters

key Memory<byte>

A collection of bytes to use for the key.

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp 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.

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.

public ConfigureYubicoOtp UseNumericKeypad(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

UsePrivateId(ReadOnlyMemory<byte>)

Explicitly sets the private ID of the Yubico OTP credential.

public ConfigureYubicoOtp UsePrivateId(ReadOnlyMemory<byte> privateId)

Parameters

privateId ReadOnlyMemory<byte>

A collection of bytes to use for the private ID.

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

Remarks

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

Exceptions

ArgumentException

This is thrown when the byte collection is not the appropriate size.

InvalidOperationException

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

UsePublicId(ReadOnlyMemory<byte>)

Explicitly sets the public ID of the Yubico OTP credential.

public ConfigureYubicoOtp UsePublicId(ReadOnlyMemory<byte> publicId)

Parameters

publicId ReadOnlyMemory<byte>

A collection of bytes to use for the public ID.

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

Remarks

The Yubico OTP online service requires the public ID to begin with 0xff (or "vv" in ModHex). If the credential will be uploaded, you must validate this or it will fail.

Setting an explicit public ID is not compatible with using the YubiKey serial number as the public ID. Specifying both will result in an exception.

Exceptions

ArgumentException

This is thrown when the byte collection is not the appropriate size.

InvalidOperationException

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

AggregateException

This is thrown when multiple exceptions have been encountered.

UseSerialNumberAsPublicId(Memory<byte>?)

Uses a binary representation of the YubiKey serial number as the public ID for this credential.

public ConfigureYubicoOtp UseSerialNumberAsPublicId(Memory<byte>? publicId = null)

Parameters

publicId Memory<byte>?

A System.Memory<T> object to receive the public ID. This object must be exactly six bytes.

Returns

ConfigureYubicoOtp

The current ConfigureYubicoOtp instance.

Remarks

Using the YubiKey serial number is not compatible with setting an explicit byte collection as the public ID. Specifying both will result in an exception.

If you do not need to receive the public ID that was generated from the serial number, you can either pass null or simply nothing.

Exceptions

InvalidOperationException

This will be thrown either if the caller called UsePublicId(ReadOnlyMemory<byte>) before calling this method, or if the serial number is not readable on the YubiKey.