oxistore-encrypt — Pure-Rust encryption-at-rest for OxiStore KV stores

oxistore-encrypt is the encryption-at-rest layer of the OxiStore stack. It decorates any oxistore_core::KvStore so that values are transparently encrypted on write and decrypted on read — keys remain in plaintext. Two complementary layers are provided:

• Cell-level encryption ([EncryptedKv]) — each value is sealed with an AEAD cipher, using a BLAKE3-derived cell identity (or an explicit (table_id, row_id, col_id) [CellId]) as AAD. This binds every ciphertext to its exact storage location, so transplanting bytes to a different key fails authentication.
• Envelope encryption ([EncryptedKvEnvelope]) — each value is encrypted under a unique random Data Encryption Key (DEK), and the DEK is wrapped under the active Key-Encrypting Key (KEK) held in a versioned [Keyring]. Key rotation re-wraps only the tiny DEK wrapper; bulk data is never re-encrypted.

All cryptography is Pure Rust via the COOLJAPAN [oxicrypto] crate — XChaCha20-Poly1305 and AES-256-GCM-SIV AEAD, BLAKE3 for cell-ID derivation, Argon2id for passphrase-based key derivation, and an OS-seeded CSPRNG. The crate is #![forbid(unsafe_code)]; no C, C++, or Fortran is involved.

Installation

[dependencies]
oxistore-encrypt = "0.1.0"

oxistore-encrypt wraps any KvStore; pair it with a backend such as oxistore-kv-redb or oxistore-kv-sled.

Quick Start

Cell-level encryption

use oxistore_encrypt::{EncryptedKv, StaticKey, KvStore};

# fn demo<T: KvStore>(inner: T) -> Result<(), Box<dyn std::error::Error>> {
let key = StaticKey::from_array([0x42u8; 32]);
let enc = EncryptedKv::new(inner, key);

enc.put(b"hello", b"world")?;
assert_eq!(enc.get(b"hello")?, Some(b"world".to_vec()));
# Ok(())
# }

Selecting a cipher via the builder

use oxistore_encrypt::{CipherBuilder, AeadChoice, KvStore};

# fn demo<T: KvStore>(store: T) -> Result<(), oxistore_encrypt::EncryptError> {
let enc = CipherBuilder::new()
    .aead(AeadChoice::AesGcmSiv256)   // misuse-resistant
    .key([0x42u8; 32])
    .build(store)?;
# let _ = enc;
# Ok(())
# }

Envelope encryption with key rotation

use oxistore_encrypt::{EncryptedKvEnvelope, EnvelopeCipher, Keyring, KvStore};

# fn demo<T: KvStore>(store: T) -> Result<(), Box<dyn std::error::Error>> {
let keyring = Keyring::new([0x11u8; 32]);           // KEK version 1
let cipher = EnvelopeCipher::new(keyring);
let mut enc = EncryptedKvEnvelope::new(store, cipher);

enc.put(b"k", b"secret")?;

// Rotate to a new KEK: re-wraps every DEK wrapper, leaving data ciphertext intact.
let rotated = enc.rotate_kek([0x22u8; 32])?;
println!("re-wrapped {rotated} entries");
# Ok(())
# }

API Overview

Cell-level decorator

EncryptedKv implements the full KvStore surface — get, put, delete, contains, range, iter, transaction (→ [EncryptedTxn]), snapshot (→ [EncryptedSnapshot]), flush.

Envelope decorator

EncryptedKvEnvelope implements get, put, delete, contains, range, iter, flush; transaction and snapshot currently return StoreError::Other (not yet supported for envelope mode).

AEAD layer (aead module)

Cell helpers (cell module)

Key providers (keys module)

Builder (cipher_builder module)

Keyring (keyring module)

Transaction / snapshot wrappers

Re-exports

oxistore_core::KvStore is re-exported at the crate root for convenience.

Algorithms

Wire formats

Cell-level: nonce (24) ‖ ciphertext ‖ Poly1305 tag (16).

Envelope: kek_version (4, LE) ‖ wrap_nonce (24) ‖ wrapped_dek (48) ‖ data_nonce (24) ‖ data_ciphertext (N + 16) — minimum 116 bytes.

Feature Flags

Error variants

EncryptError implements std::error::Error + Display, with From conversions to and from oxistore_core::StoreError.

Cross-references

• oxistore — the storage facade; enable the encrypt feature to re-export this crate.
• oxistore-core — the KvStore / KvTxn / KvSnapshot / StoreError traits decorated by this crate.
• oxicrypto — the Pure-Rust AEAD, BLAKE3, Argon2id, and CSPRNG primitives backing every operation.
• oxistore-kv-redb, oxistore-kv-sled, oxistore-kv-fjall — KV backends that can be wrapped.

License

Apache-2.0 — COOLJAPAN OU (Team Kitasan)