Cryptography

Comprehensive guidance for implementing cryptographic operations securely, covering encryption algorithms, password hashing, TLS, and key management.

When to Use This Skill

Use this skill when:

Choosing encryption algorithms
Implementing password hashing
Configuring TLS/SSL
Managing cryptographic keys
Implementing digital signatures
Generating random values
Reviewing cryptographic implementations
Considering post-quantum readiness

Algorithm Quick Reference

Encryption Algorithms

Algorithm	Type	Key Size	Use Case	Status
AES-256-GCM	Symmetric	256 bits	Data encryption	✅ Recommended
ChaCha20-Poly1305	Symmetric	256 bits	Data encryption (mobile)	✅ Recommended
RSA-OAEP	Asymmetric	2048+ bits	Key exchange	✅ Recommended
ECDH (P-256)	Asymmetric	256 bits	Key agreement	✅ Recommended
X25519	Asymmetric	256 bits	Key agreement	✅ Recommended
DES	Symmetric	56 bits	None	❌ Deprecated
3DES	Symmetric	168 bits	Legacy only	⚠️ Avoid
Blowfish	Symmetric	32-448 bits	None	⚠️ Avoid

Signature Algorithms

Algorithm	Type	Key Size	Use Case	Status
Ed25519	EdDSA	256 bits	Signatures	✅ Recommended
ECDSA (P-256)	ECC	256 bits	Signatures, JWT	✅ Recommended
RSA-PSS	RSA	2048+ bits	Signatures	✅ Recommended
RSA PKCS#1 v1.5	RSA	2048+ bits	Legacy signatures	⚠️ Use PSS instead

Hash Functions

Algorithm	Output Size	Use Case	Status
SHA-256	256 bits	General hashing	✅ Recommended
SHA-384	384 bits	Higher security	✅ Recommended
SHA-512	512 bits	Highest security	✅ Recommended
SHA-3-256	256 bits	Alternative to SHA-2	✅ Recommended
BLAKE2b	256-512 bits	Fast hashing	✅ Recommended
MD5	128 bits	None (broken)	❌ Never use
SHA-1	160 bits	None (broken)	❌ Never use

Password Hashing

Never use general-purpose hash functions (SHA-256, MD5) for passwords.

Algorithm Comparison

Algorithm	Recommended	Memory-Hard	Notes
Argon2id	✅ Best	Yes	Winner of PHC, recommended for new systems
bcrypt	✅ Good	No	Widely supported, proven
scrypt	✅ Good	Yes	Good but complex to tune
PBKDF2	⚠️ Acceptable	No	NIST approved, but GPU-vulnerable

Argon2id (Recommended)

using Konscious.Security.Cryptography;
using System.Security.Cryptography;
using System.Text;

/// <summary>
/// Argon2id password hasher with OWASP 2023 recommended parameters.
/// </summary>
public static class Argon2PasswordHasher
{
    private const int DegreeOfParallelism = 4;
    private const int MemorySize = 65536;  // 64 MB
    private const int Iterations = 3;
    private const int HashLength = 32;
    private const int SaltLength = 16;

    /// <summary>
    /// Hash password with Argon2id.
    /// </summary>
    public static string Hash(string password)
    {
        var salt = RandomNumberGenerator.GetBytes(SaltLength);
        var hash = ComputeHash(password, salt);

        // Return in PHC format: $argon2id$v=19$m=65536,t=3,p=4$salt$hash
        return $"$argon2id$v=19$m={MemorySize},t={Iterations},p={DegreeOfParallelism}${Convert.ToBase64String(salt)}${Convert.ToBase64String(hash)}";
    }

    /// <summary>
    /// Verify password against stored hash.
    /// </summary>
    public static bool Verify(string storedHash, string password)
    {
        var parts = ParseHash(storedHash);
        if (parts is null) return false;

        var computedHash = ComputeHash(password, parts.Value.Salt);
        return CryptographicOperations.FixedTimeEquals(computedHash, parts.Value.Hash);
    }

    private static byte[] ComputeHash(string password, byte[] salt)
    {
        using var argon2 = new Argon2id(Encoding.UTF8.GetBytes(password))
        {
            Salt = salt,
            DegreeOfParallelism = DegreeOfParallelism,
            MemorySize = MemorySize,
            Iterations = Iterations
        };
        return argon2.GetBytes(HashLength);
    }

    private static (byte[] Salt, byte[] Hash)? ParseHash(string storedHash)
    {
        // Parse PHC format: $argon2id$v=19$m=...,t=...,p=...$salt$hash
        var parts = storedHash.Split('$');
        if (parts.Length < 6) return null;

        var salt = Convert.FromBase64String(parts[4]);
        var hash = Convert.FromBase64String(parts[5]);
        return (salt, hash);
    }
}

