Payload Encryption

AgentVisor™ can encrypt Temporal workflow payloads using AES-256-GCM, protecting agent state data at rest in the Temporal server.

Configuration Guide

For step-by-step configuration instructions, see the Temporal Guide > Payload Encryption.

Overview

When payload encryption is enabled, all data stored in Temporal workflow history — including checkpoints, agent state, and run inputs/outputs — is encrypted before leaving the host runtime. The Temporal server stores only ciphertext and cannot read workflow data.

This provides:

• Data at rest protection: Temporal server stores only ciphertext
• Compliance requirements: Meet security requirements for sensitive data
• Multi-tenant isolation: Each deployment can use different encryption keys

How It Works

AgentVisor implements a Temporal payload codec that intercepts data before it's written to workflow history:

Agent state → Serialize → Encrypt (AES-256-GCM) → Temporal server (ciphertext)
Temporal server (ciphertext) → Decrypt → Deserialize → Agent state

The encryption/decryption happens entirely within the AgentVisor host runtime. The Temporal server never sees plaintext workflow data.

Algorithm: AES-256-GCM

AgentVisor uses AES-256-GCM (Galois/Counter Mode), an authenticated encryption algorithm that provides both confidentiality and integrity.

Why AES-256-GCM?

Property	Benefit
Authenticated encryption	Detects tampering—ciphertext modification causes decryption failure
Hardware acceleration	Modern CPUs have AES-NI instructions for fast encryption
Industry standard	NIST-approved, widely vetted, well-understood security properties
Streaming capable	Can encrypt/decrypt data incrementally

Encryption Details

Property	Value
Algorithm	AES-256-GCM (Galois/Counter Mode)
Key size	256 bits (32 bytes)
Nonce size	96 bits (12 bytes), cryptographically random
Authentication tag	128 bits (16 bytes)

Each payload is encrypted with a unique random nonce. This is critical — reusing a nonce with the same key completely breaks GCM security. AgentVisor generates nonces from a cryptographically secure random source.

Ciphertext Format

The encrypted output format is:

nonce (12 bytes) || ciphertext || auth_tag (16 bytes)

Encrypted payloads are marked with metadata encoding: binary/encrypted (or binary/encrypted-v2, see below) so the codec can identify them during decryption.

Workflow Binding (Additional Authenticated Data)

Beyond confidentiality and tamper detection, ciphertexts are bound to the namespace and workflow ID they were encrypted under, using GCM's additional authenticated data (AAD). Temporal's SDK supplies this context automatically at every workflow and activity serialization boundary. Without this binding, a party able to write to Temporal's persistence layer could copy an encrypted payload from one workflow's history into another's, and it would decrypt successfully — GCM alone proves the bytes are unmodified, not that they belong where they were found.

Payloads bound this way are marked encoding: binary/encrypted-v2. Payloads encrypted before this binding existed remain marked binary/encrypted and continue to decrypt without a context check.

Key Derivation: PBKDF2

Rather than using the password directly as the encryption key, AgentVisor derives the key using PBKDF2 (Password-Based Key Derivation Function 2).

Why Key Derivation?

Using a password directly as a key is insecure:

• Passwords have low entropy compared to random keys
• Similar passwords would produce similar keys
• Dictionary attacks become feasible

PBKDF2 addresses these issues by:

• Stretching the password through many iterations
• Using a salt to prevent rainbow table attacks
• Producing a cryptographically strong key regardless of password quality

PBKDF2 Parameters

Parameter	Value	Purpose
Hash function	HMAC-SHA256	PRF for key derivation
Iterations	600,000 (default, minimum 100,000)	Slows brute-force attacks
Salt	Required, unique per deployment	Prevents rainbow tables
Output length	256 bits	Matches AES-256 key size

The 600,000 iteration count follows OWASP recommendations for PBKDF2-HMAC-SHA256 as of 2023.

Security Properties

Key derivation protects against:

• Rainbow table attacks (salt makes precomputation impractical)
• Brute-force attacks (iterations slow down guessing)
• Password similarity issues (different passwords produce unrelated keys)

Best practices:

• Use a strong, unique password (32+ characters recommended)
• Salt is required and must be unique per deployment; startup fails without one
• Never reduce iteration count below 600,000 (values below 100,000 are rejected at startup)
• Store passwords in a secrets manager, not in config files

Codec Server

AgentVisor includes an HTTP codec server that enables the Temporal Web UI to decrypt and display workflow payloads. Without this server, the Web UI shows only encrypted binary data.

How It Works

The codec server exposes /encode and /decode endpoints that the Temporal Web UI calls:

Browser → Temporal Web UI → Codec Server → Decrypt → Browser

The codec server uses the same encryption password as the host runtime.

Cannot decrypt workflow-bound payloads

The codec server calls the codec directly over HTTP, outside the Temporal SDK's serialization pipeline, so it never has a workflow's namespace or ID available to it — Temporal's Web UI and CLI do not send workflow ID to codec server endpoints. As a result it can only decrypt payloads encoded without workflow binding: the legacy binary/encrypted format. It cannot decrypt binary/encrypted-v2 payloads (see Workflow Binding), which is what the host runtime now produces for all new workflow activity. This is an intentional trade-off — the alternative is that any payload can be relocated to a different workflow and still decrypt.

Security Considerations

• The codec server should only be accessible to authorized users
• CORS configuration restricts which origins can access the server
• In production, consider network-level access controls

For setup instructions, see the Temporal Guide.

Key Management

Key Loss = Data Loss

If the encryption password is lost, encrypted workflow data cannot be recovered. There is no backdoor or recovery mechanism.

Recommendations

1. Use a secrets manager: Store passwords in HashiCorp Vault, AWS Secrets Manager, or similar
2. Document key ownership: Ensure multiple team members have access to recovery procedures
3. Test recovery procedures: Verify you can restore access from your backup
4. Never change passwords without migration: Old workflows remain encrypted with the old key

Password Rotation

Changing encryption passwords requires careful migration:

1. Old workflows remain encrypted with the old password
2. New workflows use the new password
3. You must maintain both passwords during the transition
4. Consider running multiple codec servers for the transition period

See Also

• Temporal Guide > Payload Encryption — Configuration instructions
• Temporal Guide > Codec Server — Web UI integration
• Temporal Data Conversion — Temporal's payload codec documentation
• OWASP Password Storage — Key derivation best practices