Table of Contents

Class Credential

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

Represents a single OATH credential.

public class Credential
Inheritance
object
Credential

Remarks

The credential can be a TOTP (Time-based One-time Password) or a HOTP (HMAC-based One-time Password).

Constructors

Credential()

Constructs an instance of the Credential class.

public Credential()

Credential(string?, string, CredentialPeriod, CredentialType, HashAlgorithm)

Constructs an instance of the Credential class for List Command.

public Credential(string? issuer, string account, CredentialPeriod period, CredentialType type, HashAlgorithm algorithm)

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.

period CredentialPeriod

The credential period.

type CredentialType

The credential type, TOTP or HOTP.

algorithm HashAlgorithm

The types of hash algorithm.

Credential(string?, string, CredentialType, CredentialPeriod)

Constructs an instance of the Credential class for CalculateAllCommand.

public Credential(string? issuer, string account, CredentialType type, CredentialPeriod period)

Parameters

issuer string

An optional string indicating the provider or service.

account string

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

type CredentialType

The credential type, TOTP or HOTP.

period CredentialPeriod

The credential period.

Credential(string?, string, CredentialType, HashAlgorithm, string, CredentialPeriod, int, int?, bool)

Constructs an instance of the Credential class for PutCommand.

public Credential(string? issuer, string account, CredentialType type, HashAlgorithm algorithm, string secret, CredentialPeriod period, int digits, int? counter, bool requireTouch)

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

The credential type, TOTP or HOTP.

algorithm HashAlgorithm

The type of hash algorithm.

secret string

An arbitrary value.

period CredentialPeriod

The credential period.

digits int

The number of digits in a one-time password.

counter int?

The counter is required when the credential type is HOTP. For TOTP it's 0.

requireTouch bool

The credential requires the user to touch the key to generate a one-time password.

Properties

AccountName

The account name, which is typically the user's email address.

public string? AccountName { get; set; }

Property Value

string

Exceptions

InvalidOperationException

The value is null, empty, or consists only of white-space characters.

Algorithm

The hash algorithm used by the credential.

public HashAlgorithm? Algorithm { get; set; }

Property Value

HashAlgorithm?

Exceptions

InvalidOperationException

The value is invalid.

Counter

Counter value for HOTP.

public int? Counter { get; set; }

Property Value

int?

Remarks

The counter parameter is required when the type is HOTP. It will set the initial counter value. This property returns null if the credential type is TOTP. The server and user calculate the OTP by applying a hashing and truncating operation to Secret and Counter. The server compares the OTP it calculated against the one provided by the user. Both sides then increment the counters. The counters have to be kept in sync between the server and the user. If a user ends up not using calculated OTP, the counter on the user side will become out of sync with the server.

Digits

The number of digits in a one-time password. The value for this property can only be 6, 7 or 8.

public int? Digits { get; set; }

Property Value

int?

Exceptions

InvalidOperationException

The value is invalid.

IsValidNameLength

Checks the name length, which cannot be more than 64 bytes in UTF-8 encoding.

public bool IsValidNameLength { get; }

Property Value

bool

Exceptions

InvalidOperationException

A required parameter is missing. See Name for more information.

Issuer

The provider or the service the account is associated with.

public string? Issuer { get; set; }

Property Value

string

Remarks

The Issuer property is recommended, but it can be absent (set to null).

Name

Get-property witch serves as the unique identifier for the credential.

public string Name { get; }

Property Value

string

Remarks

The Name prevents collisions between different accounts with different providers that might be identified using the same account name, e.g. the user's email address. The Name is created from Period, Issuer and Account Name with the following format: "period/issuer:account". If Period is a default value (30seconds), or the credential's type is HOTP, it'll be: "issuer:account". Also, if Issuer is not specified, the format will be: "period/account" or just "account" for TOTP with default period or HOTP credentials.

At a minimum, this member requires AccountName and Type to be set. The Type cannot be None. Also, if Type is set to Totp, then Period cannot be null nor Undefined.

There is a maximum length allowed for the Name (64 bytes in UTF-8 encoding, see Yubico.YubiKey.Oath.Credential.MaximumNameLength). To avoid an exception from being thrown due to invalid length, IsValidNameLength can be called first. If the total length is too long, Issuer and/or AccountName should be shortened.

Exceptions

InvalidOperationException

A required parameter is missing or the name exceeds the maximum length.

Period

The validity period in seconds for TOTP code. It can only be 15, 30 or 60 seconds. For HOTP should be set to zero.

public CredentialPeriod? Period { get; set; }

Property Value

CredentialPeriod?

Exceptions

InvalidOperationException

The value is invalid.

RequiresTouch

The credential requires the user to touch the key to generate a one-time password.

public bool? RequiresTouch { get; set; }

Property Value

bool?

Secret

The secret is an arbitrary value encoded in Base32 according to RFC 3548.

public string? Secret { get; set; }

Property Value

string

Remarks

Usually, the shared secret is provided by the provider or service website to the user by means of a QR code. Both sides need to retain this secret key for one-time password generation. The YubiKey takes care of securely storing this secret on behalf of the user when the credential is added. An authenticator app does not need to store this secret anywhere else.

Exceptions

InvalidOperationException

The value is invalid.

Type

The type of the credential. Indicates the type of the credential as either HOTP or TOTP.

public CredentialType? Type { get; set; }

Property Value

CredentialType?

Exceptions

InvalidOperationException

The value is invalid.

Methods

Equals(object) 

public override bool Equals(object obj)

Parameters

obj object

Returns

bool

Equals(Credential?) 

public bool Equals(Credential? credential)

Parameters

credential Credential

Returns

bool

GetHashCode() 

public override int GetHashCode()

Returns

int

ParseUri(Uri)

Parses an 'otpauth://' Uri that received from QR reader or manually from server.

public static Credential ParseUri(Uri uri)

Parameters

uri Uri

Returns

Credential

The credential with parameters.

Remarks

When you enable two-factor authentication on websites, they usually show you a QR code and ask you to scan and launch an authenticator app. QR codes are used in scanning secrets to generate one-time passwords. Secrets may be encoded in QR codes as a URI as specified by https://github.com/google/google-authenticator/wiki/Key-Uri-Format

Exceptions

ArgumentNullException

The Uri is null.

InvalidOperationException

The Uri path or schema is invalid, or the credential's algorithm or period is invalid.

Operators

operator ==(Credential, Credential) 

public static bool operator ==(Credential lhs, Credential rhs)

Parameters

lhs Credential
rhs Credential

Returns

bool

operator !=(Credential, Credential) 

public static bool operator !=(Credential lhs, Credential rhs)

Parameters

lhs Credential
rhs Credential

Returns

bool