Skip to main content

Key Management

Data encryption via Antimatter is done using well known encryption algorithms such as AES-256-GCM. When encrypting, a new data encryption key (DEK) is generated for each capsule. This key is then wrapped with an intermediate encryption key, referred to as the key encryption key (KEK). The KEK is in turn secured using a root encryption key (REK) with the algorithm used to encrypt the KEK being governed by the REK provider.

This hierarchy of keys allows for a single key, the REK, to be used to encrypt all data associated with a domain. By introducing an intermediate, KEK between the root and data keys, it is possible to have the REK managed outside of Antimatter while still being performant. This also allows for the REK to be rotated without resulting in data loss. Managing how a root key for a domain is hosted an important component of Antimatter and can be done in a number of ways:

  • Have the root key hosted by antimatter.
  • Have the key hosted by an external key provider such as AWS, GCP or Azure.
  • Provide your own key material that can act as the provider.

Key rotation​

Whenever the active REK is changed, a new KEK is immediately generated. All future capsules that are created will automatically be encrypted using the new KEK, and therefore the new REK. However, there is still data encrypted under the previous keys. You will notice that if you attempt to remove an old key that is still required to access some capsules, you will receive an error (Antimatter will not let you remove a key if it would lead to data loss).

In order to rotate all the old KEKs and re-encrypt them under the new REK, you need to call rotate. This is a batched operation that does 100 KEKs at a time, so you will need to call it more than once if it returns has_more as True:

am keys rotate

Which will print the following, once all keys have been rotated:

Key Encryption Keys rotated
All KEKs are now encrypted with the active Root Encryption Key

Once that has been done, you can remove any of the non-active Root Encryption Keys (the default key cannot be removed).

Flush key encryption key cache​

Antimatter makes use of caches in order to keep our services performant. One such cache is the KEK cache that stores a decrypted KEK, by a REK, for 5 minutes (see Encryption for more information). If you wish to flush this KEK cache for a domain before its natural expiration time, you can use the flush command given below:

am keys flush

Due to how Antimatter's systems work, this command only requests a KEK cache flush. A successful response only indicates that the flush request has been submitted. Please allow up to 10 seconds for the request to complete. A successful request will print the following:

Flushing Key Encryption Key cache for the domain dm-xxxxxxxxxxx. Please allow 10 seconds for this operation to complete.

Furthermore, any KEK flushed will not be immediately reloaded into the cache. Instead, the KEKs flushed by this command will only be loaded back into the cache when a request is received that uses the required KEK. Only the required KEK is newly cached in this case.