README.md

Halite

Halite is a high-level cryptography interface that relies on libsodium for all of its underlying cryptography operations.

Halite was created by Paragon Initiative Enterprises as a result of our continued efforts to improve the ecosystem and make cryptography in PHP safer and easier to implement.

Halite is released under Mozilla Public License 2.0. Commercial licenses are available from Paragon Initiative Enterprises if you wish to extend Halite without making your derivative works available under the terms of the MPL.

If you are satisfied with the terms of MPL software for backend web applications but would like to purchase a support contract for your application that uses Halite, those are also offered by Paragon Initiative Enterprises.

Important: Earlier versions of Halite were available under the GNU Public License version 3 (GPLv3). Only Halite 4.0.1 and newer are available under the Mozilla Public License terms.

Installing Halite

Before you can use Halite, you must choose a version that fits the requirements of your project. The differences between the requirements for the available versions of Halite are briefly highlighted below.

	PHP	libsodium	PECL libsodium
Halite 4.1 and newer	7.2.0	1.0.15	N/A (standard)
Halite 4.0	7.2.0	1.0.13	N/A (standard)
Halite 3	7.0.0	1.0.9	1.0.6 / 2.0.4
Halite 2	7.0.0	1.0.9	1.0.6

If you need a version of Halite before 4.0, see the documentation relevant to that particular branch.

To install Halite, you first need to install libsodium. You may or may not need the PHP extension. For most people, this means running...

sudo apt-get install php7.2-sodium

...or an equivalent command for your operating system and PHP version.

If you're stuck, this step-by-step guide contributed by @aolko may be helpful.

Once you have the prerequisites installed, install Halite through Composer:

composer require paragonie/halite:^4

Using Halite in Your Project

Check out the documentation. The basic Halite API is designed for simplicity:

• Encryption
  • Symmetric
    • Symmetric\Crypto::encrypt(HiddenString, EncryptionKey): string
    • Symmetric\Crypto::decrypt(string, EncryptionKey): HiddenString
  • Asymmetric
    • Anonymous
      • Asymmetric\Crypto::seal(HiddenString, EncryptionPublicKey): string
      • Asymmetric\Crypto::unseal(string, EncryptionSecretKey): HiddenString
    • Authenticated
      • Asymmetric\Crypto::encrypt(HiddenString, EncryptionSecretKey, EncryptionPublicKey): string
      • Asymmetric\Crypto::decrypt(string, EncryptionSecretKey, EncryptionPublicKey): HiddenString
• Authentication
  • Symmetric
    • Symmetric\Crypto::authenticate(string, AuthenticationKey): string
    • Symmetric\Crypto::verify(string, AuthenticationKey, string): bool
  • Asymmetric
    • Asymmetric\Crypto::sign(string, SignatureSecretKey): string
    • Asymmetric\Crypto::verify(string, SignaturePublicKey, string): bool

Example: Encrypting and Decrypting a message

First, generate and persist a key exactly once:

<?php
use ParagonIE\Halite\KeyFactory;

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

And then you can encrypt/decrypt messages like so:

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

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

This should produce something similar to:

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

Cryptographic Keys in Halite

Important: Halite works with Key objects, not strings.

If you attempt to echo a key object, you will get an empty string rather than its contents. If you attempt to var_dump() a key object, you will just get some facts about the type of key it is.

You must invoke $obj->getRawKeyMaterial() explicitly if you want to inspect a key's raw binary contents. This is not recommended for most use cases.

Example: Generating a key from a password

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

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

A key derived from a password can be used in place of one randomly generated.

Example: Encrypting a large file on a system with low memory

Halite includes a file cryptography class that utilizes a streaming API to allow large files (e.g. gigabytes) be encrypted on a system with very little available memory (i.e. less than 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);