```html PHP libsodium 现代加密库使用教程

PHP libsodium 现代加密库使用教程

libsodium 是 PHP 7.2+ 内置的现代加密扩展（基于 NaCl 库），提供经过严格审计、易用且安全的加密原语，无需手动管理 IV、填充或密钥派生——是替代 mcrypt 和 OpenSSL 手动调用的首选方案。

✅ 基础准备

确认已启用（PHP 7.2+ 默认开启）：

<?php
if (!extension_loaded('sodium')) {
    throw new RuntimeException('libsodium 扩展未启用');
}
echo 'libsodium 版本：' . SODIUM_LIBRARY_VERSION . "\n";
?>

🔒 对称加密：AES-like 安全性（XChaCha20-Poly1305）

推荐使用 sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() 进行认证加密：

<?php
// 生成随机密钥（32 字节）和 nonce（24 字节）
$key = sodium_crypto_aead_xchacha20poly1305_ietf_keygen();
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES);

$message = "Hello, secure world!";
$ciphertext = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt(
    $message, 
    '',           // 附加关联数据（AAD），可为空
    $nonce, 
    $key
);

// 解密
$decrypted = sodium_crypto_aead_xchacha20poly1305_ietf_decrypt(
    $ciphertext, 
    '', 
    $nonce, 
    $key
);

var_dump($decrypted === $message); // bool(true)
?>

🔑 密钥派生：从密码生成密钥（Argon2id）

安全地将用户密码转换为加密密钥：

<?php
$password = 'my-super-secret-pass';
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
$key = sodium_crypto_pwhash(
    SODIUM_CRYPTO_SECRETBOX_KEYBYTES,
    $password,
    $salt,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);
?>

🛡️ 密码哈希：存储用户凭证

使用 sodium_crypto_pwhash_str() 生成可验证的哈希（兼容 Argon2id）：

<?php
$hash = sodium_crypto_pwhash_str(
    'user_password', 
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

// 验证时无需解密 —— 直接比对
if (sodium_crypto_pwhash_str_verify($hash, 'user_password')) {
    echo "登录成功！";
}
// 自动处理哈希格式与参数校验，防时序攻击 ✅
?>

⚠️ 重要提示： • 永远不要自己实现加密逻辑；
• 使用 random_bytes() 生成密钥/nonce，禁用 mt_rand()；
• 密钥、nonce、盐值需安全存储（如数据库），但切勿硬编码；
• libsodium 函数默认抗侧信道攻击，无需额外防护。

libsodium 让安全不再是“高级话题”，而是开箱即用的工程实践。拥抱现代密码学，从一行 sodium_crypto_secretbox() 开始。

```