Halite is a high-level cryptography interface that relies on libsodium for all of its underlying cryptography operations.
It’s released under the GPLv3 license. Commercial licenses are available from Paragon Initiative Enterprises if you wish to implement Halite in an application without making your source code available under a GPL-compatible license.
Using Halite in Your Applications
Step 1: Installing libsodium
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.
If you plan to use Halite 2+, you might need to compile libsodium from source since your distribution probably won’t have the necessary version quite yet.
If you plan to use Halite 1, or your distribution has the necessary version already, then you should be able to install a precompiled libsodium package.
Step 2: Installing the PECL libsodium extension
Important Note: It is important that this step is repeated every time that a different version of libsodium is installed. The resulting PECL libsodium extension is version dependent of the currently installed libsodium.
Installation instructions for the PECL libsodium extension can be found in the PECL libsodium book on the Paragon Initiative Enterprises website.
Step 3: Use Composer to install Halite
The last step required to use Halite is to install it using Composer.
For the latest version of Halite:
composer require paragonie/halite
Or for older versions of Halite, specify the version number:
composer require paragonie/halite:^v1
Using Halite in Your Project
Check out the documentation. The basic Halite API is designed for simplicity:
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 === $message); // bool(true)
This should produce something similar to:
Example: Generating a key from a password
<?php use ParagonIE\Halite\HiddenString; use ParagonIE\Halite\KeyFactory; use ParagonIE\Halite\Symmetric\Crypto as Symmetric; $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);