Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -2,52 +2,58 @@

This sample uses `NexusSerializationContext` to select an encryption key for each Nexus
endpoint. The caller invokes synchronous and workflow-backed asynchronous operations
through four endpoints. `CompressedEncryptedHandlerWorker` compresses and then
encrypts Nexus payloads. `EncryptedHandlerWorker` encrypts without
compression. Each handler selects between its own key 1 and key 2 using
the endpoint in the Nexus context.
through four endpoints. `CompressedEncryptedHandlerWorker` compresses and then encrypts
Nexus payloads. `EncryptedHandlerWorker` encrypts without compression. Each handler selects
between its own key 1 and key 2 using the endpoint in the Nexus context.
The caller and each handler run in separate namespaces.

| Handler | Endpoint | Encryption key | Nexus payload encoding |
| Handler worker | Endpoint | Key ID | Nexus payload encoding |
|---|---|---|---|
| `CompressedEncryptedHandlerWorker` | `nexus-serialization-compressed-encrypted-1` | `COMPRESSED_ENCRYPTED_KEY_1` | zlib, then AES-GCM |
| `CompressedEncryptedHandlerWorker` | `nexus-serialization-compressed-encrypted-2` | `COMPRESSED_ENCRYPTED_KEY_2` | zlib, then AES-GCM |
| `EncryptedHandlerWorker` | `nexus-serialization-encrypted-1` | `ENCRYPTED_KEY_1` | AES-GCM |
| `EncryptedHandlerWorker` | `nexus-serialization-encrypted-2` | `ENCRYPTED_KEY_2` | AES-GCM |

These four endpoint keys are distinct 128-bit AES keys. Compression runs before encryption;
decoding decrypts before decompressing. AES-GCM authenticates the ciphertext.
The AES-GCM and zlib codecs are implemented in this sample; Nexus supplies the endpoint
context used to select them.

Each worker configures `NexusCodec` with an endpoint-to-codec map and a default codec
for ordinary workflow payloads. The caller uses a separate `CALLER_WORKFLOW_KEY` for
its own input and final result, keeping those payloads independent of the keys shared
with Nexus handlers. Each handler reuses its key 1 for backing workflow inputs.

| Ordinary workflow payload | Encryption key |
| Compressed/encrypted | `nexus-serialization-compressed-encrypted-1` | `compressed-encrypted-1` | zlib, then AES-GCM |
| Compressed/encrypted | `nexus-serialization-compressed-encrypted-2` | `compressed-encrypted-2` | zlib, then AES-GCM |
| Encrypted | `nexus-serialization-encrypted-1` | `encrypted-1` | AES-GCM |
| Encrypted | `nexus-serialization-encrypted-2` | `encrypted-2` | AES-GCM |

Each endpoint uses a different 128-bit AES key. This sample implements the AES-GCM
and zlib codecs.

`NexusCodec` uses the endpoint from the Nexus context to select a codec. It uses a default
codec for ordinary workflow payloads. Add `NexusCodec` to the default data converter with
`CodecDataConverter`, then pass the result to
`WorkflowClientOptions.Builder.setDataConverter` for the caller and handler clients.

Because AES-GCM uses symmetric encryption, the caller and handler share a secret key
for each endpoint. This sample uses that key for both requests and results.

The caller uses a separate key for its workflow input and final result. Each handler
reuses its key 1 for backing workflow inputs.

| Ordinary workflow payload | Default key ID |
|---|---|
| Caller workflow input and final result | `CALLER_WORKFLOW_KEY` |
| Compressed/encrypted handler workflow inputs | `COMPRESSED_ENCRYPTED_KEY_1` |
| Encrypted handler workflow inputs | `ENCRYPTED_KEY_1` |
| Caller workflow input and final result | `caller-workflow` |
| Compressed/encrypted handler's backing workflow inputs | `compressed-encrypted-1` |
| Encrypted handler's backing workflow inputs | `encrypted-1` |

These workflow payloads use AES-GCM without compression or endpoint metadata.
An async Nexus result uses the key and compression chain selected by its endpoint,
even when that differs from the backing workflow's input encryption.

For synchronous operations, the SDK supplies Nexus context when decoding inputs and
encoding results. When an asynchronous handler starts `EchoWorkflow`, the SDK includes
the Nexus endpoint, service, and operation in the workflow-start request. The server
stores these fields in the `WorkflowExecutionStarted` history event. The worker SDK
restores the Nexus context from that event when encoding the workflow's result, so
`NexusCodec` can select the endpoint's codec and key from the worker's local configuration.
The workflow's input still uses ordinary workflow context; this sample's default codec
encrypts it with that handler's key 1.
The SDK supplies Nexus context when encoding and decoding operation requests and
results. For workflow-backed asynchronous operations, it preserves that context in
workflow history and restores it when encoding the result. A call through endpoint 2
can therefore return a result encrypted with key 2, as the caller expects, even though
the backing workflow's input uses the handler's default key 1.