// Usage
var hash = Argon2PasswordHasher.Hash("user_password");
// Returns: $argon2id$v=19$m=65536,t=3,p=4$...

if (Argon2PasswordHasher.Verify(hash, "user_password"))
{
    // Password valid
}

bcrypt

using BCrypt.Net;

// Hash password (work factor 12 = 2^12 iterations)
var passwordHash = BCrypt.Net.BCrypt.HashPassword("user_password", workFactor: 12);

// Verify password
if (BCrypt.Net.BCrypt.Verify("user_password", passwordHash))
{
    Console.WriteLine("Password valid");
}

Work Factor Guidelines

Algorithm	Minimum	Recommended	High Security
Argon2id	t=2, m=19MB	t=3, m=64MB	t=4, m=128MB
bcrypt	10	12	14
scrypt	N=2^14	N=2^16	N=2^18
PBKDF2	310,000	600,000	1,000,000

For detailed password hashing guidance: See Password Hashing Reference

Symmetric Encryption

AES-256-GCM (Recommended)

using System.Security.Cryptography;

/// <summary>
/// AES-256-GCM encryption utilities.
/// </summary>
public static class AesGcmEncryption
{
    private const int NonceSize = 12;  // 96 bits
    private const int TagSize = 16;    // 128 bits
    private const int KeySize = 32;    // 256 bits

    /// <summary>
    /// Encrypt data with AES-256-GCM. Returns nonce + ciphertext + tag.
    /// </summary>
    public static byte[] Encrypt(ReadOnlySpan<byte> plaintext, ReadOnlySpan<byte> key)
    {
        var nonce = RandomNumberGenerator.GetBytes(NonceSize);
        var ciphertext = new byte[plaintext.Length];
        var tag = new byte[TagSize];

        using var aes = new AesGcm(key, TagSize);
        aes.Encrypt(nonce, plaintext, ciphertext, tag);

        // Combine: nonce + ciphertext + tag
        var result = new byte[NonceSize + ciphertext.Length + TagSize];
        nonce.CopyTo(result.AsSpan(0, NonceSize));
        ciphertext.CopyTo(result.AsSpan(NonceSize));
        tag.CopyTo(result.AsSpan(NonceSize + ciphertext.Length));

        return result;
    }

    /// <summary>
    /// Decrypt data with AES-256-GCM. Input is nonce + ciphertext + tag.
    /// </summary>
    public static byte[] Decrypt(ReadOnlySpan<byte> combined, ReadOnlySpan<byte> key)
    {
        var nonce = combined[..NonceSize];
        var ciphertext = combined[NonceSize..^TagSize];
        var tag = combined[^TagSize..];

        var plaintext = new byte[ciphertext.Length];

        using var aes = new AesGcm(key, TagSize);
        aes.Decrypt(nonce, ciphertext, tag, plaintext);

        return plaintext;
    }

    /// <summary>
    /// Generate a secure 256-bit key.
    /// </summary>
    public static byte[] GenerateKey() => RandomNumberGenerator.GetBytes(KeySize);
}

// Usage
var key = AesGcmEncryption.GenerateKey();
var encrypted = AesGcmEncryption.Encrypt("sensitive data"u8, key);
var decrypted = AesGcmEncryption.Decrypt(encrypted, key);

Key Derivation from Password

using System.Security.Cryptography;
using System.Text;

/// <summary>
/// Derive encryption key from password using PBKDF2.
/// </summary>
public static class KeyDerivation
{
    private const int SaltSize = 16;
    private const int KeySize = 32;  // 256 bits for AES-256
    private const int Iterations = 600000;  // OWASP 2023 recommendation

    /// <summary>
    /// Derive encryption key from password. Returns (key, salt).
    /// </summary>
    public static (byte[] Key, byte[] Salt) DeriveKey(string password, byte[]? salt = null)
    {
        salt ??= RandomNumberGenerator.GetBytes(SaltSize);

        var key = Rfc2898DeriveBytes.Pbkdf2(
            password: Encoding.UTF8.GetBytes(password),
            salt: salt,
            iterations: Iterations,
            hashAlgorithm: HashAlgorithmName.SHA256,
            outputLength: KeySize
        );

        return (key, salt);  // Store salt with encrypted data
    }
}

Asymmetric Encryption

RSA Key Generation

using System.Security.Cryptography;

/// <summary>
/// RSA encryption with OAEP padding.
/// </summary>
public static class RsaEncryption
{
    /// <summary>
    /// Generate RSA key pair. Use 2048 minimum; 4096 for long-term security.
    /// </summary>
    public static RSA GenerateKeyPair(int keySizeInBits = 2048)
    {
        return RSA.Create(keySizeInBits);
    }

