CMK Tenant Security Client (Legacy)

Note: The Alloy SDKs are the preferred way of interacting with the SaaS Shield platform going forward due to their additional features and ease of support.

The Tenant Security Client is an SDK which provides a simplified interface for making requests to the Tenant Security Proxy. It provides method calls for encrypting and decrypting tenant data either as a single document or in batch operations.

All data passed to the SDK is encrypted directly within the SDK. Your customers’ data is never transferred to the Tenant Security Proxy. Instead, the Tenant Security Proxy is responsible for generating document encryption keys (DEKs) and encrypted document encryption keys (EDEKs) and providing them to the client, which uses the key to do the encryption work. If these acronyms are confusing, envelope encryption will give you a better sense of how these keys are generated and used.

On an encrypt operation, the client sends a request to the Tenant Security Proxy to generate and encrypt a DEK using your customer’s KMS. The Tenant Security Client then uses this DEK to AES encrypt the provided data. An Encrypted Document Encryption Key (EDEK) and the encrypted data are returned to your application to be persisted. The unencrypted DEK is immediately discarded.

The cardinal rule for CMK is that you, the vendor, are never given access to the unencrypted DEK. You store the encrypted DEK alongside encrypted application data. Since only the customer can unlock the EDEK, this pattern gives your customers independent access control and an independent audit log.

On a subsequent decrypt call, your application provides the encrypted DEK and the encrypted data to the Tenant Security Client, which will use the Tenant Security Proxy to decrypt this EDEK. The EDEK decryption, or unwrapping operation, is done in conjunction with your customer’s KMS, producing the original DEK used to encrypt. This resulting DEK is passed back to the Tenant Security Client, where it is used to decrypt the data back to its original form.

Deterministic Encryption

The TSC APIs include method calls for encrypting and decrypting data deterministically. (A basic description of deterministic encryption is available here, and more details on how it works in SaaS Shield are here). The APIs are similar to the standard encryption and decryption routines, with the addition of a routine that encrypts a value so that you can search your data store for matching entries.

As with the other encrypt and decrypt operations, the TSC handles all of the encryption and decryption of data; it relies on the TSP to supply a key to use for the operation, but never passes the data to the TSP. Unlike the other encryption and decryption routines, the deterministic encryption routines do not use the TSP to generate a random DEK and wrapped EDEK for each piece of data. Instead, the deterministic encryption routines take the data and a data path, which is split into a secret path and a derivation path. The TSC relies on the TSP to locate or generate a secret value for each unique combination of KMS configuration and secret path and then to use that secret to derive a DEK for each unique combination of tenant ID and derivation path.

On an encrypt operation, the caller provides the tenant ID, the secret path and derivation path to use, and the data to encrypt. The TSC sends tenant ID, secret path, and derivation path to the TSP, and the TSP sends back a DEK and corresponding secret ID. The TSC uses this DEK to encrypt the data using the AES-SIV algorithm. The TSC prepends the secret ID to the encrypted data and returns the data to the caller. Because the DEK is the same for all data items encrypted with the same data path and tenant, the TSC doesn’t return an EDEK with each response. Once the encryption operation is complete, the DEK is immediately discarded.

On a subsequent decrypt operation, the caller provides the encrypted data along with the secret and derivation paths - these two values must match the ones that were provided when the data was encrypted. The TSC extracts the secret ID from the header on the encrypted data and requests a derived key from the TSP for that secret ID and paths. If the TSP returns the requested key, the TSC decrypts and returns the data.

The TSC provides an additional operation to be used to search deterministically encrypted data for a specific value. This generate search term method takes the search data, tenant ID, and secret and derivation paths. It is very similar to an encrypt operation - the TSC requests a key from the TSP for the specified tenant and paths. If the TSP determines that the appropriate secret for the specified tenant and secret path is not being rotated, it will perform the same key derivation it would do for a normal encrypt operation, returning the key and the secret ID. The TSC method will encrypt the data with that key and ID and return the encrypted data to the caller. Your application can search the field in the data store for matches to that value.

However, if a secret rotation is in progress, the TSP will actually compute two keys, one derived from the secret being rotated and one derived from the new secret. The TSP returns both keys and secret IDs, and the TSC encrypts the search data twice, once using each key and secret ID. The TSC method returns both encrypted data values to the caller; your application is responsible for searching the data store for fields that match either of those values.

This is the flow if there is no secret rotation in progress:

If the tenant’s secret is being rotated, this is the flow:

SDK Languages

The Tenant Security client library is provided in multiple languages:

• Java
• NodeJS
• PHP
• Go

Disaster Recovery

In the case of a catastrophic disaster your tenant’s data can still be recovered as long as they (or you) have access to the KMS keys used to encrypt their data. Our disaster recovery document covers the technical details of the process. It also provides example NodeJS code, which you can easily adapt to other languages.