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