Encryption

S2 supports stream encryption with a key that you supply at request time. Configure a basin with a cipher for new streams, then provide the same key on append and read on any new streams.

Determined at stream creation

A stream captures its cipher when it is created, through its basin’s configuration.

Key supplied on data plane requests

Encrypted streams require the s2-encryption-key header on REST requests, or pass it using the corresponding CLI environment variable or flags.

Key custody stays with you

S2 does not persist or log the encryption key.

How it works

New streams inherit the stream_cipher configured on the basin at the moment they are created. Reconfiguring the basin later only affects streams created after that change.

What is encrypted

For regular records, S2 encrypts headers and body before storage, and decrypts them only when serving a read with the correct key. Command records stay plaintext because S2 must interpret them to apply service-side operations such as fencing and trimming.

Encrypted records are cryptographically bound to the stream they were written to. S2 includes the stream’s unique identifier as associated data, so ciphertext from one stream cannot be accepted as a record in another stream.

Supported ciphers

Cipher	API / CLI value	Key length
AEGIS-256 (recommended)	`aegis-256`	32 bytes
AES-256-GCM (NIST-approved)	`aes-256-gcm`	32 bytes

Keys are base64-encoded when provided in the s2-encryption-key header or to the CLI. SDKs allow providing either a string or bytes.

A stream configured with aes-256-gcm can have up to 2^32 records (~4.3 billion), and subsequent appends will be rejected. Otherwise, a stream can have up to 2^64 records (effectively unlimited) – so aegis-256 is generally preferable.

Where keys are required

Operation	Key required?	Notes
Create or reconfigure basin	No	Set `stream_cipher` here for future streams.
Create stream	No	The stream inherits the basin’s current `stream_cipher`.
Append	Yes, if the stream has a `cipher`	Provide the key on every request or session.
Read	Yes, if the stream has a `cipher`	Use the same key that encrypted the records you want to read.
Check tail	No	Tail only returns positions, not payloads.
List streams	No	Each stream’s `cipher` is returned in metadata.

Generate a key

openssl rand -base64 32

Store the resulting value as a secret to be used for one or more streams. Maintain a mapping of which key was used for which stream, so that it may be specified consistently for appends and reads.

Key management

For coarse-grained access, manage a shared key in your existing Key Management System (KMS) or secrets infrastructure. For finer-grained access, such as a key per stream, use envelope encryption:

Keep a Key Encryption Key (KEK) in your KMS.
Generate a Data Encryption Key (DEK) per stream, and store the wrapped DEK alongside your stream metadata.
At request time, your application unwraps the DEK and passes it to S2 as the stream encryption key.

If you need to rotate the key, create a new stream and cut writers and readers over deliberately. Similarly, to change the cipher used, update the basin configuration and then create a new stream.

Do not rotate a stream key in place by simply changing the request header. S2 will accept the append, but later reads with only one key will fail once they reach records encrypted under a different key.

Configure encryption for new streams

s2 create-basin secure-events \
  --stream-cipher aegis-256

# or change the default for streams created later
s2 reconfigure-basin secure-events \
  --stream-cipher aes-256-gcm

curl --request POST \
  --url 'https://a.s2.dev/v1/basins' \
  --header "Authorization: Bearer ${S2_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "basin": "secure-events",
    "config": {
      "stream_cipher": "aegis-256"
    }
  }'

curl --request PATCH \
  --url 'https://a.s2.dev/v1/basins/secure-events' \
  --header "Authorization: Bearer ${S2_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "stream_cipher": "aes-256-gcm"
  }'

await client.basins
	.create({
		basin: basinName,
		config: { streamCipher: "aegis-256" },
	})
	.catch((e) => {
		if (!(e instanceof S2Error && e.status === 409)) throw e;
	});

await client.basins.reconfigure({
	basin: basinName,
	streamCipher: "aes-256-gcm",
});

await client.create_basin(
    basin_name,
    config=BasinConfig(stream_cipher=Encryption.AEGIS_256),
)

await client.reconfigure_basin(
    basin_name,
    config=BasinConfig(stream_cipher=Encryption.AES_256_GCM),
)

client.Basins.Create(ctx, s2.CreateBasinArgs{
	Basin: basinName,
	Config: &s2.BasinConfig{
		StreamCipher: s2.Ptr(s2.EncryptionAlgorithmAegis256),
	},
})

client.Basins.Reconfigure(ctx, s2.ReconfigureBasinArgs{
	Basin: basinName,
	Config: s2.BasinReconfiguration{
		StreamCipher: s2.Ptr(s2.EncryptionAlgorithmAes256Gcm),
	},
})