    /// <summary>
    /// Encrypt with public key using OAEP-SHA256.
    /// </summary>
    public static byte[] Encrypt(byte[] plaintext, RSA publicKey)
    {
        return publicKey.Encrypt(plaintext, RSAEncryptionPadding.OaepSHA256);
    }

    /// <summary>
    /// Decrypt with private key using OAEP-SHA256.
    /// </summary>
    public static byte[] Decrypt(byte[] ciphertext, RSA privateKey)
    {
        return privateKey.Decrypt(ciphertext, RSAEncryptionPadding.OaepSHA256);
    }
}

// Usage
using var rsa = RsaEncryption.GenerateKeyPair(4096);
var publicKey = rsa.ExportRSAPublicKey();

var ciphertext = RsaEncryption.Encrypt(plaintext, rsa);
var decrypted = RsaEncryption.Decrypt(ciphertext, rsa);

Digital Signatures

using System.Security.Cryptography;

/// <summary>
/// Ed25519 digital signatures (via ECDsa with curve).
/// Note: .NET 10 has native Ed25519 support.
/// </summary>
public static class DigitalSignatures
{
    /// <summary>
    /// Create ECDSA key pair (P-256, widely supported).
    /// </summary>
    public static ECDsa CreateEcdsaKeyPair()
    {
        return ECDsa.Create(ECCurve.NamedCurves.nistP256);
    }

    /// <summary>
    /// Sign message with ECDSA-SHA256.
    /// </summary>
    public static byte[] Sign(byte[] message, ECDsa privateKey)
    {
        return privateKey.SignData(message, HashAlgorithmName.SHA256);
    }

    /// <summary>
    /// Verify signature.
    /// </summary>
    public static bool Verify(byte[] message, byte[] signature, ECDsa publicKey)
    {
        return publicKey.VerifyData(message, signature, HashAlgorithmName.SHA256);
    }
}

// Usage
using var ecdsa = DigitalSignatures.CreateEcdsaKeyPair();

var signature = DigitalSignatures.Sign(message, ecdsa);

if (DigitalSignatures.Verify(message, signature, ecdsa))
{
    Console.WriteLine("Signature valid");
}
else
{
    Console.WriteLine("Signature invalid");
}

For detailed algorithm selection guidance: See Algorithm Selection Guide

TLS Configuration

Recommended TLS Settings

# Nginx TLS configuration
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305;
ssl_prefer_server_ciphers off;

# HSTS (HTTP Strict Transport Security)
add_header Strict-Transport-Security "max-age=63072000; includeSubDomains; preload" always;

# OCSP Stapling
ssl_stapling on;
ssl_stapling_verify on;
resolver 8.8.8.8 8.8.4.4 valid=300s;

TLS Version Requirements

Version	Status	Notes
TLS 1.3	✅ Required	Best security, improved performance
TLS 1.2	✅ Acceptable	Still secure with proper ciphers
TLS 1.1	❌ Deprecated	Disabled since 2020
TLS 1.0	❌ Deprecated	Major vulnerabilities
SSL 3.0	❌ Broken	POODLE attack
SSL 2.0	❌ Broken	Many vulnerabilities

For detailed TLS configuration: See TLS Configuration Guide

Key Management

Key Hierarchy

┌─────────────────────────────────────┐
│  Master Key (KEK)                   │  <- Stored in HSM or KMS
│  - Encrypts all other keys          │
└──────────────────┬──────────────────┘
                   │
       ┌───────────┴───────────┐
       ▼                       ▼
┌──────────────┐      ┌──────────────┐
│  Data Key 1  │      │  Data Key 2  │  <- Encrypted with KEK
│  (DEK)       │      │  (DEK)       │
└──────────────┘      └──────────────┘

Key Rotation Strategy

/// <summary>
/// Key manager with automatic rotation support.
/// </summary>
public sealed class KeyManager(IKmsClient kmsClient) : IDisposable
{
    private static readonly TimeSpan RotationPeriod = TimeSpan.FromDays(90);

    private string? _currentKeyId;
    private DateTime? _keyExpiry;
    private readonly SemaphoreSlim _lock = new(1, 1);

    /// <summary>
    /// Get current encryption key, rotating if needed.
    /// </summary>
    public async Task<string> GetCurrentKeyAsync(CancellationToken cancellationToken = default)
    {
        await _lock.WaitAsync(cancellationToken);
        try
        {
            if (NeedsRotation())
            {
                await RotateKeyAsync(cancellationToken);
            }
            return _currentKeyId!;
        }
        finally
        {
            _lock.Release();
        }
    }

