Setting up CipherSweet at Run-Time

Select Your Backend

First, you'll need to decide if you have any strict operational requirements for your encryption. This mostly boils down to whether or not you need all encryption to be FIPS 140-3 compliant or not, in which case, you'll need to use the FIPSCrypto backend.

If you aren't sure, the answer is that you probably don't, and feel free to use BoringCrypto instead.

Note: FIPSCrypto doesn't magically grant you "FIPS compliance". You still must use an OpenSSL FIPS module with PHP in order to use FIPS validated cryptography in your application. When in doubt, ask your compliance officer.

<?php
use ParagonIE\CipherSweet\Backend\FIPSCrypto;
use ParagonIE\CipherSweet\Backend\BoringCrypto;

$fips = new FIPSCrypto(); // Use only FIPS 140-3 algorithms
$boring = new BoringCrypto(); // Uses libsodium

Define your Key Provider

After you choose your backend, you'll need a KeyProvider. We provide a few out-of-the-box, but we also provide an interface that can be used to integrate with any key management service in your code.

The simplest example of this is the StringProvider, which accepts a string containing your encryption key:

<?php
use ParagonIE\CipherSweet\KeyProvider\StringProvider;

$provider = new StringProvider(
    // Example key, chosen randomly, hex-encoded:
    '4e1c44f87b4cdf21808762970b356891db180a9dd9850e7baf2a79ff3ab8a2fc'
);

You can pass a raw binary string, hex-encoded string, or base64url-encoded string to the StringProvider constructor, provided the decoded key is 256 bits.

Attempting to pass a key of an invalid size (i.e. not 256-bit) will result in a CryptoOperationException being thrown. The recommended way to generate a key is:

<?php
use ParagonIE\ConstantTime\Hex;

var_dump(Hex::encode(random_bytes(32)));

Note: It's possible to use multi-tenant-aware key providers with CipherSweet, but we don't ship one with the base library to reduce bloat.

Cloud Key Management Integration

We have published the following cloud key management integrations for CipherSweet:

Start Your Engines

Once you have these two, you can actually start the engine (CipherSweet). Building on the previous code example:

<?php
use ParagonIE\CipherSweet\Backend\BoringCrypto;
use ParagonIE\CipherSweet\CipherSweet;
use ParagonIE\CipherSweet\KeyProvider\StringProvider;

$provider = new StringProvider(
    // Example key, chosen randomly, hex-encoded:
    '4e1c44f87b4cdf21808762970b356891db180a9dd9850e7baf2a79ff3ab8a2fc'
);

$engine = new CipherSweet($provider);

If you're using FIPSCrypto instead of BoringCrypto, you just need to pass it to the second argument of the CipherSweet constructor. If you do not specify a backend, it will default to BoringCrypto.

<?php
use ParagonIE\CipherSweet\Backend\FIPSCrypto;
use ParagonIE\CipherSweet\CipherSweet;
use ParagonIE\CipherSweet\KeyProvider\StringProvider;

$provider = new StringProvider(
    // Example key, chosen randomly, hex-encoded:
    '4e1c44f87b4cdf21808762970b356891db180a9dd9850e7baf2a79ff3ab8a2fc'
);
$engine = new CipherSweet($provider, new FIPSCrypto());

Next: Basic CipherSweet Usage