Provides production-ready cryptographic utilities for common security scenarios including data encryption, password hashing, and predictable hashing.
Crypto
ISecureData: Symmetric encryption utility for encrypting data in transit and at rest
IPasswordHasher: Secure storage and validation of passwords using PBKDF2
IPredictableHasher: Mechanism for producing a secure one-way hash of sensitive data that is repeatable for uniqueness checks
Tokens
A library for generating secure, Plinth-specific authentication tokens, loosely based on JWE
ISecureData - Data Encryption
ISecureData provides symmetric encryption for protecting sensitive data at rest and in transit using AES-CBC with HMAC authentication.
Setup with Single Key
using Plinth.Security.Crypto;
// Generate a 32-byte (256-bit) hex key (64 hex characters)
var encryptionKey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
var secureData = new SecureData(encryptionKey);
services.AddSingleton<ISecureData>(secureData);
Setup with Key Rotation
Support multiple keys for seamless key rotation:
var secureData = new SecureData(
defaultKeyId: 1,
keyRing: [
(0, "old_key_64_hex_chars..."),
(1, "current_key_64_hex_chars..."), // default for new encryptions
(2, "future_key_64_hex_chars...")
]
);
services.AddSingleton<ISecureData>(secureData);
Encrypting and Decrypting Data
public class UserService
{
private readonly ISecureData _secureData;
public UserService(ISecureData secureData)
{
_secureData = secureData;
}
public async Task SaveSensitiveDataAsync(string ssn)
{
// Encrypt to Base64 string (suitable for database storage)
var encrypted = _secureData.EncryptToBase64(ssn);
// Or encrypt to hex string
var encryptedHex = _secureData.EncryptToHex(ssn);
// Or encrypt to byte array
var encryptedBytes = _secureData.Encrypt(ssn);
// Save encrypted value...
}
public async Task<string> GetSensitiveDataAsync()
{
// Retrieve encrypted value...
var encrypted = "...";
// Decrypt from Base64 string
var decrypted = _secureData.DecryptBase64ToString(encrypted);
// Or decrypt from hex string
var decryptedFromHex = _secureData.DecryptHexToString(encrypted);
// Or decrypt to byte array
var decryptedBytes = _secureData.DecryptBase64(encrypted);
return decrypted;
}
}
Using Different Keys
// Encrypt with specific key ID
var encrypted = _secureData.EncryptToBase64(data, keyId: 2);
// Decryption automatically uses the correct key based on the encrypted data
var decrypted = _secureData.DecryptBase64ToString(encrypted);
Key Requirements
Keys must be 16, 24, or 32 bytes (32, 48, or 64 hex characters)
32 bytes (AES-256) is recommended for production
Store keys securely (Azure Key Vault, AWS Secrets Manager, etc.)
IPasswordHasher - Password Hashing
IPasswordHasher provides secure password hashing using PBKDF2 with SHA-256, following OWASP recommendations.
Setup
using Plinth.Security.Crypto;
var passwordHasher = new PBKDF2PasswordHasher();
services.AddSingleton<IPasswordHasher>(passwordHasher);
Hashing Passwords
public class AuthService
{
private readonly IPasswordHasher _passwordHasher;
public AuthService(IPasswordHasher passwordHasher)
{
_passwordHasher = passwordHasher;
}
public async Task RegisterUserAsync(string email, string password)
{
// Hash the password (includes salt automatically)
var hashedPassword = _passwordHasher.HashPassword(password);
// Store hashedPassword in database...
// Example: "04a1b2c3d4e5f6..."
}
public async Task<bool> LoginAsync(string email, string password)
{
// Retrieve hashed password from database...
var storedHash = "...";
// Verify password
var isValid = _passwordHasher.VerifyPasswordHash(password, storedHash);
return isValid;
}
}
Version History
The implementation supports multiple versions for backward compatibility:
Version 1: 50k iterations, SHA-1 (legacy, don't use)
Version 2: 100k iterations, SHA-1 (legacy)
Version 3: 100k iterations, SHA-256 (2016-2021)
Version 4: 310k iterations, SHA-256 (2021-2022)
Version 5: 600k iterations, SHA-256 (2023-current, recommended)
The version is automatically detected during verification, allowing seamless migration.
IPredictableHasher - Deterministic Hashing
IPredictableHasher creates deterministic hashes for sensitive data that needs to be searchable or checked for uniqueness (e.g., SSNs, credit card numbers).
Setup
using Plinth.Security.Crypto;
// Generate a 32-byte (256-bit) hex key (64 hex characters)
var hashKey = "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef";
var predictableHasher = new PBKDF2PredictableHasher(
hashKey: hashKey,
hashLength: 32, // 32 bytes recommended
iterations: 310000 // 310k iterations recommended
);
services.AddSingleton<IPredictableHasher>(predictableHasher);
Usage Example
public class UserService
{
private readonly IPredictableHasher _hasher;
private readonly ISecureData _secureData;
public UserService(IPredictableHasher hasher, ISecureData secureData)
{
_hasher = hasher;
_secureData = secureData;
}
public async Task<bool> AddSsnAsync(string ssn)
{
// Create predictable hash for uniqueness check
var ssnHash = _hasher.PredictableHash(ssn);
// Check if SSN already exists (indexed column)
if (await _db.Users.AnyAsync(u => u.SsnHash == ssnHash))
return false; // SSN already exists
// Encrypt the actual SSN for storage
var encryptedSsn = _secureData.EncryptToBase64(ssn);
// Store both encrypted SSN and hash
var user = new User
{
SsnEncrypted = encryptedSsn,
SsnHash = ssnHash // For uniqueness checks
};
await _db.Users.AddAsync(user);
await _db.SaveChangesAsync();
return true;
}
public async Task<User?> FindBySsnAsync(string ssn)
{
// Hash the SSN to search
var ssnHash = _hasher.PredictableHash(ssn);
// Search by hash (indexed)
return await _db.Users.FirstOrDefaultAsync(u => u.SsnHash == ssnHash);
}
}
Use Cases
Social Security Numbers
Credit Card Numbers
Phone Numbers
Email Addresses (for duplicate detection while maintaining privacy)
Security Considerations
Use different keys for ISecureData and IPredictableHasher
Store the hash key securely
Use at least 310k iterations for production
Consider the trade-off: predictable hashes enable searching but reveal duplicates
Best Practices
Key Management
Store all cryptographic keys in secure configuration (Azure Key Vault, AWS Secrets Manager, etc.)
Never commit keys to source control
Rotate encryption keys periodically
Use different keys for different purposes
Password Hashing
Never try to decrypt password hashes (they're one-way)
Let the verifier handle version detection automatically
Data Encryption
Use 32-byte (AES-256) keys for production
Encrypt sensitive data before storing in databases
Consider using predictable hashing for searchable encrypted data
Predictable Hashing
Only use for data that needs to be searchable
Understand that identical inputs produce identical hashes