Halite

Halite è un'interfaccia di crittografia di alto livello che si affida a libsodium per tutte le sue operazioni crittografiche sottostanti.

Halite è stato creato da Paragon Initiative Enterprises come risultato dei nostri continui sforzi per migliorare l'ecosistema e rendere la crittografia in PHP più sicura e facile da implementare.

Puoi leggere la Documentazione di Halite online.

Halite è rilasciato sotto Mozilla Public License 2.0. Sono disponibili licenze commerciali presso Paragon Initiative Enterprises se desideri estendere Halite senza rendere le tue opere derivate disponibili secondo i termini della MPL.

Se sei soddisfatto dei termini del software MPL per applicazioni web backend ma desideri acquistare un contratto di supporto per la tua applicazione che utilizza Halite, anche questi sono offerti da Paragon Initiative Enterprises.

Importante: Le versioni precedenti di Halite erano disponibili sotto GNU Public License versione 3 (GPLv3). Solo Halite 4.0.1 e successive sono disponibili secondo i termini della Mozilla Public License.

Installare Halite

Prima di poter utilizzare Halite, devi scegliere una versione che soddisfi i requisiti del tuo progetto. Le differenze tra i requisiti per le versioni disponibili di Halite sono brevemente evidenziate di seguito.

Nota: Halite 5.0.x funziona su PHP 8.0, ma le prestazioni sono peggiori rispetto a PHP 8.1.

Se hai bisogno di una versione di Halite precedente alla 5.1, consulta la documentazione relativa a quel particolare ramo.

Per installare Halite, devi prima installare libsodium. Potresti aver bisogno o meno dell'estensione PHP. Per la maggior parte delle persone, questo significa eseguire...

sudo apt-get install php7.2-sodium

...o un comando equivalente per il tuo sistema operativo e la tua versione di PHP.

Se sei bloccato, questa guida passo passo contribuita da @aolko potrebbe esserti utile.

Una volta installati i prerequisiti, installa Halite tramite Composer:

composer require paragonie/halite:^5

Supporto Commerciale per Versioni Precedenti di Halite

Il supporto gratuito per Halite si estende solo alla versione principale più recente (attualmente la 5).

Se la tua azienda richiede supporto per una versione precedente di Halite, contatta Paragon Initiative Enterprises per informazioni sulle opzioni di supporto commerciale.

Se hai bisogno di un modo semplice per migrare dalle versioni precedenti di Halite, dai un'occhiata a halite-legacy.

Usare Halite nel Tuo Progetto

Dai un'occhiata alla documentazione. L'API di base di Halite è progettata per la semplicità:

• Crittografia
  • Simmetrica
    • Symmetric\Crypto::encrypt(HiddenString, EncryptionKey): string
    • Symmetric\Crypto::encryptWithAD(HiddenString, EncryptionKey, string): string
    • Symmetric\Crypto::decrypt(string, ):

Esempio: Crittografare e Decrittografare un messaggio

Prima di tutto, genera e salva una chiave una sola volta:

<?php
use ParagonIE\Halite\KeyFactory;

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

E poi puoi crittografare/decrittografare messaggi in questo modo:

<?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)

Questo dovrebbe produrre qualcosa di simile a:

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

Chiavi Crittografiche in Halite

Importante: Halite funziona con oggetti Key, non con stringhe.

Se tenti di fare echo di un oggetto chiave, otterrai una stringa vuota piuttosto che il suo contenuto. Se tenti di fare var_dump() di un oggetto chiave, otterrai solo alcune informazioni sul tipo di chiave che è.

Devi invocare esplicitamente $obj->getRawKeyMaterial() se vuoi ispezionare il contenuto binario grezzo di una chiave. Questo non è raccomandato per la maggior parte dei casi d'uso.

Esempio: Generare una chiave da una password

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

$passwd = new HiddenString('correct horse battery staple');
// Usa random_bytes(16); per generare il salt:
$salt = "\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b";

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

Una chiave derivata da una password può essere utilizzata al posto di una generata casualmente.

Esempio: Crittografare un file di grandi dimensioni su un sistema con poca memoria

Halite include una classe di crittografia per file che utilizza un'API di streaming per consentire la crittografia di file di grandi dimensioni (ad es. gigabyte) su un sistema con pochissima memoria disponibile (cioè meno di 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);

Problemi di Supporto Comuni

Uncaught SodiumException: Cannot Wipe Memory

PHP Fatal error: Uncaught SodiumException: This is not implemented, as it is not possible to securely wipe memory from PHP

La soluzione a questo problema è assicurarsi che libsodium sia installato/abilitato. Vedi sopra in questo README per maggiori informazioni.

Contratti di Supporto

Se la tua azienda utilizza questa libreria nei propri prodotti o servizi, potresti essere interessato all'acquisto di un contratto di supporto da Paragon Initiative Enterprises.