Credential Encryption and Secret Management#

Dify encrypts all provider and tool credentials at rest using envelope encryption with one RSA key provisioned per tenant at workspace creation. The key provider is pluggable via the KEY_PROVIDER_TYPE configuration:

The architecture is built on three layers:

Configuration#

Set the key provider type via KEY_PROVIDER_TYPE (default: local). Both providers use envelope encryption (a random AES-128 key encrypts the credential; the tenant's RSA key wraps the AES key). The ciphertext format begins with HYBRID: to distinguish it from legacy pure-RSA payloads.

local provider#

A 2048-bit RSA key pair is generated during tenant creation (TenantService.create_tenant). The public key is stored in the Tenant.encrypt_public_key column in the database. The private key is written to privkeys/{tenant_id}/private.pem via the storage abstraction, which supports local filesystem, S3, Azure Blob, GCS, and a dozen other backends depending on STORAGE_TYPE.

• Encrypt: generates a random 16-byte AES key, AES-EAX-encrypts the plaintext, RSA-OAEP-encrypts the AES key with the tenant's public key, concatenates HYBRID: + enc_aes_key | nonce | tag | ciphertext.
• Decrypt: loads the private key PEM from object storage (cached in Redis for 120 seconds), RSA-OAEP-decrypts the AES key, AES-EAX-decrypts the payload. Falls back to legacy pure-RSA decryption for ciphertexts without the HYBRID: prefix.

The implementation is in api/libs/rsa.py, wrapped by RSAKeyProvider.

azure-keyvault provider#

The 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.

• Encrypt: generates a random 16-byte AES key, AES-EAX-encrypts the plaintext, calls Azure Key Vault's wrap_key API (RSA-OAEP-256) to wrap the AES key, concatenates HYBRID: + envelope_version | metadata_len | metadata | wrapped_key_len | wrapped_key | nonce | tag | ciphertext. The metadata JSON records key_version and wrap_alg to support key rotation.
• Decrypt: parses the envelope, extracts key_version, calls Azure Key Vault's unwrap_key API against that specific version, AES-EAX-decrypts the payload.

Authentication uses DefaultAzureCredential (tries managed identity, environment variables, Azure CLI login in sequence).

Configuration:

The implementation is in api/libs/key_providers/azure_keyvault_key_provider.py.

How It Works#

Application code calls encrypt_token or decrypt_token, which delegate to key_provider_manager.provider.encrypt() and .decrypt(). The manager routes to the active provider (RSAKeyProvider or AzureKeyVaultKeyProvider) based on KEY_PROVIDER_TYPE. All ciphertext is base64-encoded before being stored in the database. A batch_decrypt_token helper reuses a single decryption context across multiple tokens to avoid redundant key loads (for the local provider, this means fetching the private key PEM once from Redis/object storage; for azure-keyvault, it means resolving the current key version once and reusing the same CryptographyClient).

Provider Credential Encryption Layer#

ProviderConfigEncrypter is the schema-aware layer that sits above encrypter.py. It takes a list of BasicProviderConfig field descriptors and a ProviderConfigCache, and only processes fields declared as ProviderConfigType.SECRET_INPUT.

Key methods:

• encrypt(data) — deep-copies the credential dict and encrypts each SECRET_INPUT field in-place. Non-secret fields are left as-is.
• decrypt(data) — checks the Redis cache first; on a miss, decrypts all SECRET_INPUT fields and writes the result back to cache.
• mask_credentials(data) — replaces decrypted secret values with partial masks (first 2 + stars + last 2 chars) before the credentials are serialized back to API callers. mask_plugin_credentials delegates to this same method 5.

The factory create_provider_encrypter(tenant_id, config, cache) returns a (ProviderConfigEncrypter, ProviderConfigCache) tuple. Callers pass a live ProviderCredentialsCache for existing rows or a NoOpProviderCredentialCache during initial creation when no row ID yet exists.

Known Credential Leakage Issues#

Several open issues document places where secrets escape the encrypted store:

#39888 — API key echoed into logs and HTTP response 6
ExternalDatasetService.check_endpoint_and_api_key raises a ValueError that string-interpolates the raw api_key on 403 responses. The exception is then logged via current_app.logger.exception() and forwarded to the HTTP response body. Fix: replace the f-string with a static message. PR #39902 was opened to address this.

#37807 — OAuth CLI commands log SECRET_KEY and client secrets to stdout 7
The setup-system-tool-oauth-client, setup-system-trigger-oauth-client, and setup-datasource-oauth-client commands in api/commands/plugin.py call click.echo with the full SECRET_KEY value and raw client_params JSON (a CWE-532 violation). These values appear in shell history and CI logs. Fix: replace with non-sensitive progress messages.

Both bugs share the same root pattern: a code path that decrypts or receives a secret, then passes it to a logging or error-reporting call without masking.

External KMS Support#

The BaseKeyProvider abstraction allows operators to configure external key management without patching code. Implementations exist for:

• local — per-tenant RSA key pair, private key stored in the STORAGE_TYPE backend (see RSAKeyProvider).
• azure-keyvault — per-tenant RSA key kept in Azure Key Vault, private key never leaves the vault (see AzureKeyVaultKeyProvider).

Additional providers (AWS KMS, HashiCorp Vault, Google Cloud KMS) can be added by implementing the four abstract methods in BaseKeyProvider (generate_key_pair, encrypt, get_decrypt_decoding, decrypt_with_decoding) and registering the new provider type in KeyProviderManager.get_provider_factory().

Related community discussions:

• Issue #32328 requests support for external secret managers (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault) for centralized storage and automatic rotation, without Dify maintaining ciphertext in its own database. The key provider abstraction addresses the first part (AWS/Azure/Vault key management for envelope encryption); the second part (moving ciphertext out of Dify's database entirely) remains an open feature request.
• Issue #39278 8 proposes eliminating secrets from the agent's process environment entirely, replacing them with placeholder environment variables resolved only at the network boundary by a Go-based credential-injection proxy (dify-agent-runtime/internal/core/proxy/). The proxy validates allowlisted domains, injects the real secret into request headers, and strips unresolved placeholders — preventing both encoding-bypass and network-exfiltration attacks that pattern-based redaction cannot stop. PR #39483 was submitted with six passing conformance fixtures.