Bau.Libraries.OneTimePassword 1.0.19

OneTimePassword

Implementation of the TOTP (RFC 6238) and HOTP (RFC 4226) algorithms for generating one-time passwords with C#.

Installation of the NuGet package

dotnet add package Bau.Libraries.OneTimePassword

Introduction

A one-time password (OTP) algorithm is an authentication method that generates a unique and temporary password for a session. This type of password is used only once and expires after a brief period of time.

These algorithms are used to add an additional layer of security to applications, enabling two-factor authentication (2FA or MFA).

Key features of OTPs:

• Temporal nature: They have a limited validity period, usable only within a brief time after generation.
• Uniqueness: Each key is unique and generated using advanced algorithms, ensuring it cannot be repeated and can only be accessed by its owner.
• Secure generation: Created through cryptographic processes that prevent guessing by attackers.
• Easy implementation: Can be sent through various media, such as text messages, emails, or dedicated applications, facilitating integration into different systems.

Several algorithms exist for generating OTP keys, and this library generates keys using HOTP or TOTP:

HOTP (HMAC-Based One-Time Password) Algorithm

HOTP is an authentication method that generates unique and temporary passwords using a shared secret key and a counter. This algorithm is a fundamental part of the OATH (Initiative for Open Authentication) initiative.

See its specification in the document RFC 4226.

Key features of the HOTP algorithm:

• Shared secret key: Both parties (the server and the authentication application) share a secret key used to generate OTPs.
• Counter: A counter is incremented each time a new OTP is generated. This counter ensures each password is unique.
• HMAC function: The secret key and the counter value are processed using an HMAC (Hash-based Message Authentication Code) function to generate the OTP.
• OTP generation: The OTP is generated by combining the secret key and the counter value, then truncating the result to provide a user-friendly format, typically a 6 to 8 digit number.

HOTP algorithm workflow:

• Initialization: The server and the authentication application agree on a secret key and an initial counter.
• OTP generation: When an OTP is needed, the authentication application combines the secret key and the current counter value and applies the HMAC function to generate an OTP.
• Truncation: The HMAC function output is truncated to obtain a 6 to 8 digit OTP.
• Counter increment: After using the OTP, the counter is incremented by one unit on both the server and the authentication application.
• Authentication: The server verifies the OTP provided by the user by generating a local OTP with the secret key and the current counter and comparing it with the user-provided OTP.

Advantages of the HOTP algorithm:

• Security: OTPs are unique and temporary, making them more secure than static passwords.
• Flexibility: Can be used in a wide range of applications.

Disadvantages of the HOTP algorithm:

• Synchronization issue: If the counters on the server and the authentication application become desynchronized, a resynchronization protocol may be required to resolve the issue.
• No expiration period: OTPs generated by HOTP are valid until the next one is used, which can be a security issue if not used immediately.

TOTP (Time-Based One-Time Password) Algorithm

TOTP is an authentication method that generates unique and temporary passwords based on a shared secret key and the current time. This algorithm is a variant of the HOTP (HMAC-Based One-Time Password) algorithm and is widely used in two-factor authentication (2FA).

See its specification in the document RFC 6238.

Key features of the TOTP algorithm:

• Shared secret key: Both parties (the server and the authentication application) share a secret key used to generate OTPs.
• Current time: The current time is used as a variable to generate the OTP, ensuring each password is unique and temporary.
• HMAC function: The secret key and the current time are processed using an HMAC (Hash-based Message Authentication Code) function to generate the OTP.
• Time interval: The algorithm uses a time interval (typically 30 seconds) to determine the validity of the OTP.

TOTP algorithm workflow:

• Initialization: The server and the authentication application agree on a secret key and an initial time. The Unix EPOCH constant is commonly used: the number of ticks since January 1, 1970.
• OTP generation: When an OTP is needed, the authentication application combines the secret key and the current time and applies the HMAC function to generate an OTP.
• Truncation: The HMAC function output is truncated to obtain a 6 to 8 digit OTP.
• Verification: The server verifies the OTP provided by the user by generating a local OTP with the secret key and the current time and comparing it with the user-provided OTP.

