Download the PHP package godaddy/asherah without Composer

Asherah

Application-layer encryption with automatic key rotation. Rust implementation with bindings for Node.js, Python, .NET, Java, Ruby, and Go.

What is Asherah?

Asherah implements envelope encryption: data is encrypted with a random data key, which is itself encrypted with an intermediate key, which is encrypted by a master key held in a KMS. Keys rotate automatically based on configurable intervals, and old keys remain accessible for decryption while new data is always encrypted with fresh keys.

This design means application code never handles raw master keys, key rotation happens transparently, and compromise of a single data key exposes only one record.

KMS backends: AWS KMS (recommended), AWS Secrets Manager (migration only), static (testing only)

Metastores: DynamoDB, MySQL, Postgres, SQLite, in-memory (testing only)

Language Bindings

Platform Support

Quick Start

See each binding's README for complete examples including async APIs, session-based usage, and production configuration.

Input contract

There are two argument categories with different rules:

• Partition ID (the tenancy/isolation identifier): null, nil, undefined, and the empty string "" are always programming errors. Bindings reject them at the API boundary with the language-native exception type — no row is ever written to the metastore under a degenerate ID. (Stricter than canonical asherah-csharp / asherah-java, which silently accept null and persist _IK__service_product rows.)
• Plaintext (input to encrypt): null/nil/undefined is rejected as a programming error. Empty String and empty byte array are valid plaintexts that produce a real DataRowRecord envelope and round-trip back to empty on decrypt. Do not short-circuit empty plaintext encryption in caller code — empty data is real data, encrypting it is a real cryptographic operation, and skipping it leaks the fact that the value was empty as a side channel.
• Ciphertext (input to decrypt): null/nil/undefined and empty string/bytes are all rejected — empty input cannot be a valid DataRowRecord JSON envelope.

See docs/input-contract.md for the full per-binding behavior matrix, exception types, and rationale.

Performance

The Rust core delivers sub-microsecond encrypt/decrypt. All language bindings stay under 2μs for sync operations. The table includes both sync and async variants, plus head-to-head comparison with the canonical Go/C#/Java implementations:

Benchmark results — hot cache, Apple M4 Max

See each binding's README for detailed async behavior and per-metastore performance characteristics.

Architecture: Key Hierarchy and Secure Caching

Asherah uses a four-level key hierarchy with envelope encryption:

Secure Memory and Tiered Key Cache

Keys are protected at rest by a three-tier cache with hardware-enforced memory protection:

Tier 1 hit (typical encrypt/decrypt): The decrypted key is already in an mlock'd slab slot — zero crypto overhead, just a pointer read. This is why hot-cache encrypt is ~400ns.

Tier 1 miss, Tier 2 hit: The key's Enclave (AES-256-GCM encrypted ciphertext in heap memory) is decrypted using the Coffer master key from the slab, placed in a free slot, and promoted to the hot cache.

Tier 2 miss (cold start): The key is loaded from the metastore, decrypted through the key hierarchy (KMS decrypts SK, SK decrypts IK), sealed into an Enclave, and promoted into the slab hot cache.

Coffer: The master key for Enclave encryption is split across two mlock'd slots using XOR + hash derivation. Neither slot alone reveals the key. Initialized once at startup with OS entropy.

Session and Key Caches

Above the memory tiers, Asherah maintains logical caches with stale-while-revalidate to prevent thundering herd on cache expiry:

On cache expiry, the stale key is returned immediately while a background refresh loads the latest version from the metastore.

Testing

• 127 Rust unit tests covering core encryption engine, key management, metastore adapters, and memory protection
• 64 .NET tests (34 core + 30 compatibility layer) across net8.0 and net10.0
• 49 Node.js tests including async context, unicode, binary edge cases, and Factory/Session API
• 21 Go tests covering Factory/Session API and compatibility layer
• 21 Python tests including session-based and async APIs
• 16 Java tests including JNI lifecycle and async CompletableFuture
• 74 Ruby tests including thread safety, session lifecycle, and async callbacks
• 5 cross-language interop tests verifying Python, Node.js, Rust, and Ruby encrypt/decrypt compatibility
• 6 fuzz targets for Cargo-fuzz continuous fuzzing
• Memory safety: Miri (undefined behavior detection), AddressSanitizer, and Valgrind on every PR
• 12 publish dry-run jobs that replicate every unique compilation path in the release pipeline
• 56+ CI jobs on every pull request across x86_64 and ARM64

Project Structure

Security

• mlock'd memory: All key material lives in pages pinned to RAM (mlock), preventing the OS from swapping secrets to disk
• Guard pages: Buffer overflows and underflows are caught by hardware-enforced guard pages around protected memory regions
• Canary bytes: Optional buffer overflow detection via randomized canary values at buffer boundaries
• Wipe-on-free: All key material is cryptographically scrubbed before memory is released — no residual secrets in freed pages
• Core dump protection: Disabled at process initialization to prevent secrets from appearing in crash dumps
• Coffer key splitting: The Enclave master key is split across two mlock'd slots using XOR + hash derivation — neither slot alone reveals the key
• AES-256-GCM Enclaves: Keys at rest in regular memory are encrypted with authenticated encryption; only the mlock'd Coffer can decrypt them

License

Apache-2.0