Decode.Cryptography 3.0.0

Decode.Cryptography

Modern and secure cryptography utilities for .NET, providing a clean API for common cryptographic operations.

🚀 Features

• Secure Password Hashing (PBKDF2): Key derivation using HMAC-SHA256, 100,000 iterations by default and overridable per call.
• Password Verification: VerifyPassword re-derives with the stored salt, reads the output size from the stored hash, and compares in constant time.
• Opaque Secrets: Secret.Generate for refresh tokens and API keys, Secret.GenerateNumericCode for MFA codes — both from a CSPRNG.
• Timing Attack Protection: VerifyPassword, VerifySha256 and VerifyHmacSha256 compare with CryptographicOperations.FixedTimeEquals, and treat malformed input as a failed verification rather than throwing.
• HMAC: Message authentication using SHA256.
• SHA256: Standard hashing with support for multiple iterations.
• HEX, Base64 & base64url: Conversions built on native .NET primitives (Convert.ToHexString / FromHexString) where the target framework provides them.
• No MD5/SHA1: Insecure algorithms are not part of the API.

📦 Installation

dotnet add package Decode.Cryptography

📖 Usage

Hashing a Password (PBKDF2)

This is the recommended way to store user passwords.

using Decode.Cryptography;

// Generate a unique salt for the user
string salt = Hash.GenerateSaltToBase64String();

// Hash the password with the salt
string hash = Hash.HashPasswordToBase64String("user-password", salt);

// Store both 'salt' and 'hash' in your database

Defaults are exposed as constants — Hash.DefaultSaltSize (36 bytes), Hash.DefaultHashSize (36 bytes) and Hash.DefaultIterations (100,000).

On the iteration count. 100,000 is the default, not a ceiling — iterations is a parameter on HashPasswordToBase64String. OWASP's current guidance for PBKDF2-HMAC-SHA256 is considerably higher (600,000 at the time of writing). Raising it is a one-line change for new hashes, but it invalidates existing ones unless you store the iteration count alongside the salt and hash, so choose the value deliberately before your first deployment.

Verifying a Password

using Decode.Cryptography;

// storedSalt, storedHash and storedIterations come from your database
bool isValid = Hash.VerifyPassword(attemptedPassword, storedSalt, storedHash, storedIterations);

The derived key length is read from storedHash, so a credential created under a different hashSize still verifies. The iteration count is a parameter for the same reason: pass the value stored alongside the credential, not the current default, or raising the work factor invalidates every existing password.

Comparison uses CryptographicOperations.FixedTimeEquals. Comparing the Base64 strings with == short-circuits on the first differing character, and that timing difference is measurable across enough requests.

A missing or malformed salt or hash returns false rather than throwing, matching VerifySha256. An empty or whitespace-only stored hash is rejected explicitly — it decodes to zero bytes, and a zero-length constant-time comparison succeeds against every password.

Added in 2.1.0. Earlier versions documented the recipe above instead of providing it, leaving the constant-time comparison and the hash-size bookkeeping to the caller.

Renamed in 2.0.0. These were previously DEFAULT_SALT_SIZE, DEFAULT_HASH_SIZE and DEFAULT_ITERATIONS. The values are unchanged; only the names now follow .NET conventions.

Salt generation changed in 2.0.0. GenerateSaltToBase64String used RandomNumberGenerator.GetNonZeroBytes, a legacy PKCS#1 padding helper that never emits 0x00 and therefore narrowed each byte from 256 to 255 possible values. It now uses GetBytes. Existing stored salts and hashes remain valid — nothing needs to be rehashed.

Computing HMAC-SHA256

// hexKey must be a valid hexadecimal string
string hmac = Hash.ComputeHmacSha256ToBase64String(hexKey, "content");

SHA256 Hashing & Verification

Useful for checking file integrity or raw data hashing.

// Generate SHA256 hash as Hex string
string sha256Hex = Hash.ComputeSha256ToHexString("my-content");

// Verify if a content matches a hash (uses Constant-Time comparison)
bool isSha256Valid = Hash.VerifySha256("my-content", sha256Hex);

HMAC-SHA256 Verification

Useful for verifying webhooks or request signatures.

bool isSignatureValid = Hash.VerifyHmacSha256(hexKey, "content", base64HashToVerify);

Opaque Secrets (refresh tokens, API keys)

using Decode.Cryptography;

// 32 bytes from a CSPRNG, base64url encoded — safe in URLs, headers and JSON without escaping.
string refreshToken = Secret.Generate();

// Store only the digest. A database dump then hands over nothing usable.
string stored = Hash.ComputeSha256ToHexString(refreshToken);

// Verification is already constant-time.
bool isValid = Hash.VerifySha256(presentedToken, stored);

There is deliberately no HashOpaqueSecret/VerifyOpaqueSecret pair: they would be renames of ComputeSha256ToHexString and VerifySha256, not new behaviour.

A plain digest is the right choice here, rather than PBKDF2. The secret already carries full entropy, so there is nothing to guess — paying an iteration cost on every request would buy nothing. That reasoning does not transfer to passwords or to short numeric codes.

Guid.NewGuid() is the usual stand-in and is wrong twice over: it carries no guarantee of coming from a cryptographic source, and a version 4 GUID spends 6 of its 128 bits on version and variant markers.

Numeric Codes (MFA, confirmation)

string code = Secret.GenerateNumericCode();     // six digits, "042315" included

Drawn uniformly from the whole range. The common shortcut of generating between 10^(n-1) and 10^n to avoid a leading zero throws away a tenth of the keyspace — 900,000 six-digit codes instead of 1,000,000 — for a cosmetic reason. Lengths run from 1 to Secret.MaxNumericCodeLength (9); ten digits overflow the int range the generator draws from.

These are low-entropy by construction — six digits is under 20 bits. A numeric code is only as safe as the attempt limit and expiry you enforce around it. Storing it under an unkeyed digest buys very little, since the whole space is exhausted in milliseconds; if you need storage protection, use ComputeHmacSha256ToBase64String with a server-held key.

Base64url Conversions

string token = Utils.ToBase64UrlString(bytes);   // no '+', '/' or '=' — survives a URL unescaped
byte[] back = Utils.FromBase64UrlString(token);  // accepts padded input too

Array Manipulation

Utilities to combine and split byte arrays/spans efficiently:

byte[] part1 = [0x01, 0x02];
byte[] part2 = [0x03, 0x04];

// Combine arrays
byte[] combined = Utils.CombineArray(part1, part2);

// Split arrays back (splits 'combined' into first 2 bytes and the rest)
Utils.SplitArray(combined, length: 2, out byte[] first, out byte[] second);

HEX Conversions

byte[] data = [0xDE, 0xAD, 0xBE, 0xEF];

// Convert to HEX string
string hex = Utils.ToHexString(data);

// Convert back to byte array
byte[] back = Utils.FromHexString(hex);

🔒 Security Note

• No MD5/SHA1: Insecure algorithms are not included.
• Constant-Time Comparison: VerifyPassword, VerifySha256 and VerifyHmacSha256 use FixedTimeEquals, so they do not leak information through timing.
• Iteration Count: 100,000 by default, which raises the cost of GPU brute-force considerably over a bare hash, but sits below OWASP's current PBKDF2-HMAC-SHA256 recommendation. Set iterations explicitly if you need to match it.
• Still not a password-storage framework: VerifyPassword closes the most dangerous gap, but there is no built-in rehash-on-login, no versioned hash format and no iteration count embedded in the output. Store the iteration count and salt yourself, per credential — VerifyPassword takes the count as a parameter precisely so you can raise the default without invalidating what is already stored.

📄 License

MIT License.