KNM.CryptoHelper

Production-ready cryptographic library for .NET enterprise applications.
Provides AES‑256 encryption with HMAC integrity, JWT authentication, API key generation, TOTP MFA, OTP generation, device fingerprinting, BIP39 mnemonic handling, and multiple hash functions (MD5, SHA‑1, SHA‑2, RIPEMD‑160, etc.).

Installation

dotnet add package KNM.CryptoHelper

Configuration

DI Registration (.NET 10)

builder.Services.AddKnmCryptoCollection(options =>
{
    options.Crypto.CryptoPassword = "YourSecurePassword123!";
    options.Crypto.Iterations = 100_000;
    options.Jwt.JwtSecretKey = "your-jwt-secret-min-32-chars";
    options.Jwt.Issuer = "yourapp.com";
    options.ApiKey.ApiKeySalt = "your-hmac-salt";
    options.Mfa.Digits = 6;
    options.Mfa.Period = 30;
    options.Otp.Length = 6;
    options.Otp.ValidityDurationMinutes = 5;
    options.DeviceFingerprint.Enabled = true;
    options.DeviceFingerprint.SimilarityThreshold = 0.90;
    options.DeviceFingerprint.CacheExpiryDays = 30;
    options.Bcrypt.WorkFactor = 12;
});

Fluent Override

builder.Services.AddKnmCryptoCollection()
    .WithCrypto(opt =>
    {
        opt.CryptoPassword = "YourSecurePassword123!";
        opt.Iterations = 200_000;
    })
    .WithJwt(opt =>
    {
        opt.JwtSecretKey = "your-jwt-secret-min-32-chars";
        opt.Issuer = "yourapp.com";
        opt.Audience = "yourapp-clients";
        opt.ExpirationMinutes = 60;
    })
    .WithApiKey(opt =>
    {
        opt.ApiKeySalt = "your-hmac-salt";
    })
    .WithMfa(opt =>
    {
        opt.Digits = 6;
        opt.Period = 30;
        opt.Algorithm = MfaTotpHashMode.Sha256;
    })
    .WithOtp(opt =>
    {
        opt.Length = 6;
        opt.ValidityDurationMinutes = 5;
    })
    .WithDeviceFingerprint(opt =>
    {
        opt.Enabled = true;
        opt.SimilarityThreshold = 0.90;
        opt.CacheExpiryDays = 30;
    })
    .WithBcrypt(opt =>
    {
        opt.WorkFactor = 12;
    });

Usage

Inject ICryptoHelper in your services/controllers:

public class AuthService
{
    private readonly ICryptoHelper _crypto;

    public AuthService(ICryptoHelper crypto)
    {
        _crypto = crypto;
    }
}

Text Encryption

string encrypted = _crypto.EncryptText("Sensitive data");
string decrypted = _crypto.DecryptText(encrypted);

API Keys

// Generate
Guid userSalt = Guid.NewGuid();
DateTime expiration = DateTime.UtcNow.AddDays(30);
string apiKey = _crypto.GenerateApiKey(userSalt, expiration);

// Verify
bool isValid = _crypto.VerifyApiKey(userSalt, expiration, apiKey);

JWT Tokens

// Generate
string token = _crypto.GenerateJwtToken(
    userId: "123",
    email: "user@domain.com",
    username: "john.doe"
);

// Validate
var (isValid, jwtToken, expirationDate) = _crypto.JwtTokenIsValid(token);
if (isValid == "Valid")
{
    // Access claims via jwtToken.Claims
}

MFA TOTP

// Setup (registration/profile)
string encryptedSecret = _crypto.GenerateMfaSecret();
// Save encryptedSecret to database

string qrCode = _crypto.GenerateMfaQrCode("user@domain.com", encryptedSecret);
// Display: <img src="@qrCode" />

MfaObject mfaInfo = _crypto.GenerateMfaCode("user@domain.com", encryptedSecret);
// Display mfaInfo.Uri (for URI-based apps),
// or mfaInfo.PlainSecret for manual entry,
// or mfaInfo.QrCodeSvg for SVG QR code visualization

// Verify (login)
bool isValid = _crypto.VerifyMfaCode(user.EncryptedMfaSecret, "123456");

OTP Generation & Verification

// Generate + send
OtpResult otp = _crypto.GenerateOtp();
await db.SaveOtpAsync(userId, otp.Code, otp.ExpiryDate);
await email.SendAsync(user.Email, otp.Code);

// Verify
bool valid = _crypto.VerifyOtp(storedCode, userCode, storedExpiry);

Device Fingerprinting

// Generate fingerprint
string fingerprint = _crypto.GenerateDeviceFingerprint(context);

