diff --git a/Cargo.lock b/Cargo.lock index e4bf4f9df..9672d26e9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -3813,6 +3813,15 @@ version = "0.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" +[[package]] +name = "windows" +version = "0.48.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e686886bc078bc1b0b600cac0147aadb815089b6e4da64016cbd754b6342700f" +dependencies = [ + "windows-targets 0.48.5", +] + [[package]] name = "windows-core" version = "0.51.1" diff --git a/crates/bitwarden/src/crypto/aes_ops.rs b/crates/bitwarden/src/crypto/aes_ops.rs index 34d4021e8..87cb96029 100644 --- a/crates/bitwarden/src/crypto/aes_ops.rs +++ b/crates/bitwarden/src/crypto/aes_ops.rs @@ -1,3 +1,13 @@ +//! # AES operations +//! +//! Contains low level AES operations used by the rest of the library. +//! +//! **Warning**: Consider carefully if you have to use these functions directly, as generally we +//! expose higher level functions that are easier to use and more secure. +//! +//! In most cases you should use the [EncString] with [KeyEncryptable][super::KeyEncryptable] & +//! [KeyDecryptable][super::KeyDecryptable] instead. + use aes::cipher::{ block_padding::Pkcs7, generic_array::GenericArray, typenum::U32, BlockDecryptMut, BlockEncryptMut, KeyIvInit, @@ -10,6 +20,9 @@ use crate::{ error::{CryptoError, Result}, }; +/// Decrypt using AES-256 in CBC mode. +/// +/// Behaves similar to [decrypt_aes256_hmac], but does not validate the MAC. pub fn decrypt_aes256(iv: &[u8; 16], data: Vec, key: GenericArray) -> Result> { // Decrypt data let iv = GenericArray::from_slice(iv); @@ -18,13 +31,16 @@ pub fn decrypt_aes256(iv: &[u8; 16], data: Vec, key: GenericArray) .decrypt_padded_mut::(&mut data) .map_err(|_| CryptoError::KeyDecrypt)?; - //Data is decrypted in place and returns a subslice of the original Vec, to avoid cloning it, we truncate to the subslice length + // Data is decrypted in place and returns a subslice of the original Vec, to avoid cloning it, we truncate to the subslice length let decrypted_len = decrypted_key_slice.len(); data.truncate(decrypted_len); Ok(data) } +/// Decrypt using AES-256 in CBC mode with MAC. +/// +/// Behaves similar to [decrypt_aes256], but also validates the MAC. pub fn decrypt_aes256_hmac( iv: &[u8; 16], mac: &[u8; 32], @@ -39,12 +55,26 @@ pub fn decrypt_aes256_hmac( decrypt_aes256(iv, data, key) } +/// Encrypt using AES-256 in CBC mode. +/// +/// Behaves similar to [encrypt_aes256_hmac], but does't generate a MAC. +/// +/// ## Returns +/// +/// A AesCbc256_B64 EncString pub fn encrypt_aes256(data_dec: &[u8], key: GenericArray) -> Result { let (iv, data) = encrypt_aes256_internal(data_dec, key); Ok(EncString::AesCbc256_B64 { iv, data }) } +/// Encrypt using AES-256 in CBC mode with MAC. +/// +/// Behaves similar to [encrypt_aes256], but also generate a MAC. +/// +/// ## Returns +/// +/// A AesCbc256_HmacSha256_B64 EncString pub fn encrypt_aes256_hmac( data_dec: &[u8], mac_key: GenericArray, @@ -56,6 +86,11 @@ pub fn encrypt_aes256_hmac( Ok(EncString::AesCbc256_HmacSha256_B64 { iv, mac, data }) } +/// Encrypt using AES-256 in CBC mode. +/// +/// Used internally by: +/// - [encrypt_aes256] +/// - [encrypt_aes256_hmac] fn encrypt_aes256_internal(data_dec: &[u8], key: GenericArray) -> ([u8; 16], Vec) { let mut iv = [0u8; 16]; rand::thread_rng().fill_bytes(&mut iv); @@ -65,6 +100,7 @@ fn encrypt_aes256_internal(data_dec: &[u8], key: GenericArray) -> ([u8; (iv, data) } +/// Validate a MAC using HMAC-SHA256. fn validate_mac(mac_key: &[u8], iv: &[u8], data: &[u8]) -> Result<[u8; 32]> { let mut hmac = PbkdfSha256Hmac::new_from_slice(mac_key).expect("HMAC can take key of any size"); hmac.update(iv); diff --git a/crates/bitwarden/src/crypto/enc_string.rs b/crates/bitwarden/src/crypto/enc_string.rs index 976065e60..ac7f3fc6b 100644 --- a/crates/bitwarden/src/crypto/enc_string.rs +++ b/crates/bitwarden/src/crypto/enc_string.rs @@ -11,6 +11,45 @@ use crate::{ use super::{KeyDecryptable, KeyEncryptable, LocateKey}; +/// # Encrypted string primitive +/// +/// [EncString] is a Bitwarden specific primitive that represents an encrypted string. They are +/// are used together with the [KeyDecryptable] and [KeyEncryptable] traits to encrypt and decrypt +/// data using [SymmetricCryptoKey]s. +/// +/// The flexibility of the [EncString] type allows for different encryption algorithms to be used +/// which is represented by the different variants of the enum. +/// +/// ## Note +/// +/// We are currently in the progress of splitting the [EncString] into distinct AES and RSA +/// variants. To provide better control of which encryption algorithm is expected. +/// +/// For backwards compatibility we will rarely if ever be able to remove support for decrypting old +/// variants, but we should be opinionated in which variants are used for encrypting. +/// +/// ## Variants +/// - [AesCbc256_B64](EncString::AesCbc256_B64) +/// - [AesCbc128_HmacSha256_B64](EncString::AesCbc128_HmacSha256_B64) +/// - [AesCbc256_HmacSha256_B64](EncString::AesCbc256_HmacSha256_B64) +/// - [Rsa2048_OaepSha256_B64](EncString::Rsa2048_OaepSha256_B64) +/// - [Rsa2048_OaepSha1_B64](EncString::Rsa2048_OaepSha1_B64) +/// +/// ## Serialization +/// +/// [EncString] implements [Display] and [FromStr] to allow for easy serialization and uses a +/// custom scheme to represent the different variants. +/// +/// The scheme is one of the following schemes: +/// - `[type].[iv]|[data]` +/// - `[type].[iv]|[data]|[mac]` +/// - `[type].[data]` +/// +/// Where: +/// - `[type]`: is a digit number representing the variant. +/// - `[iv]`: (optional) is the initialization vector used for encryption. +/// - `[data]`: is the encrypted data. +/// - `[mac]`: (optional) is the MAC used to validate the integrity of the data. #[derive(Clone)] #[allow(unused, non_camel_case_types)] pub enum EncString { @@ -40,13 +79,14 @@ pub enum EncString { Rsa2048_OaepSha1_HmacSha256_B64 { data: Vec }, } -// We manually implement these to make sure we don't print any sensitive data +/// To avoid printing sensitive information, [EncString] debug prints to `EncString`. impl std::fmt::Debug for EncString { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { f.debug_struct("EncString").finish() } } +/// Deserializes an [EncString] from a string. impl FromStr for EncString { type Err = Error; @@ -291,6 +331,7 @@ impl serde::Serialize for EncString { } impl EncString { + /// The numerical representation of the encryption type of the [EncString]. const fn enc_type(&self) -> u8 { match self { EncString::AesCbc256_B64 { .. } => 0, diff --git a/crates/bitwarden/src/crypto/encryptable.rs b/crates/bitwarden/src/crypto/encryptable.rs index 10dbfaac6..f1bc78f15 100644 --- a/crates/bitwarden/src/crypto/encryptable.rs +++ b/crates/bitwarden/src/crypto/encryptable.rs @@ -19,10 +19,12 @@ pub trait LocateKey { } } +/// Deprecated: please use LocateKey and KeyDecryptable instead pub trait Encryptable { fn encrypt(self, enc: &EncryptionSettings, org_id: &Option) -> Result; } +/// Deprecated: please use LocateKey and KeyDecryptable instead pub trait Decryptable { fn decrypt(&self, enc: &EncryptionSettings, org_id: &Option) -> Result; } diff --git a/crates/bitwarden/src/crypto/fingerprint.rs b/crates/bitwarden/src/crypto/fingerprint.rs index 9473a2cda..ddcf89d40 100644 --- a/crates/bitwarden/src/crypto/fingerprint.rs +++ b/crates/bitwarden/src/crypto/fingerprint.rs @@ -7,6 +7,11 @@ use crate::{ wordlist::EFF_LONG_WORD_LIST, }; +/// Computes a fingerprint of the given `fingerprint_material` using the given `public_key`. +/// +/// This is commonly used for account fingerprints. With the following arguments: +/// - `fingerprint_material`: user's id. +/// - `public_key`: user's public key. pub(crate) fn fingerprint(fingerprint_material: &str, public_key: &[u8]) -> Result { let mut h = sha2::Sha256::new(); h.update(public_key); @@ -22,6 +27,7 @@ pub(crate) fn fingerprint(fingerprint_material: &str, public_key: &[u8]) -> Resu Ok(hash_word(user_fingerprint).unwrap()) } +/// Derive a 5 word phrase from a 32 byte hash. fn hash_word(hash: [u8; 32]) -> Result { let minimum_entropy = 64;