sodium_compat
Version 2.1.0
Sodium Compat คือ PHP polyfill ล้วนๆ สำหรับไลบรารีการเข้ารหัส Sodium (libsodium) ซึ่งเป็นส่วนขยายหลักใน PHP 7.2.0+ และอย่างอื่นที่มีใน PECL
หากคุณติดตั้งส่วนขยาย PHP แล้ว Sodium Compat จะใช้ส่วนขยาย PHP อย่างฉวยโอกาสและโปร่งใสแทนการใช้งานของเรา
โซเดียม_compat v1.21.0 เป็นรุ่น v1.x ล่าสุดจากสาขาหลัก จากนี้ไป รุ่นในอนาคตทั้งหมดที่รองรับ PHP 5.2 - 8.0 และจำนวนเต็ม 32 บิตจะอยู่ในสาขา v1.x
Sodium_compat เวอร์ชันใหม่กว่า (เช่น เวอร์ชัน 2.0.0) จะยังคงใช้งานอยู่ในสาขาหลักต่อไป เว้นแต่จำเป็นต้องใช้เวอร์ชันหลักใหม่ เป้าหมายของงานนี้คือการปรับปรุงความสามารถในการอ่านและประสิทธิภาพของโค้ด ในขณะเดียวกันก็ลดโค้ดสำเร็จรูป
หากมีข้อสงสัย โปรดดูไฟล์ README ในสาขาหลักเพื่อดูข้อมูลเวอร์ชันล่าสุด
| รุ่นโซเดียม_คอมแพต | รองรับเวอร์ชัน PHP | รองรับ 32 บิต? | สาขา |
|---|---|---|---|
v1.xy | 5.2.4 - ล่าสุด | ใช่ | v1.x |
v2.xy | 8.1 - ล่าสุด | เลขที่ | ผู้เชี่ยวชาญ |
หากคุณต้องการการสนับสนุน PHP 32 บิต ( PHP_INT_SIZE == 4 ) ให้ใช้โซเดียม_compat v1.x ต่อไป หากคุณต้องการประสิทธิภาพที่ดีขึ้นและการพึ่งพาที่น้อยลง ให้ใช้ v2.x
เราขอแนะนำให้ไลบรารีและเฟรมเวิร์กตั้งค่าข้อจำกัดเวอร์ชันของ Composer ดังต่อไปนี้:
{
"require" : {
/* ... */
"paragonie/sodium_compat" : ">= 1"
/* ... */
}
}ในทางกลับกัน แอปพลิเคชันควรระบุเวอร์ชันจริงที่สำคัญและการใช้งาน
ไลบรารีการเข้ารหัสนี้ยังไม่ได้รับการตรวจสอบอย่างเป็นทางการโดยบุคคลที่สามอิสระที่เชี่ยวชาญด้านการเข้ารหัสหรือการเข้ารหัส
หากคุณต้องการการตรวจสอบก่อนที่คุณจะสามารถใช้ Sodium_compat ในโครงการของคุณและมีเงินทุนสำหรับการตรวจสอบดังกล่าว โปรดเปิดปัญหาหรือติดต่อ security at paragonie dot com เพื่อให้เราช่วยดำเนินการได้
อย่างไรก็ตาม Sodium_compat ได้ถูกนำไปใช้โดยโครงการโอเพ่นซอร์สที่มีชื่อเสียงระดับสูง เช่น Joomla! และวีโอไอพี นอกจากนี้ Sodium_compat ยังได้รับการพัฒนาโดย Paragon Initiative Enterprises ซึ่งเป็นบริษัทที่ เชี่ยวชาญ ด้านการพัฒนา PHP ที่ปลอดภัยและการเข้ารหัส PHP และได้รับการตรวจสอบอย่างไม่เป็นทางการโดยผู้เชี่ยวชาญด้านความปลอดภัยอื่นๆ จำนวนมากที่เชี่ยวชาญด้าน PHP เช่นกัน
หากคุณต้องการเรียนรู้เพิ่มเติมเกี่ยวกับมาตรการรักษาความปลอดภัยเชิงป้องกันที่เราดำเนินการเพื่อป้องกันไม่ให้โซเดียมคอมแพตเป็นแหล่งที่มาของช่องโหว่ในระบบของคุณ โปรดอ่าน การพัฒนา PHP ที่ปลอดภัยด้วยการเข้ารหัส
หากคุณใช้นักแต่งเพลง:
composer require paragonie/sodium_compat หากคุณไม่ได้ใช้ Composer ให้ดาวน์โหลด tarball รุ่นต่างๆ (ซึ่งควรลงนามด้วยคีย์สาธารณะ GnuPG ของเรา) แยกเนื้อหาออก จากนั้นรวมสคริปต์ autoload.php ของเราไว้ในโปรเจ็กต์ของคุณ
<?php
require_once " /path/to/sodium_compat/autoload.php " ;ตั้งแต่เวอร์ชัน 1.3.0 การเผยแพร่โซเดียม_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 เราไม่รับประกันความพร้อมใช้งานของเราในการแก้ไขปัญหาเกี่ยวกับการผสานรวมโซเดียมคอมแพตเข้ากับซอฟต์แวร์บุคคลที่สามได้ฟรี แต่จะพยายามแก้ไขข้อบกพร่องใดๆ (ที่เกี่ยวข้องกับความปลอดภัยหรืออื่นๆ) ในไลบรารีของเรา
หากบริษัทของคุณใช้ไลบรารีนี้ในผลิตภัณฑ์หรือบริการของตน คุณอาจสนใจซื้อสัญญาการสนับสนุนจาก 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 ' );
} โดยทั่วไป: หากคุณแทนที่ sodium_ ด้วย ParagonIE_Sodium_Compat:: โค้ดใดๆ ที่เขียนไว้แล้วสำหรับส่วนขยาย 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 โปรดอ่าน การใช้ Libsodium ในโปรเจ็กต์ PHP
มีสามวิธีในการทำให้รวดเร็ว:
ParagonIE_Sodium_Compat::$fastMult = true; โดยไม่กระทบต่อความปลอดภัยของคีย์การเข้ารหัสของคุณ หากโปรเซสเซอร์ของคุณ ไม่ ปลอดภัย ให้ตัดสินใจว่าคุณต้องการความเร็วหรือความปลอดภัยเพราะคุณไม่สามารถมีทั้งสองอย่างได้ ตั้งแต่เวอร์ชัน 1.8 คุณสามารถใช้เมธอดแบบคง polyfill_is_fast() เพื่อตรวจสอบว่าโซเดียมคอมแพตจะช้าที่รันไทม์หรือไม่
<?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 Quick Reference มีจุดมุ่งหมายเพื่อตอบว่า "ฉันควรใช้ฟังก์ชันใดสำหรับ [ปัญหาทั่วไป]"
หากคุณไม่พบคำตอบในหน้าอ้างอิงด่วน โปรดดู การใช้ Libsodium ใน PHP Projects
สุดท้ายนี้ เอกสารอย่างเป็นทางการของ 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 ไว้โซเดียม_compat จะใช้การใช้งานแบบเนทิฟเพื่อทำให้สตริงที่ให้ไว้เป็นศูนย์ มิฉะนั้นมันจะส่ง SodiumException
sodium_crypto_pwhash() - เป็นไปไม่ได้ที่จะ polyfill scrypt หรือ Argon2 ใน PHP และได้รับประสิทธิภาพที่สมเหตุสมผล ผู้ใช้จะรู้สึกมีแรงจูงใจในการเลือกพารามิเตอร์ที่ดาวน์เกรดความปลอดภัยเพื่อหลีกเลี่ยงการโจมตีแบบปฏิเสธการให้บริการ (DoS)
สิ่งเดียวที่ชนะคือไม่ต้องเล่น
หากมีการติดตั้ง ext/sodium หรือ ext/libsodium วิธี API เหล่านี้จะตกอยู่ในส่วนขยาย มิฉะนั้น ไลบรารี polyfill ของเราจะโยน SodiumException
หากต้องการตรวจจับการสนับสนุน Argon2i ณ รันไทม์ ให้ใช้ ParagonIE_Sodium_Compat::crypto_pwhash_is_available() ซึ่งส่งคืนค่าบูลีน ( TRUE หรือ FALSE )
ไม่รวม HKDF API ของ Libsodium ( crypto_kdf_hkdf_*() ) เนื่องจาก PHP มีคุณสมบัติ HMAC ของตัวเองและถือว่าไม่จำเป็น
สำหรับผู้ใช้ Sodium_compat และใช้ PHPCompatibility ในกระบวนการ CI ของตน ขณะนี้มีชุดกฎที่กำหนดเองซึ่งสามารถใช้เพื่อป้องกันการส่งผลบวกลวงโดย PHPCompatibility สำหรับฟังก์ชันการทำงานของ PHP ดั้งเดิมที่ถูกโพลีฟิลโดย repo นี้
คุณสามารถค้นหา repo สำหรับชุดกฎ PHPCompatibilityParagonieSodiumCompat ได้ที่นี่บน Github และบน Packagist