client
    .create_basin(
        CreateBasinInput::new(basin_name.clone())
            .with_config(BasinConfig::new().with_stream_cipher(EncryptionAlgorithm::Aegis256)),
    )
    .await?;

client
    .reconfigure_basin(ReconfigureBasinInput::new(
        basin_name.clone(),
        BasinReconfiguration::new().with_stream_cipher(EncryptionAlgorithm::Aes256Gcm),
    ))
    .await?;

Stream create endpoints do not take a per-stream encryption field. A stream inherits the basin default when it is created, and that cipher is immutable for the lifetime of the stream.

Append and read with the key

export S2_ENCRYPTION_KEY="$(openssl rand -base64 32)"

printf 'top secret\n' | s2 append s2://secure-events/audit-log
s2 read s2://secure-events/audit-log -s 0 -n 1

# Alternatively, read the key from a file
s2 read s2://secure-events/audit-log \
  --encryption-key-file ./stream-key.b64 \
  -s 0 -n 10

curl --request POST \
  --url 'https://secure-events.b.s2.dev/v1/streams/audit-log/records' \
  --header "Authorization: Bearer ${S2_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --header 's2-format: raw' \
  --header "s2-encryption-key: ${S2_ENCRYPTION_KEY}" \
  --data '{
    "records": [
      { "body": "top secret" }
    ]
  }'

curl --request GET \
  --url 'https://secure-events.b.s2.dev/v1/streams/audit-log/records?seq_num=0&count=10' \
  --header "Authorization: Bearer ${S2_ACCESS_TOKEN}" \
  --header "s2-encryption-key: ${S2_ENCRYPTION_KEY}"

const stream = basin.stream(streamName, { encryptionKey: encKey });

await stream.append(
	AppendInput.create([AppendRecord.string({ body: "top secret" })]),
);

const batch = await stream.read({
	start: { from: { seqNum: 0 } },
	stop: { limits: { count: 10 } },
});

stream = basin.stream(
    stream_name,
    encryption_key=os.environ["S2_ENCRYPTION_KEY"],
)

await stream.append(
    AppendInput(
        records=[
            Record(body=b"top secret"),
        ]
    )
)

batch = await stream.read(
    start=SeqNum(0),
    limit=ReadLimit(count=10),
)

key, err := s2.NewEncryptionKey(os.Getenv("S2_ENCRYPTION_KEY"))
if err != nil {
	log.Fatalf("S2_ENCRYPTION_KEY: %v", err)
}

stream := basin.StreamWithOptions(s2.StreamName(streamName), &s2.StreamOptions{
	EncryptionKey: &key,
})

_, _ = stream.Append(ctx, &s2.AppendInput{
	Records: []s2.AppendRecord{
		{Body: []byte("top secret")},
	},
})

batch, _ := stream.Read(ctx, &s2.ReadOptions{
	SeqNum: s2.Uint64(0),
	Count:  s2.Uint64(10),
})

let stream = basin
    .stream(stream_name.clone())
    .with_encryption_key(std::env::var("S2_ENCRYPTION_KEY")?.parse()?);

stream
    .append(AppendInput::new(AppendRecordBatch::try_from_iter([
        AppendRecord::new("top secret")?,
    ])?))
    .await?;

let batch = stream
    .read(
        ReadInput::new()
            .with_start(ReadStart::new().with_from(ReadFrom::SeqNum(0)))
            .with_stop(ReadStop::new().with_limits(ReadLimits::new().with_count(10))),
    )
    .await?;

The same keying pattern applies to single-request operations, append/read sessions, SSE reads, and S2S sessions. The encryption key is just an HTTP header on the wire.

Inspect cipher config

Get basin config to see the basin’s current stream_cipher for new streams.
List streams to inspect current streams’ cipher.

Errors

Situation	Result
Missing key on an encrypted stream	`422 invalid`
Key is not valid base64 or not 32 bytes	`422 invalid`
Wrong key	`400 decryption_failed`

Core Model

Data Plane

Encryption

Determined at stream creation

Key supplied on data plane requests

Key custody stays with you

How it works

What is encrypted

Supported ciphers

Where keys are required

Generate a key

Key management

Configure encryption for new streams

Append and read with the key

Inspect cipher config

Errors

Determined at stream creation

Key supplied on data plane requests

Key custody stays with you

​How it works

​What is encrypted

​Supported ciphers

​Where keys are required

​Generate a key

​Key management

​Configure encryption for new streams

​Append and read with the key

​Inspect cipher config

​Errors

How it works

What is encrypted

Supported ciphers

Where keys are required

Generate a key

Key management

Configure encryption for new streams

Append and read with the key

Inspect cipher config

Errors