Principle:Langchain ai Langgraph Data Encryption
| Attribute | Value |
|---|---|
| Knowledge Sources | LangGraph |
| Domains | Encryption, Security |
| Last Updated | 2026-02-11 15:00 GMT |
Overview
Data encryption at rest is the principle by which LangGraph Server protects persisted data -- including checkpoint blobs, thread metadata, and store values -- through a decorator-based framework that delegates to external key management services.
Description
LangGraph provides a server-side encryption framework that allows developers to encrypt data before it is written to storage and decrypt it when read back. The framework distinguishes between two categories of data:
- Blob encryption handles opaque binary data such as serialized checkpoint state. Handlers are registered via
@encryption.encrypt.bloband@encryption.decrypt.blob. Each receives anEncryptionContextand raw bytes, and returns transformed bytes. This is the primary mechanism for protecting checkpoint payloads that contain the full graph state.
- JSON encryption handles structured dictionaries such as thread metadata, assistant context, run kwargs, and store values. Handlers are registered via
@encryption.encrypt.jsonand@encryption.decrypt.json. Each receives anEncryptionContextand a dict, and returns a transformed dict. A critical constraint is that JSON encryptors must preserve dictionary keys -- only values may be transformed -- because the server uses SQL JSONB merge operations at the key level. This also means encrypted values cannot be reliably searched, since real-world encryption is non-deterministic due to nonce usage.
Each handler receives an EncryptionContext containing:
model-- the entity type being encrypted (e.g.,"thread","checkpoint","assistant")field-- the specific field (e.g.,"metadata","values","context")metadata-- non-secret key-value pairs for key resolution decisions
An optional @encryption.context handler derives encryption context from the authenticated user, enabling tenant-specific encryption keys resolved from JWT claims without requiring a separate header. This handler runs once per request before any encrypt/decrypt operations.
All handlers must be async functions, reflecting the expectation that they will interact with external key management services (KMS). The type system defines callback aliases (BlobEncryptor, BlobDecryptor, JsonEncryptor, JsonDecryptor, ContextHandler) for all handler signatures. The Encryption class enforces a one-handler-per-slot constraint and validates handlers at registration time.
Usage
Use data encryption when deploying LangGraph Server with requirements for at-rest data protection, regulatory compliance (HIPAA, GDPR, SOC 2), or multi-tenant key isolation. Create an encryption.py file, instantiate Encryption(), register your encrypt/decrypt handlers, and add "encryption": {"path": "./encryption.py:my_encryption"} to langgraph.json. The API is currently in beta, and a LangGraphBetaWarning is emitted on first instantiation.
Theoretical Basis
The encryption framework applies the decorator pattern at the data persistence layer, wrapping all storage operations with transparent encrypt/decrypt steps. This ensures that encryption is applied uniformly without modifying the storage backends themselves, following the separation of concerns principle.
The separation of blob and JSON encryption reflects a fundamental distinction in data handling: blob data is opaque and can be encrypted as a single unit, while structured JSON data requires selective field-level encryption where some fields (such as ownership metadata used for filtering) must remain in plaintext for query operations.
The context handler mechanism implements tenant-aware key derivation, allowing each tenant's data to be encrypted with a different key without requiring separate storage infrastructure. This follows the envelope encryption pattern commonly used with cloud KMS services, where a data encryption key is itself encrypted by a master key associated with the tenant.
The async-only handler requirement reflects the I/O-bound nature of KMS operations: encrypting data typically involves a network call to an external service, and blocking on this call would degrade server throughput. The async constraint ensures that the encryption layer integrates naturally with the server's event loop.