• Nerdigy
  • \
  • How It Works: Time-Based One-Time Passwords (TOTP)

frontmatter.coverAlt

How It Works: Time-Based One-Time Passwords (TOTP)

In this post, we’ll take a closer look at time-based one-time passwords (TOTP). TOTP is widely used to add an extra layer of security by generating a unique code that changes every few seconds or minutes. We’ll break down how this works and explain the key components using a C# implementation.

🔑 What is TOTP?

TOTP adds a strong layer of security due to its ability to mitigate the risk of replay attacks. A unique one-time password is generated based on a shared secret key and the current time. This time-dependent code is typically valid for a short period, usually 30 seconds, before it expires and a new code is generated. Even if an attacker intercepts a one-time code, its short lifespan means the intercepted code will soon be rendered useless, thereby enhancing overall security. The original proposal for TOTP can be found in RFC 6238.

⏱️ How Does TOTP Work?

TOTP builds on the HMAC-based One-Time Password (HOTP) algorithm by incorporating the current time as a factor. Essentially, both the client and server use a shared secret key along with the current time (usually in intervals of 30 seconds) to generate a one-time password. Since the code is time-dependent, it remains valid only for a short period, reducing the window of opportunity for potential attackers.

At the heart of TOTP is a hash function, typically HMAC-SHA1, which combines the shared secret and a time counter. This time counter is derived by dividing the current Unix time by a predetermined time step. The resulting value is then fed into the HMAC algorithm, producing a hash that is subsequently truncated and reduced to form the final one-time password.

🛡️ Additional Considerations

Accurate time synchronization between the client and server is crucial. If the time difference is significant, the generated code on the client might not match the server’s expected value, leading to authentication failures. We refer to this time difference as “time skew.” To account for this, the server often allows a certain degree of flexibility in the time window to accommodate minor discrepancies.

Furthermore, the shared secret key must be securely stored and transmitted to prevent unauthorized access. If a malicious actor gains access to the shared secret, they can generate valid one-time passwords, compromising the entire security of the system. If a breach occurs, the shared secret should be revoked and replaced with a new one to maintain the integrity of the system.

🧩 Key Components of TOTP

Before we delve into the implementation, let’s review the key components of TOTP:

  • Shared Secret: The unique key shared between the client and server
  • Time Step: The fixed interval (usually 30 seconds) used to calculate the time counter
  • Hash Function: Typically HMAC-SHA1 is used to combine the shared secret with the time counter
  • Dynamic Truncation: The process of extracting a shorter, user-friendly code from the generated hash
  • Modulus Operation: Reduces the truncated hash to a numeric value, usually resulting in a 6-digit code

⚠️ Disclaimer

If you’re implementing TOTP in your application, consider using a reputable library or service that adheres to industry standards and best practices. This will help ensure that your implementation is secure and reliable. This post is focused on understanding the underlying principles of TOTP and providing a C# implementation for educational purposes.

💻 Generating A Time-Based One-Time Password

The following C# implementation demonstrates how to generate a time-based one-time password using a shared secret and timestamp. The code includes methods to calculate the current time step number, compute the TOTP value, and generate the 6-digit TOTP code.

