Halite

Halite ist eine High-Level-Schnittstelle für Kryptografie, die für alle ihre zugrunde liegenden kryptografischen Operationen auf libsodium aufbaut.

Halite wurde von Paragon Initiative Enterprises als Ergebnis unserer fortgesetzten Bemühungen entwickelt, das Ökosystem zu verbessern und Kryptografie in PHP sicherer und einfacher zu implementieren.

Sie können die Halite-Dokumentation online lesen.

Halite wird unter der Mozilla Public License 2.0 veröffentlicht. Kommerzielle Lizenzen sind verfügbar bei Paragon Initiative Enterprises, falls Sie Halite erweitern möchten, ohne Ihre abgeleiteten Werke unter den Bedingungen der MPL verfügbar zu machen.

Wenn Sie mit den Bedingungen von MPL-Software für Backend-Webanwendungen zufrieden sind, aber einen Supportvertrag für Ihre Anwendung erwerben möchten, die Halite verwendet, werden diese ebenfalls von Paragon Initiative Enterprises angeboten.

Wichtig: Frühere Versionen von Halite waren unter der GNU Public License Version 3 (GPLv3) verfügbar. Nur Halite 4.0.1 und neuere Versionen sind unter den Bedingungen der Mozilla Public License verfügbar.

Halite installieren

Bevor Sie Halite verwenden können, müssen Sie eine Version auswählen, die den Anforderungen Ihres Projekts entspricht. Die Unterschiede zwischen den Anforderungen der verfügbaren Versionen von Halite werden im Folgenden kurz hervorgehoben.

Hinweis: Halite 5.0.x funktioniert unter PHP 8.0, aber die Leistung ist schlechter als unter PHP 8.1.

Wenn Sie eine Version von Halite vor 5.1 benötigen, lesen Sie die Dokumentation, die für diesen speziellen Zweig relevant ist.

Um Halite zu installieren, müssen Sie zunächst libsodium installieren. Möglicherweise benötigen Sie die PHP-Erweiterung. Für die meisten Menschen bedeutet das, Folgendes auszuführen...

sudo apt-get install php7.2-sodium

...oder einen entsprechenden Befehl für Ihr Betriebssystem und Ihre PHP-Version.

Wenn Sie nicht weiterkommen, kann diese Schritt-für-Schritt-Anleitung von @aolko hilfreich sein.

Sobald Sie die Voraussetzungen installiert haben, installieren Sie Halite über Composer:

composer require paragonie/halite:^5

Kommerzieller Support für ältere Halite-Versionen

Kostenloser (gratis) Support für Halite erstreckt sich nur auf die neueste Hauptversion (derzeit 5).

Wenn Ihr Unternehmen Support für eine ältere Version von Halite benötigt, kontaktieren Sie Paragon Initiative Enterprises, um sich nach kommerziellen Support-Optionen zu erkundigen.

Wenn Sie einen einfachen Weg benötigen, um von älteren Versionen von Halite zu migrieren, schauen Sie sich halite-legacy an.

Halite in Ihrem Projekt verwenden

Sehen Sie sich die Dokumentation an. Die grundlegende Halite-API ist auf Einfachheit ausgelegt:

• Verschlüsselung
  • Symmetrisch
    • Symmetric\Crypto::encrypt(HiddenString, EncryptionKey): string
    • Symmetric\Crypto::encryptWithAD(HiddenString, EncryptionKey, string): string
    • Symmetric\Crypto::decrypt(string, ):

Beispiel: Verschlüsseln und Entschlüsseln einer Nachricht

Generieren und speichern Sie zunächst genau einmal einen Schlüssel:

<?php
use ParagonIE\Halite\KeyFactory;

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

Und dann können Sie Nachrichten wie folgt ver-/entschlüsseln:

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

Dies sollte in etwa Folgendes ergeben:

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

Kryptografische Schlüssel in Halite

Wichtig: Halite arbeitet mit Key-Objekten, nicht mit Zeichenketten.

Wenn Sie versuchen, ein Schlüsselobjekt mit echo auszugeben, erhalten Sie einen leeren String anstelle seines Inhalts. Wenn Sie versuchen, ein Schlüsselobjekt mit var_dump() auszugeben, erhalten Sie nur einige Informationen über den Typ des Schlüssels.

Sie müssen $obj->getRawKeyMaterial() explizit aufrufen, wenn Sie die rohen binären Inhalte eines Schlüssels untersuchen möchten. Dies wird für die meisten Anwendungsfälle nicht empfohlen.

Beispiel: Generieren eines Schlüssels aus einem Passwort

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

Ein aus einem Passwort abgeleiteter Schlüssel kann anstelle eines zufällig generierten Schlüssels verwendet werden.

Beispiel: Verschlüsseln einer großen Datei auf einem System mit wenig Arbeitsspeicher

Halite enthält eine Dateikryptografie-Klasse, die eine Streaming-API nutzt, um das Verschlüsseln großer Dateien (z. B. Gigabyte) auf einem System mit sehr wenig verfügbarem Arbeitsspeicher (d. h. weniger als 8 MB) zu ermöglichen.

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

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

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

Häufige Support-Probleme

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

Die Lösung hierfür ist, sicherzustellen, dass libsodium installiert/aktiviert ist. Weitere Informationen finden Sie weiter oben in dieser README.

Supportverträge

Wenn Ihr Unternehmen diese Bibliothek in seinen Produkten oder Dienstleistungen verwendet, könnten Sie daran interessiert sein, einen Supportvertrag von Paragon Initiative Enterprises zu erwerben.