How to program a slot with an OATH HOTP credential

To configure a slot with an OATH HOTP credential, you will use a ConfigureHotp instance. It is instantiated by calling the factory method of the same name (ConfigureHotp()) on your OtpSession instance.

The properties of the HOTP credential you wish to set are specified by calling their respective methods on your ConfigureHotp instance.

ConfigureHotp example

Before running any of the code provided below, make sure you have already connected to a particular YubiKey on your host device via the YubiKeyDevice class.

To select the first available YubiKey connected to your host, use:

IEnumerable<IYubiKeyDevice> yubiKeyList = YubiKeyDevice.FindAll();

var yubiKey = yubiKeyList.First();

Configure a slot with a provided secret key or a randomly generated key

When calling ConfigureHotp(), you must either provide a secret key for the credential with UseKey() or generate one randomly with GenerateKey(). The keys must be equal to the length of HmacKeySize (20 bytes).

To configure the LongPress slot with an HOTP using a provided secret key ( which contains all 0s in this example), use:

using (OtpSession otp = new OtpSession(yubiKey))
{
    ReadOnlyMemory<byte> hmacKey = new byte[ConfigureHotp.HmacKeySize] {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, };

    otp.ConfigureHotp(Slot.LongPress)
       .UseKey(hmacKey)
       .Execute();
}    

To configure the LongPress slot with an HOTP using a randomly generated secret key, use:

using (OtpSession otp = new OtpSession(yubiKey))
{
    Memory<byte> hmacKey = new byte[ConfigureHotp.HmacKeySize];

    otp.ConfigureHotp(Slot.LongPress)
       .GenerateKey(hmacKey)
       .Execute();
}

The API does not own the object where secrets are stored. Therefore, you must still provide the place to put the generated information (which is hmacKey in this example). Once you have done what is needed with the data, clear the memory where it is located.

Set the initial moving factor and/or generate 8-digit HOTPs

You may optionally set the initial moving factor (the counter) with UseInitialMovingFactor(). If you do not call this method, the counter will be set to 0 by default.

Note

UseInitialMovingFactor() must be given an integer between 0 and 0xffff0 (1,048,560) that is divisible by 0x10 ( 16), otherwise an exception will be thrown.

ConfigureHotp() will configure a slot to generate 6-digit HOTPs by default. If you would like to generate 8-digit HOTPs, you must call Use8Digits() during configuration.

To set the initial moving factor to 16 and generate 8-digit HOTPs (with a randomly generated secret key), run the following:

using (OtpSession otp = new OtpSession(yubiKey))
{
    Memory<byte> hmacKey = new byte[ConfigureHotp.HmacKeySize];

    otp.ConfigureHotp(Slot.LongPress)
       .UseInitialMovingFactor(16)
       .GenerateKey(hmacKey)
       .Use8Digits()
       .Execute();
}

Slot reconfiguration and access codes

If a slot is protected by an access code and you wish to reconfigure it with an OATH HOTP credential, you must provide that access code with UseCurrentAccessCode() during the ConfigureHotp() operation. Otherwise, the operation will fail and throw the following exception:

System.InvalidOperationException has been thrown. YubiKey Operation Failed. [Warning, state of non-volatile memory is unchanged.]

For more information on slot access codes, please see How to set, reset, remove, and use slot access codes.

Additional settings

The following additional (optional) settings can be applied during configuration:

• AppendCarriageReturn()
• AppendDelayToFixed()
• AppendDelayToOtp()
• AppendTabToFixed()
• SendReferenceString()
• SendTabFirst()
• SetAllowUpdate()
• Use10msPacing()
• Use20msPacing()
• UseFastTrigger()
• UseNumericKeypad()

The OATH HOTP does not have a fixed part, but you can still use AppendDelayToFixed() and AppendTabToFixed(). These will simply add a delay or send a tab prior to the HOTP, respectively.

With the exception of SendReferenceString(), these settings can also be toggled after HOTP configuration by calling UpdateSlot().

Note

If you call SetAllowUpdate(false) during the inital configuration, you will not be able to update these settings with UpdateSlot() (the SDK will throw an exception). This can only be undone by reconfiguring the slot with ConfigureHotp(). It is not necessary to call SetAllowUpdate(true) during configuration because updates are allowed by default.