/// <summary>
/// Provides functionality to generate and validate time-based one-time passwords (TOTP) using a shared secret and a timestamp.
/// </summary>
public static class TokenProvider
{
    // The time step duration is 30 seconds
    private static readonly TimeSpan TimeStep = TimeSpan.FromSeconds(30);
    // The encoding used for the shared secret
    private static readonly Encoding Encoding = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false, throwOnInvalidBytes: true);
    // The modulo value used to generate the 6-digit TOTP
    private const int Mod = 1_000_000;

    /// <summary>
    /// Generates a time-based one-time password (TOTP) using the specified secret and timestamp.
    /// </summary>
    /// <param name="secret">The shared secret used for generating the TOTP.</param>
    /// <param name="timestamp">The timestamp for which the TOTP should be generated.</param>
    /// <returns>A string representing the generated TOTP, formatted as a 6-digit number.</returns>
    public static string Generate(string secret, DateTimeOffset timestamp)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(secret);

        var currentTimeStep = GetCurrentTimeStepNumber(timestamp);
        var key = Encoding.GetBytes(secret);

        var value = ComputeTotp(key, currentTimeStep);
        
        return value.ToString("D6");
    }
    
    /// <summary>
    /// Computes the TOTP value given a key and a time step number.
    /// </summary>
    /// <param name="key">The byte array representing the shared secret.</param>
    /// <param name="timeStepNumber">The time step number used for TOTP computation.</param>
    /// <returns>An integer representing the computed TOTP value before formatting.</returns>
    private static int ComputeTotp(byte[] key, ulong timeStepNumber)
    {
        // Convert the time step number to network byte order (big-endian)
        Span<byte> timeStepAsBytes = stackalloc byte[sizeof(long)];
        
        BitConverter.TryWriteBytes(timeStepAsBytes, IPAddress.HostToNetworkOrder((long)timeStepNumber));

        // Compute the HMAC-SHA1 hash using the key and time step
        Span<byte> hash = stackalloc byte[HMACSHA1.HashSizeInBytes];
        
        HMACSHA1.HashData(key, timeStepAsBytes, hash);

        // Leverage Dynamic Truncation to extract a 4-byte dynamic binary code
        var offset = hash[^1] & 0xf;

        var binaryCode = (hash[offset] & 0x7f) << 24
                         | (hash[offset + 1] & 0xff) << 16
                         | (hash[offset + 2] & 0xff) << 8
                         | (hash[offset + 3] & 0xff);

        // Apply the modulus operation to obtain a 6-digit TOTP value
        return binaryCode % Mod;
    }

    /// <summary>
    /// Calculates the current time step number based on the provided timestamp.
    /// </summary>
    /// <param name="timestamp">The timestamp for which to calculate the time step number.</param>
    /// <returns>The current time step number as an unsigned long.</returns>
    private static ulong GetCurrentTimeStepNumber(DateTimeOffset timestamp)
    {
        var delta = timestamp - DateTimeOffset.UnixEpoch;

        return (ulong)(delta.Ticks / TimeStep.Ticks);
    }
}

✅ Verifying the TOTP

To validate a TOTP code, you can compare the provided code against the expected value generated using the shared secret and timestamp. The following method demonstrates how to validate a TOTP code for the current time step and the previous and next steps to account for minor time discrepancies between the client and server (time skew).

/// <summary>
/// Validates a provided TOTP against the expected value generated using the secret and timestamp.
/// </summary>
/// <param name="secret">The shared secret used for generating the TOTP.</param>
/// <param name="code">The TOTP code to validate.</param>
/// <param name="timestamp">The timestamp at which the TOTP code is being validated.</param>
/// <returns><c>true</c> if the provided code is valid; otherwise, <c>false</c>.</returns>
public static bool Validate(string secret, string code, DateTimeOffset timestamp)
{
    ArgumentException.ThrowIfNullOrWhiteSpace(secret);
    ArgumentException.ThrowIfNullOrWhiteSpace(code);

    var currentTimeStep = GetCurrentTimeStepNumber(timestamp);
    var key = Encoding.GetBytes(secret);

    // Validate the code for the current time step and the previous and next steps
    // This accounts for minor time discrepancies between the client and server (time skew)
    for (var i = -2; i <= 2; i++)
    {
        var computed = ComputeTotp(key, (ulong)((long)currentTimeStep + i));
        var computedString = computed.ToString("D6");
        
        if (computedString == code)
            return true;
    }

    return false;
}

🎉 Conclusion

In this post, we’ve explored the inner workings of time-based one-time passwords (TOTP) in detail. We’ve seen how TOTP relies on a shared secret, time steps, and secure hashing to generate dynamic, short-lived codes that enhance security. A full copy of the source code can be found on GitHub.

If you’re building a .NET application and want to leverage TOTP, you should use the built-in Rfc6238AuthenticationService and TotpSecurityStampBasedTokenProvider classes where appropriate. Until next time, stay curious! 🚀