    private bool NeedsRotation() =>
        _keyExpiry is null || DateTime.UtcNow > _keyExpiry;

    private async Task RotateKeyAsync(CancellationToken cancellationToken)
    {
        // Create new key in KMS
        var newKey = await kmsClient.CreateKeyAsync(
            description: $"Data key created {DateTime.UtcNow:O}",
            keyUsage: KeyUsage.EncryptDecrypt,
            cancellationToken: cancellationToken
        );

        _currentKeyId = newKey.KeyId;
        _keyExpiry = DateTime.UtcNow.Add(RotationPeriod);

        // Keep old keys for decryption (don't delete immediately)
        // Data encrypted with old keys can still be decrypted
    }

    public void Dispose() => _lock.Dispose();
}

// KMS client interface (implement for Azure Key Vault, AWS KMS, etc.)
public interface IKmsClient
{
    Task<KmsKey> CreateKeyAsync(string description, KeyUsage keyUsage, CancellationToken cancellationToken);
}

public enum KeyUsage { EncryptDecrypt, SignVerify }
public sealed record KmsKey(string KeyId, DateTime CreatedAt);

Random Number Generation

using System.Security.Cryptography;

// For cryptographic use - ALWAYS use these
var secureRandomBytes = RandomNumberGenerator.GetBytes(32);  // 32 random bytes
var secureRandomHex = Convert.ToHexString(RandomNumberGenerator.GetBytes(32));  // 64 hex chars
var secureRandomUrl = Convert.ToBase64String(RandomNumberGenerator.GetBytes(32))
    .Replace('+', '-').Replace('/', '_').TrimEnd('=');  // URL-safe base64

// For random integers in a range (e.g., tokens, OTPs)
var randomInt = RandomNumberGenerator.GetInt32(100000, 999999);  // 6-digit OTP

// NEVER use for cryptography
var random = new Random();
random.Next();  // NOT cryptographically secure - for games/simulations only

Post-Quantum Considerations

Current asymmetric algorithms (RSA, ECDSA, ECDH) are vulnerable to quantum computers.

NIST Post-Quantum Standards (2024)

Algorithm	Type	Status
ML-KEM (Kyber)	Key Encapsulation	✅ Standardized
ML-DSA (Dilithium)	Digital Signature	✅ Standardized
SLH-DSA (SPHINCS+)	Digital Signature	✅ Standardized

Hybrid Approach (Recommended Now)

// Combine classical and post-quantum algorithms
// If either is broken, the other still provides security

// Key exchange: X25519 + ML-KEM-768
// Signature: ECDSA P-256 + ML-DSA-65

// .NET 10+ will include ML-KEM and ML-DSA support
// Until then, use libraries like BouncyCastle for PQ algorithms

// This provides defense-in-depth during the transition period:
// 1. Classical algorithms handle today's threats
// 2. PQ algorithms protect against future quantum attacks
// 3. Combined key material ensures security if either is compromised

Quick Decision Tree

What cryptographic operation do you need?

Encrypt data at rest → AES-256-GCM
Encrypt data in transit → TLS 1.3
Hash passwords → Argon2id
Hash data (non-password) → SHA-256 or BLAKE2b
Digital signatures → Ed25519 or ECDSA P-256
Key exchange → X25519 or ECDH P-256
Message authentication → HMAC-SHA256
Generate random values → RandomNumberGenerator.GetBytes() or RandomNumberGenerator.GetInt32()

Security Checklist

Encryption

Use authenticated encryption (AES-GCM, ChaCha20-Poly1305)
Generate keys with sufficient entropy (256 bits)
Never reuse nonces/IVs
Implement proper key management

Password Hashing

Use Argon2id, bcrypt, or scrypt
Never use MD5, SHA-1, or unsalted hashes
Use appropriate work factors
Implement rehashing when parameters change

TLS

TLS 1.2 minimum, prefer TLS 1.3
Strong cipher suites only
Valid certificates from trusted CA
Enable HSTS

Keys

Secure key generation
Proper key storage (HSM/KMS for sensitive keys)
Key rotation policy
Secure key destruction

References

Algorithm Selection Guide - Detailed algorithm comparison
Password Hashing Reference - Password hashing deep dive
TLS Configuration Guide - TLS setup for various platforms

Related Skills

Skill	Relationship
`authentication-patterns`	Uses cryptography for JWT, sessions
`secrets-management`	Secure storage of cryptographic keys
`secure-coding`	General secure implementation patterns

Version History

v1.0.0 (2025-12-26): Initial release with algorithms, password hashing, TLS, key management

Last Updated: 2025-12-26