README

This repository exists to provide a distinct Composer package useful for integrating CipherSweet with AWS KMS.

Installing

composer require paragonie/ciphersweet-provider-aws-kms

Usage

KmsKeyProvider

The basic KmsKeyProvider class is intended to work with a single Encrypted Data Key (EDK). If you're looking to provide multi-tenancy (e.g., one data key per user), look instead at MultiTenantKmsKeyProvider.

First, you'll need a KmsClient object, a desired CipherSweet backend, and the Key ID or ARN for the KMS key you want to use.

<?php
use Aws\Kms\KmsClient;
use ParagonIE\Certainty\RemoteFetch;
use ParagonIE\CipherSweet\Backend\BoringCrypto;
use ParagonIE\CipherSweet\KeyProvider\KmsKeyProvider;

// Recommended: always use the latest CACert bundle
$remoteFetch = new RemoteFetch('/path/to/cacert-dir');
$latestBundle = $remoteFetch->getLatestBundle()->getFilePath();
$keyID = ''; /* get this from KMS */

$kmsClient = new KmsClient([
    'profile' => 'default',
    'region' => 'us-east-1',
    'http' => ['verify' => $latestBundle]
]);

// Recommended: Use encryption context for your apps
$encryptionContext = [
    'app' => 'foo.example.com'
];

Once you have these value defined, you will first want to generate a new data key and persist the Encrypted Data Key to be reused, like so:

$newKey = KmsKeyProvider::generate(
    $kmsClient,
    new BoringCrypto(), // Your backend goes here
    $keyID,
    $encryptionContext
);
// Save this somewhere so you can reuse it:
$edk = $newKey->getEncryptedDataKey();

From now on, you can simply load your backend as follows:

// Moving forward, you can simply instantiate your key provider like so:
$provider = new KmsKeyProvider(
    $kmsClient,
    new BoringCrypto(), // Your backend goes here
    $keyID,
    $encryptionContext,
    $edk
);

See also: caching

MultiTenantKmsKeyProvider

The purpose of the provided MultiTenantKmsKeyProvider class is to facilitate workloads where multiple users have their data encrypted with different EDKs. This can safely be used with the same KMS Key or with different KMS Keys. Whatever makes the most sense for your application.

The basic idea behind our design is that some metadata about tenants is stored in a column (which has a value populated for each row):

/** @var \ParagonIE\CipherSweet\KeyProvider\MultiTenantKmsKeyProvider $multiPro */
$multiPro->setTenantColumnForTable('table_name', 'tenant_id_column_name');

Somewhere else in your application, you will need a mapping of tenant IDs to EDKs. This MAY be a separate SQL table. We have provided some convenience utilities to make integration easier, but you're free to decide your own mapping and persistence strategy.

To that end, our multi-tenant key provider allows you to provide a class that implements TenantEDKInterface to fetch EDKs and other metadata, as well as create tenants. You are free to implement this however you wish. See, for example, our EasyDB test class.

To create a new tenant (and a new EDK), simply pass the new tenant's ID, the KMS Key ID or ARN, and Encryption Context to use for encrypting this key.

// Calling createTenant() will persist it to memory
$specificProvider = $multiPro->createTenant($tenantID, $kmsKeyID, $encryptionContext);

With this little bit of additional glue code on your end, you're all set.

<?php
use ParagonIE\CipherSweet\CipherSweet;
use ParagonIE\CipherSweet\EncryptedMultiRows;
use ParagonIE\CipherSweet\KeyProvider\MultiTenantKmsKeyProvider;

/**
 * @var \Aws\Kms\KmsClient $kmsClient
 * @var \ParagonIE\CipherSweet\KeyProvider\TenantEDKInterface $edkLookup
 */

$multiPro = (new MultiTenantKmsKeyProvider())
    ->setEDKLookup($edkLookup)
    ->setKmsClient($kmsClient);

$multiPro->setTenantColumnForTable('table_1_name', 'tenant_id');

$multiPro->createTenant('example_1', 'kms_key_id_goes_here', ['region' => 'us-east-2']);
$multiPro->createTenant('example_2', 'kms_key_id_goes_here', ['region' => 'us-west-1']);

$engine = new CipherSweet($multiPro, $multiPro->getBackend());
$encryptManyRows = (new EncryptedMultiRows($engine))->setAutoBindContext(true);

And then you can just use CipherSweet as usual.

Using a Static Key for Blind Indexing with Multi-Tenancy

You can toggle this on with a single call to multi-tenant key provider.

$multiPro->setStaticBlindIndexTenant("dedicated-searching-tenant-id-goes-here");

To toggle this feature back off, pass null instead:

$multiPro->setStaticBlindIndexTenant(null);

Caching

Network round-trips to AWS KMS can be a performance bottleneck for your application, especially if you're running it outside of AWS.

Applications MAY provide a PSR-16 compatible cache to persist plaintext data keys across requests.

/**
 * @var \ParagonIE\CipherSweet\KeyProvider\MultiTenantKmsKeyProvider $multiPro
 * @var \ParagonIE\CipherSweet\KeyProvider\KmsKeyProvider $provider
 * @var \Psr\SimpleCache\CacheInterface $yourCache
 */

// This will pass $yourCache to all KmsKeyProviders managed by this multi-tenant provider:
$multiPro->setDataKeyCache($yourCache);

// For only one single-tenant provider:
$provider->setDataKeyCache($yourCache);