Basic Halite Usage

This is the Basic Halite API:

* Encryption

* Symmetric
   * `Symmetric\Crypto::encrypt`(`string`, EncryptionKey, `bool?`): `string`
   * `Symmetric\Crypto::decrypt`(`string`, EncryptionKey, `bool?`): `string`
* Asymmetric
   * Anonymous
     * `Asymmetric\Crypto::seal`(`string`, EncryptionPublicKey, `bool?`): `string`
     * `Asymmetric\Crypto::unseal`(`string`, EncryptionSecretKey, `bool?`): `string`
   * Authenticated
     * `Asymmetric\Crypto::encrypt`(`string`, EncryptionSecretKey, EncryptionPublicKey, `bool?`): `string`
     * `Asymmetric\Crypto::decrypt`(`string`, EncryptionSecretKey, EncryptionPublicKey, `bool?`): `string`

* Authentication

* Symmetric
   * `Symmetric\Crypto::authenticate`(`string`, AuthenticationKey, `bool?`): `string`
   * `Symmetric\Crypto::verify`(`string`, AuthenticationKey, `string`, `bool?`): `bool`
* Asymmetric
   * `Asymmetric\Crypto::sign`(`string`, SignatureSecretKey, `bool?`): `string`
   * `Asymmetric\Crypto::verify`(`string`, SignaturePublicKey, `string`, `bool?`): `bool`

Most of the other Halite features build on top of these simple APIs.

Fundamentals

If you're not sure what any of the terms on this page mean, you might be better served reading our guide to cryptography terms and concepts for PHP developers.

Error Handling

Unless stated otherwise, any time Halite encounters invalid data (an attacker tampered with the ciphertext, you have the wrong decryption key, etc.), Halite will throw a typed Exception. If you catch one, you should log the incident and fail closed (i.e. terminate the script gracefully) rather than proceeding as if nothing happened.

For authentication functions, Halite will typically just return false.

Encryption

Symmetric-Key Encryption

First, you'll need is an encryption key. The easiest way to obtain one is to generate it:

$enc_key = \ParagonIE\Halite\KeyFactory::generateEncryptionKey();

This generates a strong random key. If you'd like to reuse it, you can simply store it in a file.

\ParagonIE\Halite\KeyFactory::save($enc_key, '/path/to/encryption.key');

Later, you can load it like so:

$enc_key = \ParagonIE\Halite\KeyFactory::loadEncryptionKey('/path/to/encryption.key');

Encryption should be rather straightforward:

$ciphertext = \ParagonIE\Halite\Symmetric\Crypto::encrypt(
    "Your message here. Any string content will do just fine.",
    $enc_key
);

By default, Crypto::encrypt() will return a hexadecimal encoded string. If you want raw binary, simply pass true as the third argument (similar to the API used by PHP's hash() function).

The inverse operation, decryption is congruent:

$plaintext = \ParagonIE\Halite\Symmetric\Crypto::decrypt(
    $ciphertext,
    $enc_key
);

The important thing to keep in mind is that $enc_key is not a string, it is an instance of \ParagonIE\Halite\Symmetric\EncryptionKey.

If you're attempting to decrypt a raw binary string rather than a hex-encoded string, pass true to the third argument of Crypto::decrypt.

Authenticated Asymmetric-Key Encryption (Encrypting)

This API facilitates message encryption between to participants in a conversation. It requires your secret key and your partner's public key.

Assuming you are Alice, you would generate your keypair like so. (The other person, Bob, will do the same on his end.)

$alice_keypair = \ParagonIE\Halite\KeyFactory::generateEncryptionKeyPair();
$alice_secret = $alice_keypair->getSecretKey();
$alice_public = $alice_keypair->getPublicKey();
$send_to_bob = \Sodium\bin2hex($alice_public->get());

Alice will then load Bob's public key into the appropriate object like so:

$bob_public = new \ParagonIE\Halite\Asymmetric\EncryptionPublicKey(
    \Sodium\hex2bin($recv_from_bob)
);

Encrypting a message from Alice to send to Bob:

$send_to_bob = \ParagonIE\Halite\Asymmetric\Crypto::encrypt(
    "Your message here. Any string content will do just fine.",
    $alice_secret,
    $bob_public
);

As with symmetric-key encryption, this defaults to hexadecimal encoded output. If you desire raw binary, you can pass an optional true as the fourth argument to Crypto::encrypt().

Decrypting a message that Alice received from Bob:

$message = \ParagonIE\Halite\Asymmetric\Crypto::decrypt(
    $received_ciphertext,
    $alice_secret,
    $bob_public
);

Anonymous Asymmetric-Key Encryption (Sealing)

A sealing interface is one where you encrypt a message with a public key, such that only the person possessing the corresponding secret key can decrypt it.

If you wish to seal information, you only need one keypair rather than two:

$seal_keypair = \ParagonIE\Halite\KeyFactory::generateEncryptionKeyPair();
$seal_secret = $seal_keypair->getSecretKey();
$seal_public = $seal_keypair->getPublicKey();

You want to only keep $seal_public stored outside of the trusted environment.

Encrypting an anonymous message:

$sealed = \ParagonIE\Halite\Asymmetric\Crypto::seal(
    "Your message here. Any string content will do just fine.",
    $seal_public
);

Once again, this defaults to hexadecimal encoded output. If you desire raw binary, you can pass an optional true as the fourth argument to Crypto::seal().

Decrypting an anonymous message:

$opened = \ParagonIE\Halite\Asymmetric\Crypto::unseal(
    $sealed,
    $seal_secret
);

Authentication

Symmetric-Key Authentication

Symmetric-key authentication is useful if you'd like to authenticate, but not encrypt, some information that you transfer over a network or share with your end users.

First, you will need an appropriate key. The easiest way to get one is to simply generate one randomly then store it for reuse (similar to secret-key encryption above):

$auth_key = \ParagonIE\Halite\KeyFactory::generateAuthenticationKey();

Authenticating a message:

// MAC stands for Message Authentication Code
$mac = \ParagonIE\Halite\Symmetric\Crypto::authenticate(
    "Your message here. Any string content will do just fine.",
    $auth_key
);

Verifying a message, given the message and a message authentication code:

$valid = \ParagonIE\Halite\Symmetric\Crypto::verify(
    "Your message here. Any string content will do just fine.",
    $auth_key,
    $mac
);
if ($valid) {
    // Success!
}

By default, $mac will be hex-encoded. If you need a raw binary string, pass true as the third (optional) argument to Crypto::authenticate(). You will also need to pass true as the fourth (optional) argument in Crypto::verify().

Asymmetric-Key Authentication (Digital Signatures)

As with anonymous asymmetric-key encryption, you only need one keypair and you only give out your public key.

$sign_keypair = \ParagonIE\Halite\KeyFactory::generateSignatureKeyPair();
$sign_secret = $sign_keypair->getSecretKey();
$sign_public = $sign_keypair->getPublicKey();

Signing a message with a secret key:

$signature = \ParagonIE\Halite\Asymmetric\Crypto::sign(
    "Your message here. Any string content will do just fine.",
    $sign_secret
);

Verifying the signature of a message with its corresponding public key:

$valid = \ParagonIE\Halite\Asymmetric\Crypto::verify(
    "Your message here. Any string content will do just fine.",
    $sign_public,
    $signature
);

The typical rules for hex-encoding apply here as well.