Domain
¶ Baileys sessions
Key
CHANNEL_SESSION_KEY
Object pathchannels/{id}/auth.bin
Layout
Security
¶ Media and Session Encryption
Sessions and media are encrypted at rest in object storage using AES-256-GCM, each with its own key.
AES-256-GCM at rest
Two separate keys
rbx-env records the media layout
Never guess from bytes
Two domains
¶ What is encrypted, with which key, and where it lives
Domain
¶ Media
Key
MEDIA_OBJECT_KEY
Object pathchannels/{id}/media/{message_id}
Layout
Media objects can also use the streamable v2 layout. See envelope formats.
Keep the keys separate. Both use [iv(12) | tag(16) | ciphertext], but a session key must never decrypt media, or the other way round.
Media object envelope formats and metadata
¶ Two AES-GCM layouts exist for stored media
Which layout an object uses is recorded in S3 user metadata under the key rbx-env (e.g. rbx-env: v2).
v1 · legacy
Writers may continue to produce v1.
v2 · streamable
Connectors that stream upload should produce v2 so encryption can be done without buffering the whole payload.
MarkerStore an explicit envelope marker (e.g.
rbx-env / MEDIA_ENVELOPE_META_KEY) with every encrypted media object.
ReadersFetch the object's user metadata and choose the correct decrypt path.
Server componentsRead the envelope metadata and use an envelope-aware decryption API (decrypt_media_envelope) to avoid auth-tag failures when formats differ between producers.
Never
¶ Never infer the envelope layout from raw bytes
Losing the marker makes objects undecryptable.
Don't guessNever guess the layout by inspecting bytes. Read
rbx-env.
Preserve it on copiesS3 copy operations preserve user metadata by default. Preserve the marker on server-side copies.
Don't replace metadataDo not drop or replace rbx-env (e.g. via MetadataDirective=REPLACE) unless you explicitly reapply the same marker.