Re-key

Re-keying the EDEK for a document changes which customer KMS is required to access the document without touching the encrypted data. It is a faster, simpler alternative to decrypting data and encrypting it again. re-keying is possible because of envelope encryption and is done by unwrapping just the encrypted document encryption key (EDEK) and then re-wrapping it using a new KMS config. The EDEK can be re-wrapped using a different tenant’s KMS configuration, or using a different KMS config for its existing tenant; this provides a way to update documents to use a new KMS config so the old KMS config can be removed. This can be useful for migrating a tenant’s data from one KMS config to another or for merging/splitting tenant accounts.

In order to re-key an existing encrypted document, you first define metadata that specifies the tenant ID that was used when the document was encrypted. Similar to encrypt, you must also provide the ID of the service or user that is performing the decryption and a label for the type of data being re-keyed. These fields help build richer audit trails that provide more context to your customers about what data is being re-keyed, by whom, and why.

The tenantId field of the provided metadata must be the same as the one specified when the data was encrypted so that the proper tenant KMS config is used to unwrap the EDEK. The other metadata fields do not have to match and are only used to improve auditing.

Java

DocumentMetadata metadata = new DocumentMetadata("TENANT_ID", "serviceOrUserId", "data label");

JavaScript

const metadata = new DocumentMetadata("TENANT_ID", "serviceOrUserId", "data label");

PHP

$metadata = new RequestMetadata("TENANT_ID", new IclFields("serviceOrUserId", "data label"), []);

Go

metadata := tsc.RequestMetadata{TenantID: "TENANT_ID", 
    IclFields: tsc.IclFields{RequestingID: "serviceOrUserId", DataLabel: "data label"},
    CustomFields: nil}

re-key the EDEK by providing it along with the target tenant ID (the tenant whose KMS should now be used to protect the document). The re-key call makes a request to the Tenant Security Proxy which in turn makes a request to the original tenant’s KMS to unwrap the EDEK that you’ve provided. The Tenant Security Proxy then makes an additional call to the new tenant’s KMS (using the KMS config currently marked as primary for the new tenant) to re-wrap the decrypted DEK. The new EDEK is returned to the client as a byte string.

Java

String edek = /* base64 encoded EDEK from your persistence layer */;
client.rekeyEdek(edek, metadata, newTenantId).thenCompose(rekeyed -> {
    String newEdek = rekeyed.getEdek();
    // Store the updated edek in your persistence layer.
})

JavaScript

const edek = /* base64 encoded EDEK from your persistence layer */;
client.rekeyEdek(edek, newTenantId, metadata).then((rekeyed) => {
    const newEdek = rekeyed.edek;
    // Store the updated edek in your persistence layer.
});

PHP

$edek = new Bytes(/* base64 encoded EDEK from your persistence layer */);
$newEdek = $client->rekeyEdek($edek, $newTenantId, $metadata);
$newEdekString = $newEdek->getByteString();
// Store the updated edek in your persistence layer.

Go

edek := /* base64 encoded EDEK from your persistence layer */
newEdek, err := client.RekeyEdek(ctx, &tsc.Edek{Bytes: edek}, newTenantId, &metadata)
// Store the updated edek in your persistence layer.