sodium_compat
Version 2.1.0
Sodium Compat 是 Sodium 加密库 (libsodium) 的纯 PHP 填充，它是 PHP 7.2.0+ 中的核心扩展，并且在 PECL 中可用。
如果您安装了 PHP 扩展，Sodium Compat 将机会性地、透明地使用 PHP 扩展而不是我们的实现。
odium_compat v1.21.0 是 master 分支的最后一个 v1.x 版本。从现在开始，所有支持 PHP 5.2 - 8.0 和 32 位整数的未来版本都将位于v1.x分支中。
除非需要新的主要版本，否则较新版本的odium_compat（即 v2.0.0）将继续存在于 master 分支中。这项工作的目标是提高代码的可读性和性能，同时减少样板代码。
如有疑问，请参阅 master 分支中的 README 文件以获取最新版本信息。
| 钠兼容版本 | 支持的 PHP 版本 | 32位支持吗？ | 分支 |
|---|---|---|---|
v1.xy | 5.2.4 - 最新 | 是的 | v1.x |
v2.xy | 8.1 - 最新 | 不 | 掌握 |
如果您需要 32 位 PHP 支持 ( PHP_INT_SIZE == 4 )，请继续使用odium_compat v1.x。如果您希望提高性能并减少依赖关系，请使用 v2.x。
我们建议库和框架设置 Composer 版本约束，如下所示：
{
"require" : {
/* ... */
"paragonie/sodium_compat" : ">= 1"
/* ... */
}
}相反，应用程序应该指定对其及其部署重要的实际版本。
该密码学库尚未经过专门从事密码学或密码分析的独立第三方的正式审核。
如果您在项目中使用odium_compat 之前需要进行此类审核，并且有资金进行此类审核，请提出问题或联系security at paragonie dot com以便我们帮助您顺利开展工作。
然而，sodium_compat 已被备受瞩目的开源项目采用，例如 Joomla!和马真托。此外，sodium_compat 是由 Paragon Initiative Enterprises（一家专门从事安全 PHP 开发和 PHP 加密技术的公司）开发的，并且已经过许多其他同样专门研究 PHP 的安全专家的非正式审查。
如果您想详细了解我们为防止odium_compat 成为系统漏洞来源而采取的防御性安全措施，请阅读加密安全 PHP 开发。
如果您使用 Composer：
composer require paragonie/sodium_compat如果您不使用 Composer，请下载发布 tarball（应使用我们的 GnuPG 公钥进行签名），提取其内容，然后将我们的autoload.php脚本包含在您的项目中。
<?php
require_once " /path/to/sodium_compat/autoload.php " ;自版本 1.3.0 起，sodium_compat 版本包含 PHP 存档（.phar 文件）和关联的 GPG 签名。首先，下载这两个文件并使用我们的 GPG 公钥验证它们，如下所示：
# Getting our public key from the keyserver:
gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
if [ $? -ne 0 ] ; then
echo -e " 33[33mDownloading PGP Public Key... 33[0m "
gpg --keyserver pgp.mit.edu --recv-keys 7F52D5C61D1255C731362E826B97A1C2826404DA
# Security <[email protected]>
gpg --fingerprint 7F52D5C61D1255C731362E826B97A1C2826404DA
if [ $? -ne 0 ] ; then
echo -e " 33[31mCould not download PGP public key for verification 33[0m "
exit 1
fi
fi
# Verifying the PHP Archive
gpg --verify sodium-compat.phar.sig sodium-compat.phar现在，只需将此 .phar 文件包含在您的应用程序中即可。
<?php
require_once " /path/to/sodium-compat.phar " ;多家供应商都提供了对 libsodium 的商业支持。如果您需要在您的项目之一中使用odium_compat 的帮助，请联系 Paragon Initiative Enterprises。
非商业报告将通过 Github issues 进行促进。我们不保证我们可以免费解决有关将odium_compat 集成到第三方软件中的问题，但将努力修复我们库中的任何错误（与安全相关或其他方面）。
如果您的公司在其产品或服务中使用此库，您可能有兴趣从 Paragon Initiative Enterprises 购买支持合同。
根据 libsodium RFC 的第二次投票，PHP 7.2 使用sodium_*而不是Sodium* 。
<?php
require_once " /path/to/sodium_compat/autoload.php " ;
$ alice_kp = sodium_crypto_sign_keypair ();
$ alice_sk = sodium_crypto_sign_secretkey ( $ alice_kp );
$ alice_pk = sodium_crypto_sign_publickey ( $ alice_kp );
$ message = ' This is a test message. ' ;
$ signature = sodium_crypto_sign_detached ( $ message , $ alice_sk );
if ( sodium_crypto_sign_verify_detached ( $ signature , $ message , $ alice_pk )) {
echo ' OK ' , PHP_EOL ;
} else {
throw new Exception ( ' Invalid signature ' );
}如果您的用户使用 PHP < 5.3，或者您想要编写无论 PECL 扩展是否可用都可以工作的代码，您将需要使用ParagonIE_Sodium_Compat类来满足您的大部分 libsodium 需求。
上面的例子是为一般用途而写的：
<?php
require_once " /path/to/sodium_compat/autoload.php " ;
$ alice_kp = ParagonIE_Sodium_Compat:: crypto_sign_keypair ();
$ alice_sk = ParagonIE_Sodium_Compat:: crypto_sign_secretkey ( $ alice_kp );
$ alice_pk = ParagonIE_Sodium_Compat:: crypto_sign_publickey ( $ alice_kp );
$ message = ' This is a test message. ' ;
$ signature = ParagonIE_Sodium_Compat:: crypto_sign_detached ( $ message , $ alice_sk );
if (ParagonIE_Sodium_Compat:: crypto_sign_verify_detached ( $ signature , $ message , $ alice_pk )) {
echo ' OK ' , PHP_EOL ;
} else {
throw new Exception ( ' Invalid signature ' );
}一般来说：如果您用ParagonIE_Sodium_Compat::替换sodium_ ，任何已经为 libsodium PHP 扩展编写的代码都应该可以与我们的 polyfill 一起使用，而无需进行额外的代码更改。
由于这不需要命名空间，因此该 API 在 PHP 5.2 上公开。
从版本 0.7.0 开始，我们拥有自己的命名空间 API ( ParagonIESodium* )，以简化使用 PHP 5.3+ 的软件。如果您想使用我们的文件加密功能而不是每次都写入ParagonIE_Sodium_File这非常有用。这在 PHP < 5.3 上没有公开，因此如果您的项目支持 PHP < 5.3，请改用下划线方法。
要了解如何使用 Libsodium，请阅读在 PHP 项目中使用 Libsodium 。
可以通过三种方法来加快速度：
ParagonIE_Sodium_Compat::$fastMult = true;不会损害您的加密密钥的安全性。如果您的处理器不安全，请决定您想要速度还是安全，因为您无法两者兼得。从1.8版本开始，您可以使用polyfill_is_fast()静态方法来确定sodium_compat在运行时是否会变慢。
<?php
if (ParagonIE_Sodium_Compat:: polyfill_is_fast ()) {
// Use libsodium now
$ process -> execute ();
} else {
// Defer to a cron job or other sort of asynchronous process
$ process -> enqueue ();
}首先，您需要阅读 Libsodium 快速参考。它的目的是回答“我应该使用哪个函数来解决[常见问题]？”。
如果您在快速参考页面中找不到答案，请查看在 PHP 项目中使用 Libsodium 。
最后，官方 libsodium 文档（是为 C 库而不是 PHP 库编写的）还包含许多有洞察力的技术信息，您可能会觉得有用。
推荐阅读： Libsodium 快速参考
crypto_auth()crypto_auth_verify()crypto_box()crypto_box_open()crypto_scalarmult()crypto_secretbox()crypto_secretbox_open()crypto_sign()crypto_sign_open()crypto_aead_aegis128l_encrypt()crypto_aead_aegis128l_decrypt()crypto_aead_aegis256_encrypt()crypto_aead_aegis256_decrypt()crypto_aead_aes256gcm_encrypt()crypto_aead_aes256gcm_decrypt()crypto_aead_chacha20poly1305_encrypt()crypto_aead_chacha20poly1305_decrypt()crypto_aead_chacha20poly1305_ietf_encrypt()crypto_aead_chacha20poly1305_ietf_decrypt()crypto_aead_xchacha20poly1305_ietf_encrypt()crypto_aead_xchacha20poly1305_ietf_decrypt()crypto_box_xchacha20poly1305()crypto_box_xchacha20poly1305_open()crypto_box_seal()crypto_box_seal_open()crypto_generichash()crypto_generichash_init()crypto_generichash_update()crypto_generichash_final()crypto_kx()crypto_secretbox_xchacha20poly1305()crypto_secretbox_xchacha20poly1305_open()crypto_shorthash()crypto_sign_detached()crypto_sign_ed25519_pk_to_curve25519()crypto_sign_ed25519_sk_to_curve25519()crypto_sign_verify_detached()crypto_core_ristretto255_add()crypto_core_ristretto255_from_hash()crypto_core_ristretto255_is_valid_point()crypto_core_ristretto255_random()crypto_core_ristretto255_scalar_add()crypto_core_ristretto255_scalar_complement()crypto_core_ristretto255_scalar_invert()crypto_core_ristretto255_scalar_mul()crypto_core_ristretto255_scalar_negate()crypto_core_ristretto255_scalar_random()crypto_core_ristretto255_scalar_reduce()crypto_core_ristretto255_scalar_sub()crypto_core_ristretto255_sub()crypto_scalarmult_ristretto255_base()crypto_scalarmult_ristretto255()crypto_stream()crypto_stream_keygen()crypto_stream_xor()crypto_stream_xchacha20()crypto_stream_xchacha20_keygen()crypto_stream_xchacha20_xor()crypto_stream_xchacha20_xor_ic()crypto_*_keypair() ）add()base642bin()bin2base64()bin2hex()hex2bin()crypto_kdf_derive_from_key()crypto_kx_client_session_keys()crypto_kx_server_session_keys()crypto_secretstream_xchacha20poly1305_init_push()crypto_secretstream_xchacha20poly1305_push()crypto_secretstream_xchacha20poly1305_init_pull()crypto_secretstream_xchacha20poly1305_pull()crypto_secretstream_xchacha20poly1305_rekey()pad()unpad()sodium_memzero() - 尽管我们公开了此 API 端点，但我们无法可靠地将 PHP 的缓冲区清零。
如果您安装了 PHP 扩展，sodium_compat 将使用本机实现将提供的字符串清零。否则它将抛出SodiumException 。
sodium_crypto_pwhash() - 将 scrypt 或 Argon2 填充到 PHP 中并获得合理的性能是不可行的。用户会感到有动力选择降低安全性的参数以避免拒绝服务 (DoS) 攻击。
唯一的胜利之举就是不玩。
如果安装了 ext/sodium 或 ext/libsodium，这些 API 方法将落入扩展程序。否则，我们的 polyfill 库将抛出SodiumException 。
要在运行时检测对 Argon2i 的支持，请使用ParagonIE_Sodium_Compat::crypto_pwhash_is_available() ，它返回一个布尔值（ TRUE或FALSE ）。
Libsodium 的 HKDF API ( crypto_kdf_hkdf_*() ) 不包括在内，因为 PHP 有自己的 HMAC 功能，并且认为没有必要。
对于odium_compat 用户以及在 CI 流程中使用PHPCompatibility的用户，现在有一个可用的自定义规则集，可用于防止PHPCompatibility对该存储库填充的本机 PHP 功能抛出误报。
您可以在 Github 和 Packagist 上找到PHPCompatibilityParagonieSodiumCompat规则集的存储库。
