Repository files navigation

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

Halite was created byParagon Initiative Enterprises asa result of our continued efforts to improve the ecosystem and makecryptography in PHPsafer and easier to implement.

You can read theHalite Documentation online.

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

If you are satisfied with the terms of MPL software for backend web applicationsbut 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 Licenseversion 3 (GPLv3). Only Halite 4.0.1 and newer are available under the Mozilla PublicLicense terms.

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

Note: Halite 5.0.x works on PHP 8.0, but performance is worse than on PHP 8.1.

If you need a version of Halite before 5.1, see the documentation relevant to thatparticular branch.

To install Halite, you first need toinstall 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 throughComposer:

composer require paragonie/halite:^5

Free (gratis) support for Halite only extends to the most recent major version (currently 5).

If your company requires support for an older version of Halite,contact Paragon Initiative Enterprises to inquire aboutcommercial support options.

If you need an easy way to migrate from older versions of Halite, check outhalite-legacy.

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

• Encryption
  • Symmetric
    • Symmetric\Crypto::encrypt(HiddenString,EncryptionKey):string
    • Symmetric\Crypto::encryptWithAD(HiddenString,EncryptionKey,string):string
    • Symmetric\Crypto::decrypt(string,EncryptionKey):HiddenString
    • Symmetric\Crypto::decryptWithAD(string,EncryptionKey,string):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::encryptWithAD(HiddenString,EncryptionSecretKey,EncryptionPublicKey,string):string
      • Asymmetric\Crypto::decrypt(string,EncryptionSecretKey,EncryptionPublicKey):HiddenString
      • Asymmetric\Crypto::decryptWithAD(string,EncryptionSecretKey,EncryptionPublicKey,string):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

First, generate and persist a key exactly once:

<?phpuseParagonIE\Halite\KeyFactory;$encKey = KeyFactory::generateEncryptionKey();KeyFactory::save($encKey,'/path/outside/webroot/encryption.key');

And then you can encrypt/decrypt messages like so:

<?phpuseParagonIE\Halite\KeyFactory;useParagonIE\Halite\Symmetric\CryptoasSymmetric;useParagonIE\HiddenString\HiddenString;$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');$message =newHiddenString('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

Important: Halite works withKey objects, not strings.

If you attempt toecho a key object, you will get an empty stringrather than its contents. If you attempt tovar_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 wantto inspect a key's raw binary contents. This is not recommended formost use cases.

<?phpuseParagonIE\Halite\KeyFactory;useParagonIE\HiddenString\HiddenString;$passwd =newHiddenString('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.

Halite includes a file cryptography class that utilizes a streaming API toallow large files (e.g. gigabytes) be encrypted on a system with very littleavailable memory (i.e. less than 8 MB).

<?phpuseParagonIE\Halite\File;useParagonIE\Halite\KeyFactory;$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');File::encrypt('input.txt','output.txt',$encryptionKey);

PHP Fatal error: Uncaught SodiumException: This is not implemented, as it is not possible to securely wipe memory from PHP

The solution to this is to make sure libsodium is installed/enabled. See above in thisREADME for more information.

If your company uses this library in their products or services, you may beinterested inpurchasing a support contract from Paragon Initiative Enterprises.