encryption

31 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

Symmetric vs asymmetric encryption for Temporal

Symmetric encryption is generally faster and produces smaller payloads than asymmetric encryption. An advantage of asymmetric encryption is distributing encryption and decryption keys separately, but depending on infrastructure, this may not offer security benefits with Temporal.

AES-256-GCM recommended for Temporal encryption

AES-based algorithms are hardware accelerated in Go and other languages. AES algorithms are widely vetted and trusted with many variants available. The ALG_AES_256_GCM_HKDF_SHA512_COMMIT_KEY algorithm has performed well in load tests for Temporal applications.

Encryption key storage best practices

Store encryption keys in the same manner as passwords and other sensitive configuration data. When possible, load the key into the application to avoid network calls for retrieval. Separate keys for each environment or namespace as much as possible.

Key rotation strategy for encryption

Implement a key rotation strategy in case encryption keys are compromised or need replacement. Consider using a dedicated secrets engine or key management system (KMS). When rotating keys, retain old keys to query old Workflows, as they may be needed to decrypt historical data.

NIST key rotation guidance for AES-GCM

National Institute of Standards and Technology (NIST) publication 800-38D recommends that AES-GCM keys be rotated before approximately 2^32 encryptions have been performed by a key version. Operators should estimate the encryption rate and determine rotation frequency accordingly. For example, at an estimated rate of 40 million operations per day, rotating every three months is sufficient.

Key rotation transparency in Data Converters

Key rotation should be transparent to the Temporal Data Converter implementation. The Encode() and Decode() steps only need to trigger as expected, and Temporal has no knowledge of how or when encryption keys are generated. Design Encode and Decode steps to accept key version and other key management parameters alongside payloads.

Namespace-specific encryption keys

Encryption keys should be mapped to a Namespace in Temporal, similar to how Data Converters are managed.

Payload Codec definition and purpose

A Payload Codec transforms an array of Payloads into another array of Payloads, performing bytes-to-bytes transformations. Unlike Payload Converters, Payload Codecs do not operate within the Workflow sandbox, allowing them to execute operations including calls to remote services and use of non-deterministic modules. Payload Codecs are critical for encrypting Payloads, compressing data, or offloading large payloads to an object store.

Payload Codec Operational Chain serialization

When serializing to Payloads, the Payload Converter is applied first to convert objects to bytes through the toPayload method, followed by codecs that convert bytes to bytes through the encode method. When deserializing from Payloads, codecs are applied first to last through the decode method to reverse the effect, followed by the Payload Converter through the fromPayload method.

End-to-end encryption with custom Payload Codec

Applying encryption logic in a custom Payload Codec ensures that sensitive application data is secure when handled by the Temporal Server. The developer maintains all encryption keys, and the Temporal Server sees only encrypted data. Unencrypted data exists only on the Client and the Worker process executing Workflows and Activities, on hosts that the developer controls.

Payload Codec as Codec Server

Payload Codecs can be implemented as a Codec Server, providing an alternative implementation pattern.

Encryption samples in multiple SDKs

Sample implementations of AES GCM encryption with 256-bit key in custom Data Converters are available in the following languages: Go at https://github.com/temporalio/samples-go/tree/main/encryption, Java at https://github.com/temporalio/samples-java/tree/main/core/src/main/java/io/temporal/samples/encryptedpayloads, Python at https://github.com/temporalio/samples-python/tree/main/encryption, and TypeScript at https://github.com/temporalio/samples-typescript/tree/main/encryption.

Remote data encoding definition

Remote data encoding is exposing your Payload Codec via HTTP endpoints to support remote encoding and decoding of data.

CLI and Web UI support for remote data encoding

The Temporal CLI and Web UI provide built-in hooks to call the Codec Server to decode encrypted payloads on demand. Users can specify Codec Server endpoints with the codec-endpoint parameter in the Temporal CLI and configure the Web UI to use the Codec Server endpoints.

Encoding sensitive data via CLI and Web UI

When starting or signaling a Workflow Execution from the CLI or canceling a Workflow Execution from the Web UI, users can encode sensitive data inputs by specifying Codec Server endpoints with the codec-endpoint parameter in the CLI and configuring the Web UI to use the Codec Server endpoints.

Data storage and visibility database

When using custom encoding, Payload data handled by the Temporal Service is stored in encoded format. The Web UI uses the Visibility database to show events, so all data in the Workflow Execution History displayed in the Web UI is shown in encoded format.

