1. Docs

What is Key Leasing?

Once you have added CMK to your application, your customers can be confident that they control access to their sensitive data that you are holding. However, this comes at a cost - each request within your application to save or access sensitive data requires a round-trip over the Internet to the appropriate customer’s KMS to wrap or unwrap a key. Depending on your use case and response times, this could increase latency more than is desirable inside your application. It can also subject your application to errors if the network path to a customer’s KMS is down. SaaS Shield provides a feature that mitigates the impact, without sacrificing your customers’ ability to protect their data and monitor its usage.

Key leasing is a technique that SaaS Shield provides to do an extra layer of key wrapping, so that it is not necessary for the TSP to make a request to a tenant’s KMS on every key wrap and unwrap operation. Instead, it leases a key, wrapping it using the tenant’s KMS, and it uses that key for a period of time to wrap and unwrap the keys that encrypt application data. This key is only used for a single tenant’s data; each tenant that enables key leasing gets separate keys.

How Does It Work?

When a tenant enables key leasing, a TSP that services that tenant generates a random Leased Key (LK) for the tenant and wraps that key using the tenant’s active KMS to create an Encrypted Leased Key (ELK). The TSP holds LKs in memory, and any time the TSP gets a request to wrap a DEK for a tenant, it uses that tenant’s active LK to encrypt the DEK and create the EDEK. The LK serves as a surrogate for the tenant’s KMS. The TSP embeds the LK’s ID in the EDEK, so it knows how to unwrap the EDEK in the future. (This is analogous to the way KMSes embed a key identifier in a wrapped key and use that to unwrap the key later.)

SaaS Shield includes a number of features to protect the leased keys and allow the tenant to control access to data, including the following:

  • Per-tenant LKs are rotated every 90 days. Old LKs are still available to unwrap older EDEKs, but the new one is used for all key wrap requests.
  • LKs are flushed from TSP memory after four hours. If the LK is needed again, the TSP calls the tenant’s KMS to unwrap the ELK.
  • The TSP does a revocation check on each ELK with the tenant’s KMS every ten minutes. If the KMS refuses to unwrap the ELK, the corresponding LK is considered revoked and is removed from memory.

Performing the revocation checks ensure that if a tenant revokes the vendor’s access to their KMS, the TSPs will stop encrypting or decrypting data protected by that KMS within at most ten minutes. This is the worst case; on average, revocation would take effect in five minutes. However, if a network error or other problem disrupts the ability for the TSP to contact the KMS, the LK can still be used until it is flushed from memory. This gives the SaaS Shield system resilience to transient interruptions of KMS service.

When a TSP generates a new ELK, it sends that ELK, along with the ID of the KMS configuration, to the Configuration Broker. The Configuration Broker checks to see if there is already an active ELK for that KMS; if so, it sends the active ELK back to the TSP. If not, it stores the ELK, assigns it an ID, and returns the same ELK to the TSP. This process ensures that there is a single active ELK for each KMS, even if multiple TSPs attempt to create an LK for a tenant after key leasing is enabled or an LK expires.

Guaranteeing Encrypted Data Access

In order to enable recovery of any data encrypted while key leasing is enabled, the TSP includes the ELK along with the LK ID when it generates an EDEK using an LK. This would allow the tenant’s administrators to use their KMS to unwrap the ELKs and recover the DEKs that could decrypt encrypted data.

Requiring Key Leasing

Because key leasing significantly reduces the latency on calls to encrypt or decrypt data, a vendor that uses SaaS Shield in their application might prefer for each of their tenants to enable key leasing on each of their KMS configurations. SaaS Shield allows a vendor to set a configuration setting, key leasing required, for each tenant. This setting specifies that all KMS configurations that are assigned to the vendor for that tenant (whether by the tenant or the vendor) must have key leasing enabled. If the admin tries to assign a KMS configuration that doesn’t have key leasing enabled, they will be notified, and the assignment will not be saved. If key leasing is required for a tenant and an admin tries to disable key leasing on a KMS configuration assigned to the tenant, an error will also be generated. This is a per-tenant setting that the vendor admins can change. If an admin tries to require key leasing for a tenant, but the tenant has one or more KMS configurations that do not have key leasing enabled, the admin will also be notified of the error.

There is also a configuration setting for the vendor, default key leasing required; if this is set, any new tenants that the vendor invites will automatically have the key leasing required setting enabled.

More details about how these settings are accessed in the Configuration Broker here.


Operation without Key Leasing

Recall the normal sequence of operations when your application wants to encrypt some data:

Your ApplicationTenant Security ClientTenant Security ProxyCustomer KMSencrypt(data)Request DEK+EDEKGenerate random DEKwrap(DEK)Return EDEKReturn DEK, EDEKaes-encrypt(data, DEK)Discard DEKReturn enc data, EDEKYour ApplicationTenant Security ClientTenant Security ProxyCustomer KMS
Likewise, when your application wants to decrypt the data, it follows this sequence: Your ApplicationTenant Security ClientTenant Security ProxyCustomer KMSdecrypt(encrypted data, EDEK)unwrap(EDEK)unwrap(EDEK)Return DEKReturn DEKaes-decrypt(encrypted data, DEK)Discard DEKReturn dataYour ApplicationTenant Security ClientTenant Security ProxyCustomer KMS

Operation with Key Leasing

When key leasing is enabled for a tenant, this is the sequence of operations to encrypt data:

Your ApplicationTenant Security ClientTenant Security ProxyCustomer KMSConfiguration Brokerencrypt(data)Request DEK+EDEKGenerate random DEKGenerate random LKwrap(LK)Return ELKSend ELKReturn active ELK for KMSopt[TSP does not have ELK for tenant]unwrap(ELK)Return LKopt[TSP does not have LK for tenant]local_wrap(DEK, LK)Return DEK, ELK+EDEKaes-encrypt(data, DEK)Discard DEKReturn enc data, ELK+EDEKYour ApplicationTenant Security ClientTenant Security ProxyCustomer KMSConfiguration Broker
Decrypting data using key leasing follows this sequence: Your ApplicationTenant Security ClientTenant Security ProxyCustomer KMSdecrypt(enc data, ELK+EDEK)unwrap(ELK+EDEK)unwrap(ELK)Return LKopt[TSP does not haveLK matching the ELK]local_unwrap(EDEK, LK)aes-decrypt(enc data, DEK)Discard DEKReturn dataYour ApplicationTenant Security ClientTenant Security ProxyCustomer KMS

Was this page helpful?