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

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

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

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

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

<?php
$password = 'my-super-secret-pass';
$salt = random_bytes(SODIUM_CRYPTO_PWHASH_SALTBYTES);
$opslimit = SODIUM_CRYPTO_PWHASH_OPSLIMIT_INTERACTIVE;
$memlimit = SODIUM_CRYPTO_PWHASH_MEMLIMIT_INTERACTIVE;

$key = sodium_crypto_pwhash(
    SODIUM_CRYPTO_SECRETBOX_KEYBYTES,
    $password,
    $salt,
    $opslimit,
    $memlimit
);

echo bin2hex($key); // 32 字节密钥（十六进制）
?>

🔐 非对称加密：密钥交换（X25519）

用于安全协商共享密钥：

<?php
// Alice 生成密钥对
$alice_sk = sodium_crypto_box_keypair();
$alice_pk = sodium_crypto_box_publickey($alice_sk);
$alice_sk = sodium_crypto_box_secretkey($alice_sk);

// Bob 同理
$bob_sk = sodium_crypto_box_keypair();
$bob_pk = sodium_crypto_box_publickey($bob_sk);

// Alice 用 Bob 公钥加密消息
$message = 'Top secret!';
$nonce = random_bytes(SODIUM_CRYPTO_BOX_NONCEBYTES);
$encrypted = sodium_crypto_box($message, $nonce, $bob_pk, $alice_sk);

// Bob 解密
$decrypted = sodium_crypto_box_open($encrypted, $nonce, $alice_pk, $bob_sk);
echo $decrypted; // "Top secret!"
?>

⚠️ 重要提示：所有 nonce、salt、密钥必须唯一且不可重用；密文需与 nonce 一同存储/传输；私钥务必保密。libsodium 的设计哲学是「安全默认」——只要不绕过 API，就很难出错。

掌握 libsodium，就是拥抱现代密码学的最佳实践。它让安全不再依赖开发者对底层细节的理解，而是通过简洁、防误用的接口，真正实现“加密即服务”。立即升级你的 PHP 加密逻辑吧！

```