Credential Encryption and Secret Management#

Overview#

Dify encrypts all provider and tool credentials at rest using envelope encryption scoped per tenant. A random AES-128-EAX key encrypts the credential; the tenant's RSA key wraps the AES key. Ciphertext starts with the HYBRID: prefix to distinguish it from legacy pure-RSA payloads. The key provider is pluggable via KEY_PROVIDER_TYPE.

Architecture#

Four layers compose the encryption stack:

Application code should only call encrypt_token / decrypt_token in encrypter.py, never api/libs/rsa.py directly — an .importlinter rule enforces this contract 1.

Key Providers#

local (default)#

A 2048-bit RSA key pair is generated per tenant at workspace creation. The public key is stored in Tenant.encrypt_public_key. The private key is written to privkeys/{tenant_id}/private.pem via the STORAGE_TYPE backend (local FS, S3, GCS, Azure Blob, etc.) and cached in Redis for 120 seconds 2.

Encrypt path 3: generates 16-byte AES key → AES-EAX-encrypts plaintext → RSA-OAEP-wraps AES key → concatenates HYBRID: + enc_aes_key | nonce | tag | ciphertext.

Decrypt path 4: strips prefix → RSA-OAEP-unwraps AES key → AES-EAX-decrypts. Falls back to pure-RSA for ciphertexts without HYBRID:.

Implementation: api/libs/rsa.py, wrapped by RSAKeyProvider.

azure-keyvault#

RSA key pair (default 2048-bit) is created in Azure Key Vault, named dify-tenant-{tenant_id}. The key name is stored in Tenant.encrypt_public_key; the private key never leaves the vault. Uses Azure Key Vault's wrap_key / unwrap_key APIs (RSA-OAEP-256). The ciphertext envelope includes metadata JSON with key_version and wrap_alg to support key rotation. Authentication uses DefaultAzureCredential.

Implementation: api/libs/key_providers/azure_keyvault_key_provider.py.

Schema-Aware Encryption (ProviderConfigEncrypter)#

ProviderConfigEncrypter selectively encrypts/decrypts only fields declared as SECRET_INPUT in the provider's credential schema 5.

• encrypt(data) — deep-copies the credential dict; encrypts each SECRET_INPUT field in-place 5.
• decrypt(data) — checks the Redis cache first; on miss, decrypts all SECRET_INPUT fields and writes back to cache 6.
• mask_credentials(data) — replaces decrypted secrets with partial masks (first2 + *** + last2) before returning to API callers 7.

The factory create_provider_encrypter(tenant_id, config, cache) returns a (ProviderConfigEncrypter, ProviderConfigCache) tuple. Use NoOpProviderCredentialCache during initial creation before a row ID exists.

Batch decryption uses batch_decrypt_token to load the private key once and reuse it across multiple tokens 8.

Workflow-Level Credential Handling#

• Per-node credential override (PR #28850, PR #37078): LLM nodes in workflows can carry their own API key instead of inheriting the global tenant credential.
• Secret-type environment variables (PR #37048): Workflow execution redacts secrets from node outputs, logs, and traces via substring matching (minimum 8 characters). DSL export containing secrets is restricted to workspace owners/admins only. Secret variables are also filtered from Answer/End node UIs in the builder.

Known Credential Leakage Issues#

External KMS / Secret Manager Support#

The BaseKeyProvider abstraction 9 is the extension point. Implementations currently ship for local and azure-keyvault. To add a new provider (AWS KMS, HashiCorp Vault, Google Cloud KMS), implement the four abstract methods and register the type in KeyProviderManager.get_provider_factory() 10.

Community requests for moving ciphertext out of Dify's database entirely (AWS Secrets Manager, HashiCorp Vault as a secret store — not just a key store) remain open (Issue #32328). A more radical proposal (Issue #39278) eliminates secrets from the agent's process environment entirely using a Go-based outbound proxy that resolves placeholder env vars at the network boundary, domain-pins injection, and strips unresolved placeholders.