```html

PHP libsodium 现代加密库使用教程

自 PHP 7.2 起，libsodium 已作为核心扩展内置，无需额外安装（Windows 用户需确认启用 extension=sodium）。它基于 NaCl（Networking and Cryptography Library），提供**易用、安全、抗侧信道攻击**的现代加密原语，是替代 mcrypt、openssl 手动实现的理想选择。

✅ 基础准备

检查是否可用：

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

🔒 对称加密：AES 级别的安全，API 级别的简洁

使用 sodium_crypto_secretbox()（XSalsa20-Poly1305）进行认证加密：

<?php
// 生成 256 位密钥（32 字节）
$key = random_bytes(SODIUM_CRYPTO_SECRETBOX_KEYBYTES); // 32 bytes

// 生成 24 字节随机 nonce（每次加密必须唯一！）
$nonce = random_bytes(SODIUM_CRYPTO_SECRETBOX_NONCEBYTES); // 24 bytes

$message = "Hello, secure world!";
$ciphertext = sodium_crypto_secretbox($message, $nonce, $key);

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

🔑 非对称加密：安全密钥交换

使用 sodium_crypto_box() 实现公钥加密（X25519 + XSalsa20-Poly1305）：

<?php
// 生成密钥对
$alice_keypair = sodium_crypto_box_keypair();
$alice_secret = sodium_crypto_box_secretkey($alice_keypair);
$alice_public = sodium_crypto_box_publickey($alice_keypair);

$bob_keypair = sodium_crypto_box_keypair();
$bob_public = sodium_crypto_box_publickey($bob_keypair);

// Alice 用 Bob 公钥加密消息
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$message = "Secret for Bob only";
$encrypted = sodium_crypto_box($message, $nonce, $bob_public, $alice_secret);

// Bob 解密
$decrypted = sodium_crypto_box_open($encrypted, $nonce, $alice_public, $bob_keypair);
if ($decrypted === false) die("验证失败");
echo $decrypted; // Secret for Bob only
?>

🛡️ 密码哈希：抵御暴力与彩虹表

永远不要用 md5() 或 sha1() 存储密码！

<?php
$password = "user@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 "密码正确 ✅";
}

// 安全擦除敏感数据（PHP 7.3+）
sodium_memzero($password);
?>

✨ 小结

libsodium 不仅安全可靠，更以“防错设计”著称：默认启用认证加密、强制常数时间比较、自动内存清零。从今天起，用 sodium_crypto_* 替代所有手写加密逻辑——让安全成为默认，而非配置项。

延伸阅读：官方文档：php.net/sodium｜RFC 8439（ChaCha20/Poly1305）

```