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規則集的儲存庫。
