memseal

Encrypt and store secrets in memory with password-based key derivation, authenticated encryption, and automatic zeroization.

Note: This crate is not a wrapper around Linux mseal(2). "memseal" refers to sealing secrets in an encrypted in-memory vault.

Disclaimer: This library has not been independently audited. While it uses well-established cryptographic primitives (XChaCha20-Poly1305, Argon2i, HKDF-SHA256 via orion), the integration has not been reviewed by a third-party security firm. Use at your own risk in production environments. If you find a vulnerability, please see SECURITY.md for responsible disclosure.

Quick Start

use memseal::Vault;

let mut vault = Vault::create(b"my-password-here").unwrap();

// Store secrets
vault.store("api_key", b"sk-secret-12345").unwrap();
vault.store("db_url", b"postgres://user:pass@host/db").unwrap();

// Export to bytes (for persistence or transmission)
let bytes = vault.export().unwrap();

// Reopen with the same password
let vault = Vault::open(b"my-password-here", &bytes).unwrap();
let api_key = vault.retrieve("api_key").unwrap();
assert_eq!(api_key, Some(b"sk-secret-12345".to_vec()));

API

use memseal::{Vault, VaultError};
use std::path::Path;

// Create & open (password must be >= 8 bytes)
let mut vault = Vault::create(password)?;
let vault = Vault::open(password, &bytes)?;

// File I/O
vault.save(Path::new("vault.seal"))?;          // &mut self (rotates nonce)
let vault = Vault::load(Path::new("vault.seal"), password)?;

// Store, retrieve, remove
vault.store("name", b"secret")?;               // name max 255B, data max 64 MiB
let data = vault.retrieve("name")?;            // Option<Vec<u8>>
let existed = vault.remove("name")?;           // bool

// Export to bytes
let bytes = vault.export()?;                   // &mut self (rotates nonce)

// Change password (re-derives keys, re-encrypts all entries one-at-a-time)
vault.change_password(b"old-pass", b"new-pass")?;

Use Cases

• Secret management -- Hold API keys, database credentials, or signing keys in memory without exposing plaintext to swap, core dumps, or memory scanners.
• Encrypted vaults -- Store secrets with authenticated encryption. The index hides entry names behind HMAC and protects KDF parameters against downgrade attacks.
• Key derivation pipelines -- Derive purpose-specific subkeys from a master secret using HKDF with domain separation.
• Credential caches -- Cache decrypted credentials with automatic zeroization on drop. Memory is locked with mlock to prevent paging to disk.

Threat Model

What memseal protects against

What memseal does NOT protect against

Architecture

            Password (>= 8 bytes)
               |
           Argon2i (128 MiB, 4 iterations, random 16B salt)
               |
          Master Key (32B)
               |
         HKDF-SHA256 (salt = kdf_salt)
          /         \
    enc_subkey    hmac_subkey
      (32B)         (32B)
        |              |
  SecureMemoryVault  SecureMemoryVault
  (XChaCha20-Poly1305  (HMAC-SHA256
   streaming AEAD,      entry name hashing)
   mlock'd memory)
        |
  derive_nonce(enc_key, counter, salt)
  via HKDF with domain separation
        |
  Per-entry: seal_with_aad(key, nonce, data, hmac_key || counter)

Cryptographic Primitives

Security Properties

• #![deny(unsafe_code)] at crate level. Only secure_memory_vault.rs allows unsafe for mlock/munlock syscalls and unsafe impl Send/Sync (the struct uses a Mutex for interior synchronization and raw pointer fields are only accessed in Drop).
• Domain separation for all key derivation: MEMSEAL_SUBKEY_ENC_v1, MEMSEAL_SUBKEY_HMAC_v1, MEMSEAL_NONCE_CTR_v1, MEMSEAL_DATA_NONCE_v1, MEMSEAL_NAME_NONCE_v1.
• Partial swap protection. Only the ciphertext buffer inside each SecureMemoryVault is mlock'd. The internal encryption key and nonce reside on the heap without mlock — if swapped to disk, they could be recovered. This is a known trade-off.
• Caller-owned plaintext. retrieve() returns Vec<u8>. Internal temporaries are zeroized, but the returned plaintext is the caller's responsibility to zeroize or limit in scope.
• Authenticated encryption everywhere. No unauthenticated ciphertext path exists. Per-entry AAD prevents entry-swap attacks.
• Version validation on deserialization of VaultIndex and VaultHeader.
• Bounded input processing. Header length, KDF parameters, file size (256 MiB), entry name (255B), and entry data (64 MiB) are all validated before use.
• Zeroization on all paths. Key material, plaintext, and entry names are zeroized even on error returns within the library.

Building

cargo build
cargo test
cargo bench --bench full_bench

CI

GitHub Actions runs on every push and PR to main (actions SHA-pinned, stable toolchain):

• cargo check -- compilation
• cargo fmt --check -- formatting
• cargo clippy -D warnings -- lints
• cargo test -- unit and doc tests
• cargo audit -- vulnerability scanning

MSRV

Rust 2024 edition. CI runs stable toolchain.

License

MIT -- see LICENSE.