Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/temporal-sa/temporal-cloud-proxy/llms.txt

Use this file to discover all available pages before exploring further.

When encryption is configured on a workload, the proxy intercepts payload encoding and decoding using a gRPC client interceptor (converter.NewPayloadCodecGRPCClientInterceptor). Outgoing payloads are encrypted with AES-GCM before being written to Temporal Cloud; incoming encrypted payloads are decrypted before being returned to the worker. Workers send and receive plaintext — the encryption is entirely transparent to them and requires no changes to worker code.

​
How it works

The proxy uses envelope encryption: a fresh data key is generated by (or via) KMS for each encrypt operation, used to perform AES-GCM encryption of the payload bytes, and then stored in its encrypted form alongside the ciphertext. Three metadata fields are written into every encrypted payload:
Metadata keyValue
encodingbinary/encrypted
encryption-key-idThe KMS key ID used to generate the data key
encrypted-data-keyThe KMS-encrypted data key bytes
On decryption, the proxy reads encrypted-data-key from the payload metadata, calls KMS to decrypt it back to the plaintext key, and then uses that key to decrypt the payload body with AES-GCM. To avoid a KMS API call on every payload, data keys are cached in an LRU. Encryption (GetMaterial) and decryption (DecryptMaterial) operations maintain separate cache entries, each subject to the same max_age and max_usage eviction policies.

​
AWS KMS

encryption:
  type: "aws-kms"
  config:
    key-id: "arn:aws:kms:us-east-1:123456789012:key/your-key-id"
​
encryption.config.key-id
string
required
The ARN or alias of the AWS KMS symmetric key used for envelope encryption. The proxy calls GenerateDataKey (key spec AES_256) to obtain data keys for encryption, and Decrypt to unwrap data keys for decryption.

​
Required IAM permissions

The AWS identity running the proxy (IAM user, role, or instance profile) needs the following permissions on the configured key:
  • kms:GenerateDataKey — to create new data keys during encryption
  • kms:Decrypt — to unwrap encrypted data keys during decryption

​
Create the key

aws kms create-key --description "Temporal Cloud Proxy encryption key"
aws kms create-alias \
  --alias-name alias/temporal-proxy \
  --target-key-id <key-id>

​
AWS credentials

The proxy uses the standard AWS SDK credential chain. Configure credentials via environment variables before starting the proxy: 
export AWS_ACCESS_KEY_ID=your_access_key
export AWS_SECRET_ACCESS_KEY=your_secret_key
export AWS_REGION=us-east-1
Alternatively, when running on EC2, ECS, or EKS, attach an instance profile or task/pod IAM role with the required permissions — no environment variables needed. The default region is us-west-2. Override it with the AWS_REGION environment variable.

​
GCP KMS

encryption:
  type: "gcp-kms"
  config:
    key-name: "projects/my-project/locations/global/keyRings/temporal-proxy/cryptoKeys/payload-key"
​
encryption.config.key-name
string
required
The fully qualified GCP KMS key resource name. Must follow the format:
projects/{project}/locations/{location}/keyRings/{keyRing}/cryptoKeys/{key}
The location component is parsed from this path to construct the GenerateRandomBytes request location.

​
How GCP envelope encryption differs from AWS

The GCP KMS provider does not use a GenerateDataKey API equivalent. Instead it:
  1. Calls GenerateRandomBytes with LengthBytes: 32 and ProtectionLevel: HSM to obtain 256 bits of HSM-protected random data.
  2. Calls Encrypt on the KMS key to wrap those random bytes, producing the encrypted data key stored in payload metadata.
Decryption calls Decrypt on the KMS key to recover the original random bytes, which are then used for AES-GCM decryption of the payload.

​
GCP credentials

The proxy uses Application Default Credentials (ADC) to authenticate with GCP KMS. The most common approaches are:
  • Set GOOGLE_APPLICATION_CREDENTIALS to the path of a service account key file.
  • Attach a Workload Identity or service account to the GKE pod / GCE instance — no environment variables needed.
The region is derived from the key-name path, but you can override the GCP region used for the GenerateRandomBytes call with the GCP_REGION environment variable: 
export GCP_REGION=us-central1
The default region is us-central1. Override it with the GCP_REGION environment variable.

​
Required IAM role

Grant the service account running the proxy the following role on the key resource:
  • roles/cloudkms.cryptoKeyEncrypterDecrypter

​
Create the key ring and key

gcloud kms keyrings create temporal-proxy --location=global

gcloud kms keys create payload-key \
  --location=global \
  --keyring=temporal-proxy \
  --purpose=encryption

​
Key caching

The proxy caches data keys in an LRU to minimise the number of KMS API calls. The cache settings are defined globally under the top-level encryption.caching block and apply to all workloads. 
encryption:
  caching:
    max_cache: 100   # max LRU entries
    max_age: "10m"   # max key lifetime
    max_usage: 100   # max uses before refresh
​
encryption.caching.max_cache
integer
default:"100"
Maximum number of key entries held in the LRU cache at once. When the limit is reached, the least-recently-used entry is evicted to make room for a new key. Must be >= 0.
​
encryption.caching.max_age
string
default:"10m"
Maximum lifetime of a cached key expressed as a Go duration string (e.g. "5m", "1h30m", "30s"). A key that has been in the cache longer than this value is evicted on the next access and a fresh key is fetched from KMS.
​
encryption.caching.max_usage
integer
default:"100"
Maximum number of times a single cached key entry may be used before it is evicted and a fresh key is requested from KMS. Encryption (GetMaterial) and decryption (DecryptMaterial) operations each track usage in separate cache entries, so this limit applies independently to each direction.
Tune max_age and max_usage based on your compliance requirements and traffic volume. Lower values increase key rotation frequency — improving the security posture of your key material — at the cost of more KMS API calls and the associated latency and cost. Higher values reduce KMS traffic but mean individual keys are used for longer.
If the encryption block is omitted from a workload, payloads for that workload are forwarded to Temporal Cloud without any encryption applied. The proxy logs a warning at startup for each such workload:
WARN  workload configured without payload encryption  {"workload-id": "<id>"}
Review this warning before deploying to production to confirm that unencrypted payload forwarding is intentional for that workload.

Build docs developers (and LLMs) love

Get started for freeTalk to us