// Get device info
DeviceInfo device = _crypto.GetDeviceInfo(context);
// device.Browser, device.OS, device.DeviceType, device.IpAddress

// Compare fingerprints
double similarity = _crypto.CalculateFingerprintSimilarity(fp1, fp2, threshold: 0.90);
bool isSameDevice = similarity >= 0.90;

// Inject device context (middleware)
await _crypto.InjectDeviceContextAsync(context, userId);
// Sets context.Items["DeviceInfo"], context.Items["DeviceFingerprint"], context.Items["MFARequired"]

Bcrypt Password Hashing

string passwordHash = _crypto.BcryptHashPassword("plaintextPassword", workFactor);
bool isMatch = _crypto.BcryptVerifyPassword("plaintextPassword", passwordHash);
bool needsUpgrade = _crypto.BcryptNeedsRehash(passwordHash, targetWorkFactor);

// Optional: upgrade to a new work factor on login
bool isValid = _crypto.BcryptUpgradePasswordHash(
    plainPassword: "plaintextPassword",
    oldHash: passwordHash,
    targetWorkFactor: 12,
    out string newHash);

if (isValid && newHash != null)
{
    // Persist newHash to DB to reduce load on old lower-cost hashes
}

Hashing

// Compute any standard hash (MD5, SHA1, SHA256, SHA3, RIPEMD160, etc.)
string hash = _crypto.ComputeHash("text", HashAlgorithmType.SHA256);

// Verify against an existing hash
bool matches = _crypto.VerifyHash("text", "existing-hash", HashAlgorithmType.SHA256);

// Supported algorithms include:
// - MD5, SHA1, SHA224, SHA256, SHA384, SHA512
// - SHA3 variants (SHA3-256, SHA3-512)
// - RIPEMD-160 for cryptocurrency-style digests

BIP39 Mnemonic & Seed

// Generate 12-word italian mnemonic
string mnemonic = _crypto.GenerateMnemonic(wordCount: KnmWordCount.Twelve,language: KnmLanguage.English);

// Convert mnemonic to 64-byte BIP39 seed (hex)
string seed = _crypto.MnemonicToSeed("mnemonic", password: "optional-passphrase", language: KnmLanguage.English);

// Validate before sensitive operations
bool isValid = _crypto.ValidateMnemonic(mnemonic, KnmLanguage.English);

Additional Features

// Bcrypt helpers (as in "Bcrypt Password Hashing" section)
string passwordHash = _crypto.BcryptHashPassword("plaintextPassword", workFactor);
bool isMatch = _crypto.BcryptVerifyPassword("plaintextPassword", passwordHash);
bool needsUpgrade = _crypto.BcryptNeedsRehash(passwordHash, targetWorkFactor);
bool isValid = _crypto.BcryptUpgradePasswordHash("plaintextPassword", passwordHash, 12, out string newHash);

Configuration Options

public class Options
{
    public CryptoOptions Crypto { get; set; }
    public JwtOptions Jwt { get; set; }
    public ApiKeyOptions ApiKey { get; set; }
    public MfaOptions Mfa { get; set; }
    public OtpOptions Otp { get; set; }
    public DeviceFingerprintOptions DeviceFingerprint { get; set; }
    public BcryptOptions Bcrypt { get; set; }
}

CryptoOptions

• CryptoPassword: AES encryption password
• SaltSize: Salt bytes (default 32)
• IvSize: IV bytes (default 16)
• KeySize: Key bytes (default 32)
• Iterations: PBKDF2 iterations (default 100,000)

JwtOptions

• JwtSecretKey: HMAC‑SHA256 secret (min 32 chars)
• Issuer: Token issuer
• Audience: Token audience
• ExpirationMinutes: Token lifetime (default 60)

MfaOptions

• Digits: TOTP code length (default 6)
• Period: Time step seconds (default 30)
• Algorithm: Hash mode (SHA1/SHA256/SHA512)
• VerificationWindow: Time tolerance (default ±1 step)
• DefaultIssuer: QR code issuer name

OtpOptions

• Length: OTP digits (1–10, default 6)
• ValidityDurationMinutes: Expiration time (default 5)

DeviceFingerprintOptions

• Enabled: Enable device tracking (default true)
• SimilarityThreshold: Match threshold 0.0–1.0 (default 0.90)
• CacheExpiryDays: Trusted device cache duration (default 30)
• MaskLevel: 32, 24, 20, 16 (default 20)

BcryptOptions

• WorkFactor: Bcrypt cost factor (default 12)

Technical Details

License

Proprietary — KoNiMa Software & More