Decode.Cryptography 2.0.1

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.
• Timing Attack Protection: 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: 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

There is no VerifyPassword helper: re-derive with the stored salt and compare in constant time. Do not compare the Base64 strings with ==, which short-circuits on the first differing character and leaks timing information.

using System.Security.Cryptography;
using Decode.Cryptography;

// storedSalt and storedHash come from your database
string candidate = Hash.HashPasswordToBase64String(attemptedPassword, storedSalt);

bool isValid = CryptographicOperations.FixedTimeEquals(
    Convert.FromBase64String(candidate),
    Convert.FromBase64String(storedHash));

Pass the same iterations and hashSize used when the password was first hashed, if you overrode the defaults.

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);

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: VerifySha256 and VerifyHmacSha256 use FixedTimeEquals, so they do not leak information through timing. Password verification is your code's responsibility — follow the recipe above.
• 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.
• Not a password-storage framework: there is no built-in rehash-on-login, no versioned hash format and no iteration count embedded in the output. If you need those, store the parameters yourself alongside the salt and hash.

📄 License

MIT License.