cryptography

密码学

关于安全实施密码学操作的全面指南，涵盖加密算法、密码哈希、TLS 和密钥管理。

何时使用此技能

在以下情况下使用此技能：

• 选择加密算法
• 实施密码哈希
• 配置 TLS/SSL
• 管理密钥
• 实施数字签名
• 生成随机值
• 审查密码学实现
• 考虑后量子就绪情况

算法快速参考

加密算法

算法	类型	密钥长度	用例	状态
AES-256-GCM	对称	256 位	数据加密	✅ 推荐
ChaCha20-Poly1305	对称	256 位	数据加密（移动设备）	✅ 推荐
RSA-OAEP	非对称	2048+ 位	密钥交换	✅ 推荐
ECDH (P-256)	非对称	256 位	密钥协商	✅ 推荐
X25519	非对称	256 位	密钥协商	✅ 推荐
DES	对称	56 位	无	❌ 已弃用
3DES	对称	168 位	仅限旧系统	⚠️ 避免使用
Blowfish	对称	32-448 位	无	⚠️ 避免使用

签名算法

算法	类型	密钥长度	用例	状态
Ed25519	EdDSA	256 位	签名	✅ 推荐
ECDSA (P-256)	ECC	256 位	签名、JWT	✅ 推荐
RSA-PSS	RSA	2048+ 位	签名	✅ 推荐
RSA PKCS#1 v1.5	RSA	2048+ 位	旧版签名	⚠️ 改用 PSS

哈希函数

算法	输出长度	用例	状态
SHA-256	256 位	通用哈希	✅ 推荐
SHA-384	384 位	更高安全性	✅ 推荐
SHA-512	512 位	最高安全性	✅ 推荐
SHA-3-256	256 位	SHA-2 的替代方案	✅ 推荐
BLAKE2b	256-512 位	快速哈希	✅ 推荐
MD5	128 位	无（已破解）	❌ 切勿使用
SHA-1	160 位	无（已破解）	❌ 切勿使用

密码哈希

切勿将通用哈希函数（SHA-256、MD5）用于密码。

算法对比

算法	推荐程度	内存硬化	备注
Argon2id	✅ 最佳	是	PHC 获胜算法，推荐用于新系统
bcrypt	✅ 良好	否	广泛支持，经过验证
scrypt	✅ 良好	是	效果良好，但参数调优复杂
PBKDF2	⚠️ 可接受	否	获得 NIST 批准，但易受 GPU 攻击

Argon2id（推荐）

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

工作因子指南

算法	最低	推荐	高安全性
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

**密码哈希详细指南：**参见密码哈希参考

对称加密

AES-256-GCM（推荐）

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

从密码派生密钥

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
    }
}

非对称加密

RSA 密钥生成

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

数字签名

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

**算法选择详细指南：**参见算法选择指南

TLS 配置

推荐的 TLS 设置

# 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 版本要求

版本	状态	备注
TLS 1.3	✅ 必需	安全性最佳，性能有所提升
TLS 1.2	✅ 可接受	配置适当的密码套件后仍然安全
TLS 1.1	❌ 已弃用	自 2020 年起禁用
TLS 1.0	❌ 已弃用	存在严重漏洞
SSL 3.0	❌ 已破解	POODLE 攻击
SSL 2.0	❌ 已破解	存在许多漏洞

**TLS 配置详细指南：**参见TLS 配置指南

密钥管理

密钥层级

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

密钥轮换策略

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

随机数生成

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

后量子考量

当前的非对称算法（RSA、ECDSA、ECDH）容易受到量子计算机攻击。

NIST 后量子标准（2024 年）

算法	类型	状态
ML-KEM (Kyber)	密钥封装	✅ 已标准化
ML-DSA (Dilithium)	数字签名	✅ 已标准化
SLH-DSA (SPHINCS+)	数字签名	✅ 已标准化

混合方案（当前推荐）

// 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

快速决策树

你需要执行什么加密操作？

1. 加密静态数据 → AES-256-GCM
2. 加密传输中的数据 → TLS 1.3
3. 哈希密码 → Argon2id
4. 哈希数据（非密码） → SHA-256 或 BLAKE2b
5. 数字签名 → Ed25519 或 ECDSA P-256
6. 密钥交换 → X25519 或 ECDH P-256
7. 消息认证 → HMAC-SHA256
8. 生成随机值 → RandomNumberGenerator.GetBytes() 或 RandomNumberGenerator.GetInt32()

安全检查清单

加密

• 使用认证加密（AES-GCM、ChaCha20-Poly1305）
• 使用足够的熵生成密钥（256 位）
• 切勿重复使用随机数/初始向量
• 实施妥善的密钥管理

密码哈希

• 使用 Argon2id、bcrypt 或 scrypt
• 切勿使用 MD5、SHA-1 或不加盐的哈希
• 使用适当的工作因子
• 参数变更时实施重新哈希

TLS

• 最低使用 TLS 1.2，优先使用 TLS 1.3
• 仅使用强加密套件
• 使用受信任 CA 签发的有效证书
• 启用 HSTS

密钥

• 安全地生成密钥
• 妥善存储密钥（敏感密钥使用 HSM/KMS）
• 制定密钥轮换策略
• 安全销毁密钥

参考资料

• 算法选择指南 - 详细的算法比较
• 密码哈希参考 - 深入了解密码哈希
• TLS 配置指南 - 各平台的 TLS 设置

相关技能

技能	关联
authentication-patterns	使用加密技术实现 JWT、会话
secrets-management	安全存储加密密钥
secure-coding	通用安全实现模式

版本历史

• v1.0.0 (2025-12-26)：首次发布，包含算法、密码哈希、TLS、密钥管理

---

最后更新： 2025-12-26