Installation

The S3 store needs an HTTP client, chosen with an extra:

pip install truhe[urllib3]   # synchronous
pip install truhe[httpx]     # asynchronous

Without extra, the filesystem and the memory store are available.

Usage

A store wrapped in EncryptedBlobStore encrypts on the way in and decrypts on the way out:

import os

from truhe import EncryptedBlobStore
from truhe import Keyring
from truhe.s3 import S3BlobStore
from truhe.sigv4 import Credentials

credentials = Credentials(
    access_key='...',
    secret_key='...',
    region='fsn1',
)
store = EncryptedBlobStore(
    S3BlobStore(credentials, 'https://fsn1.your-objectstorage.com', 'bucket'),
    Keyring.from_setting(keys),
    magic=b'MYAPP',
)

# bytes
store.put('reports/2026/q3.pdf', data, 'application/pdf')

# a stream, with its length up front
with open('intro.mp4', 'rb') as f:
    store.put(
        'videos/intro.mp4',
        iter(lambda: f.read(65536), b''),
        'video/mp4',
        content_length=os.fstat(f.fileno()).st_size,
    )

with store.open('videos/intro.mp4') as stream:
    for chunk in stream.chunks:
        ...

store.head('videos/intro.mp4')    # StoredBlob(size=..., content_type=...)
list(store.list('videos/'))       # ListedBlob(key, size, modified)
store.delete('videos/intro.mp4')

The asynchronous stores have the same operations as coroutines, open is an async context manager, list an async iterator, a stream to put an async iterable:

import httpx

from truhe.aio import EncryptedBlobStore
from truhe.aio.s3 import S3BlobStore

async with httpx.AsyncClient() as client:
    store = EncryptedBlobStore(
        S3BlobStore(credentials, endpoint, 'bucket', client),
        keyring,
    )
    await store.put('k', data, 'application/octet-stream')
    async with store.open('k') as stream:
        async for chunk in stream.chunks:
            ...

Sizes are always plaintext sizes, the framing stays inside EncryptedBlobStore.

Streams

put takes bytes, or an iterable of bytes together with content_length. A stream which delivers more or fewer bytes than announced fails, and nothing is stored: the piece which would complete the object is only passed on once the stream is known to end there.

Bytes go to S3 with their SHA-256 in the signature and Content-MD5, so the store verifies what arrived. A stream goes out with UNSIGNED-PAYLOAD and its Content-Length; hashing it first would mean holding it. One request per object, so an object is at most 5 GiB, the limit of a single PUT.

Keys

A Keyring holds 32 byte keys, newest first. New objects are sealed with the first, every object names its key in its header. To rotate, put a new key in front, old objects stay readable. Dropping a key makes its objects unreadable.

openssl rand -hex 32

Keyring.from_setting reads a comma separated list of hex keys, the form of an environment variable. Keyring.primary_id is the id of the current key, worth recording next to every object, so the progress of a rotation is a query.

The key is the data. Lose it, and every object is gone while the store is perfectly healthy.

S3 compatible stores

S3BlobStore addresses the bucket virtual hosted, {bucket}.{endpoint host}, the form most providers document. Pass path_style=True for {endpoint}/{bucket}, e.g. MinIO or Garage without a domain. The region is the location code of the provider.

The stores do not retry. A retried upload after a lost answer is the application’s decision.

Format

An object is a header and its sealed blocks:

The nonce of a block is the prefix and the block counter, the associated data is the header and a flag for the last block. So a block cannot be reordered or moved to another object, a truncated object does not verify, and a header cannot be swapped. An empty object has one sealed empty block.

truhe.format has the format without I/O: Sealer and Opener take bytes as they arrive and return complete blocks, ciphertext_length gives the stored size before the first byte.

Not supported: HTTP Range, multipart uploads, presigned URLs.

Tests

make install
make test

The S3 stores are tested offline. The tests against a store are opt-in, make test skips them. To run them against a throwaway MinIO:

make test-s3

This starts the container from testing/compose.minio.yml, runs the S3 tests and discards the container, also when a test fails. To keep it running while working on the tests:

./scripts/minio.sh up
eval "$(./scripts/minio.sh env)"
make test
./scripts/minio.sh down

The store is selected by TRUHE_TEST_S3_ENDPOINT, TRUHE_TEST_S3_ACCESS_KEY, TRUHE_TEST_S3_SECRET_KEY, TRUHE_TEST_S3_REGION and TRUHE_TEST_S3_BUCKET, plus TRUHE_TEST_S3_PATH_STYLE=1 if needed. The bucket is emptied before each test, so it must be one which holds nothing else.

Contributors

• Robert Niederreiter

1.0.0 (2026-11-04)

• Initial release. Encrypted blob store with stores for memory, the filesystem and S3, synchronous over urllib3, asynchronous over httpx. AES-256-GCM in 64 KiB blocks, streaming in both directions. [rnix]