Table of Contents

Class OtpSession

Namespace
Yubico.YubiKey.Otp
Assembly
Yubico.YubiKey.dll

Entry point for all high-level OTP operations.

public sealed class OtpSession : ApplicationSession, IOtpSession
Inheritance
object
OtpSession
Implements
Inherited Members

Examples

This is an example of using the fluent builder pattern to configure a YubiKey OTP slot to emit a static password.

ReadOnlyMemory<char> password = "Shhhh!Don'tTell!".ToCharArray();
using (OtpSession otp = new OtpSession(yubiKey))
{
    otp.ConfigureStaticPassword(Slot.ShortPress)
        .SetPassword(password)
        .WithKeyboard(KeyboardLayout.en_US)
        .AppendCarriageReturn()
        .Execute();
};

The method, ConfigureStaticPassword(Slot), instantiates an instance of the class ConfigureStaticPassword. The next line configures the operation with the password to set. The next line configures the keyboard layout. The next line configures the operation to tell the YubiKey to send a carriage-return after sending the password, and finally, Execute() tells the operation class to perform the configuration on the YubiKey.

Remarks

Most methods will return a reference to the operation class that performs the operation being executed. Then, methods on that class that configure the operation also return the same reference. This is known as a fluent builder pattern. This allows operations to be built by stringing together configuration methods. The operation is usually concluded with a call to a method named Execute().

Methods in this class that instantiate classes that support the fluent builder pattern are any that return a class reference. Methods that return void do not require additional configuration to perform their operations. See the example section below for more details.

Constructors

OtpSession(IYubiKeyDevice, ScpKeyParameters?)

Constructs a OtpSession instance for high-level OTP operations.

public OtpSession(IYubiKeyDevice yubiKey, ScpKeyParameters? keyParameters = null)

Parameters

yubiKey IYubiKeyDevice

An instance of a class that implements IYubiKeyDevice.

keyParameters ScpKeyParameters

An instance of Scp03KeyParameters containing the parameters for the SCP03 key. If null, the default parameters will be used.

Remarks

This constructor should be used to obtain an instance of this class for performing operations on the YubiKey OTP application. The instance of IYubiKeyDevice passed in should be a connected YubiKey.

Properties

IsLongPressConfigured

Indicates that the long-press configuration (slot 2) is present and valid.

public bool IsLongPressConfigured { get; }

Property Value

bool

IsShortPressConfigured

Indicates that the short-press configuration (slot 1) is present and valid.

public bool IsShortPressConfigured { get; }

Property Value

bool

LongPressRequiresTouch

Indicates that the long-press configuration (slot 2) requires touch for operation.

public bool LongPressRequiresTouch { get; }

Property Value

bool

ShortPressRequiresTouch

Indicates that the short-press configuration (slot 1) requires touch for operation.

public bool ShortPressRequiresTouch { get; }

Property Value

bool

Methods

CalculateChallengeResponse(Slot)

Submits a challenge to the YubiKey OTP application to be calculated.

public CalculateChallengeResponse CalculateChallengeResponse(Slot slot)

Parameters

slot Slot

The identifier for the OTP application slot to configure.

Returns

CalculateChallengeResponse

An instance of CalculateChallengeResponse.

ConfigureChallengeResponse(Slot)

Configures one of the OTP application slots to respond to challenges.

public ConfigureChallengeResponse ConfigureChallengeResponse(Slot slot)

Parameters

slot Slot

The identifier for the OTP application slot to configure.

Returns

ConfigureChallengeResponse

Instance of ConfigureChallengeResponse.

ConfigureHotp(Slot)

Configures a YubiKey OTP slot to emit sequence-based OTP codes.

public ConfigureHotp ConfigureHotp(Slot slot)

Parameters

slot Slot

OTP Slot to configure.

Returns

ConfigureHotp

ConfigureNdef(Slot)

Configures a YubiKey's NDEF slot for text or URI.

public ConfigureNdef ConfigureNdef(Slot slot)

Parameters

slot Slot

OTP Slot to configure.

Returns

ConfigureNdef

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

ConfigureStaticPassword(Slot)

Sets a static password for an OTP application slot on a YubiKey.

