Skip to main content
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

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 and KMS and Vault adapters for the exact fields and provider examples.