Module bonsaidb::local::vault

Encryption and secret management.

BonsaiDb’s vault is the core of encryption and secret management. To offer this security, BonsaiDb relies on external VaultKeyStorage to provide the key needed to decrypt the master keys. After the master keys have been decrypted, the vault is able to function without VaultKeyStorage. This design ensures that if a copy of a database was stolen, the data that is stored at-rest cannot be decrypted without gaining access to VaultKeyStorage.

At-Rest Encryption

At-rest encryption only ensures that if the database files are stolen that an attacker cannot access the data without the encryption key. BonsaiDb will regularly decrypt data to process it, and while the data is in-memory, it is subject to the security of the machine running it. If using BonsaiDb over a network, the network transport layer’s encryption is what ensures your data’s safety.

Security Best Practices

Vault Key Storage

In most situations, do not use LocalVaultKeyStorage in a production environment. If you store the vault keys on the same disk as the database, it’s similar to hiding a key to your house under your doormat. It might stop the casual person from entering your house, but give any attacker a few minutes, and they’ll find the key.

Instead, you should use a storage location that provides authentication and encryption. Our recommendation for production enviroments is to find an Amazon S3-compatible storage service and use S3VaultKeyStorage. Eventually, other BonsaiDb servers will be able to operate as key storage for each other.

Encryption Algorithms Used

BonsaiDb uses the hpke crate to provide Hybrid Public Key Encryption (HPKE) when public key encryption is being used. This is currently only utilized for encrypting the master keys with the vault key. Our HPKE uses P256+HKDF-SHA256+ChaCha20Poly1305. Long term, we plan to offer public key encryption APIs on top of these same choices.

For at-rest data encryption, the AEAD XChaCha20Poly1305 implementation is used directly. This variant of ChaCha20Poly1305 extends the nonce from 12 bytes to 24 bytes, which allows for random nonces to be used.

Structs

• LocalVaultKeyStorage
  Stores vault key locally on disk. This is in general considered insecure, and shouldn’t be used without careful consideration.

Enums

• Error
  Errors relating to encryption and/or secret storage.
• KeyPair
  A private encryption key.
• LocalVaultKeyStorageError
  Errors from local vault key storage.
• PublicKey
  A public key corresponding to a KeyPair.

Traits

• AnyVaultKeyStorage
  A VaultKeyStorage trait that wraps the Error type before returning. This type is used to allow the Vault to operate without any generic parameters. This trait is auto-implemented for all VaultKeyStorage implementors.
• VaultKeyStorage
  Stores encrypted keys for a vault.