asherah

Python bindings for the Asherah envelope encryption and key rotation library.

Native Rust implementation via PyO3/maturin. Prebuilt wheels are published to PyPI for Linux (x86_64 and aarch64, both glibc and musl), macOS (x86_64 and arm64), and Windows (x86_64 and arm64).

Installation

pip install asherah

Requires Python ≥ 3.8.

Documentation

Task-oriented walkthroughs under docs/:

Choosing an API style

Two API styles are exposed; both are fully supported and produce the same wire format. New code should prefer the Factory / Session API.

A complete runnable example exercising both styles plus async, log hook, and metrics hook is in samples/python/sample.py.

Quick start (static API)

import os
import asherah

os.environ["STATIC_MASTER_KEY_HEX"] = "22" * 32  # testing only

asherah.setup({
    "ServiceName": "my-service",
    "ProductID":   "my-product",
    "Metastore":   "memory",   # testing only — use "rdbms" or "dynamodb" in production
    "KMS":         "static",   # testing only — use "aws" in production
})

ct = asherah.encrypt_string("user-42", "secret")
pt = asherah.decrypt_string("user-42", ct)
assert pt == "secret"

asherah.shutdown()

Quick start (factory / session API)

import asherah

config = {
    "ServiceName": "my-service",
    "ProductID":   "my-product",
    "Metastore":   "memory",
    "KMS":         "static",
    "StaticMasterKeyHex": "22" * 32,
}

with asherah.SessionFactory(config) as factory:
    with factory.get_session("user-42") as session:
        ct = session.encrypt_text("secret")
        pt = session.decrypt_text(ct)
        assert pt == "secret"

SessionFactory(config) and SessionFactory.from_config(config) construct from an explicit config dict. SessionFactory() and SessionFactory.from_env() read config from environment variables; set them with asherah.setenv({...}) or via os.environ before constructing the factory.

Async API

There are two flavors of async to choose from depending on your call pattern:

• Module-level async (encrypt_string_async, decrypt_string_async, setup_async, shutdown_async) — wraps the sync calls with loop.run_in_executor. Lowest setup, but the sync work runs on the default thread pool executor.

• Session-level async (session.encrypt_bytes_async, session.decrypt_bytes_async) — true async PyO3 coroutines that run on the Rust tokio runtime. The asyncio event loop is not blocked, and there is no thread pool overhead.

import asyncio
import asherah

async def main():
    # Module-level
    await asherah.setup_async({...})
    ct = await asherah.encrypt_string_async("user-42", "secret")
    pt = await asherah.decrypt_string_async("user-42", ct)
    await asherah.shutdown_async()

    # Session-level (true async)
    with asherah.SessionFactory() as factory:
        session = factory.get_session("user-42")
        ct = await session.encrypt_bytes_async(b"secret")
        pt = await session.decrypt_bytes_async(ct)

asyncio.run(main())

Observability hooks

Log hook

Receive every log event from the Rust core (encrypt/decrypt path, metastore drivers, KMS clients).

def on_log(event):
    # event = {"level": "trace"|"debug"|"info"|"warn"|"error",
    #          "message": str, "target": str}
    if event["level"] in ("warn", "error"):
        print(f"[asherah {event['level']}] {event['message']}")

asherah.set_log_hook(on_log)

# later, to deregister:
asherah.set_log_hook(None)

The callback may fire from any thread (Rust tokio worker threads, DB driver threads). PyO3 acquires the GIL before invoking the callback, so the callback runs single-threaded from Python's perspective.

Metrics hook

Receive timing events for encrypt/decrypt/store/load and counter events for cache hit/miss/stale.

def on_metric(event):
    if event["type"] in ("encrypt", "decrypt", "store", "load"):
        # event = {"type": ..., "duration_ns": int}
        my_histogram.observe(event["type"], event["duration_ns"] / 1e6)
    else:
        # event = {"type": "cache_hit"|"cache_miss"|"cache_stale", "name": str}
        my_counter.inc(result=event["type"], cache=event["name"])

asherah.set_metrics_hook(on_metric)

# later:
asherah.set_metrics_hook(None)

Metrics collection is enabled automatically when a hook is installed and disabled when cleared.

Input contract

Partition ID (None, ""): always rejected as programming errors with TypeError (None) or ValueError/Exception ("partition id cannot be empty"). No row is ever written to the metastore under a degenerate partition ID.

Plaintext to encrypt:

• None → TypeError from PyO3 type conversion before any native call.
• Empty str ("") and empty bytes (b"") are valid plaintexts. encrypt_string / encrypt_bytes produce a real DataRowRecord envelope; decrypt_string / decrypt_bytes return exactly "" or b"".

Ciphertext to decrypt:

• None → TypeError.
• Empty str / bytes → exception from JSON parse (not valid DataRowRecord).

Do not short-circuit empty plaintext encryption in caller code — empty data is real data, encrypting it produces a genuine envelope, and skipping encryption leaks the fact that the value was empty. See docs/input-contract.md for the full rationale.

Configuration

setup() accepts a dict (or any JSON-serializable object) using PascalCase keys to match the canonical Go/Java/.NET API:

Both PascalCase and snake_case keys are accepted; PascalCase is canonical.

Environment variables

AWS KMS example

asherah.setup({
    "ServiceName": "payments-api",
    "ProductID": "acme-corp",
    "Metastore": "rdbms",
    "ConnectionString": "mysql://user:pass@host:3306/asherah",
    "SQLMetastoreDBType": "mysql",
    "KMS": "aws",
    "RegionMap": {"us-west-2": "arn:aws:kms:us-west-2:000:key/abc"},
    "PreferredRegion": "us-west-2",
    "EnableSessionCaching": True,
    "SessionCacheMaxSize": 1000,
})

Performance

Native Rust implementation. Typical latencies on Apple M4 Max (in-memory metastore, session caching enabled, 64-byte payload):

Async overhead is from the asyncio event loop dispatch + GIL handoff. Use sync for CPU-bound batches; use async when you need non-blocking behavior in an asyncio application.

API Reference

Full docstrings live in asherah/_asherah.pyi and asherah/__init__.py and surface in your IDE on hover. The tables below summarize each API; the type stubs are the source of truth.

Static / module-level API (legacy compatibility)

Lifecycle

Encrypt / decrypt

Hooks

Factory / Session API (recommended)

class SessionFactory

class Session

Event dict shapes

LogEvent = {
    "level": "trace" | "debug" | "info" | "warn" | "error",
    "message": str,
    "target": str,
}

# Metrics event for timing measurements:
TimingEvent = {
    "type": "encrypt" | "decrypt" | "store" | "load",
    "duration_ns": int,
}

# Metrics event for cache lifecycle:
CacheEvent = {
    "type": "cache_hit" | "cache_miss" | "cache_stale",
    "name": str,  # cache name, e.g. "session", "intermediate-key"
}

Cross-language compatibility

Wire-format compatible with all other Asherah implementations:

• canonical godaddy/asherah (Go core via cobhan)
• canonical godaddy/asherah-csharp
• canonical godaddy/asherah-java
• this repo's other bindings: Node, .NET, Java, Ruby, Go

A DataRowRecord written by any of these can be decrypted by any other, provided they share the same metastore and KMS configuration.

License

Licensed under the Apache License, Version 2.0.