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`]), XAES-256-GCM ([`XAes256Gcm`]), and XChaCha20-Poly1305
6//!   ([`XChaCha20Poly1305`]).
7//!
8//! These are dangerous primitives that operate directly on raw key material. In most cases you
9//! should use the higher-level [`safe`](crate::safe) module (e.g. the password-protected key
10//! envelope or data envelope) instead.
11
12use crate::CryptoError;
13pub(crate) mod aes256_cbc;
14
15#[allow(dead_code)]
16#[derive(Debug, PartialEq, Eq)]
17pub(crate) enum SymmetricEncryptionError {
18    /// The input is malformed — wrong length, invalid padding, or otherwise not a valid
19    /// ciphertext for the cipher.
20    FormatWrong,
21    /// The integrity check (MAC / authentication tag) failed; the ciphertext, associated data,
22    /// nonce/IV, and key do not match.
23    IntegrityCheckFailed,
24}
25
26impl From<SymmetricEncryptionError> for CryptoError {
27    fn from(_: SymmetricEncryptionError) -> Self {
28        CryptoError::KeyDecrypt
29    }
30}
31pub(crate) mod aes256_cbc_hmac_sha256_ae;
32pub(crate) mod aes_gcm;
33pub(crate) mod xaes_256_gcm;
34pub(crate) mod xchacha20;
35
36#[allow(unused_imports)]
37pub(crate) use aes_gcm::Aes256Gcm;
38pub(crate) use aes256_cbc::Aes256Cbc;
39pub(crate) use aes256_cbc_hmac_sha256_ae::Aes256CbcHmacSha256;
40#[allow(unused_imports)]
41pub(crate) use xaes_256_gcm::XAes256Gcm;
42#[allow(unused_imports)]
43pub(crate) use xchacha20::XChaCha20Poly1305;
44
45/// Authenticated encryption **with** associated data (AEAD).
46///
47/// In addition to encrypting and authenticating the plaintext, a cipher implementing this trait
48/// authenticates (but does not encrypt) caller-supplied associated data. The exact same associated
49/// data must be supplied to [`decrypt`](Aead::decrypt) for authentication to succeed.
50#[allow(dead_code)]
51pub(crate) trait Aead {
52    /// Key material used by the cipher.
53    type Key;
54    /// Authenticated ciphertext (the encrypted bytes). The nonce is tracked separately, by the
55    /// caller.
56    type Ciphertext;
57    /// The per-message nonce. A fresh nonce must be supplied for every encryption under a given
58    /// key.
59    type Nonce;
60
61    /// Encrypts `plaintext` under `key` with `nonce`, authenticating `associated_data` along with
62    /// the ciphertext.
63    ///
64    /// The same `nonce` must be supplied to [`decrypt`](Aead::decrypt). A fresh nonce must be used
65    /// for every message encrypted under a given key.
66    fn encrypt(
67        key: &Self::Key,
68        nonce: &Self::Nonce,
69        plaintext: &[u8],
70        associated_data: &[u8],
71    ) -> Self::Ciphertext;
72
73    /// Authenticates and decrypts `ciphertext` under `key` with `nonce`, verifying
74    /// `associated_data`.
75    ///
76    /// Returns [`CryptoError::KeyDecrypt`] if authentication fails (including a mismatch of
77    /// `associated_data` or `nonce`) or the ciphertext is malformed.
78    fn decrypt(
79        key: &Self::Key,
80        nonce: &Self::Nonce,
81        ciphertext: &Self::Ciphertext,
82        associated_data: &[u8],
83    ) -> Result<Vec<u8>, CryptoError>;
84}
bitwarden_crypto/hazmat/symmetric_encryption/mod.rs

bitwarden_crypto/hazmat/symmetric_encryption/
mod.rs
