> ## Documentation Index
> Fetch the complete documentation index at: https://keyring.docs.composio.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Encryption and key hierarchy
> Understand the customer-owned keys that protect credentials at ingress, storage, and use.
export const KeyHierarchyDiagram = () => ;
export const DekFlowDiagram = ({mode}) => {
const labels = {
mint: "Composio sends Keyring a request for a new data-encryption key. Keyring generates it, your KMS wraps it with the root key, and the wrapped DEK envelope travels back to Composio, which stores it in its database.",
cache: "Composio sends three decrypt requests with the same DEK envelope. The first makes Keyring ask your KMS to unwrap the DEK; the next two are served from Keyring's in-memory cache without a KMS call.",
revoke: "KMS access is revoked. Composio sends a decrypt request with a DEK envelope, Keyring asks your KMS to unwrap it, the KMS refuses, and the credential stays locked."
};
const dbCaptions = {
mint: "DEK envelopes",
cache: "DEK envelopes",
revoke: "DEK envelopes"
};
return
;
};
Keyring uses envelope encryption so Composio can store encrypted credentials without holding the keys
that make them readable. Your KMS root key never leaves your KMS. Keyring generates the data-encryption
keys (DEKs) that do the actual encryption and decryption, and your root key is the only thing that can
unwrap them.
## Key hierarchy
1. **Root key** — lives in your AWS KMS, GCP Cloud KMS, or HashiCorp Vault. It only ever wraps and
unwraps DEKs; it never touches a credential directly.
2. **Data-encryption keys** — generated by Keyring on request, wrapped by your root key, and stored by
Composio as wrapped DEK envelopes. Composio currently requests one DEK per project.
3. **Credentials** — encrypted with AES-256-GCM under their project's DEK. Composio stores only the
resulting credential envelopes, each tagged with the ID of the DEK that protects it.
## How a data key is created
1. Composio asks your Keyring for a new DEK for a scope. Keyring generates a random 256-bit key and a
DEK ID.
2. Keyring asks your KMS to wrap that key with the active root key, packages the wrapped key into a DEK
envelope, and returns the envelope to Composio. The plaintext DEK is discarded immediately.
3. Composio stores the wrapped DEK envelope. It cannot unwrap it: only your KMS root key can.
## How a data key is used
When a credential must be encrypted or decrypted, Composio sends the DEK envelope along with the
request. Keyring asks your KMS to unwrap the DEK, then performs the AES-256-GCM operation inside the
Keyring process and returns only ciphertext or the approved provider response.
Composio stores the encrypted credential envelope next to the wrapped DEK envelope. A copy of the
Composio database therefore contains wrapped keys and ciphertext only — no plaintext DEK and no
readable credential.
## Scoping data keys
DEKs are cheap to create, so Keyring can issue as many as you want to narrow the blast radius of any
single key. Today Composio requests one DEK per project: every credential in a project is encrypted
under that project's DEK, and unwrapping it once lets Keyring serve many credential operations for that
project without another KMS round trip. Finer scopes, such as one DEK per connected account, use the
same mechanism.
## Three separate key purposes
| Key purpose | What it protects |
| ------------------ | --------------------------------------------------------------------------------- |
| Credential root | Provider credentials and sensitive fields returned during token exchange |
| Authorization gate | A second, outer envelope around a credential, tied to a grant or consent decision |
| Secret transfer | Credentials encrypted by the Composio Dashboard before reaching the backend |
Each purpose has its own KMS keys, and Keyring refuses a configuration that reuses a key across
purposes. This prevents material created for one security role from being accepted in another.
## Transfer keys
Transfer keys are asymmetric RSA keys used only when a credential first enters Keyring. Composio and
the Composio Dashboard receive the public key. The private key remains in your KMS and is available only
to the Keyring workload identity.
Keep an older transfer key configured during rotation until in-flight credential setup attempts have
expired. New credentials can start using the new public key immediately.
## In-process key cache
Keyring can cache unwrapped DEKs in process memory as non-extractable key handles, so one KMS unwrap
serves many credential operations for the same scope. The cache holds up to 256 keys for 10 minutes by
default, never writes keys to disk or an external store, and is disabled unless `dek_cache` is set.
Restarting or scaling Keyring only causes another authorized KMS unwrap; it does not affect stored
credentials.
## Rotation and revocation
Rotate a root key with overlapping configuration:
1. Add the new KMS key and grant the Keyring workload identity the minimum required access.
2. Make the new key active so newly generated DEKs are wrapped by it, while keeping the old key
available for unwrapping existing DEKs.
3. Have Composio request a fresh DEK and re-encrypt existing credentials under it through Keyring's
rekey operation. Plaintext exists only inside the Keyring process during the rekey.
4. Confirm that no stored DEK envelope references the old key, then remove its Keyring access.
5. Apply your KMS disablement or deletion policy only after the migration is complete.
For an immediate global kill switch, stop Keyring or revoke its KMS permissions. Without the root key,
no DEK can be unwrapped, so every credential Composio holds becomes unusable until you restore access.
See [Encryption configuration](/configuration/encryption) and
[KMS and Vault adapters](/configuration/kms_adapters) for the exact fields and provider examples.