Encrypted Storage#

RAGFlow provides optional encryption-at-rest for all object storage backends via EncryptedStorageWrapper 1, a transparent proxy that encrypts on put and decrypts on get without changing any calling code.

Architecture#

Caller → EncryptedStorageWrapper → (MinIO / S3 / Azure / OSS / GCS / OpenDAL)
                    ↓
               CryptoUtil
         (AES-256-CBC default)

EncryptedStorageWrapper 1 wraps any storage backend and validates that it exposes five required methods: put, get, rm, obj_exist, and health. Optional methods (get_presigned_url, copy, move, scan, bucket_exists, remove_bucket) are forwarded only when present 2. The rm, obj_exist, and health calls pass through directly without encryption/decryption 3.

Magic Header & Backward Compatibility#

Every encrypted blob is prepended with the 4-byte magic header b"RAGF" 4. On get, the decrypt() method checks for this header before attempting decryption:

• Header present → strip header, extract the embedded IV (next 16 bytes), decrypt ciphertext, remove PKCS7 padding.
• Header absent → data is plaintext; return it as-is.

This makes the wrapper safe to deploy over existing buckets containing unencrypted objects — legacy files are read correctly without migration.

Wire Format#

Encrypted blobs have the layout:

| 4 bytes: "RAGF" | 16 bytes: random IV | N bytes: AES-CBC ciphertext (PKCS7-padded) |

Each put generates a fresh random IV via os.urandom(16) 5. The key is derived from the raw RAGFLOW_CRYPTO_KEY string using PBKDF2-HMAC-SHA256 with a fixed salt (ragflow_crypto_salt, 100,000 iterations) so the derived key is always the same for a given passphrase 6.

Supported Algorithms#

Configured via RAGFLOW_CRYPTO_ALGORITHM 7:

All three are implemented in common/crypto_utils.py using the cryptography library.

Initialization & Fallback#

Encryption is wired in init_settings():

1. The underlying storage backend is always instantiated first via StorageFactory.create().
2. If RAGFLOW_CRYPTO_ENABLED=true, create_encrypted_storage() wraps it with EncryptedStorageWrapper.
3. On any exception (missing key, unsupported algorithm, import error), the error is logged and STORAGE_IMPL falls back to the unwrapped plaintext backend 8.

⚠️ Initialization failure is silent at runtime — storage continues to work but writes are unencrypted. Monitor startup logs for "Failed to initialize encrypted storage".

Configuration#

CryptoUtil raises ValueError if RAGFLOW_CRYPTO_KEY is absent or if an unsupported algorithm name is provided 9, which triggers the fallback in init_settings.

Key Source Files#

History#

• PR #11838 (merged Dec 2025) — initial implementation: added crypto_utils.py, encrypted_storage.py, wired into settings.py, added cryptography dependency 10.
• PR #13458 (Mar 2026) — proposed StorageBase Protocol to formalize the required backend interface, replacing ad-hoc hasattr() checks 11.