bitwarden_crypto/hazmat/symmetric_encryption/
mod.rs

1//! # Symmetric key encryption
2//!
3//! Low-level ("hazmat") authenticated symmetric ciphers, exposed behind two traits:
4//! - [`Aead`]: authenticated encryption *with* associated data. Implemented by AES-256-GCM
5//!   ([`Aes256Gcm`]) and XChaCha20-Poly1305 ([`XChaCha20Poly1305`]).
6//!
7//! These are dangerous primitives that operate directly on raw key material. In most cases you
8//! should use the higher-level [`safe`](crate::safe) module (e.g. the password-protected key
9//! envelope or data envelope) instead.
10
11use crate::CryptoError;
12pub(crate) mod aes_gcm;
13pub(crate) mod xchacha20;
14
15#[allow(unused_imports)]
16pub(crate) use aes_gcm::Aes256Gcm;
17#[allow(unused_imports)]
18pub(crate) use xchacha20::XChaCha20Poly1305;
19
20/// Authenticated encryption **with** associated data (AEAD).
21///
22/// In addition to encrypting and authenticating the plaintext, a cipher implementing this trait
23/// authenticates (but does not encrypt) caller-supplied associated data. The exact same associated
24/// data must be supplied to [`decrypt`](Aead::decrypt) for authentication to succeed.
25#[allow(dead_code)]
26pub(crate) trait Aead {
27    /// Key material used by the cipher.
28    type Key;
29    /// Authenticated ciphertext (the encrypted bytes). The nonce is tracked separately, by the
30    /// caller.
31    type Ciphertext;
32    /// The per-message nonce. A fresh nonce must be supplied for every encryption under a given
33    /// key.
34    type Nonce;
35
36    /// Encrypts `plaintext` under `key` with `nonce`, authenticating `associated_data` along with
37    /// the ciphertext.
38    ///
39    /// The same `nonce` must be supplied to [`decrypt`](Aead::decrypt). A fresh nonce must be used
40    /// for every message encrypted under a given key.
41    fn encrypt(
42        key: &Self::Key,
43        nonce: &Self::Nonce,
44        plaintext: &[u8],
45        associated_data: &[u8],
46    ) -> Self::Ciphertext;
47
48    /// Authenticates and decrypts `ciphertext` under `key` with `nonce`, verifying
49    /// `associated_data`.
50    ///
51    /// Returns [`CryptoError::KeyDecrypt`] if authentication fails (including a mismatch of
52    /// `associated_data` or `nonce`) or the ciphertext is malformed.
53    fn decrypt(
54        key: &Self::Key,
55        nonce: &Self::Nonce,
56        ciphertext: &Self::Ciphertext,
57        associated_data: &[u8],
58    ) -> Result<Vec<u8>, CryptoError>;
59}
bitwarden_crypto/hazmat/symmetric_encryption/mod.rs

bitwarden_crypto/hazmat/symmetric_encryption/
mod.rs
