SimpleOtp.Net 1.0.0

TotpService - Usage Documentation

TotpService is a stateless OTP service based on TOTP, with a secret split into two parts: server and client. The client receives the OTP along with the client secret for validation.

1️⃣ Dependency Injection Setup

You can add TotpService to the ASP.NET Core service container using the AddSimpleOtp extension:

using Microsoft.Extensions.DependencyInjection;

public void ConfigureServices(IServiceCollection services)
{
    // Default configuration: OtpSize = 6, TimeStep = 30 seconds
    services.AddSimpleOtp();

    // OR with custom configuration
    var otpConfig = new SimpleOtpConfiguration
    {
        OtpSize = 8,     // OTP length
        TimeStep = 60    // OTP validity duration in seconds
    };
    services.AddSimpleOtp(otpConfig);
}

2️⃣ Configurable Parameters

Example of custom values:

var otpConfig = new SimpleOtpConfiguration
{
    OtpSize = 8,   // 8-digit OTP
    TimeStep = 60  // OTP valid for 60 seconds
};
services.AddSimpleOtp(otpConfig);

3️⃣ Using ITotpService in Services or Controllers

With dependency injection, you can inject ITotpService directly:

using Microsoft.AspNetCore.Mvc;

public class AuthController : ControllerBase
{
    private readonly ITotpService _totpService;

    public AuthController(ITotpService totpService)
    {
        _totpService = totpService;
    }

    [HttpGet("generate-otp")]
    public IActionResult GenerateOtp()
    {
        var (otp, secret) = _totpService.GenerateOtp();

        return Ok(new
        {
            Otp = otp,
            Secret = secret
        });
    }

    [HttpPost("validate-otp")]
    public IActionResult ValidateOtp([FromBody] string otp, [FromBody] string secret)
    {
        bool isValid = _totpService.ValidateOtp(otp, secret);
        return Ok(new { IsValid = isValid });
    }
}

4️⃣ Complete Example (Minimal API)

var builder = WebApplication.CreateBuilder(args);

// Add OTP service with custom configuration
builder.Services.AddSimpleOtp(new SimpleOtpConfiguration
{
    OtpSize = 6,
    TimeStep = 30
});

var app = builder.Build();

app.MapGet("/generate-otp", (ITotpService otpService) =>
{
    var (otp, secret) = otpService.GenerateOtp();
    return Results.Ok(new { otp, secret });
});

app.MapPost("/validate-otp", (ITotpService otpService, string otp, string secret) =>
{
    bool isValid = otpService.ValidateOtp(otp, secret);
    return Results.Ok(new { isValid });
});

app.Run();

5️⃣ Example Flow Diagram

+----------------+           +----------------+          +-----------------+
|                |           |                |          |                 |
|  TotpService   |  OTP +    |    Client      |  OTP +   | TotpService     |
|  (Server)      | secret    | receives OTP   | secret   | Validates OTP  |
| generates OTP  | --------> | stores secret  | --------> | recombines     |
| and secret     |           | for later use  |          | secret & checks|
+----------------+           +----------------+          +-----------------+

6️⃣ Key Notes

• TotpService is stateless; no server-side storage is required.
• The client must keep the secret for OTP validation.
• Configurable parameters (OtpSize and TimeStep) allow adjusting security and OTP validity duration.
• Can be injected into any service or controller via ITotpService.
• Recommended: store masterSecret securely on the server (e.g., Azure Key Vault, environment variable).
• TimeStep controls OTP validity. Adjust according to your security requirements.

7️⃣ Quick Usage Summary

1. Register the service with DI:

services.AddSimpleOtp(new SimpleOtpConfiguration { OtpSize = 6, TimeStep = 30 });

2. Inject ITotpService in a controller or service.

3. Generate OTP + secret:

var (otp, secret) = _totpService.GenerateOtp();

4. Send both to the client.

5. Validate OTP with secret:

bool isValid = _totpService.ValidateOtp(otp, secret);