PHP libsodium 现代加密库使用教程

自 PHP 7.2 起，libsodium 成为内置扩展（无需额外安装），提供经过严格审计、易用且安全的现代密码学原语。它替代了易出错的传统函数（如 mcrypt），是当前 PHP 加密实践的黄金标准。

✅ 基础准备

确保已启用扩展（PHP 7.2+ 默认启用）：

var_dump(extension_loaded('sodium')); // bool(true)
echo sodium_version_string(); // e.g. "1.0.18"

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

推荐使用 sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() —— 抗侧信道、支持长 nonce、性能优异：

// 生成密钥与随机 nonce
$key = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_KEYBYTES); // 32 字节
$nonce = random_bytes(SODIUM_CRYPTO_AEAD_XCHACHA20POLY1305_IETF_NPUBBYTES); // 24 字节

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

🔑 非对称加密：密钥封装（Seal/Unseal）

无需处理公私钥格式细节，自动完成密钥协商与加密：

// 生成密钥对
$kp = sodium_crypto_box_keypair();
$public = sodium_crypto_box_publickey($kp);
$secret = sodium_crypto_box_secretkey($kp);

// 封装消息（仅接收方能解）
$sealed = sodium_crypto_box_seal("Secret payload", $public);
$unsealed = sodium_crypto_box_seal_open($sealed, $public, $secret);

var_dump($unsealed); // string(15) "Secret payload"

🧾 密码哈希：安全存储用户密码

永远不用 md5() 或 sha1()！使用 sodium_crypto_pwhash_str()：

$password = "user_pass_123";
$hash = sodium_crypto_pwhash_str(
    $password,
    SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE,
    SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE
);

// 验证
if (sodium_crypto_pwhash_str_verify($hash, $password)) {
    echo "✅ 密码正确";
}

// 注意：验证失败后务必调用 sodium_memzero() 清理敏感内存（PHP 8.1+ 自动处理）

libsodium 让安全不再复杂——它把“正确”设为默认。拥抱现代密码学，从启用 sodium 开始。