Halite is a PHP library that offers a simplified interface to using the PHP extension for libsodium.
Halite emphasizes simplicity without sacrificing any of the security that libsodium offers.
Halite is free software, released under GPLv3.
If you require a non-GPL commercial license for your project, please get in touch.
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).
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.
Halite offers secure HTTP cookies using authenticated encryption out of the box.
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.
Your mileage may vary. The link contains detailed instructions for various operating systems.
apt-get install libsodium-dev php5-dev pecl install libsodium
composer require paragonie/halite
Please see the documentation on the Halite repository on Github for up-to-date usage instructions and guidelines.
<?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 */
Keyobject 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();
<?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);
/** * 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 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);
Will tomorrow bring costly and embarrassing data breaches? Or will it bring growth, success, and peace of mind?
Our team of technology consultants have extensive knowledge and experience with application security and web/application development.
Want the latest from Paragon Initiative Enterprises delivered straight to your inbox? We have two newsletters to choose from.
The first mails quarterly and often showcases our behind-the-scenes projects.
The other is unscheduled and gives you a direct feed into the findings of our open source security research initiatives.