Benefits of Halite over Vanilla Libsodium

1. Simplicity

Halite carries no additional complexity overhead for nonce management. You only need to manage your keys (which are represented by data objects to prevent common sources of user error).

2. Streaming File Encryption Library

Halite offers a simplified interface for encrypting and decrypting files. It exposes both a shared secret-key interface (leveraging purely symmetric-key cryptography) and a public-key interface where files are encrypted with a public key and decrypted with the associated private key.

3. Pre-Built Components

Halite offers secure HTTP cookies using authenticated encryption out of the box.

Relationship with Libsodium

Much of the functionality Halite offers was at one point requested to be added to libsodium, but they were specific use-cases and rightly rejected, since for most users they would only add clutter to the API.

Paragon Initiative Enterprises wrote Halite to satisfy these users' requirements with a higher-level interface.

Libsodium is a powerful NaCl fork created and maintained by Frank Denis and released under the ISC License. None if this would be possible if not for his efforts to make cryptography more accessible to developers in every language.

How to Install Halite in Your Projects

1. Make sure you install the PHP extension for libsodium. On newer versions of Debian-based Linux, this consists of two commands:

   apt-get install libsodium-dev php5-dev
   pecl install libsodium

   Your mileage may vary. The link contains detailed instructions for various operating systems.
2. Use composer to add Halite as a dependency:

   composer require paragonie/halite

Getting Started with Halite

Please see the documentation on the Halite repository on Github for up-to-date usage instructions and guidelines.

---

Generating Encryption Keys

<?php

use \ParagonIE\Halite\EncryptionKeyPair;
use \ParagonIE\Halite\SignatureKeyPair;
use \ParagonIE\Halite\Symmetric\AuthenticationKey;
use \ParagonIE\Halite\Symmetric\EncryptionKey;

// For symmetric-key encryption:
$encryption_key = EncryptionKey::generate();

// For symmetric-key authentication:
$message_auth_key = AuthenticationKey::generate();

// For asymmetric-key encryption:
$enc_keypair = EncryptionKeyPair::generate();
    $enc_secret = $enc_keypair->getSecretKey();
    $enc_public = $enc_keypair->getPublicKey();

// For asymmetric-key authentication (digital signatures):
$sign_keypair = SignatureKeyPair::generate();
    $sign_secret = $sign_keypair->getSecretKey();
    $sign_public = $sign_keypair->getPublicKey();

/**
 * $enc_secret will be an instance of \ParagonIE\Halite\Asymmetric\EncryptionSecretKey
 * $enc_public will be an instance of \ParagonIE\Halite\Asymmetric\EncryptionPublicKey
 * $sign_secret will be an instance of \ParagonIE\Halite\Asymmetric\SignatureSecretKey
 * $sign_public will be an instance of \ParagonIE\Halite\Asymmetric\SignaturePublicKey
 */

Additionally, any Key object can be derived from a password and stored salt, which leverages scrypt (provided by libsodium) to stretch a password into the desired key:

$encryption_key = EncryptionKey::deriveFromPassword(
    $password,
    getenv('HALITE_ENCRYPTION_KEY_SALT')
);

$enc_keypair = EncryptionKeyPair::deriveFromPassword(
    $password,
    getenv('HALITE_ENCRYPTION_KEY_SALT')
);
    $enc_secret = $enc_keypair->getSecretKey();
    $enc_public = $enc_keypair->getPublicKey();

Symmetric-Key Cryptography with Halite

Encryption:

<?php
use \ParagonIE\Halite\Primitive\Symmetric;
use \ParagonIE\Halite\EncryptionKey;

/**
 * Generate a new encryption key
 */
$encryption_key = EncryptionKey::generate();

/**
 * This will return a hex-encoded string.
 * 
 * $plaintext is your message
 * $encryption_key is a Key object (generated above)
 */
$ciphertext = Symmetric::encrypt($plaintext, $encryption_key);

/**
 * To get raw binary, pass TRUE as the third argument:
 */
$raw_ciphertext = Symmetric::encrypt($plaintext, $encryption_key, true);

Decryption:

/**
 * This expects a hex-encoded string.
 */
$decrypted = Symmetric::decrypt($ciphertext, $encryption_key);

/**
 * If you're decrypting raw binary, pass TRUE to the third argument:
 */
$raw_decrypt = Symmetric::decrypt($raw_ciphertext, $encryption_key, true);

As you can see, you don't need to create and manage your own nonces. Halite does this step for you. Nonces are included with the ciphertext, and are covered by the authentication tag (along with a prefix that identifies the version of Halite used to encrypt a particular message).

File Cryptography with Halite

Halite's File class is a swiss army knife of simple tools that allow you to perform cryptographic operations on large files with minimal memory usage.

<?php
use \ParagonIE\Halite\File;
// Encrypt a file with symmetric-key cryptography
File::encrypt($inputFile, $outputFile, $encryption_key);

// Decrypt a file with symmetric-key cryptography
File::decrypt($inputFile, $outputFile, $encryption_key);

// Encrypt a file with asymmetric-key cryptography
File::seal($inputFile, $outputFile, $enc_public);

// Decrypt a file with asymmetric-key cryptography
File::unseal($inputFile, $outputFile, $enc_secret);

// Get the checksum of a file
$checksum = File::checksum($filename);

// Get the cryptographic signature of a file's checksum
$signature = File::sign($filename, $sign_secret);

// Verify the authenticity of a digitally signed file
$valid = File::verify($filename, $sign_public, $signature);