halite

Garam karang

Halite adalah antarmuka kriptografi tingkat tinggi yang mengandalkan libsodium untuk semua operasi kriptografi yang mendasarinya.

Halite diciptakan oleh Paragon Initiative Enterprises sebagai hasil dari upaya berkelanjutan kami untuk meningkatkan ekosistem dan membuat kriptografi di PHP lebih aman dan mudah diterapkan.

Anda dapat membaca Dokumentasi Halite online.

Halite dirilis di bawah Mozilla Public License 2.0. Lisensi komersial tersedia dari Paragon Initiative Enterprises jika Anda ingin memperluas Halite tanpa membuat karya turunan Anda tersedia berdasarkan ketentuan MPL.

Jika Anda puas dengan persyaratan perangkat lunak MPL untuk aplikasi web backend namun ingin membeli kontrak dukungan untuk aplikasi Anda yang menggunakan Halite, kontrak tersebut juga ditawarkan oleh Paragon Initiative Enterprises.

Penting: Halite versi sebelumnya tersedia di bawah Lisensi Publik GNU versi 3 (GPLv3). Hanya Halite 4.0.1 dan yang lebih baru yang tersedia berdasarkan ketentuan Lisensi Publik Mozilla.

Memasang Halit

Sebelum Anda dapat menggunakan Halite, Anda harus memilih versi yang sesuai dengan kebutuhan proyek Anda. Perbedaan antara persyaratan untuk versi Halite yang tersedia dijelaskan secara singkat di bawah ini.

	PHP	libsodium	libsodium PECL	Mendukung
Halit 5.1 dan yang lebih baru	8.1.0	1.0.18	T/A (standar)	Aktif
Halit 5.0.x	8.0.0	1.0.18	T/A (standar)	Aktif
Halit 4.1+	7.2.0	1.0.15	T/A (standar)	Tidak Didukung
Halit 4.0	7.2.0	1.0.13	T/A (standar)	Tidak Didukung
Halit 3	7.0.0	1.0.9	1.0.6 / 2.0.4	Tidak Didukung
Halit 2	7.0.0	1.0.9	1.0.6	Tidak Didukung
Halit 1	5.6.0	1.0.6	1.0.2	Tidak Didukung

Catatan: Halite 5.0.x berfungsi pada PHP 8.0, tetapi kinerjanya lebih buruk dibandingkan pada PHP 8.1.

Jika Anda memerlukan versi Halite sebelum 5.1, lihat dokumentasi yang relevan dengan cabang tersebut.

Untuk menginstal Halite, Anda perlu menginstal libsodium terlebih dahulu. Anda mungkin memerlukan ekstensi PHP atau tidak. Bagi kebanyakan orang, ini berarti berlari...

 sudo apt-get install php7.2-sodium

...atau perintah yang setara untuk sistem operasi dan versi PHP Anda.

Jika Anda mengalami kebuntuan, panduan langkah demi langkah yang disumbangkan oleh @aolko ini mungkin bisa membantu.

Setelah Anda menginstal prasyarat, instal Halite melalui Komposer:

 composer require paragonie/halite:^5

Dukungan Komersial untuk Versi Halite Lama

Dukungan gratis (gratis) untuk Halite hanya berlaku hingga versi mayor terbaru (saat ini 5).

Jika perusahaan Anda memerlukan dukungan untuk Halite versi lama, hubungi Paragon Initiative Enterprises untuk menanyakan tentang opsi dukungan komersial.

Jika Anda memerlukan cara mudah untuk bermigrasi dari Halite versi lama, lihat halite-legacy.

Menggunakan Halite di Proyek Anda

Lihat dokumentasinya. API Halite dasar dirancang untuk kesederhanaan:

• Enkripsi
  • Simetris
    • SymmetricCrypto::encrypt ( HiddenString , EncryptionKey ): string
    • SymmetricCrypto::encryptWithAD ( HiddenString , EncryptionKey , string ): string
    • SymmetricCrypto::decrypt ( string , EncryptionKey ): HiddenString
    • SymmetricCrypto::decryptWithAD ( string , EncryptionKey , string ): HiddenString
  • Asimetris
    • Anonim
      • AsymmetricCrypto::seal ( HiddenString , EncryptionPublicKey ): string
      • AsymmetricCrypto::unseal ( string , EncryptionSecretKey ): HiddenString
    • Diautentikasi
      • AsymmetricCrypto::encrypt ( HiddenString , EncryptionSecretKey , EncryptionPublicKey ): string
      • AsymmetricCrypto::encryptWithAD ( HiddenString , EncryptionSecretKey , EncryptionPublicKey , string ): string
      • AsymmetricCrypto::decrypt ( string , EncryptionSecretKey , EncryptionPublicKey ): HiddenString
      • AsymmetricCrypto::decryptWithAD ( string , EncryptionSecretKey , EncryptionPublicKey , string ): HiddenString
