sodium_compat
Version 2.1.0
Sodium Compat は、Sodium 暗号化ライブラリ (libsodium) 用の純粋な PHP ポリフィルであり、PHP 7.2.0 以降のコア拡張機能であり、PECL で利用可能です。
PHP 拡張機能がインストールされている場合、Sodium Compat は実装の代わりに PHP 拡張機能を便宜的かつ透過的に使用します。
sodium_compat v1.21.0 は、master ブランチからの最後の v1.x リリースでした。今後、PHP 5.2 ～ 8.0 および 32 ビット整数をサポートする将来のリリースはすべてv1.xブランチに含まれます。
新しいメジャー バージョンが必要でない限り、sodium_compat の新しいバージョン (v2.0.0) は引き続き master ブランチに存在します。この作業の目標は、定型コードを削減しながら、コードの可読性とパフォーマンスを向上させることです。
疑問がある場合は、master ブランチの README ファイルで最新のバージョン情報を参照してください。
| sodium_compat バージョン | サポートされている PHP バージョン | 32ビットサポート? | 支店 |
|---|---|---|---|
v1.xy | 5.2.4 - 最新 | はい | v1.x |
v2.xy | 8.1 - 最新 | いいえ | マスター |
32 ビット PHP サポート ( PHP_INT_SIZE == 4 ) が必要な場合は、引き続きsodium_compat v1.x を使用してください。パフォーマンスを向上させ、依存関係を小さくしたい場合は、v2.x を使用してください。
ライブラリとフレームワークでは、次のように Composer のバージョン制約を設定することをお勧めします。
{
"require" : {
/* ... */
"paragonie/sodium_compat" : ">= 1"
/* ... */
}
}逆に、アプリケーションは、アプリケーションとその展開にとって重要な実際のバージョンを指定する必要があります。
この暗号ライブラリは、暗号または暗号解析を専門とする独立した第三者による正式な監査を受けていません。
プロジェクトでsodium_compatを使用し、そのような監査のための資金を用意する前にそのような監査が必要な場合は、問題を報告するか、 security at paragonie dot comご連絡ください。私たちが準備をお手伝いします。
ただし、sodium_compat は、Joomla! などの注目度の高いオープンソース プロジェクトで採用されています。そしてマジェント。さらに、sodium_compat は、安全な PHP 開発と PHP 暗号化を専門とする企業である Paragon Initiative Enterprises によって開発され、同様に PHP を専門とする他の多くのセキュリティ専門家によって非公式にレビューされています。
sodium_compat がシステムの脆弱性の原因となるのを防ぐために当社が講じた防御セキュリティ対策について詳しく知りたい場合は、 「暗号的に安全な PHP 開発」を参照してください。
Composer を使用している場合:
composer require paragonie/sodium_compatComposer を使用していない場合は、リリース 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 の商用サポートは複数のベンダーから入手できます。プロジェクトのいずれかでsodium_compatを使用する際にサポートが必要な場合は、Paragon Initiative Enterprisesにお問い合わせください。
非営利的なレポートは、Github の問題を通じて促進されます。私たちは、sodium_compat をサードパーティ ソフトウェアに無料で統合することに関する質問を解決できるという保証はありませんが、ライブラリ内のバグ (セキュリティ関連またはその他) を修正するよう努めます。
あなたの会社が製品またはサービスでこのライブラリを使用している場合は、Paragon Initiative Enterprises からサポート契約を購入することに興味があるかもしれません。
libsodium RFC の 2 番目の投票に従って、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 拡張機能が利用可能かどうかに関係なく動作するコードを作成したい場合は、libsodium のニーズのほとんどにParagonIE_Sodium_Compatクラスを使用することをお勧めします。
上記の例は、一般的な使用のために書かれています。
<?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 ' );
}一般的に: sodium_ ParagonIE_Sodium_Compat::に置き換えると、libsodium PHP 拡張機能用にすでに記述されているコードは、コードを追加変更することなくポリフィルで動作するはずです。
これには名前空間が必要ないため、この API は PHP 5.2 で公開されます。
バージョン 0.7.0 以降、PHP 5.3 以降を使用するソフトウェアを簡潔にするために、独自の名前空間 API ( ParagonIESodium* ) が使用されています。これは、毎回ParagonIE_Sodium_Fileを書き込まずにファイル暗号化機能を使用したい場合に便利です。これは PHP < 5.3 では公開されていないため、プロジェクトが PHP < 5.3 をサポートしている場合は、代わりにアンダースコア方式を使用してください。
Libsodium の使用方法については、 「PHP プロジェクトでの Libsodium の使用」を参照してください。
高速化するには次の 3 つの方法があります。
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 の公式ドキュメント (PHP ライブラリではなく C ライブラリ用に書かれたもの) にも、役立つと思われる洞察力に富んだ技術情報が多数含まれています。
推奨読書: 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() - PHP に scrypt または Argon2 をポリフィルして、適切なパフォーマンスを得るのは現実的ではありません。ユーザーは、サービス拒否 (DoS) 攻撃を回避するために、セキュリティをダウングレードするパラメータを選択する意欲を感じるでしょう。
唯一の勝利策はプレイしないことだ。
ext/sodium または ext/libsodium がインストールされている場合、これらの API メソッドは拡張機能にフォールスルーされます。それ以外の場合、ポリフィル ライブラリはSodiumExceptionをスローします。
実行時に Argon2i のサポートを検出するには、ブール値 ( TRUEまたはFALSE ) を返すParagonIE_Sodium_Compat::crypto_pwhash_is_available()を使用します。
Libsodium の HKDF API ( crypto_kdf_hkdf_*() ) は、PHP には独自の HMAC 機能があり、必要ないとみなされたため含まれていません。
CI プロセスでPHPCompatibility利用するsodium_compat ユーザー向けに、このリポジトリでポリフィルされているネイティブ PHP 機能に対してPHPCompatibilityによってスローされる誤検知を防ぐために使用できるカスタム ルールセットが利用可能になりました。
PHPCompatibilityParagonieSodiumCompatルールセットのリポジトリは、Github および Packagist にあります。
