#security #crypto #xchacha20 #aes #lz4


envelope encryption with strong cryptography and key management

5 releases

0.3.5 Jul 11, 2020
0.3.4 Jul 8, 2020
0.3.2 Jul 1, 2020
0.3.1 Jun 30, 2020
0.3.0 Jun 30, 2020

#7 in #xchacha20

Used in 4 crates

Apache-2.0 OR MIT



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. CloudKms

  • 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.


~165K SLoC