guazi/halite

High-level cryptography interface powered by libsodium

Thursday, March 23, 2017
by leo2018
Repository
1 Watchers
0 Stars
503 Installations

PHP
0 Dependents
0 Suggesters
47 Forks
0 Open issues
43 Versions
3 % Grown

The README.md

Halite

, _(*1)

Halite is a high-level cryptography interface that relies on libsodium for all of its underlying cryptography operations., _(*2)

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., _(*3)

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., _(*4)

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., _(*5)

	PHP	libsodium	PECL libsodium
Halite 2+	7.0.0	1.0.9	1.0.6
Halite 1	5.6.0	1.0.6	1.0.2

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., _(*6)

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., _(*7)

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., _(*8)

Installation instructions for the PECL libsodium extension can be found in the PECL libsodium book on the Paragon Initiative Enterprises website., _(*9)

Step 3: Use Composer to install Halite

The last step required to use Halite is to install it using Composer., _(*10)

For the latest version of Halite:, _(*11)

composer require paragonie/halite

Or for older versions of Halite, specify the version number:, _(*12)

composer require paragonie/halite:^v1

Using Halite in Your Project

Check out the documentation. The basic Halite API is designed for simplicity:, _(*13)

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:, _(*14)

<?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:, _(*15)

<?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:, _(*16)

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

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., _(*17)

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)., _(*18)

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

$encryptionKey = KeyFactory::loadEncryptionKey('/path/outside/webroot/encryption.key');

File::encrypt('input.txt', 'output.txt', $encryptionKey);

The Versions

23/03 2017

dev-stable

High-level cryptography interface powered by libsodium

library halite

High-level cryptography interface powered by libsodium

guazi/halite

The README.md

Halite

Using Halite in Your Applications

Step 1: Installing libsodium

Step 2: Installing the PECL libsodium extension

Step 3: Use Composer to install Halite

Using Halite in Your Project

Example: Encrypting and Decrypting a message

Example: Generating a key from a password

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

The Versions

dev-stable

The Requires

The Development Requires

by Paragon Initiative Enterprises

1.5.6

The Requires

The Development Requires

by Paragon Initiative Enterprises

dev-master

The Requires

The Development Requires

by Paragon Initiative Enterprises

1.5.4

The Requires

The Development Requires

by Paragon Initiative Enterprises

v1.5.3

The Requires

The Development Requires

by Paragon Initiative Enterprises

dev-php5.5_compat

The Requires

The Development Requires

by Paragon Initiative Enterprises

v1.5.2

The Requires

The Development Requires

by Paragon Initiative Enterprises

v3.2.0

The Requires

by Paragon Initiative Enterprises

v3.1.1

The Requires

by Paragon Initiative Enterprises

v2.2.x-dev

The Requires

by Paragon Initiative Enterprises

v2.2.0

The Requires

by Paragon Initiative Enterprises

v3.1.0

The Requires

by Paragon Initiative Enterprises

v3.0.0

The Requires

by Paragon Initiative Enterprises

v1.5.1

The Requires

by Paragon Initiative Enterprises

v2.1.x-dev

The Requires

by Paragon Initiative Enterprises

v2.1.3

The Requires

by Paragon Initiative Enterprises

v2.1.2

The Requires

by Paragon Initiative Enterprises

v2.1.1

The Requires

by Paragon Initiative Enterprises

v2.1.0

The Requires

by Paragon Initiative Enterprises

v2.0.x-dev

The Requires