Table of Contents

Class CalculateChallengeResponse

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

Operation class for sending an HMAC-SHA1, TOTP, or Yubico OTP challenge to an OTP application slot on a YubiKey and receiving its response.

public class CalculateChallengeResponse : OperationBase<CalculateChallengeResponse>
Inheritance
object
CalculateChallengeResponse
Inherited Members

Fields

MaxHmacChallengeSize

Maximum length in bytes for an HMAC challenge.

public const int MaxHmacChallengeSize = 64

Field Value

int

MaxOtpDigits

Maximum digits for an OTP (one-time password).

public const int MaxOtpDigits = 10

Field Value

int

MinOtpDigits

Minimum digits for an OTP (one-time password).

public const int MinOtpDigits = 6

Field Value

int

YubicoOtpChallengeSize

Size in bytes for a Yubico OTP challenge.

public const int YubicoOtpChallengeSize = 6

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.

GetCode(int)

Get the OTP code as a string representation of numeric digits.

public string GetCode(int digits = 6)

Parameters

digits int

The number of digits in the string (default is 6).

Returns

string

A string representation of the OTP.

GetDataBytes()

Get the raw bytes for the OTP (one-time password).

public ReadOnlyMemory<byte> GetDataBytes()

Returns

ReadOnlyMemory<byte>

System.ReadOnlyMemory<T> collection of bytes.

GetDataInt()

Get the OTP (one-time password) as an int.

public int GetDataInt()

Returns

int

Single int representing the OTP.

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

UseChallenge(byte[])

Accepts the challenge phrase as a byte array.

public CalculateChallengeResponse UseChallenge(byte[] challenge)

Parameters

challenge byte[]

A byte array.

Returns

CalculateChallengeResponse

The CalculateChallengeResponse instance

UseTotp()

Instructs the operation to use TOTP instead of a byte array for the challenge.

public CalculateChallengeResponse UseTotp()

Returns

CalculateChallengeResponse

The CalculateChallengeResponse instance

Remarks

UseYubiOtp(false) must be called along with UseTotp() in order for the YubiKey to calculate the response code using the HMAC-SHA1 algorithm.

UseTouchNotifier(Action)

Set an System.Action delegate to notify users to touch the YubiKey button.

public CalculateChallengeResponse UseTouchNotifier(Action notifier)

Parameters

notifier Action

System.Action delegate.

Returns

CalculateChallengeResponse

The CalculateChallengeResponse instance

Examples

Here is a very simple example of performing a challenge-response operation on a YubiKey.

using (var otpSess = new OtpSession(_yubiKey))
{
    string otp = otp.CalculateChallengeResponse(_slot)
        .UseTouchNotifier(() => Console.WriteLine("Press the YubiKey button."))
        .UseTotp()
        .GetCode();
}

As mentioned in the remarks section, showing a prompt in a GUI application requires a little bit more work. Here is an example of calling a notifier method.

using (var otpSess = new OtpSession(_yubiKey))
{
    string otp = otpSess.CalculateChallengeResponse(_slot)
        .UseTouchNotifier(() => _appWindow.AlertUser())
        .UseTotp()
        .GetCode();
    _appWindow.SetOtpCode(otp);
}

Here is how the notifier would handle making sure the notification is handled on the correct thread.

public void AlertUser()
{
    if (!Dispatcher.CheckAccess())
    {
        Dispatcher.Invoke(() => AlertUser());
    }
    MessageBox.Show(this, "Press the YubiKey button.");
}

Remarks

This delegate will be launched as a System.Threading.Tasks.Task. The SDK will not wait or otherwise track the completion of the delegate. It is meant as a simple notifier.

It is important to take into consideration that it will execute on an unknown thread, so if you are using it to do a notification on a graphical user interface, then you should be sure that you marshall the call to the appropriate thread.

UseYubiOtp(bool)

Sets the operation to use the Yubico OTP or HMAC-SHA1 algorithm to calculate the response.

public CalculateChallengeResponse UseYubiOtp(bool setting)

Parameters

setting bool

A bool specifying whether to use the Yubico OTP or HMAC-SHA1 algorithm.

Returns

CalculateChallengeResponse

The CalculateChallengeResponse instance

Remarks

There is no default algorithm. You must either call this method with a true parameter, which will configure the YubiKey to use Yubico OTP as the algorithm, or a false parameter, which will configure the YubiKey to use the HMAC-SHA1 algorithm (for both HMAC-SHA1 and TOTP challenges).

WithPeriod(int)

Sets the time period in seconds that a TOTP challenge is good for.

public CalculateChallengeResponse WithPeriod(int seconds)

Parameters

seconds int

Time resolution in seconds for the challenge.

Returns

CalculateChallengeResponse

The CalculateChallengeResponse instance