Table of Contents

Class OathSession

Namespace
Yubico.YubiKey.Oath
Assembly
Yubico.YubiKey.dll

The main entry-point for all OATH related operations.

public sealed class OathSession : ApplicationSession
Inheritance
object
OathSession
Inherited Members

Constructors

OathSession(IYubiKeyDevice, ScpKeyParameters?)

Create an instance of OathSession class, the object that represents the OATH application on the YubiKey.

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

Parameters

yubiKey IYubiKeyDevice

The object that represents the actual YubiKey which will perform the operations.

keyParameters ScpKeyParameters

If supplied, the parameters used open the SCP connection.

Remarks

Because this class implements IDisposable, use the using keyword. For example,

IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
using (var oath = new OathSession(yubiKeyToUse))
{
    /* Perform OATH operations. */
}

Exceptions

ArgumentNullException

The yubiKey argument is null.

InvalidOperationException

The SelectApplicationData received from the yubiKey is null.

Properties

IsPasswordProtected

Indicates whether the OATH application on the YubiKey is password-protected or not, whether password verification is required before operations can be executed.

public bool IsPasswordProtected { get; }

Property Value

bool

KeyCollector

The Delegate this class will call when it needs a password to unlock the OATH application.

public Func<KeyEntryData, bool>? KeyCollector { get; set; }

Property Value

Func<KeyEntryData, bool>

Remarks

The delegate provided will read the KeyEntryData which contains the information needed to determine what to collect and methods to submit what was collected. The delegate will return true for success or false for "cancel". A cancel will usually happen when the user has clicked a "Cancel" button.

Note that the SDK will call the KeyCollector with a Request of Release when the process completes. In this case, the KeyCollector MUST NOT throw an exception. The Release is called from inside a finally block, and it is a bad idea to throw exceptions from inside finally.

Methods

AddCredential(string)

Adds a credential from the string that received from the QR reader or manually from the server.

public Credential AddCredential(string stringFromURI)

Parameters

stringFromURI string

The string that received from the QR reader or manually from the server.

Returns

Credential

The Credential that was created and added to the YubiKey.

Remarks

This method parses an 'otpauth://' Uri string that received from the QR reader or manually from the server, as specified by https://github.com/google/google-authenticator/wiki/Key-Uri-Format

Exceptions

ArgumentNullException

Provided string is null, empty, or consists only of white-space characters.

InvalidOperationException

There is no KeyCollector loaded if the authentication is required, some credential properties are not supported on this YubiKey, the PutCommand failed, or the URI string is invalid or it contains invalid elements.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

AddCredential(string?, string, CredentialType, CredentialPeriod)

Adds a new credential or overwrites the existing one on the YubiKey with default parameters.

public Credential AddCredential(string? issuer, string account, CredentialType type = CredentialType.Totp, CredentialPeriod period = CredentialPeriod.Period30)

Parameters

issuer string

The issuer is an optional string indicating the provider or service.

account string

The account name that usually is the user's email address.

type CredentialType

Indicates the CredentialType of the credential as either HOTP or TOTP. The default value is TOTP.

period CredentialPeriod

Indicates the CredentialPeriod of the credential in seconds for TOTP code. It can only be 15, 30, or 60 seconds. For HOTP should be set to zero (Undefined). The default value is 30.

Returns

Credential

The Credential that was created and added to the YubiKey.

Remarks

If type and period properties are not modified, this will add a TOTP credential with default parameters like: Type - TOTP, Period - 30 seconds, Algorithm - SHA-1, Digits - 6, No secret, No touch.

Exceptions

InvalidOperationException

There is no KeyCollector loaded if the authentication is required, the PutCommand failed, or the provided account, type, or period is invalid.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

AddCredential(Credential)

Adds a new credential or overwrites the existing one on the YubiKey.

public void AddCredential(Credential credential)

Parameters

credential Credential

The Credential to add to the YubiKey.

Exceptions

ArgumentNullException

Provided credential is null.

InvalidOperationException

There is no KeyCollector loaded if the authentication is required, some credential properties are not supported on this YubiKey, or the PutCommand failed.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

CalculateAllCredentials(ResponseFormat)

Gets OTP (One-Time Password) values for all configured credentials on the YubiKey.

public IDictionary<Credential, Code> CalculateAllCredentials(ResponseFormat responseFormat = ResponseFormat.Truncated)

Parameters

