halite

Halit

Halite ist eine High-Level-Kryptografieschnittstelle, die für alle zugrunde liegenden Kryptografieoperationen auf libsodium basiert.

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

Sie können die Halite-Dokumentation online lesen.

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

Wenn Sie mit den Bedingungen der MPL-Software für Backend-Webanwendungen zufrieden sind, aber einen Supportvertrag für Ihre Anwendung erwerben möchten, die Halite verwendet, werden diese auch 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 höher sind unter den Mozilla Public License-Bedingungen 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 für die verfügbaren Versionen von Halite werden im Folgenden kurz hervorgehoben.

	PHP	libsodium	PECL-Libsodium	Unterstützung
Halite 5.1 und neuer	8.1.0	1.0.18	N/A (Standard)	Aktiv
Halit 5.0.x	8.0.0	1.0.18	N/A (Standard)	Aktiv
Halit 4.1+	7.2.0	1.0.15	N/A (Standard)	Nicht unterstützt
Halit 4.0	7.2.0	1.0.13	N/A (Standard)	Nicht unterstützt
Halit 3	7.0.0	1.0.9	1.0.6 / 2.0.4	Nicht unterstützt
Halit 2	7.0.0	1.0.9	1.0.6	Nicht unterstützt
Halit 1	5.6.0	1.0.6	1.0.2	Nicht unterstützt

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

Wenn Sie eine Version von Halite vor 5.1 benötigen, lesen Sie die Dokumentation zu diesem bestimmten Zweig.

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

 sudo apt-get install php7.2-sodium

...oder ein gleichwertiger 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

Kommerzielle Unterstützung für ältere Halite-Versionen

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

Wenn Ihr Unternehmen Unterstützung für eine ältere Version von Halite benötigt, wenden Sie sich an Paragon Initiative Enterprises, um sich nach kommerziellen Supportoptionen zu erkundigen.

Wenn Sie eine einfache Möglichkeit zur Migration von älteren Versionen von Halite benötigen, schauen Sie sich halite-legacy an.

Verwenden Sie Halit in Ihrem Projekt

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

• Verschlüsselung
  • Symmetrisch
    • SymmetricCrypto::encrypt ( HiddenString , EncryptionKey ): string
    • SymmetricCrypto::encryptWithAD ( HiddenString , EncryptionKey , string ): string
    • SymmetricCrypto::decrypt ( string , EncryptionKey ): HiddenString
    • SymmetricCrypto::decryptWithAD ( string , EncryptionKey , string ): HiddenString
  • Asymmetrisch
    • Anonym
      • AsymmetricCrypto::seal ( HiddenString , EncryptionPublicKey ): string
      • AsymmetricCrypto::unseal ( string , EncryptionSecretKey ): HiddenString
    • Authentifiziert
      • 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
• Authentifizierung
  • Symmetrisch
    • SymmetricCrypto::authenticate ( string , AuthenticationKey ): string
    • SymmetricCrypto::verify ( string , AuthenticationKey , string ): bool
  • Asymmetrisch
    • AsymmetricCrypto::sign ( string , SignatureSecretKey ): string
    • AsymmetricCrypto::verify ( string , SignaturePublicKey , string ): bool

Beispiel: Verschlüsseln und Entschlüsseln einer Nachricht

Generieren Sie zunächst genau einmal einen Schlüssel und behalten Sie ihn bei:

 <?php
use ParagonIE  Halite  KeyFactory ;

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

Und dann können Sie Nachrichten wie folgt verschlüsseln/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 etwas Ähnliches ergeben wie:

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

Kryptografische Schlüssel in Halit

Wichtig : Halite funktioniert mit Key , nicht mit Zeichenfolgen.

Wenn Sie versuchen, ein Schlüsselobjekt echo , erhalten Sie anstelle seines Inhalts eine leere Zeichenfolge. Wenn Sie versuchen, ein Schlüsselobjekt var_dump() , erhalten Sie lediglich einige Fakten über den Typ des Schlüssels.

Sie müssen $obj->getRawKeyMaterial() explizit aufrufen, wenn Sie den rohen Binärinhalt eines Schlüssels überprüfen 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 = "xddx7bx1ex38x75x9fx72x86x0axe9xc8x58xf6x16x0dx3b" ;

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

Anstelle eines zufällig generierten Schlüssels kann auch ein aus einem Passwort abgeleiteter Schlüssel verwendet werden.

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

Halite enthält eine Dateikryptografieklasse, die eine Streaming-API verwendet, um die Verschlüsselung großer Dateien (z. B. Gigabyte) auf einem System mit sehr wenig verfügbarem Speicher (dh 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 Supportprobleme

Nicht erfasste SodiumException: Speicher kann nicht gelöscht werden

Schwerwiegender PHP-Fehler: Nicht erfasste SodiumException: Dies ist nicht implementiert, da es nicht möglich ist, den Speicher von PHP sicher zu löschen

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

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 abzuschließen.