public ConfigureStaticPassword ConfigureStaticPassword(Slot slot)

Parameters

slot Slot

The identifier for the OTP application slot to configure.

Returns

ConfigureStaticPassword

Instance of ConfigureStaticPassword.

Remarks

This method returns a ConfigureStaticPassword instance. This instance exposes methods to set the parameters for the static password you intend to set. Each of those parameters returns a reference to the ConfigureStaticPassword instance so they can be chained together. Once all the parameters are set, the last call should be to the Execute() method.

ConfigureYubicoOtp(Slot)

Configures one of the OTP application slots to act as a Yubico OTP device.

public ConfigureYubicoOtp ConfigureYubicoOtp(Slot slot)

Parameters

slot Slot

The identifier for the OTP application slot to configure.

Returns

ConfigureYubicoOtp

Instance of ConfigureYubicoOtp.

DeleteSlot(Slot)

Removes an OTP slot configuration and sets it to empty.

public void DeleteSlot(Slot slot)

Parameters

slot Slot

The Slot to reset to empty.

Remarks

Use this method if there is not access code set on the slot. If you need to specify an access code, use the builder version (DeleteSlotConfiguration(Slot)), which exposes UseCurrentAccessCode(SlotAccessCode).

DeleteSlotConfiguration(Slot)

Removes a slot configuration in the YubiKey's OTP application.

public DeleteSlotConfiguration DeleteSlotConfiguration(Slot slot)

Parameters

slot Slot

The identifier for the OTP application slot configuration to delete.

Returns

DeleteSlotConfiguration

An instance of DeleteSlotConfiguration.

ReadNdefTag()

Reads the OTP programmed in the short-press slot using the NFC Data-Exchange Format (NDEF) tag from NFC enabled YubiKeys. (Requires the YubiKey be connected via NFC).

public NdefDataReader ReadNdefTag()

Returns

NdefDataReader

An NdefDataReader instance that can interpret the NDEF data in the form that best suits your needs.

Remarks

YubiKeys like the NEO and the 5-NFC series supports Near-Field Communication (NFC). NFC is a method in which the YubiKey can draw power from and communicate with another device over very short distances. This device can be a mobile phone, or a dedicated NFC smart card reader. The distances in which the YubiKey can operate depend on the signal strength provided by the reader, but is typically 1-3 centimeters.

For most YubiKey operations, the behavior will be the same over NFC as would be seen over USB. One significant difference, however, is reading content out of the "touch-enabled" configuration slots that the OTP application is built around. Devices like a smart phone will often automatically read the contents out of an NDEF tag. This allows the YubiKey to emulate the touch experience over NFC, at least when smart phones are involved.

Typically, desktop NFC readers do not automatically read NDEF tag contents. Therefore, a mechanism to programmatically read NDEF tags is required to achieve full feature parity with USB and NFC enabled smart phones. This method allows you to read the contents of an NDEF tag. Since the NDEF "slot" can contain either a URI or a text blob, an NdefDataReader instance is returned. This class allows you to read the NDEF data and interpret in a form that is the most appropriate for your application's needs.

Note: This method modifies the underlying connection to the YubiKey that the session uses. If an exception is thrown from this method, it is not guaranteed that the session will still be connected to the YubiKey. In that case, a new session will need to be established.

Exceptions

NotSupportedException

Thrown when this method is called on a YubiKey that is not connected via NFC.

InvalidOperationException

Thrown when the YubiKey could not select the NDEF file ID.

SwapSlots()

Swaps the configurations in the short and long press slots.

public void SwapSlots()

Remarks

If either of the two slots is protected with an access code, this command will fail. In order to swap slot configurations, you will need to remove the access codes in a separate operation. After the swap, you can reapply the access codes, also in a separate operation.

Exceptions

InvalidOperationException

The SwapSlotsCommand failed or is not supported on this YubiKey.

UpdateSlot(Slot)

Updates the settings of an OTP application slot on a YubiKey without removing the existing configuration.

public UpdateSlot UpdateSlot(Slot slot)

Parameters

slot Slot

The identifier for the OTP application slot to configure.

Returns

UpdateSlot

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.