responseFormat ResponseFormat

Full or truncated ResponseFormat to receive back. The default value is Truncated.

Returns

IDictionary<Credential, Code>

The dictionary of Credential and Code pairs.

Remarks

CalculateAllCredentialsCommand doesn't return a Code for HOTP credentials and credentials requiring touch. They will need to be calculated separately using CalculateCredentialCommand.

Exceptions

InvalidOperationException

There is no KeyCollector loaded if the authentication is required, the CalculateAllCredentialsCommand failed, or the CalculateCredentialCommand failed.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

CalculateCredential(string?, string, CredentialType, CredentialPeriod, ResponseFormat)

Gets an OTP code for the specific credential.

public Code CalculateCredential(string? issuer, string account, CredentialType type, CredentialPeriod period, ResponseFormat responseFormat = ResponseFormat.Truncated)

Parameters

issuer string

The issuer is an optional string indicating the provider or service.

account string

The account name that usually is the user's email address.

type CredentialType

Indicates the CredentialType of the credential as either HOTP or TOTP.

period CredentialPeriod

Indicates the CredentialPeriod of the credential in seconds for TOTP code. It can only be 15, 30, or 60 seconds. For HOTP should be set to zero (Undefined).

responseFormat ResponseFormat

Full or truncated ResponseFormat to receive back. The default value is Truncated.

Returns

Code

The Code for the requested credential.

Exceptions

InvalidOperationException

There is no KeyCollector loaded if the authentication is required, the CalculateCredentialCommand failed, or the provided account, type, or period is invalid.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

CalculateCredential(Credential, ResponseFormat)

Gets an OTP (One-Time Password) value for the specific credential on the YubiKey.

public Code CalculateCredential(Credential credential, ResponseFormat responseFormat = ResponseFormat.Truncated)

Parameters

credential Credential

The Credential on the YubiKey to calculate.

responseFormat ResponseFormat

Full or truncated ResponseFormat to receive back. The default value is Truncated.

Returns

Code

The Code for the requested credential.

Exceptions

ArgumentNullException

Provided credential is null.

InvalidOperationException

There is no KeyCollector loaded if the authentication is required or the CalculateCredentialCommand failed.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

Dispose(bool) 

protected override void Dispose(bool disposing)

Parameters

disposing bool

GetCredentials()

Gets all configured credentials on the YubiKey.

public IList<Credential> GetCredentials()

Returns

IList<Credential>

The list of credentials.

Exceptions

InvalidOperationException

There is no KeyCollector loaded if the authentication is required or the ListCommand failed.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

RemoveCredential(string?, string, CredentialType, CredentialPeriod)

Removes an existing credential from the YubiKey.

public Credential RemoveCredential(string? issuer, string account, CredentialType type = CredentialType.Totp, CredentialPeriod period = CredentialPeriod.Period30)

Parameters

issuer string

The issuer is an optional string indicating the provider or service.

account string

The account name that usually is the user's email address.

type CredentialType

Indicates the CredentialType of the credential as either HOTP or TOTP. The default value is TOTP.

period CredentialPeriod

Indicates the CredentialPeriod of the credential in seconds for TOTP code. It can only be 15, 30, or 60 seconds. For HOTP should be set to zero (Undefined). The default value is 30.

Returns

Credential

The Credential that was removed from the YubiKey.

Exceptions

InvalidOperationException

There is no KeyCollector loaded if the authentication is required, the DeleteCommand failed, or the provided account, type, or period is invalid.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

RemoveCredential(Credential)

Removes an existing credential from the YubiKey.

public void RemoveCredential(Credential credential)

Parameters

credential Credential

The Credential to remove from the YubiKey.

Exceptions

ArgumentNullException

Provided credential is null.

InvalidOperationException

There is no KeyCollector loaded if the authentication is required or the DeleteCommand failed.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

RenameCredential(string?, string, string?, string, CredentialType, CredentialPeriod)

Renames an existing credential on the YubiKey by setting new issuer and account names.

public Credential RenameCredential(string? currentIssuer, string currentAccount, string? newIssuer, string newAccount, CredentialType currentType = CredentialType.Totp, CredentialPeriod currentPeriod = CredentialPeriod.Period30)

Parameters

currentIssuer string

The current credential's issuer.

currentAccount string

The current credential's account name.

newIssuer string

The new issuer to set on the credential. The issuer is optional and can be null.

newAccount string

