Halite

Halite est une interface de cryptographie de haut niveau qui s'appuie sur libsodium pour toutes ses opérations cryptographiques sous-jacentes.

Halite a été créé par Paragon Initiative Enterprises à la suite de nos efforts continus pour améliorer l'écosystème et rendre la cryptographie en PHP plus sûre et plus facile à mettre en œuvre.

Vous pouvez lire la documentation de Halite en ligne.

Halite est publié sous licence publique Mozilla 2.0. Des licences commerciales sont disponibles auprès de Paragon Initiative Enterprises si vous souhaitez étendre Halite sans rendre vos œuvres dérivées disponibles selon les termes de la MPL.

Si vous êtes satisfait des termes du logiciel MPL pour les applications web backend mais que vous souhaitez acheter un contrat de support pour votre application qui utilise Halite, ceux-ci sont également proposés par Paragon Initiative Enterprises.

Important : Les versions antérieures de Halite étaient disponibles sous licence publique générale GNU version 3 (GPLv3). Seules Halite 4.0.1 et les versions plus récentes sont disponibles selon les termes de la licence publique Mozilla.

Installer Halite

Avant de pouvoir utiliser Halite, vous devez choisir une version qui correspond aux exigences de votre projet. Les différences entre les exigences des versions disponibles de Halite sont brièvement présentées ci-dessous.

Note : Halite 5.0.x fonctionne sur PHP 8.0, mais les performances sont moins bonnes que sur PHP 8.1.

Si vous avez besoin d'une version de Halite antérieure à 5.1, consultez la documentation relative à cette branche particulière.

Pour installer Halite, vous devez d'abord installer libsodium. Vous pouvez ou non avoir besoin de l'extension PHP. Pour la plupart des gens, cela signifie exécuter...

sudo apt-get install php7.2-sodium

...ou une commande équivalente pour votre système d'exploitation et votre version de PHP.

Si vous êtes bloqué, ce guide pas à pas contribué par @aolko peut vous être utile.

Une fois les prérequis installés, installez Halite via Composer :

composer require paragonie/halite:^5

Support commercial pour les anciennes versions de Halite

Le support gratuit de Halite ne s'étend qu'à la version majeure la plus récente (actuellement la 5).

Si votre entreprise a besoin d'une prise en charge pour une ancienne version de Halite, contactez Paragon Initiative Enterprises pour vous renseigner sur les options de support commercial.

Si vous avez besoin d'un moyen simple de migrer depuis les anciennes versions de Halite, consultez halite-legacy.

Utiliser Halite dans votre projet

Consultez la documentation. L'API de base de Halite est conçue pour la simplicité :

• Chiffrement
  • Symétrique
    • Symmetric\Crypto::encrypt(HiddenString, EncryptionKey): string
    • Symmetric\Crypto::encryptWithAD(HiddenString, EncryptionKey, string): string
    • Symmetric\Crypto::decrypt(string, ):

Exemple : Chiffrer et déchiffrer un message

D'abord, générez et persistez une clé une seule fois :

<?php
use ParagonIE\Halite\KeyFactory;

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

Ensuite, vous pouvez chiffrer/déchiffrer des messages comme ceci :

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

Cela devrait produire quelque chose de similaire à :

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

Clés cryptographiques dans Halite

Important : Halite fonctionne avec des objets Key, pas avec des chaînes de caractères.

Si vous tentez d'echo un objet clé, vous obtiendrez une chaîne vide plutôt que son contenu. Si vous tentez de faire un var_dump() sur un objet clé, vous obtiendrez simplement quelques informations sur le type de clé dont il s'agit.

Vous devez invoquer $obj->getRawKeyMaterial() explicitement si vous voulez inspecter le contenu binaire brut d'une clé. Ce n'est pas recommandé pour la plupart des cas d'utilisation.

Exemple : Générer une clé à partir d'un mot de passe

<?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 = "\xdd\x7b\x1e\x38\x75\x9f\x72\x86\x0a\xe9\xc8\x58\xf6\x16\x0d\x3b";

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

Une clé dérivée d'un mot de passe peut être utilisée à la place d'une clé générée aléatoirement.

Exemple : Chiffrer un fichier volumineux sur un système avec peu de mémoire

Halite inclut une classe de cryptographie de fichiers qui utilise une API de streaming pour permettre à de gros fichiers (par exemple des gigaoctets) d'être chiffrés sur un système avec très peu de mémoire disponible (c'est-à-dire moins de 8 Mo).

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

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

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

Problèmes de support courants

SodiumException non interceptée : impossible d'effacer la mémoire

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

La solution consiste à s'assurer que libsodium est installé/activé. Voir plus haut dans ce README pour plus d'informations.

Contrats de support

Si votre entreprise utilise cette bibliothèque dans ses produits ou services, vous pouvez être intéressé par l'achat d'un contrat de support auprès de Paragon Initiative Enterprises.