```html

PHP libsodium 现代加密库使用教程

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

✅ 基础准备

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

var_dump(function_exists('sodium_crypto_secretbox')); // 应返回 true

🔒 对称加密：AES 替代方案（XChaCha20-Poly1305）

推荐使用 sodium_crypto_secretbox() 进行认证加密（AEAD），自动处理 nonce 和 MAC：

<?php
$key = sodium_crypto_secretbox_keygen(); // 32 字节密钥
$nonce = sodium_crypto_secretbox_noncegen(); // 24 字节随机数
$message = "Hello, secure world!";

// 加密
$ciphertext = sodium_crypto_secretbox($message, $nonce, $key);

// 解密（需相同 key + nonce）
$plaintext = sodium_crypto_secretbox_open($ciphertext, $nonce, $key);
if ($plaintext === false) {
    throw new Exception("解密失败：密钥或 nonce 错误");
}
echo $plaintext; // Hello, secure world!
?>

🔑 非对称加密：密钥交换与签名

使用 crypto_box 实现安全通信（基于 X25519 + XSalsa20-Poly1305）：

<?php
// Alice 生成密钥对
[$alice_secret, $alice_public] = sodium_crypto_box_keypair();
[$bob_secret, $bob_public] = sodium_crypto_box_keypair();

$message = "Top secret!";
$nonce = sodium_crypto_box_noncegen();

// Alice 用 Bob 公钥加密
$cipher = sodium_crypto_box($message, $nonce, $bob_public, $alice_secret);

// Bob 用自己的私钥解密
$plain = sodium_crypto_box_open($cipher, $nonce, $alice_public, $bob_secret);
echo $plain; // Top secret!
?>

🛡️ 密码哈希：安全存储用户密码

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

<?php
$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 "密码正确";
}
?>

libsodium 让安全不再复杂——它把“正确做事”变成默认行为。拥抱现代密码学，从今天启用 sodium_* 函数开始。

```