sodium_compat
Version 2.1.0
Sodium Compat adalah polyfill PHP murni untuk perpustakaan kriptografi Sodium (libsodium), ekstensi inti di PHP 7.2.0+ dan tersedia di PECL.
Jika Anda memasang ekstensi PHP, Sodium Compat akan secara oportunis dan transparan menggunakan ekstensi PHP alih-alih implementasi kami.
sodium_compat v1.21.0 adalah rilis v1.x terakhir dari cabang master. Mulai sekarang, semua rilis mendatang yang mendukung PHP 5.2 - 8.0 dan bilangan bulat 32-bit akan berada di cabang v1.x
Versi sodium_compat yang lebih baru (yaitu, v2.0.0) akan terus ada di cabang master, kecuali diperlukan versi utama yang baru. Tujuan dari pekerjaan ini adalah untuk meningkatkan keterbacaan dan kinerja kode, sekaligus mengurangi kode boilerplate.
Jika ragu, lihat file README di cabang master untuk informasi versi terbaru.
| versi sodium_compat | Versi PHP didukung | dukungan 32-bit? | Cabang |
|---|---|---|---|
v1.xy | 5.2.4 - TERBARU | YA | v1.x |
v2.xy | 8.1 - TERBARU | TIDAK | menguasai |
Jika Anda memerlukan dukungan PHP 32-bit ( PHP_INT_SIZE == 4 ), lanjutkan menggunakan sodium_compat v1.x. Jika Anda ingin peningkatan kinerja dan ketergantungan yang lebih kecil, gunakan v2.x.
Kami merekomendasikan perpustakaan dan kerangka kerja untuk menetapkan batasan versi Komposer sebagai berikut:
{
"require" : {
/* ... */
"paragonie/sodium_compat" : ">= 1"
/* ... */
}
}Sebaliknya, aplikasi harus menentukan versi sebenarnya yang penting bagi mereka dan penerapannya.
Perpustakaan kriptografi ini belum diaudit secara formal oleh pihak ketiga independen yang berspesialisasi dalam kriptografi atau kriptanalisis.
Jika Anda memerlukan audit semacam itu sebelum dapat menggunakan sodium_compat dalam proyek Anda dan memiliki dana untuk audit semacam itu, silakan buka terbitan atau hubungi security at paragonie dot com agar kami dapat membantu menyelesaikannya.
Namun, sodium_compat telah diadopsi oleh proyek sumber terbuka terkenal, seperti Joomla! dan Magento. Selanjutnya, sodium_compat dikembangkan oleh Paragon Initiative Enterprises, sebuah perusahaan yang berspesialisasi dalam pengembangan PHP aman dan kriptografi PHP, dan telah ditinjau secara informal oleh banyak pakar keamanan lain yang juga berspesialisasi dalam PHP.
Jika Anda ingin mempelajari lebih lanjut tentang langkah-langkah keamanan defensif yang kami ambil untuk mencegah sodium_compat menjadi sumber kerentanan di sistem Anda, silakan baca Pengembangan PHP yang Aman Secara Kriptografis .
Jika Anda menggunakan Komposer:
composer require paragonie/sodium_compat Jika Anda tidak menggunakan Composer, unduh tarball rilis (yang harus ditandatangani dengan kunci publik GnuPG kami), ekstrak isinya, lalu sertakan skrip autoload.php kami di proyek Anda.
<?php
require_once " /path/to/sodium_compat/autoload.php " ;Sejak versi 1.3.0, rilis sodium_compat menyertakan Arsip PHP (file .phar) dan tanda tangan GPG terkait. Pertama, unduh kedua file dan verifikasi dengan kunci publik GPG kami, seperti:
# 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.pharSekarang, cukup sertakan file .phar ini di aplikasi Anda.
<?php
require_once " /path/to/sodium-compat.phar " ;Dukungan komersial untuk libsodium tersedia dari berbagai vendor. Jika Anda memerlukan bantuan dalam menggunakan sodium_compat di salah satu proyek Anda, hubungi Paragon Initiative Enterprises.
Laporan non-komersial akan difasilitasi melalui isu Github. Kami tidak memberikan jaminan atas ketersediaan kami untuk menyelesaikan pertanyaan tentang pengintegrasian sodium_compat ke perangkat lunak pihak ketiga secara gratis, namun kami akan berusaha memperbaiki bug apa pun (terkait keamanan atau lainnya) di perpustakaan kami.
Jika perusahaan Anda menggunakan perpustakaan ini dalam produk atau layanannya, Anda mungkin tertarik untuk membeli kontrak dukungan dari Paragon Initiative Enterprises.
Sesuai pemungutan suara kedua di libsodium RFC, PHP 7.2 menggunakan sodium_* alih-alih 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 ' );
} Jika pengguna Anda menggunakan PHP <5.3, atau Anda ingin menulis kode yang akan berfungsi baik ekstensi PECL tersedia atau tidak, Anda dapat menggunakan kelas ParagonIE_Sodium_Compat untuk sebagian besar kebutuhan libsodium Anda.
Contoh di atas, ditulis untuk penggunaan umum:
<?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 ' );
} Secara umum: Jika Anda mengganti sodium_ dengan ParagonIE_Sodium_Compat:: , kode apa pun yang sudah ditulis untuk ekstensi libsodium PHP akan berfungsi dengan polyfill kami tanpa perubahan kode tambahan.
Karena ini tidak memerlukan namespace, API ini diekspos pada PHP 5.2.
Sejak versi 0.7.0, kami memiliki API namespace kami sendiri ( ParagonIESodium* ) untuk memungkinkan keringkasan dalam perangkat lunak yang menggunakan PHP 5.3+. Ini berguna jika Anda ingin menggunakan fitur kriptografi file kami tanpa harus menulis ParagonIE_Sodium_File setiap saat. Ini tidak diekspos pada PHP <5.3, jadi jika proyek Anda mendukung PHP <5.3, gunakan metode garis bawah sebagai gantinya.
Untuk mempelajari cara menggunakan Libsodium, baca Menggunakan Libsodium di Proyek PHP .
Ada tiga cara untuk mempercepatnya:
ParagonIE_Sodium_Compat::$fastMult = true; tanpa merusak keamanan kunci kriptografi Anda. Jika prosesor Anda tidak aman, putuskan apakah Anda menginginkan kecepatan atau keamanan karena Anda tidak dapat memiliki keduanya. Sejak versi 1.8, Anda dapat menggunakan metode statis polyfill_is_fast() untuk menentukan apakah sodium_compat akan lambat saat runtime.
<?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 ();
}Pertama, Anda ingin membaca Referensi Cepat Libsodium. Hal ini bertujuan untuk menjawab, “Fungsi manakah yang harus saya gunakan untuk [masalah umum]?”.
Jika Anda tidak menemukan jawabannya di halaman Referensi Cepat, lihat Menggunakan Libsodium di Proyek PHP .
Terakhir, dokumentasi resmi libsodium (yang ditulis untuk pustaka C, bukan pustaka PHP) juga berisi banyak informasi teknis mendalam yang mungkin berguna bagi Anda.
Bacaan yang disarankan: Referensi Cepat 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() - Meskipun kami mengekspos titik akhir API ini, kami tidak dapat secara andal menghilangkan buffer dari PHP.
Jika Anda memasang ekstensi PHP, sodium_compat akan menggunakan implementasi asli untuk menghilangkan string yang disediakan. Kalau tidak, itu akan memunculkan SodiumException .
sodium_crypto_pwhash() - Tidak mungkin melakukan polyfill scrypt atau Argon2 ke dalam PHP dan mendapatkan performa yang wajar. Pengguna akan merasa termotivasi untuk memilih parameter yang menurunkan keamanan untuk menghindari serangan penolakan layanan (DoS).
Satu-satunya langkah kemenangan adalah tidak bermain.
Jika ext/sodium atau ext/libsodium diinstal, metode API ini akan masuk ke dalam ekstensi. Jika tidak, perpustakaan polyfill kami akan memunculkan SodiumException .
Untuk mendeteksi dukungan untuk Argon2i saat runtime, gunakan ParagonIE_Sodium_Compat::crypto_pwhash_is_available() , yang mengembalikan nilai boolean ( TRUE atau FALSE ).
API HKDF Libsodium ( crypto_kdf_hkdf_*() ) tidak disertakan karena PHP memiliki fitur HMAC sendiri dan tidak dianggap perlu.
Untuk pengguna sodium_compat dan yang menggunakan PHPCompatibility dalam proses CI mereka, kini tersedia kumpulan aturan khusus yang dapat digunakan untuk mencegah kesalahan positif yang diberikan oleh PHPCompatibility untuk fungsi asli PHP yang diisi oleh repo ini.
Anda dapat menemukan repo untuk kumpulan aturan PHPCompatibilityParagonieSodiumCompat di sini di Github dan di Packagist.