Security considerations for remote data encoders

A remote data encoder is a separate system with access to encryption keys and exposes APIs to encode and decode any data. Users must evaluate and ensure that remote data encoder endpoints are secured and only authorized users have access to them.

Temporal Cloud Nexus Endpoint access control policy

In Temporal Cloud, each Nexus Endpoint has an access control policy that is an allowlist of caller Namespaces. When a caller Workflow executes a Nexus Operation, Temporal Cloud verifies the caller's Namespace is in the Endpoint's allowlist before routing the request to the handler.

Temporal Cloud acts as trusted broker across Namespace boundaries

Temporal Cloud acts as a trusted broker across Namespace boundaries for Nexus operations. Workers authenticate with their Namespace using mTLS or API key.

Nexus secure connectivity in Temporal Cloud

Temporal Cloud secures all Nexus communication through multiple mechanisms: workers authenticate to their Namespace using mTLS or API key; mTLS encrypts all cross-Namespace Nexus traffic (start, cancel, and completion callbacks) across cells and regions; Endpoints are only accessible from within a Temporal Cloud Account through the Temporal SDK and are not externally accessible.

Self-hosted Nexus security relies on Temporal Cluster security

Self-hosted deployments do not have built-in secure connectivity for Nexus and rely on the Temporal Cluster itself being secure. They can implement custom Authorizers for access control.

Nexus uses same Data Converter as Workflows and Activities

Nexus uses the same Data Converter as Workflows and Activities, supporting JSON, Proto, and binary payloads. If a Codec is used for encryption, it also encrypts Nexus payloads. Caller and handler Workers must have compatible Data Converters.

Nexus payload encryption direction

In Nexus operations, payloads are encrypted by the sender: the caller encrypts the input payload, and the handler encrypts the result payload.

Nexus encryption option 1: shared encryption key

Option 1 for cross-Namespace Nexus payload encryption is to have both Namespaces share the same encryption key. This is the simplest approach and requires no additional configuration.

Nexus encryption option 2: pass KMS key ID in payload metadata

Option 2 for cross-Namespace Nexus payload encryption is for each Namespace to use its own encryption key, with the KMS key ID passed in Temporal payload metadata. The receiver reads the key ID from metadata and decrypts using KMS IAM permissions. Works bi-directionally: caller encrypts input with the caller's key, handler decrypts using the key ID from metadata, then encrypts the result with the handler's key. The Codec Server needs KMS decrypt permissions for all relevant keys.

Nexus encryption option 3: wrapper types for endpoint-specific keys

Option 3 for cross-Namespace Nexus payload encryption uses wrapper types (for example, EndpointValue) so the Data Converter selects an Endpoint-specific encryption key. This encrypts only Nexus traffic with a dedicated key, without sharing Namespace keys across teams. This approach only works when the operation is passed as a string name; when calling ExecuteOperation with a non-string operation (for example, an operation definition or reference), the wrapper changes the input type and ExecuteOperation fails type-checking.

Nexus encryption approach selection guidance

Options 1 and 2 for Nexus encryption, where both sides share the same key or flow the KMS key ID in payload metadata, work with the standard Data Converter. Option 3 is more advanced and is intended for teams that do not want to share their Namespace encryption keys with other teams.

mTLS encrypts network traffic between services and clients

Temporal supports Mutual Transport Layer Security (mTLS) to encrypt network traffic between services within a Temporal Service, or between application processes and a Temporal Service. On the self-hosted Temporal Service, mTLS is configured in the tls section of the Temporal Service configuration as a static configuration property.

mTLS has separate internode and frontend sections

The mTLS configuration includes two sections: internode for encrypting communication between nodes within the Temporal Service, and frontend for encrypting the public endpoints of the Frontend Service. Setting mTLS for internode and frontend separately allows using different certificates and settings to encrypt each section of traffic.

clientCAFiles and clientCAData restrict client access

On the self-hosted Temporal Service, you can restrict access to Temporal Service endpoints by using the clientCAFiles or clientCAData property and the requireClientAuth property in your Temporal Service configuration. These properties can be specified in both the internode and frontend sections of the mTLS configuration.

serverName prevents spoofing and MITM attacks

On the self-hosted Temporal Service, you can specify serverName in the client section of your mTLS configuration to prevent spoofing and MITM attacks. Entering a value for serverName enables established connections to authenticate the endpoint, ensuring that the server certificate presented to any connected client has the specified server name in its CN property.

Give your agent this brain