[][src]Crate secret_keeper


Envelope encryption with strong cryptography and key management. A SecretKeeper encrypts a data encryption key (DEK) with a key-encryption-key (KEK), returning a WrappedKey. This crate (and sub-crates) implement several SecretKeepers, plus three content encryption ciphers:

  • XCha20Cha20-Poly1305 with AEAD
  • AES-GCM (256-bit)
  • and a compressing cipher that combines LZ4 with XChaCha20-Poly1305

The APIs in this crate are intended to provide good security practices while minimizing opportunities for unintentional developer errors that could reduce the security. One such principle is that encryption keys are always stored encrypted at rest.

Some SecretKeeper implementations have already been developed. If you create a new one, please send me a link and I'll link to it from here.

  • Env generates a key from a passphrase stored in an environment variable, using PBKDF2+HMAC+SHA256+SALT. EnvKeeper

  • Prompt prompts the user at a terminal for a passphrase. The KEK is generated from the passphrase using PBKDF2+HMAC+SHA256+SALT. Requires the secret-keeper-prompt crate. PromptKeeper

  • Hashivault Using Vault's Transit engine, the HashivaultKeeper can create keys (key-encryption-keys) with a variety of encryption algorithms, including aes-gcm-256, ed25519, and several others). A DEK is encrypted or decrypted by the Vault, using the KEK managed-by and stored-on the Vault. Hashivault

  • CloudKMS The CloudKmsKeeper uses keys in Google CloudKMS service.

  • 1Password (linux/mac only). 1Password is included in the example directory to show how external programs can be used with EnvKeeper and a shell script; no additionl rust code is required. Uses the free 1password op cli tool,

Implementation notes

Crypto algorithms used are implemented by other packages, notably RustCrypto, a pure-rust implemenation.

LZ4 compression is a pure rust implementation by lz_fear.

The concept for this library is based on the google cloud secret-keeper library


This is a new crate and it should be considered alpha quality.

Additional SecretKeeper implementations are planned. If you create any, please let me know and I'll link to it from here.

The core secret-keeper library compiles into wasm without error, but I haven't tested it in a browser yet.



Encryption ciphers


Crate error handling


SecretKeeper definitions and implementations. This crate contains a small number of built-in SecretKeepers that are automatically registered and discoverable with SecretKeeper::for_uri(). Any SecretKeeper that is not pure rust, or that would prevent secret-keeper core from compiling to wasm, should be implemented as a separate optional crate. Additionally, SecretKeepers that depend on external services (such as a Google Cloud or AWS) or hardware, should be packaged separately from the core library.


CSRNG based on platform (OS) CSRNG.




This macro, used by Cipher implementations, provides a struct KeyBox containing sized key and nonce arrays. See cipher implementations for implementation examples



A WrappedKey provides a way to store and communicate encrypted-encryption keys.