Class ConfigureStaticPassword

Namespace

Yubico.YubiKey.Otp.Operations

Assembly

Yubico.YubiKey.dll

Operation class for configuring a YubiKey slot to send a static password, whether generated or specified.

public class ConfigureStaticPassword : OperationBase<ConfigureStaticPassword>

Inheritance

object

OperationBase<ConfigureStaticPassword>

ConfigureStaticPassword

Inherited Members

OperationBase<ConfigureStaticPassword>.CurrentAccessCode

OperationBase<ConfigureStaticPassword>.NewAccessCode

OperationBase<ConfigureStaticPassword>.OtpSlot

OperationBase<ConfigureStaticPassword>.Session

OperationBase<ConfigureStaticPassword>.Version

OperationBase<ConfigureStaticPassword>.Connection

OperationBase<ConfigureStaticPassword>.Execute()

OperationBase<ConfigureStaticPassword>.UseCurrentAccessCode(SlotAccessCode)

OperationBase<ConfigureStaticPassword>.SetNewAccessCode(SlotAccessCode)

Fields

AccessCodeLength

The length of an access code, which is exactly six bytes.

public const int AccessCodeLength = 6

Field Value

int

MaxPasswordLength

The maximum length for a YubiKey static password.

public const int MaxPasswordLength = 38

Field Value

int

Methods

AllowManualUpdate(bool)

Configures the slot to allow for user-triggered static password change.

public ConfigureStaticPassword AllowManualUpdate(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

Remarks

YubiKey 2 and later supports user-initiated update of a static password. If configured, the user presses and holds the key for 8-15 seconds. When the button is released, the indicator light flashes. By pressing shortly, the change is confirmed and the new OTP is yielded. The static ticket flag must be set before calling this method or an exception will occur.

AppendCarriageReturn(bool)

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

public ConfigureStaticPassword AppendCarriageReturn(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

AppendDelayToFixed(bool)

Adds a 500ms delay after sending the fixed string.

public ConfigureStaticPassword AppendDelayToFixed(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

AppendTabToFixed(bool)

Sends a tab character after the fixed string.

public ConfigureStaticPassword AppendTabToFixed(bool setConfig)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

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.

GeneratePassword(Memory<char>)

Instruct the API to generate a password for the YubiKey.

public ConfigureStaticPassword GeneratePassword(Memory<char> generatedPassword)

Parameters

generatedPassword Memory<char>

Memory reference to contain the generated password.

Returns

ConfigureStaticPassword

The ConfigureStaticPassword instance

Remarks

The generated password will be placed in generatedPassword. The length of the generated password is directly controlled by the length of the buffer supplied. The length of the password must be between 1 and MaxPasswordLength.

This API can generate passwords by calling this method, or it can use a specified password. These are mutually exclusive, so if you use both, an exception will occur.

Exceptions

InvalidOperationException

You cannot both generate and specify a static password.

ArgumentException

The static password must be between 1 and 38 characters.

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

SendTabFirst(bool)

Sends a tab character before the fixed string.

public ConfigureStaticPassword SendTabFirst(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

SetAllowUpdate(bool)

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

public ConfigureStaticPassword SetAllowUpdate(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

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.

SetPassword(ReadOnlyMemory<char>)

Set the static password the slot on the YubiKey should be configured with.

public ConfigureStaticPassword SetPassword(ReadOnlyMemory<char> password)

Parameters

password ReadOnlyMemory<char>

The static password to configure the YubiKey with.

Returns

ConfigureStaticPassword

The ConfigureStaticPassword instance

Remarks

This API can take explicit passwords set by this method, or it can generate a password. These are mutually exclusive options, so if you call both GeneratePassword(Memory<char>) and this method, an exception will happen.

Because this method needs to know which KeyboardLayout you're using before we can know if there are any invalid characters, this method will only check that if you have already specified the layout.

If you specify the password before you specify the KeyboardLayout, the when you set the layout, that operation will check the characters and throw an System.InvalidOperationException if there are invalid characters.

Exceptions

InvalidOperationException

You cannot both generate and specify a static password.

ArgumentException

Thrown if your password is too long or zero-length.

InvalidOperationException

Thrown if your password has characters that are not available in your selected KeyboardLayout.

Use10msPacing(bool)

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

public ConfigureStaticPassword Use10msPacing(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

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 ConfigureStaticPassword Use20msPacing(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

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 ConfigureStaticPassword UseFastTrigger(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

Remarks

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

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 ConfigureStaticPassword UseNumericKeypad(bool setConfig = true)

Parameters

setConfig bool

Returns

ConfigureStaticPassword

WithKeyboard(KeyboardLayout)

Set the KeyboardLayout to use.

public ConfigureStaticPassword WithKeyboard(KeyboardLayout keyboard)

Parameters

keyboard KeyboardLayout

The keyboard layout to use for the static password.

Returns

ConfigureStaticPassword

The ConfigureStaticPassword instance

Remarks

The YubiKey itself does not understand the concept of a keyboard layout. It only sends HID codes to the USB port. The keyboard layout is used at the operating system level to translate between the HID codes and actual characters.

For example, if you have an English, U.S. keyboard and press the [Y] button, an HID usage report with an ID of 0x1C is generated by your keyboard. This is converted by your operating system to whatever internal scheme it uses, then to the letter "Y".

However, if you program your key with a keyboard setting, but then someone uses the key on a system that has a German layout, the keyboard key that sends an HID usage ID of 0x1C is the [Z] key.

If you can be reasonably sure that your YubiKey will always be used on a system with the same keyboard layout, you can use this setting. However, Yubico's custom layout called ModHex is a reduced set that only includes mappings that are the same on most keyboard layouts.

Exceptions

InvalidOperationException

Thrown if your password has characters that are not available in your selected KeyboardLayout.