A deep dive into how Bitwarden and its self-hosted clone Vaultwarden encrypt and decrypt secrets. The post explains the two-layer encryption model: a passphrase-derived key (via PBKDF2 + HKDF) protects the master key, which in turn encrypts all vault secrets using AES-CBC with HMAC-SHA256 integrity checks. Complete working Python code is provided for both decryption and encryption, covering key derivation, MAC verification, and AES operations using the pyaes and hkdf libraries. The author was motivated by a supply chain attack on the official Bitwarden CLI and interest in building a local client that works directly with a Vaultwarden SQLite database.
Table of contents
The 10,000 foot viewThe master keyDecoding a Bitwarden secretSecuring the master keyEncrypting secretsConclusionSort: