Documentation Index
Fetch the complete documentation index at: https://s2.dev/docs/llms.txt
Use this file to discover all available pages before exploring further.
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.
What is encrypted
For regular records, S2 encrypts headers and body before storage, and decrypts it 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 |
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
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.
CLI
REST
TypeScript
Python
Go
Rust
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"
}'
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",
});
try:
await client.create_basin(
basin_name,
config=BasinConfig(stream_cipher=Encryption.AEGIS_256),
)
except Exception:
pass
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),
},
})
let _ = 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
CLI
REST
TypeScript
Python
Go
Rust
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(_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
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 |
