Documentation
¶
Overview ¶
Package stdtemporalcodec implements a Temporal converter.PayloadCodec that encrypts payloads using AWS KMS envelope encryption, together with an HTTP handler that exposes the codec over Temporal's remote codec contract.
Tenant isolation is achieved by passing an EncryptionContext of {"namespace": <ns>} to KMS on both GenerateDataKey and Decrypt. KMS will refuse to decrypt if the namespace in the context does not match the one used at encryption time.
Wire format of the encrypted payload data:
| uint32 wrappedLen (big-endian) | wrapped DEK | 12-byte nonce | AES-GCM ciphertext |
The plaintext that is encrypted is the protobuf-marshaled commonpb.Payload (including its original metadata + data). Payloads that are not encoded with MetadataEncodingEncrypted pass through Decode unchanged.
Index ¶
Constants ¶
const ( // MetadataEncodingEncrypted is the value of the standard "encoding" // metadata key for payloads produced by this codec. MetadataEncodingEncrypted = "binary/encrypted" // MetadataKeyID is the metadata key holding the KMS key ARN/alias used to // produce the wrapped data encryption key. MetadataKeyID = "encryption-key-id" // MetadataCipher is the metadata key holding the cipher identifier used // to encrypt the payload. MetadataCipher = "encryption-cipher" // MetadataContextNamespace is the metadata key holding the value of the // KMS EncryptionContext "namespace" entry. It is captured for // observability; KMS itself enforces the binding at decrypt time. MetadataContextNamespace = "encryption-context-namespace" // CipherAES256GCM identifies AES-256-GCM with a 12-byte nonce. CipherAES256GCM = "AES_256_GCM" )
Metadata keys and well-known values used on commonpb.Payload to identify payloads that were encrypted by this codec.
const ( PathEncode = "/encode" PathDecode = "/decode" )
Default route paths.
const HeaderNamespace = "X-Namespace"
HeaderNamespace is the HTTP request header that carries the Temporal namespace for the codec call.
Variables ¶
This section is empty.
Functions ¶
func Handler ¶
func Handler(opts HandlerOptions) (http.Handler, error)
Handler returns an http.Handler that serves POST /encode and POST /decode. The returned handler routes by request path suffix so it can be mounted at any prefix.
func StripCloudAccountSuffix ¶
StripCloudAccountSuffix is a NormalizeNamespace helper that trims everything after (and including) the last dot in the given namespace. Temporal Cloud's Web UI sends X-Namespace as `<name>.<accountID>`; the codec is configured with bare namespace names, so callers integrating with Cloud should set HandlerOptions.NormalizeNamespace = StripCloudAccountSuffix.
If the input contains no dot it is returned unchanged.
Types ¶
type Codec ¶
type Codec struct {
// contains filtered or unexported fields
}
Codec implements converter.PayloadCodec using KMS-backed envelope encryption scoped to a single Temporal namespace.
func (*Codec) Decode ¶
Decode decrypts each payload that bears MetadataEncodingEncrypted; any other payload is passed through unchanged.
func (*Codec) Encode ¶
Encode encrypts each payload using a freshly-generated KMS data key and returns new payloads with metadata describing the encryption parameters.
func (*Codec) WithNamespace ¶
WithNamespace returns a copy of the codec scoped to a different namespace. This is useful on the server side where the namespace is determined per request.
type HandlerOptions ¶
type HandlerOptions struct {
// Codec performs the actual encryption/decryption work. It will be
// scoped to the per-request namespace via Codec.WithNamespace before
// each call. Required.
Codec *Codec
// AllowedNamespaces is the set of Temporal namespaces the server will
// service. A request bearing any other namespace is rejected with
// 403 Forbidden. If empty, all namespaces are rejected. Compared
// against the value returned by NormalizeNamespace (if set).
AllowedNamespaces []string
// NormalizeNamespace, if set, is applied to the X-Namespace header
// value before allowlist comparison and before passing to the codec
// (which forwards it as the KMS EncryptionContext namespace value).
// Defaults to identity. Use StripCloudAccountSuffix when serving the
// Temporal Cloud Web UI.
NormalizeNamespace func(string) string
// Logger receives structured warnings (auth denials) and errors
// (codec failures). Defaults to zap.NewNop().
Logger *zap.Logger
}
HandlerOptions configures the codec server handler.
type KMS ¶
type KMS interface {
GenerateDataKey(
ctx context.Context,
in *kms.GenerateDataKeyInput,
optFns ...func(*kms.Options),
) (*kms.GenerateDataKeyOutput, error)
Decrypt(
ctx context.Context,
in *kms.DecryptInput,
optFns ...func(*kms.Options),
) (*kms.DecryptOutput, error)
}
KMS abstracts the subset of the AWS KMS API used by Codec so it can be mocked or faked in tests.
type Options ¶
type Options struct {
// KeyID is the KMS key ARN or alias used to generate data encryption
// keys. Required.
KeyID string
// Namespace is the Temporal namespace that scopes the codec instance.
// It is included in the KMS EncryptionContext on every operation.
// Required.
Namespace string
}
Options configures a Codec.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package stdtemporalcodectest provides test doubles for the stdtemporalcodec package.
|
Package stdtemporalcodectest provides test doubles for the stdtemporalcodec package. |