1Link.OtpSecurity 1.1.0

1Link.OtpSecurity

A lightweight and secure One-Time Password (OTP) generation and verification library.

• Built-in OTP email template (optional)
• Secure SHA-256 hashing with fixed-time comparison
• Works in ASP.NET Core, WebForms, MVC, Console, and any .NET app
• Configure once, use anywhere

Targets

• netstandard2.0 (WebForms / .NET Framework 4.6.1+)
• net8.0

Installation

Install via NuGet:

Install-Package 1Link.OtpSecurity

Configuration (Required, Call Once at App Startup)

ASP.NET Core

// Program.cs or Startup.cs (call once at startup)
OtpSecurity.OtpConfig.Initialize(
    connectionString: "Server=...;Database=...;User Id=...;Password=...;",
    otpExpiryMinutes: 5,
    maxAttempts: 5
);

WebForms / Classic .NET Framework

// Global.asax.cs
protected void Application_Start(object sender, EventArgs e)
{
    OtpSecurity.OtpConfig.Initialize(
        connectionString: ConfigurationManager.ConnectionStrings["Sdrs"].ConnectionString,
        otpExpiryMinutes: Convert.ToInt32(ConfigurationManager.AppSettings["OtpExpiry"]),
        maxAttempts: Convert.ToInt32(ConfigurationManager.AppSettings["OtpLimit"])
    );
}

Note: Call OtpConfig.Initialize(...) exactly once during application startup. Subsequent calls are ignored.

Usage

1. Generate a New OTP Challenge

// Returns (challengeId, otpPlainText)
var (challengeId, otp) = OtpSecurity.OtpServices.CreateOtp(
    userId,
    browser,
    ip
);

// Send `otp` to user via your preferred email/SMS provider

Returned values

• challengeId GUID to use when verifying later
• otp 6-digit OTP (plaintext) send via your own delivery channel

Optional: Email HTML Template

mailMessage.Body = OtpSecurity.EmailTemplates.OtpEmailTemplate(
    otp,
    "Username",
    "5 minutes"
);
mailMessage.IsBodyHtml = true;

2. Verify OTP Input

bool isValid = OtpSecurity.OtpServices.VerifyOtp(
    challengeId,
    otpInput,
    userId,
    browser,
    ip
);

if (isValid)
{
    // Success: OTP matched and marked as Used
}
else
{
    // Failure: invalid, expired, exceeded attempts, or fingerprint mismatch
}

SQL Table Schema (Required)

Create the following table in your configured database:

CREATE TABLE OtpChallenges (
    ChallengeId UNIQUEIDENTIFIER PRIMARY KEY,
    UsersId BIGINT NOT NULL,
    OtpHash NVARCHAR(MAX) NOT NULL,
    ExpiresAt DATETIME NOT NULL,
    Attempts INT NOT NULL DEFAULT 0,
    MaxAttempts INT NOT NULL DEFAULT 3,
    Status VARCHAR(20) NOT NULL DEFAULT 'Pending',  -- Pending, Used, Expired
    CreatedAt DATETIME NOT NULL DEFAULT GETUTCDATE(),
    FingerPrint VARCHAR(MAX) NOT NULL
);

Features

• Secure 6-digit OTP generator
• SHA-256 hashing and base64 storage
• Fixed-time hash comparison to prevent timing attacks
• Fingerprint binding using ChallengeId + Browser + IP
• Auto-cleanup pattern for Used/Expired records (library issues delete commands during creation)
• Configurable expiry and max attempts via single startup initialization
• Usable in WebForms (.NET Framework) and modern .NET (ASP.NET Core)

Notes & Best Practices

• Do not send OTPs from the library send via your own mail/SMS provider so you control security and deliverability.
• Always call OtpConfig.Initialize once at startup. Failing to do so will throw an InvalidOperationException when using the service.
• Keep OtpHash column length sufficient (NVARCHAR(MAX) recommended) to avoid truncation.
• Use parameterized queries (the library uses parameters internally) avoid concatenating user input into SQL.
• Consider logging (server-side) for OTP failures for troubleshooting but do not log plaintext OTP values.

Example (Quick)

// Startup (ASP.NET Core)
OtpSecurity.OtpConfig.Initialize(
    connectionString: Configuration["ConnectionStrings:Sdrs"],
    otpExpiryMinutes: 5,
    maxAttempts: 3
);

// Controller
var (challengeId, otp) = OtpSecurity.OtpServices.CreateOtp(userId, browser, ip);
// send otp
bool ok = OtpSecurity.OtpServices.VerifyOtp(challengeId, userInputOtp, userId, browser, ip);

License & Contribution

Include your preferred license file (e.g., LICENSE with MIT).
Contributions: open pull requests, include tests for new features.