Advantages of the TOTP algorithm:

• Security: OTPs are unique and temporary, making them more secure than static passwords.
• Offline availability: OTPs can be generated without an internet connection, making them ideal for users who need to access their accounts in areas with little or no connectivity.
• Usability: The TOTP algorithm is easy to implement and use.

Disadvantages of the TOTP algorithm:

• Synchronization issue: If the clocks on the server and the authentication application are not synchronized, a resynchronization protocol may be required to resolve the issue.
• Security limitations: Although OTPs are temporary, an attacker could intercept and use an OTP before it expires if they have access to the secret key.

Using the Library

Generating a HOTP Key

To generate a HOTP key, we will use the HotpGenerator class. In the constructor, we need to specify:

• Key: The key returned by the key server.
• Encoding: The encoding mode of the key returned by the key server (plain text, Base64, or Base32).
• Algorithm: The hashing algorithm used to obtain the resulting codes (Sha1, Sha256, Sha512). The default is SHA1.
• Digits: The number of characters generated by the code (6 to 8, typically 6).

Once the class is initialized, we can access the validation code by calling the Compute method with the appropriate counter:

using Bau.Libraries.OneTimePassword;

HotpGenerator hotp = new("KEY", Secret.Encoding.Plain, BaseTokenGenerator.HashAlgorithm.Sha1, 6);

string code = hotp.Compute(19238);

Generating a TOTP Key

To generate a TOTP key, we will use the TotpGenerator class. In the constructor, we need to specify:

• Key: The key returned by the key server.
• Encoding: The encoding mode of the key returned by the key server (plain text, Base64, or Base32).
• Algorithm: The hashing algorithm used to obtain the resulting codes (Sha1, Sha256, Sha512). The default is SHA1.
• Digits: The number of characters generated by the code (6 to 8, typically 6).

Once the class is initialized, we can obtain the validation code by calling the Compute method:

using Bau.Libraries.OneTimePassword;

TotpGenerator totp = new("KEY", Secret.Encoding.Plain, BaseTokenGenerator.HashAlgorithm.Sha1, 6);

string code = totp.Compute();

In this case, if no date is passed, the system date is used, but we can specify a specific date:

string code = totp.Compute(new DateTime(2024, 8, 2, 17, 30, 5));

or use long specifying the Unix date (number of ticks since January 1, 1970):

string code = totp.Compute(1_991_289);

Initially, the validity period of the key is 30 seconds, but we can modify it at any time:

using Bau.Libraries.OneTimePassword;

TotpGenerator totp = new("KEY", Secret.Encoding.Plain, BaseTokenGenerator.HashAlgorithm.Sha1, 6);

totp.TimeManager.IntervalSeconds = 60;

string code = totp.Compute();

Validity Period of the Key

The codes generated by TotpGenerator are valid for 30 seconds or the specified interval, but this time is measured not from the code generation but from the start of the interval of the specified date. For example, if we generate the code at 12:05, the start of the generation window will be 12:00, and we will have 25 seconds of validity left.

To check the remaining validity time of the code (for example, to display it in an application), we can use the GetRemainingSeconds method of the TopTimeManager class, where methods related to the date are grouped:

using Bau.Libraries.OneTimePassword;

TotpGenerator totp = new("KEY", Secret.Encoding.Plain, BaseTokenGenerator.HashAlgorithm.Sha1, 6);

totp.TimeManager.IntervalSeconds = 60;

string code = totp.Compute(DateTime.UtcNow);
int remainingSeconds = totp.TimeManager.GetRemainingSeconds(DateTime.UtcNow);

Credits

This project is based on Otp.Net developed by Kyle Spearrin.