Skip to content

Latest commit

 

History

History
372 lines (281 loc) · 11.9 KB

Basic.md

File metadata and controls

372 lines (281 loc) · 11.9 KB

Basic Halite Usage

This is the Basic Halite API:

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

Encryption functions expect your message to be encapsulated in an instance of the HiddenString class. Decryption functions will return the decrypted plaintext in a HiddenString object.

Symmetric-Key Encryption

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

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

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

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

Later, you can load it like so:

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

Or if you want to store it in a string, rather than on the filesystem:

$key_hex = KeyFactory::export($enc_key)->getString();

and get it back later

$enc_key = KeyFactory::importEncryptionKey(new HiddenString($key_hex));

Encryption should be rather straightforward:

use ParagonIE\HiddenString\HiddenString;

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

By default, Crypto::encrypt() will return a base64url-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.

Additional Associated Data

Sometimes encrypting a message isn't sufficient protection, and you also want to bind an encrypted message to some context. Usually, this happens when you're concerned with Confused Deputy Attacks.

The simplest way to accomplish this is to use Halite's EncryptWithAD() and DecryptWithAD() methods.

Note: The Additional Associated Data is NOT stored in the encrypted message. You must manage these strings yourself to ensure successful decryption.

use ParagonIE\HiddenString\HiddenString;

$ad = 'Additional data that must be passed to both encrypt and decrypt calls';

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

This string must also be provided in the other direction:

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

This will not succeed:

try {
    \ParagonIE\Halite\Symmetric\Crypto::decryptWithAD(
        $ciphertext,
        $enc_key,
        'Incorrect String'
    );
} catch (\ParagonIE\Halite\Alerts\HaliteAlert $ex) {
    var_dump($ex->getMessage());
    exit;
}

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->getRawKeyMaterial());

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

$bob_public = new \ParagonIE\Halite\Asymmetric\EncryptionPublicKey(
    new HiddenString(
        sodium_hex2bin($recv_from_bob)
    )
);

Encrypting a message from Alice to send to Bob:

$send_to_bob = \ParagonIE\Halite\Asymmetric\Crypto::encrypt(
    new HiddenString(
        "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
);

Additional Associated Data with Asymmetric Encryption

If you've read the section on Symmetric Encryption, this should be unsurprising.

$ad = 'Additional Data that must be asserted on decrypt';

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

And decryption is similarly straightforward:

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

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:

use ParagonIE\HiddenString\HiddenString;

$sealed = \ParagonIE\Halite\Asymmetric\Crypto::seal(
    new HiddenString(
        "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.