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. S2 stores the stream’s algorithm in metadata, but not the key material itself.

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 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.

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.

Configure encryption for new streams

CLI
REST
Rust SDK

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://aws.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://aws.s2.dev/v1/basins/secure-events' \
  --header "Authorization: Bearer ${S2_ACCESS_TOKEN}" \
  --header 'Content-Type: application/json' \
  --data '{
    "stream_cipher": "aes-256-gcm"
  }'

use s2::types::{
    BasinConfig, BasinReconfiguration, CreateBasinInput, EncryptionAlgorithm,
    ReconfigureBasinInput,
};

client
    .create_basin(
        CreateBasinInput::new("secure-events".parse()?).with_config(
            BasinConfig::new().with_stream_cipher(EncryptionAlgorithm::Aegis256),
        ),
    )
    .await?;

client
    .reconfigure_basin(ReconfigureBasinInput::new(
        "secure-events".parse()?,
        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

CLI
REST
Rust SDK

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}"

use s2::types::{
    AppendInput, AppendRecord, AppendRecordBatch, EncryptionKey, ReadFrom, ReadInput,
    ReadLimits, ReadStart, ReadStop,
};

let encryption_key: EncryptionKey = std::env::var("S2_ENCRYPTION_KEY")?.parse()?;
let stream = basin
    .stream("audit-log".parse()?)
    .with_encryption_key(encryption_key);

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 unary 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.

Key rotation and errors

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.

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`

Encrypted record payloads are authenticated to the stream they were written to.

Get Started

Concepts

Platform

Use Cases

Local

Infra-as-Code

Integrations

Encryption

Determined at stream creation

Key supplied on data plane requests

Key custody stays with you

How it works

Supported ciphers

Where keys are required

Generate a key

Configure encryption for new streams

Append and read with the key

Inspect cipher config

Key rotation and errors

Get Started

Concepts

Platform

Use Cases

Local

Infra-as-Code

Integrations

Determined at stream creation

Key supplied on data plane requests

Key custody stays with you

​How it works

​Supported ciphers

​Where keys are required

​Generate a key

​Configure encryption for new streams

​Append and read with the key

​Inspect cipher config

​Key rotation and errors

How it works

Supported ciphers

Where keys are required

Generate a key

Configure encryption for new streams

Append and read with the key

Inspect cipher config

Key rotation and errors