• Otentikasi
  • Simetris
    • SymmetricCrypto::authenticate ( string , AuthenticationKey ): string
    • SymmetricCrypto::verify ( string , AuthenticationKey , string ): bool
  • Asimetris
    • AsymmetricCrypto::sign ( string , SignatureSecretKey ): string
    • AsymmetricCrypto::verify ( string , SignaturePublicKey , string ): bool

Contoh: Mengenkripsi dan Mendekripsi pesan

Pertama, buat dan pertahankan kunci tepat satu kali:

 <?php
use ParagonIE  Halite  KeyFactory ;

$ encKey = KeyFactory:: generateEncryptionKey ();
KeyFactory:: save ( $ encKey , ' /path/outside/webroot/encryption.key ' );

Dan kemudian Anda dapat mengenkripsi/mendekripsi pesan seperti:

 <?php
use ParagonIE  Halite  KeyFactory ;
use ParagonIE  Halite  Symmetric  Crypto as Symmetric ;
use ParagonIE  HiddenString  HiddenString ;

$ encryptionKey = KeyFactory:: loadEncryptionKey ( ' /path/outside/webroot/encryption.key ' );

$ message = new HiddenString ( ' This is a confidential message for your eyes only. ' );
$ ciphertext = Symmetric:: encrypt ( $ message , $ encryptionKey );

$ decrypted = Symmetric:: decrypt ( $ ciphertext , $ encryptionKey );

var_dump ( $ decrypted -> getString () === $ message -> getString ()); // bool(true)

Ini akan menghasilkan sesuatu yang mirip dengan:

 MUIDAEpQznohvNlQ-ZRk-ZZ59Mmox75D_FgAIrXY2cUfStoeL-GIeAe0m-uaeURQdPsVmc5XxRw3-2x5ZAsZH_es37qqFuLFjUI-XK9uG0s30YTsorWfpHdbnqzhRuUOI09c-cKrfMQkNBNm0dDDwZazjTC48zWikRHSHXg8NXerVDebzng1aufc_S-osI_zQuLbZDODujEnpbPZhMMcm4-SWuyVXcBPdGZolJyT

Kunci Kriptografi di Halite

Penting : Halite bekerja dengan objek Key , bukan string.

Jika Anda mencoba echo objek kunci, Anda akan mendapatkan string kosong, bukan isinya. Jika Anda mencoba var_dump() objek kunci, Anda hanya akan mendapatkan beberapa fakta tentang jenis kuncinya.

Anda harus memanggil $obj->getRawKeyMaterial() secara eksplisit jika Anda ingin memeriksa konten biner mentah suatu kunci. Hal ini tidak disarankan untuk sebagian besar kasus penggunaan.

Contoh: Menghasilkan kunci dari kata sandi

 <?php
use ParagonIE  Halite  KeyFactory ;
use ParagonIE  HiddenString  HiddenString ;

$ passwd = new HiddenString ( ' correct horse battery staple ' );
// Use random_bytes(16); to generate the salt:
$ salt = "xddx7bx1ex38x75x9fx72x86x0axe9xc8x58xf6x16x0dx3b" ;

$ encryptionKey = KeyFactory:: deriveEncryptionKey ( $ passwd , $ salt );

Kunci yang berasal dari kata sandi dapat digunakan sebagai pengganti kunci yang dibuat secara acak.

Contoh: Mengenkripsi file besar pada sistem dengan memori rendah

Halite menyertakan kelas kriptografi file yang menggunakan API streaming untuk memungkinkan file besar (misalnya gigabyte) dienkripsi pada sistem dengan memori yang tersedia sangat sedikit (yaitu kurang dari 8 MB).

 <?php
use ParagonIE  Halite  File ;
use ParagonIE  Halite  KeyFactory ;

$ encryptionKey = KeyFactory:: loadEncryptionKey ( ' /path/outside/webroot/encryption.key ' );

File:: encrypt ( ' input.txt ' , ' output.txt ' , $ encryptionKey );

Masalah Dukungan Umum

SodiumException yang Tidak Tertangkap: Tidak Dapat Menghapus Memori

Kesalahan Fatal PHP: SodiumException Tidak Tertangkap: Ini tidak diterapkan, karena tidak mungkin menghapus memori dari PHP dengan aman

Solusi untuk ini adalah memastikan libsodium diinstal/diaktifkan. Lihat di atas dalam README ini untuk informasi lebih lanjut.

Kontrak Pendukung

Jika perusahaan Anda menggunakan perpustakaan ini dalam produk atau layanannya, Anda mungkin tertarik untuk membeli kontrak dukungan dari Paragon Initiative Enterprises.