The new account name to set on the credential.

currentType CredentialType

Indicates the CredentialType of the current credential as either HOTP or TOTP. The default value is TOTP.

currentPeriod CredentialPeriod

Indicates the CredentialPeriod of the current credential in seconds for TOTP code. It can only be 15, 30, or 60 seconds. For HOTP should be set to zero (Undefined). The default value is 30.

Returns

Credential

Remarks

This command is only available on the YubiKeys with firmware version 5.3.0 and later.

Exceptions

InvalidOperationException

There is no KeyCollector loaded if the authentication is required, the RenameCommand is not supported on this YubiKey, the RenameCommand failed, or the provided current or new account, type, or period is invalid.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

RenameCredential(Credential, string?, string)

Renames an existing credential on the YubiKey by setting new issuer and account names.

public void RenameCredential(Credential credential, string? newIssuer, string newAccount)

Parameters

credential Credential

The Credential to rename.

newIssuer string

The new issuer to set on the credential. The issuer is optional and can be null.

newAccount string

The new account name to set on the credential.

Remarks

This command is only available on the YubiKeys with firmware version 5.3.0 and later.

Exceptions

ArgumentNullException

The credential to rename is null. Or the new account name to set is null, empty, or consists only of white-space characters.

InvalidOperationException

There is no KeyCollector loaded if the authentication is required, the RenameCommand is not supported on this YubiKey, or the RenameCommand failed.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or an incorrect password was provided if authentication is required.

ResetApplication()

Resets the YubiKey's OATH application back to a factory default state.

public void ResetApplication()

Remarks

This will remove the password if one set and delete all credentials stored on the YubiKey.

Exceptions

InvalidOperationException

The ResetCommand failed.

SetPassword()

Sets the password.

public void SetPassword()

Remarks

If the authentication was previously configured on the YubiKey, this method will prompt for the current password to verify, as well as a new password to change to using the KeyCollector callback. If the authentication is not configured, this method will collect only a new password to set. In this case, the challenge supplied from the YubiKey will be an empty byte array meaning no password was set yet. The password can be any string of bytes, however most applications will choose to encode a user supplied string using UTF-8. Next, 1,000 rounds of PBKDF2 are applied with a salt supplied by the YubiKey, ensuring an extra level of security against brute force attacks.

Exceptions

InvalidOperationException

There is no KeyCollector loaded, the new password to set is incorrect, or the SetPasswordCommand failed.

OperationCanceledException

The user canceled password collection.

SecurityException

Unable to verify password because the incorrect current password was provided.

TrySetPassword(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>)

Verify the currentPassword in order to set the OATH application in the YubiKey to be password-protected with the given newPassword.

public bool TrySetPassword(ReadOnlyMemory<byte> currentPassword, ReadOnlyMemory<byte> newPassword)

Parameters

currentPassword ReadOnlyMemory<byte>

If the OATH application is already password-protected, then this is the current password. If it is not password-protected, you must pass in an Empty value.

newPassword ReadOnlyMemory<byte>

The password to which the OATH application will be set.

Returns

bool

A boolean, true if the OATH application is set to the given password, and false otherwise.

Remarks

If the OATH application on the YubiKey is not yet password-protected, you should pass in an Empty currentPassword argument. If you pass in an actual password, this method will try to verify it, which will fail, the method will return false, and the application will not be set with the newPassword.

If the OATH application is already password-protected, the current password must be verified before setting. Hence, this method will verify the currentPassword. Once that password has been verified, this method will be able to set the OATH application on the YubiKey with the newPassword. This is how the password is changed. If the currentPassword does not verify, then this method will return false.

To see if the OATH application is password-protected or not, look at the property IsPasswordProtected.

For example, 

bool isSetToNewPassword = false;
if (oathSession.IsPasswordProtected)
{
    // The OATH application is set to password-Protected,
    // this call will change it to a new password.
    isSetToNewPassword = oathSession.TrySetPassword(currentPassword, newPassword);
}
else
{
    // The OATH application is not yet password-protected,
    // this call will set it to be so.
    isSetToNewPassword =
        oathSession.TrySetPassword(ReadOnlyMemory<byte>.Empty, newPassword);
}

Note that if the OATH application is password-protected, and the password has already been verified, it is still necessary to pass in the current password. For example, 

if (!oathSession.TryVerifyPassword(currentPassword))
{
    // Some error handling code, maybe exit.
}
  . . . // Some other code, more operations