The caller starts all eight operations before waiting for their results. Each operation
keeps its own endpoint context, even when operations for different keys are in flight.
No custom interceptor or workflow-header propagation is required.

A workflow execution produces one serialized result, shared by all Nexus operations
attached to it. Operations that need differently encrypted results therefore need
separate workflow executions. This sample starts a backing workflow for each async
operation, using its Nexus request ID as the workflow ID suffix. Retrying the same
request uses the same workflow ID.

The outer encrypted payload includes `encoding`, `encryption-key-id`, and, for Nexus
payloads, `nexus-endpoint-name` metadata. For example:

Expand All @@ -57,12 +63,12 @@ encryption-key-id: compressed-encrypted-1
nexus-endpoint-name: nexus-serialization-compressed-encrypted-1
```

A Codec Server can use that metadata to select the key and decompression chain without
SDK context. Ordinary workflow payloads have a key ID but no endpoint metadata or compression.
The metadata identifies the key and endpoint. The key material stays in the codec
configuration.
Ordinary workflow payloads have a key ID but no endpoint metadata or compression.

The hard-coded keys are only for this local example. For production encryption,
use a secure key store, as in the
[AWS Encryption SDK sample](../keymanagementencryption/awsencryptionsdk/README.md).
The AES-GCM codec and hard-coded keys are for this example. For production, use an
established encryption implementation and secure key storage.

## Prerequisites

Expand All @@ -84,7 +90,7 @@ namespace and task queue.
| Compressed/encrypted handler | `nexus-serialization-compressed-encrypted-handler` |
| Encrypted handler | `nexus-serialization-encrypted-handler` |

Start the dev server:
Start the server in its own terminal and leave it running:

```bash
./temporal server start-dev \
Expand All @@ -93,7 +99,7 @@ Start the dev server:
--namespace nexus-serialization-encrypted-handler
```

Create two endpoints for each handler worker:
In another terminal, create two endpoints for each handler worker:

```bash
./temporal operator nexus endpoint create \
Expand All @@ -114,7 +120,7 @@ Create two endpoints for each handler worker:
--target-task-queue nexus-serialization-encrypted-handler
```

Run each of the following in its own terminal from the repository root:
Run each worker in its own terminal and leave all three running alongside the server:

```bash
./gradlew -q :core:execute -PmainClass=io.temporal.samples.nexusserializationcontext.handler.CompressedEncryptedHandlerWorker \
Expand All @@ -131,14 +137,21 @@ Run each of the following in its own terminal from the repository root:
--args="-namespace nexus-serialization-caller"
```

Start the caller workflow in another terminal:

```bash
./gradlew -q :core:execute -PmainClass=io.temporal.samples.nexusserializationcontext.caller.CallerStarter \
--args="-namespace nexus-serialization-caller"
```

### Output

The starter prints a sync result and an async result for each endpoint. All eight
results should be `Hello from Nexus`.

The run creates five workflow executions: one caller and four async backing workflows.
The four sync operations return directly from their handlers.

## Test

Run the codec tests:
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -48,6 +48,8 @@ private AesGcmCodec(String keyId, SecretKey key, String endpoint) {
@Nonnull
public PayloadCodec withContext(@Nonnull SerializationContext context) {
if (context instanceof NexusSerializationContext nexusSerializationContext) {
// Return a lightweight context-bound codec without mutating the shared instance.
// Reuse the key; keep each operation's endpoint on its own codec instance.
return new AesGcmCodec(keyId, key, nexusSerializationContext.getEndpoint());
}
return this;
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@

import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;

import com.google.protobuf.ByteString;
import io.temporal.api.common.v1.Payload;
import io.temporal.common.converter.DataConverter;
import io.temporal.common.converter.EncodingKeys;
Expand All @@ -17,26 +19,40 @@
import io.temporal.samples.nexusserializationcontext.handler.CompressedEncryptedHandlerWorker;
import io.temporal.samples.nexusserializationcontext.handler.EncryptedHandlerWorker;
import io.temporal.samples.nexusserializationcontext.service.SyncEchoService;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.List;
import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import org.junit.jupiter.api.Test;

class NexusCodecTest {
@Test
void callerAndHandlersUseTheKeyForEachEndpoint() {
void callerAndHandlersUseTheKeyForEachEndpoint() throws Exception {
DataConverter compressedEncryptedHandler = CompressedEncryptedHandlerWorker.dataConverter();
DataConverter encryptedHandler = EncryptedHandlerWorker.dataConverter();

assertEndpointRoundTrip(
compressedEncryptedHandler,
SampleConfig.COMPRESSED_ENCRYPTED_1_ENDPOINT,
SampleConfig.COMPRESSED_ENCRYPTED_KEY_1_ID);
SampleConfig.COMPRESSED_ENCRYPTED_KEY_1_ID,
"handler-a-key-01");
assertEndpointRoundTrip(
compressedEncryptedHandler,
SampleConfig.COMPRESSED_ENCRYPTED_2_ENDPOINT,
SampleConfig.COMPRESSED_ENCRYPTED_KEY_2_ID);
SampleConfig.COMPRESSED_ENCRYPTED_KEY_2_ID,
"handler-a-key-02");
assertEndpointRoundTrip(
encryptedHandler, SampleConfig.ENCRYPTED_1_ENDPOINT, SampleConfig.ENCRYPTED_KEY_1_ID);
encryptedHandler,
SampleConfig.ENCRYPTED_1_ENDPOINT,
SampleConfig.ENCRYPTED_KEY_1_ID,
"handler-b-key-01");
assertEndpointRoundTrip(
encryptedHandler, SampleConfig.ENCRYPTED_2_ENDPOINT, SampleConfig.ENCRYPTED_KEY_2_ID);
encryptedHandler,
SampleConfig.ENCRYPTED_2_ENDPOINT,
SampleConfig.ENCRYPTED_KEY_2_ID,
"handler-b-key-02");
}

@Test
Expand All @@ -48,7 +64,7 @@ void compressesBeforeEncryptingWithEitherKey() {
}

@Test
void callerWorkflowPayloadsUseTheirOwnKey() {
void callerWorkflowPayloadsUseTheirOwnKey() throws Exception {
DataConverter converter =
CallerWorker.dataConverter()
.withContext(
Expand Down Expand Up @@ -78,6 +94,8 @@ void callerWorkflowPayloadsUseTheirOwnKey() {
assertFalse(input.containsMetadata(SampleConfig.ENDPOINT_METADATA_KEY));
assertFalse(result.containsMetadata(SampleConfig.ENDPOINT_METADATA_KEY));
assertFalse(input.getData().toStringUtf8().contains("Hello from Nexus"));
assertEncryptedWithKey(input, "sample-key-C-123");
assertEncryptedWithKey(result, "sample-key-C-123");
assertEquals("Hello from Nexus", converter.fromPayload(input, String.class, String.class));
assertEquals(
results, converter.fromPayload(result, EndpointResults.class, EndpointResults.class));
Expand All @@ -89,16 +107,99 @@ void rejectsUnknownEndpoints() {
assertThrows(PayloadCodecException.class, () -> converter.toPayload("hello"));
}

@Test
void handlerWorkflowInputsUseTheirDefaultKeys() throws Exception {
WorkflowSerializationContext context =
new WorkflowSerializationContext("handler", "workflow-id");
assertWorkflowDefault(
CompressedEncryptedHandlerWorker.dataConverter().withContext(context),
SampleConfig.COMPRESSED_ENCRYPTED_KEY_1_ID,
"handler-a-key-01");
assertWorkflowDefault(
EncryptedHandlerWorker.dataConverter().withContext(context),
SampleConfig.ENCRYPTED_KEY_1_ID,
"handler-b-key-01");
}

@Test
void bindingAnotherEndpointKeepsEarlierBindings() throws Exception {
DataConverter base = CallerWorker.dataConverter();
DataConverter first = base.withContext(contextFor(SampleConfig.ENCRYPTED_1_ENDPOINT));
DataConverter second = base.withContext(contextFor(SampleConfig.ENCRYPTED_2_ENDPOINT));
DataConverter workflow =
first.withContext(new WorkflowSerializationContext("caller", "caller-id"));

Payload firstPayload = first.toPayload("hello").orElseThrow();
assertEncryptionMetadata(
firstPayload, SampleConfig.ENCRYPTED_1_ENDPOINT, SampleConfig.ENCRYPTED_KEY_1_ID);
assertEncryptedWithKey(firstPayload, "handler-b-key-01");
assertEquals("hello", first.fromPayload(firstPayload, String.class, String.class));

Payload secondPayload = second.toPayload("reply").orElseThrow();
assertEncryptionMetadata(
secondPayload, SampleConfig.ENCRYPTED_2_ENDPOINT, SampleConfig.ENCRYPTED_KEY_2_ID);
assertEncryptedWithKey(secondPayload, "handler-b-key-02");
assertEquals("reply", second.fromPayload(secondPayload, String.class, String.class));

assertWorkflowDefault(base, SampleConfig.CALLER_WORKFLOW_KEY_ID, "sample-key-C-123");
assertWorkflowDefault(workflow, SampleConfig.CALLER_WORKFLOW_KEY_ID, "sample-key-C-123");

DataConverter handler = EncryptedHandlerWorker.dataConverter();
handler.withContext(contextFor(SampleConfig.ENCRYPTED_1_ENDPOINT)).toPayload("hello");
assertWorkflowDefault(
handler.withContext(new WorkflowSerializationContext("handler", "workflow-id")),
SampleConfig.ENCRYPTED_KEY_1_ID,
"handler-b-key-01");
}

@Test
void encryptingTheSameValueUsesAFreshNonce() {
DataConverter converter = converterFor(SampleConfig.ENCRYPTED_1_ENDPOINT);
Payload first = converter.toPayload("hello").orElseThrow();
Payload second = converter.toPayload("hello").orElseThrow();
assertNotEquals(first.getData().substring(0, 12), second.getData().substring(0, 12));
assertNotEquals(first.getData(), second.getData());
assertEquals("hello", converter.fromPayload(first, String.class, String.class));
assertEquals("hello", converter.fromPayload(second, String.class, String.class));
}

@Test
void rejectsAlteredAndTruncatedCiphertext() {
DataConverter converter = converterFor(SampleConfig.ENCRYPTED_1_ENDPOINT);
Payload original = converter.toPayload("hello").orElseThrow();
byte[] bytes = original.getData().toByteArray();
byte[] altered = bytes.clone();
altered[12] ^= 1;
for (byte[] damaged :
List.of(altered, Arrays.copyOf(bytes, 1), Arrays.copyOf(bytes, bytes.length - 1))) {
Payload payload = original.toBuilder().setData(ByteString.copyFrom(damaged)).build();
assertThrows(
PayloadCodecException.class,
() -> converter.fromPayload(payload, String.class, String.class));
}
}

private static void assertWorkflowDefault(DataConverter converter, String keyId, String key)
throws Exception {
Payload input = converter.toPayload("hello").orElseThrow();
assertEquals(keyId, input.getMetadataOrThrow(AesGcmCodec.KEY_ID_METADATA_KEY).toStringUtf8());
assertFalse(input.containsMetadata(SampleConfig.ENDPOINT_METADATA_KEY));
assertEncryptedWithKey(input, key);
assertEquals("hello", converter.fromPayload(input, String.class, String.class));
}

private static void assertEndpointRoundTrip(
DataConverter handler, String endpoint, String keyId) {
DataConverter handler, String endpoint, String keyId, String key) throws Exception {
DataConverter caller = converterFor(endpoint);
DataConverter contextualHandler = handler.withContext(contextFor(endpoint));
Payload request = caller.toPayload("hello").orElseThrow();
assertEncryptionMetadata(request, endpoint, keyId);
assertEncryptedWithKey(request, key);
assertEquals("hello", contextualHandler.fromPayload(request, String.class, String.class));

Payload result = contextualHandler.toPayload("reply").orElseThrow();
assertEncryptionMetadata(result, endpoint, keyId);
assertEncryptedWithKey(result, key);
assertEquals("reply", caller.fromPayload(result, String.class, String.class));
}

Expand Down Expand Up @@ -128,4 +229,16 @@ private static void assertEncryptionMetadata(Payload payload, String endpoint, S
assertEquals(
endpoint, payload.getMetadataOrThrow(SampleConfig.ENDPOINT_METADATA_KEY).toStringUtf8());
}

private static void assertEncryptedWithKey(Payload payload, String key) throws Exception {
byte[] encrypted = payload.getData().toByteArray();
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
cipher.init(
Cipher.DECRYPT_MODE,
new SecretKeySpec(key.getBytes(StandardCharsets.UTF_8), "AES"),
new GCMParameterSpec(128, Arrays.copyOf(encrypted, 12)));
Payload plaintext =
Payload.parseFrom(cipher.doFinal(Arrays.copyOfRange(encrypted, 12, encrypted.length)));
assertFalse(plaintext.getData().isEmpty());
}
}
Loading