👁 Image
Plinth.Security 1.8.1

README

Plinth.Security

Security, Cryptography, and Token Utilities

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

1. 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

2. Password Hashing

   • Never try to decrypt password hashes (they're one-way)
   • Let the verifier handle version detection automatically

3. 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

4. Predictable Hashing

   • Only use for data that needs to be searchable
   • Understand that identical inputs produce identical hashes
   • Use separate keys from ISecureData