Skip to main content
Soma uses envelope encryption to secure your secrets, MCP provider credentials and sensitive auth middleware configuration.
Envelope encryption is a strategy where data is encrypted with a Data Encryption Key (DEK), and the DEK itself is encrypted with a Key Encryption Key (KEK). This approach allows for efficient key rotation and limits the exposure of cryptographic material. Some key details:
  • The DEK remains encrypted at all times and is never stored in plaintext. It is stored in a secure cache in memory, in the database and in the soma.yaml file.
  • The KEK is used to encrypt the DEK. This can be configured to use AWS KMS or a local file.
  • Key rotation & migration involves decrypting the DEK with the old KEK, then, encrypting the DEK with the new KEK and storing the new DEK in the database.
  • Secrets are encrypted with the DEK before being stored in the database. They reference a DEK alias and soma decrypts secrets on the fly when needed by looking up the DEK via it’s alias.
  • Soma uses AES-256-GCM (Galois/Counter Mode) for all encryption operations
Soma currently supports multiple encryption key types for the KEK.

​
AWS KMS

Soma supports using AWS KMS as the KEK. This is the recommended approach for production environments. This also allows you to safely commit your soma.yaml file without exposing any ecnryption keys. Instead, as long as other engineers / environments have access to the same AWS KMS key, they can decrypt the secrets without needing to know the encryption key. To configure AWS KMS as the KEK, you can use the soma enc-key add aws command.

​
Local file

Soma supports using a local file as the KEK. This is the recommended approach for quick start development environments and for exploring Soma. To configure a local file as the KEK, you can use the soma enc-key add local command.

​
Secrets manager integrations

​
AWS Secrets Manager

Nothing to see here, move along 👀 Coming soon.

​
Vault

Nothing to see here, move along 👀 Coming soon.