bool isSetToNewPassword = oathSession.TrySetPassword(currentPassword, newPassword);
If the password has already been verified in the session, and an Empty currentPassword is passed in, this method will return false. If the wrong password is passed in, this method will try to verify it, which will fail, the method will return false, and the application will not be set with the newPassword, even though the current password had been verified in the session previously.

Note also that the only way to get a false return is if the currentPassword does not verify.

Exceptions

InvalidOperationException

The YubiKey had some error, such as unreliable connection.

TryUnsetPassword(ReadOnlyMemory<byte>)

Try to set the OATH application in the YubiKey to no longer be password-protected. This operation requires verifying the current password provided.

public bool TryUnsetPassword(ReadOnlyMemory<byte> password)

Parameters

password ReadOnlyMemory<byte>

If the OATH application is already password-protected, then this is the current password.

Returns

bool

A boolean, true if the OATH application is unset, and false otherwise.

Remarks

If the OATH application is password-protected, the current password must be verified before unsetting. Hence, this method will verify the password. Once that password has been verified, this method will be able to set the OATH application on the YubiKey to no longer be password-protected. If the password does not verify, then this method will return false.

If the OATH application on the YubiKey is not yet password-protected, this method will ignore the password argument, do nothing, and return true.

To see if the OATH application is password-protected or not, look at the property IsPasswordProtected.

For example, 

if (oathSession.IsPasswordProtected)
{
    // The OATH application is set to password-Protected,
    // this call will change it to no longer password-protected
    bool isUnset = oathSession.TryUnsetPassword(currentPassword);
}

Note that if the OATH application is password-protected, and the password has already been verified, then it is not necessary to pass in the current password. For example, 

if (oathSession.TryVerifyPassword(currentPassword)
{
    bool isUnset =
        oathSession.TryUnsetPassword(ReadOnlyMemory<byte>.Empty);
}
If the password has already been verified in the session, this method will not try to verify the password. That is, the password can be the wrong value or Empty, and if the password has already been verified, this method will succeed.

Note also that the only way to get a false return is if the OATH application is password-protected, the password has not yet been verified in the session, and the provided password is Empty or does not verify.

Exceptions

InvalidOperationException

The YubiKey had some error, such as unreliable connection.

TryVerifyPassword()

Attempts to verify the password.

public bool TryVerifyPassword()

Returns

bool

Remarks

Performs mutual authentication with the YubiKey using the password collected by the key collector. You need to verify the password only once per session if the authentication is configured for the OATH application on the YubiKey.

Exceptions

InvalidOperationException

There is no KeyCollector loaded.

TryVerifyPassword(ReadOnlyMemory<byte>)

Try to verify using the given password.

public bool TryVerifyPassword(ReadOnlyMemory<byte> password)

Parameters

password ReadOnlyMemory<byte>

The password to verify.

Returns

bool

A boolean, true if the password verifies, and false otherwise.

Remarks

Perform mutual authentication with the YubiKey using the password given. You need to verify the password only once per session if authentication is enabled for the OATH application on the YubiKey.

If the OATH application is not password-protected (IsPasswordProtected is false), the given password obviously does not verify, so the method will return false.

If the password has already been verified during this session, this method will try to verify it again. If it fails, the return will be false, but the session will still be verified and it will still be able to perform operations.

Exceptions

InvalidOperationException

The YubiKey had some error, such as unreliable connection.

UnsetPassword()

Unsets the password.

public void UnsetPassword()

Remarks

Removes the authentication.

Exceptions

InvalidOperationException

There is no KeyCollector loaded. Or the SetPasswordCommand failed.

OperationCanceledException

The user canceled password collection.

SecurityException

Unable to verify password either because the authentication is not enabled on the YubiKey or the incorrect password was provided.

VerifyPassword()

Verify the password, throw an exception if the user cancels or the verification failed.

public void VerifyPassword()

Remarks

This is the same as TryVerifyPassword, except this method will throw an exception if the KeyCollector indicates user cancellation or the verification failed due to the authentication is not enabled for the YubiKey or the incorrect password was provided.

See the TryVerifyPassword() method for further documentation on this method.

Exceptions

InvalidOperationException

There is no KeyCollector loaded.

SecurityException

Unable to verify password either because KeyCollector was canceled by the user or the authentication is not enabled on the YubiKey or the incorrect password was provided.