Skip to main content

bitwarden_crypto/store/
mod.rs

1//!
2//! This module contains all the necessary parts to create an in-memory key store that can be used
3//! to securely store key and use them for encryption/decryption operations.
4//!
5//! ## Organization
6//!
7//! ### Key Identifiers
8//! To avoid having to pass key materials over the crate boundaries, the key store API uses key
9//! identifiers in its API. These key identifiers are user-defined types that contain no key
10//! material, and are used to uniquely identify each key in the store. The key store doesn't specify
11//! how these traits should be implemented, but we recommend using `enums`, and we provide an
12//! optional macro ([key_slot_ids](crate::key_slot_ids)) that makes it easier to define them.
13//!
14//! ### Key Store
15//! [KeyStore] is a thread-safe in-memory key store and the main entry point for using this module.
16//! It provides functionality to encrypt and decrypt data using the keys stored in the store. The
17//! store is designed to be used by a single user and should not be shared between users.
18//!
19//! ### Key Store Context
20//! From a [KeyStore], you can also create an instance of [KeyStoreContext], which initializes a
21//! temporary context-local key store for encryption/decryption operations that require the use of
22//! per-item keys (like cipher keys or send keys, for example). Any keys stored in the context-local
23//! store will be cleared when the context is dropped.
24
25use std::sync::{Arc, RwLock};
26
27use bitwarden_ffi::{LargeVec, LargeVecError};
28use rayon::prelude::*;
29
30use crate::{CompositeEncryptable, Decryptable, IdentifyKey, KeySlotId, KeySlotIds};
31
32mod backend;
33mod cipher_suite;
34mod context;
35
36use backend::{StoreBackend, create_store};
37pub use cipher_suite::CipherSuite;
38use context::GlobalKeys;
39pub use context::KeyStoreContext;
40
41/// An in-memory key store that provides a safe and secure way to store keys and use them for
42/// encryption/decryption operations. The store API is designed to work only on key identifiers
43/// ([KeySlotId]). These identifiers are user-defined types that contain no key material, which
44/// means the API users don't have to worry about accidentally leaking keys.
45///
46/// Each store is designed to be used by a single user and should not be shared between users, but
47/// the store itself is thread safe and can be cloned to share between threads.
48///
49/// ```rust
50/// # use bitwarden_crypto::*;
51///
52/// // We need to define our own key identifier types. We provide a macro to make this easier.
53/// key_slot_ids! {
54///     #[symmetric]
55///     pub enum SymmKeySlotIds {
56///         User,
57///         #[local]
58///         Local(LocalId),
59///     }
60///     #[private]
61///     pub enum PrivateKeySlotIds {
62///         UserPrivate,
63///         #[local]
64///         Local(LocalId),
65///     }
66///     #[signing]
67///     pub enum SigningKeySlotIds {
68///        UserSigning,
69///        #[local]
70///        Local(LocalId),
71///     }
72///     pub Ids => SymmKeySlotIds, PrivateKeySlotIds, SigningKeySlotIds;
73/// }
74///
75/// // Initialize the store and insert a test key
76/// let store: KeyStore<Ids> = KeyStore::default();
77///
78/// #[allow(deprecated)]
79/// store.context_mut().set_symmetric_key(SymmKeySlotIds::User, SymmetricCryptoKey::make(SymmetricKeyAlgorithm::Aes256CbcHmac));
80///
81/// // Define some data that needs to be encrypted
82/// struct Data(String);
83/// impl IdentifyKey<SymmKeySlotIds> for Data {
84///    fn key_identifier(&self) -> SymmKeySlotIds {
85///        SymmKeySlotIds::User
86///    }
87/// }
88/// impl CompositeEncryptable<Ids, SymmKeySlotIds, EncString> for Data {
89///     fn encrypt_composite(&self, ctx: &mut KeyStoreContext<Ids>, key: SymmKeySlotIds) -> Result<EncString, CryptoError> {
90///         self.0.encrypt(ctx, key)
91///     }
92/// }
93///
94/// // Encrypt the data
95/// let decrypted = Data("Hello, World!".to_string());
96/// let encrypted = store.encrypt(decrypted).unwrap();
97/// ```
98pub struct KeyStore<Ids: KeySlotIds> {
99    // We use an Arc<> to make it easier to pass this store around, as we can
100    // clone it instead of passing references
101    inner: Arc<RwLock<KeyStoreInner<Ids>>>,
102}
103
104// Manually implement Clone to avoid requiring Ids: Clone
105impl<Ids: KeySlotIds> Clone for KeyStore<Ids> {
106    fn clone(&self) -> Self {
107        KeyStore {
108            inner: Arc::clone(&self.inner),
109        }
110    }
111}
112
113/// [KeyStore] contains sensitive data, provide a dummy [Debug] implementation.
114impl<Ids: KeySlotIds> std::fmt::Debug for KeyStore<Ids> {
115    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
116        f.debug_struct("KeyStore").finish()
117    }
118}
119
120struct KeyStoreInner<Ids: KeySlotIds> {
121    symmetric_keys: Box<dyn StoreBackend<Ids::Symmetric>>,
122    private_keys: Box<dyn StoreBackend<Ids::Private>>,
123    signing_keys: Box<dyn StoreBackend<Ids::Signing>>,
124    security_state_version: u64,
125    cipher_suite: CipherSuite,
126}
127
128/// Create a new key store with the best available implementation for the current platform.
129impl<Ids: KeySlotIds> Default for KeyStore<Ids> {
130    fn default() -> Self {
131        Self {
132            inner: Arc::new(RwLock::new(KeyStoreInner {
133                symmetric_keys: create_store(),
134                private_keys: create_store(),
135                signing_keys: create_store(),
136                security_state_version: 1,
137                cipher_suite: CipherSuite::default(),
138            })),
139        }
140    }
141}
142
143impl<Ids: KeySlotIds> KeyStore<Ids> {
144    /// Clear all keys from the store. This can be used to clear all keys from memory in case of
145    /// lock/logout, and is equivalent to destroying the store and creating a new one.
146    pub fn clear(&self) {
147        let mut keys = self.inner.write().expect("RwLock is poisoned");
148        keys.symmetric_keys.clear();
149        keys.private_keys.clear();
150        keys.signing_keys.clear();
151    }
152
153    /// Sets the security state version for this store.
154    pub fn set_security_state_version(&self, version: u64) {
155        let mut data = self.inner.write().expect("RwLock is poisoned");
156        data.security_state_version = version;
157    }
158
159    /// Sets the [CipherSuite] for this store, which determines the algorithms operations are
160    /// allowed to use (e.g. the KDF for a new account). This should be set once when the store
161    /// is constructed, based on the client's environment.
162    pub fn set_cipher_suite(&self, cipher_suite: CipherSuite) {
163        let mut data = self.inner.write().expect("RwLock is poisoned");
164        data.cipher_suite = cipher_suite;
165    }
166
167    /// Initiate an encryption/decryption context. This context will have read only access to the
168    /// global keys, and will have its own local key stores with read/write access. This
169    /// context-local store will be cleared when the context is dropped.
170    ///
171    /// If you are only looking to encrypt or decrypt items, you should implement
172    /// [CompositeEncryptable]/[Decryptable] and use the [KeyStore::encrypt], [KeyStore::decrypt],
173    /// [KeyStore::encrypt_list] and [KeyStore::decrypt_list] methods instead.
174    ///
175    /// The current implementation of context only clears the keys automatically when the context is
176    /// dropped, and not between operations. This means that if you are using the same context
177    /// for multiple operations, you may want to clear it manually between them. If possible, we
178    /// recommend using [KeyStore::encrypt_list] and [KeyStore::decrypt_list] instead.
179    ///
180    /// [KeyStoreContext] is not [Send] or [Sync] and should not be shared between threads. Note
181    /// that this can also be problematic in async code, and you should take care to ensure that
182    /// you're not holding references to the context across await points, as that would cause the
183    /// future to also not be [Send].
184    ///
185    /// Some other possible use cases for this API and alternative recommendations are:
186    /// - Decrypting or encrypting multiple [Decryptable] or [CompositeEncryptable] items while
187    ///   sharing any local keys. This is not recommended as it can lead to fragile and flaky
188    ///   decryption/encryption operations. We recommend any local keys to be used only in the
189    ///   context of a single [CompositeEncryptable] or [Decryptable] implementation. In the future
190    ///   we might enforce this.
191    /// - Obtaining the key material directly. We strongly recommend against doing this as it can
192    ///   lead to key material being leaked, but we need to support it for backwards compatibility.
193    ///   If you want to access the key material to encrypt it or derive a new key from it, we
194    ///   provide functions for that:
195    ///     - [KeyStoreContext::wrap_symmetric_key]
196    ///     - [KeyStoreContext::derive_shareable_key]
197    pub fn context(&'_ self) -> KeyStoreContext<'_, Ids> {
198        let data = self.inner.read().expect("RwLock is poisoned");
199        let security_state_version = data.security_state_version;
200        let cipher_suite = data.cipher_suite;
201        KeyStoreContext {
202            global_keys: GlobalKeys::ReadOnly(data),
203            local_symmetric_keys: create_store(),
204            local_private_keys: create_store(),
205            local_signing_keys: create_store(),
206            security_state_version,
207            cipher_suite,
208            _phantom: std::marker::PhantomData,
209        }
210    }
211
212    /// <div class="warning">
213    /// This is an advanced API, use with care and ONLY when needing to modify the global keys.
214    ///
215    /// The same pitfalls as [Self::context] apply here, but with the added risk of accidentally
216    /// modifying the global keys and leaving the store in an inconsistent state.
217    /// If you still need to use it, make sure you read this documentation to understand how to use
218    /// it safely.
219    /// </div>
220    ///
221    /// Initiate an encryption/decryption context. This context will have MUTABLE access to the
222    /// global keys, and will have its own local key stores with read/write access. This
223    /// context-local store will be cleared up when the context is dropped.
224    ///
225    /// The only supported use case for this API is initializing the store with the user's symetric
226    /// and private keys, and setting the organization keys. This method will be marked as
227    /// `pub(crate)` in the future, once we have a safe API for key initialization and updating.
228    ///
229    /// [KeyStoreContext] is not [Send] or [Sync] and should not be shared between threads. Note
230    /// that this can also be problematic in async code, and you should take care to ensure that
231    /// you're not holding references to the context across await points, as that would cause the
232    /// future to also not be [Send].
233    pub fn context_mut(&'_ self) -> KeyStoreContext<'_, Ids> {
234        let inner = self.inner.write().expect("RwLock is poisoned");
235        let security_state_version = inner.security_state_version;
236        let cipher_suite = inner.cipher_suite;
237        KeyStoreContext {
238            global_keys: GlobalKeys::ReadWrite(inner),
239            local_symmetric_keys: create_store(),
240            local_private_keys: create_store(),
241            local_signing_keys: create_store(),
242            security_state_version,
243            cipher_suite,
244            _phantom: std::marker::PhantomData,
245        }
246    }
247
248    /// Decript a single item using this key store. The key returned by `data.key_identifier()` must
249    /// already be present in the store, otherwise this will return an error.
250    /// This method is not parallelized, and is meant for single item decryption.
251    /// If you need to decrypt multiple items, use `decrypt_list` instead.
252    pub fn decrypt<
253        Key: KeySlotId,
254        Data: Decryptable<Ids, Key, Output> + IdentifyKey<Key>,
255        Output,
256    >(
257        &self,
258        data: &Data,
259    ) -> Result<Output, crate::CryptoError> {
260        let key = data.key_identifier();
261        data.decrypt(&mut self.context(), key)
262    }
263
264    /// Encrypt a single item using this key store. The key returned by `data.key_identifier()` must
265    /// already be present in the store, otherwise this will return an error.
266    /// This method is not parallelized, and is meant for single item encryption.
267    /// If you need to encrypt multiple items, use `encrypt_list` instead.
268    pub fn encrypt<
269        Key: KeySlotId,
270        Data: CompositeEncryptable<Ids, Key, Output> + IdentifyKey<Key>,
271        Output,
272    >(
273        &self,
274        data: Data,
275    ) -> Result<Output, crate::CryptoError> {
276        let key = data.key_identifier();
277        data.encrypt_composite(&mut self.context(), key)
278    }
279
280    /// Decrypt a list of items using this key store. The keys returned by
281    /// `data[i].key_identifier()` must already be present in the store, otherwise this will
282    /// return an error. This method will try to parallelize the decryption of the items, for
283    /// better performance on large lists.
284    pub fn decrypt_list<
285        Key: KeySlotId,
286        Data: Decryptable<Ids, Key, Output> + IdentifyKey<Key> + Send + Sync,
287        Output: Send + Sync,
288    >(
289        &self,
290        data: &[Data],
291    ) -> Result<Vec<Output>, crate::CryptoError> {
292        self.decrypt_batch(data).into_iter().collect()
293    }
294
295    /// Decrypt a list of items using this key store, returning a tuple of successful and failed
296    /// items.
297    ///
298    /// # Arguments
299    /// * `data` - The list of items to decrypt.
300    ///
301    /// # Returns
302    /// A tuple containing two vectors: the first vector contains the successfully decrypted items,
303    /// and the second vector contains the original items that failed to decrypt.
304    pub fn decrypt_list_with_failures<
305        'a,
306        Key: KeySlotId,
307        Data: Decryptable<Ids, Key, Output> + IdentifyKey<Key> + Send + Sync + 'a,
308        Output: Send + Sync,
309    >(
310        &self,
311        data: &'a [Data],
312    ) -> (Vec<Output>, Vec<&'a Data>) {
313        let mut successes = Vec::with_capacity(data.len());
314        let mut failures = Vec::new();
315        for (item, result) in data.iter().zip(self.decrypt_batch(data)) {
316            match result {
317                Ok(output) => successes.push(output),
318                Err(_) => failures.push(item),
319            }
320        }
321        (successes, failures)
322    }
323
324    /// Decrypt a list that can be large. Items from Rust are decrypted together, as
325    /// [KeyStore::decrypt_list] does. Items from JavaScript are converted and decrypted a batch at
326    /// a time, so only one batch is held in memory.
327    ///
328    /// Results come in input order: `Ok(Ok(output))` when an item decrypts, `Ok(Err(failure))` with
329    /// the item and its error when it does not, and `Err(error)` for an item from JavaScript that
330    /// does not convert, which ends the list.
331    pub fn decrypt_large_vec<'a, Key, Data, Output>(
332        &'a self,
333        items: LargeVec<Data>,
334    ) -> impl Iterator<Item = Result<Result<Output, Box<(Data, crate::CryptoError)>>, LargeVecError>> + 'a
335    where
336        Key: KeySlotId,
337        Data: Decryptable<Ids, Key, Output> + IdentifyKey<Key> + Sync + 'a,
338        Output: Send + 'a,
339    {
340        let results: Box<dyn Iterator<Item = _> + 'a> = match items.try_into_vec() {
341            // Items from Rust are already in memory, so they are decrypted as one slice, which
342            // avoids moving each item into a batch.
343            Ok(items) => {
344                let results = self.decrypt_batch(&items);
345                Box::new(
346                    items
347                        .into_iter()
348                        .zip(results)
349                        .map(|(item, result)| result.map_err(|error| Box::new((item, error))))
350                        .map(Ok),
351                )
352            }
353            Err(items) => Box::new(self.decrypt_iter(items)),
354        };
355        results
356    }
357
358    /// Decrypt items from an iterator a batch at a time, so only one batch is held in memory.
359    ///
360    /// Results come in input order: `Ok(Ok(output))` when an item decrypts, `Ok(Err(failure))` with
361    /// the item and its error when it does not, and `Err(error)` in place of an input error. The
362    /// iteration goes on after an input error. To fail on it, stop reading.
363    fn decrypt_iter<'a, Key, Data, Output, E>(
364        &'a self,
365        items: impl IntoIterator<Item = Result<Data, E>> + 'a,
366    ) -> impl Iterator<Item = Result<Result<Output, Box<(Data, crate::CryptoError)>>, E>> + 'a
367    where
368        Key: KeySlotId,
369        Data: Decryptable<Ids, Key, Output> + IdentifyKey<Key> + Sync + 'a,
370        Output: Send + 'a,
371        E: 'a,
372    {
373        self.decrypt_iter_in_batches(items, decrypt_iter_batch_size())
374    }
375
376    /// [KeyStore::decrypt_iter] with a given batch size (at least one).
377    fn decrypt_iter_in_batches<'a, Key, Data, Output, E>(
378        &'a self,
379        items: impl IntoIterator<Item = Result<Data, E>> + 'a,
380        batch_size: usize,
381    ) -> impl Iterator<Item = Result<Result<Output, Box<(Data, crate::CryptoError)>>, E>> + 'a
382    where
383        Key: KeySlotId,
384        Data: Decryptable<Ids, Key, Output> + IdentifyKey<Key> + Sync + 'a,
385        Output: Send + 'a,
386        E: 'a,
387    {
388        let batch_size = batch_size.max(1);
389        let mut items = items.into_iter();
390        let mut ready = Vec::new().into_iter();
391
392        std::iter::from_fn(move || {
393            loop {
394                if let Some(result) = ready.next() {
395                    return Some(result);
396                }
397                // Free the previous batch's results before reading the next batch.
398                ready = Default::default();
399
400                // Reserve only what the input can still yield, up to one batch.
401                let capacity = match items.size_hint() {
402                    (_, Some(upper)) => upper.min(batch_size),
403                    (_, None) => batch_size,
404                };
405                let mut batch = Vec::with_capacity(capacity);
406                let mut input_error = None;
407                while batch.len() < batch_size {
408                    match items.next() {
409                        Some(Ok(item)) => batch.push(item),
410                        Some(Err(error)) => {
411                            input_error = Some(error);
412                            break;
413                        }
414                        None => break,
415                    }
416                }
417                if batch.is_empty() && input_error.is_none() {
418                    return None;
419                }
420
421                // `decrypt_iter` takes ownership of the items, so the caller has no copy of an
422                // item that fails to decrypt, meaning that we can't give back a reference. The
423                // result returns the item itself, because callers such as the vault need to return
424                // failed ciphers to their clients. The item is boxed to keep the `Err` variant
425                // small, as clippy's `result_large_err` requires, because encrypted items such as
426                // a `Cipher` can be large.
427                let results = self.decrypt_batch(&batch);
428                ready = batch
429                    .into_iter()
430                    .zip(results)
431                    .map(|(item, result)| result.map_err(|error| Box::new((item, error))))
432                    .map(Ok)
433                    .chain(input_error.map(Err))
434                    .collect::<Vec<_>>()
435                    .into_iter();
436            }
437        })
438    }
439
440    /// Decrypts the items of a slice, returning each item's result in order. The decrypt behind
441    /// [KeyStore::decrypt_list], [KeyStore::decrypt_list_with_failures], and each batch of
442    /// [KeyStore::decrypt_iter].
443    ///
444    /// The items are spread over the rayon threads in pieces of at least `batch_chunk_size` items.
445    /// Each piece gets its own context, whose local keys are cleared after every item.
446    fn decrypt_batch<Key, Data, Output>(
447        &self,
448        batch: &[Data],
449    ) -> Vec<Result<Output, crate::CryptoError>>
450    where
451        Key: KeySlotId,
452        Data: Decryptable<Ids, Key, Output> + IdentifyKey<Key> + Sync,
453        Output: Send,
454    {
455        batch
456            .par_iter()
457            .with_min_len(batch_chunk_size(batch.len()))
458            .map_init(
459                || self.context(),
460                |ctx, item| {
461                    let result = item.decrypt(ctx, item.key_identifier());
462                    ctx.clear_local();
463                    result
464                },
465            )
466            .collect()
467    }
468
469    /// Encrypt a list of items using this key store. The keys returned by
470    /// `data[i].key_identifier()` must already be present in the store, otherwise this will
471    /// return an error. This method will try to parallelize the encryption of the items, for
472    /// better performance on large lists. This method is not parallelized, and is meant for
473    /// single item encryption.
474    pub fn encrypt_list<
475        Key: KeySlotId,
476        Data: CompositeEncryptable<Ids, Key, Output> + IdentifyKey<Key> + Send + Sync,
477        Output: Send + Sync,
478    >(
479        &self,
480        data: &[Data],
481    ) -> Result<Vec<Output>, crate::CryptoError> {
482        let res: Result<Vec<_>, _> = data
483            .par_chunks(batch_chunk_size(data.len()))
484            .map(|chunk| {
485                let mut ctx = self.context();
486
487                let mut result = Vec::with_capacity(chunk.len());
488
489                for item in chunk {
490                    let key = item.key_identifier();
491                    result.push(item.encrypt_composite(&mut ctx, key));
492                    ctx.clear_local();
493                }
494
495                result
496            })
497            .flatten()
498            .collect();
499
500        res
501    }
502}
503
504/// Calculate the optimal chunk size for parallelizing encryption/decryption operations.
505fn batch_chunk_size(len: usize) -> usize {
506    // In an optimal scenario with no overhead, we would split the data evenly between
507    // all available threads, rounding up to the nearest integer.
508    let items_per_thread = usize::div_ceil(len, rayon::current_num_threads());
509
510    // Because the addition of each chunk has some overhead (e.g. creating a new context, thread
511    // synchronization), we want to split the data into chunks that are large enough to amortize
512    // this overhead, but not too large that we get no benefit from multithreading. We've chosen
513    // a value more or less arbitrarily, but it seems to work well in practice.
514    const MINIMUM_CHUNK_SIZE: usize = 50;
515
516    // As a result, we pick whichever of the two values is larger.
517    usize::max(items_per_thread, MINIMUM_CHUNK_SIZE)
518}
519
520/// How many items [KeyStore::decrypt_iter] reads and decrypts at a time.
521fn decrypt_iter_batch_size() -> usize {
522    // The batch has to be large enough to give every thread a share well above the minimum chunk
523    // size of `batch_chunk_size`, so that the per-batch cost of spreading the work over the threads
524    // and waiting for the slowest one stays small. It has to be small enough that one batch of
525    // input and output takes little memory: in WASM, which has a single thread and whose memory
526    // never shrinks, this is 250 items. A caller reading the items out of a `Vec` holds the batch
527    // on top of the `Vec`, which keeps its buffer until it is dropped.
528    const ITEMS_PER_THREAD: usize = 250;
529
530    rayon::current_num_threads() * ITEMS_PER_THREAD
531}
532
533#[cfg(test)]
534pub(crate) mod tests {
535    use crate::{
536        EncString, PrimitiveEncryptable, SymmetricKeyAlgorithm,
537        store::{KeyStore, KeyStoreContext},
538        traits::tests::{TestIds, TestSymmKey},
539    };
540
541    pub struct DataView(pub String, pub TestSymmKey);
542    pub struct Data(pub EncString, pub TestSymmKey);
543
544    impl crate::IdentifyKey<TestSymmKey> for DataView {
545        fn key_identifier(&self) -> TestSymmKey {
546            self.1
547        }
548    }
549
550    impl crate::IdentifyKey<TestSymmKey> for Data {
551        fn key_identifier(&self) -> TestSymmKey {
552            self.1
553        }
554    }
555
556    impl crate::CompositeEncryptable<TestIds, TestSymmKey, Data> for DataView {
557        fn encrypt_composite(
558            &self,
559            ctx: &mut KeyStoreContext<TestIds>,
560            key: TestSymmKey,
561        ) -> Result<Data, crate::CryptoError> {
562            Ok(Data(self.0.encrypt(ctx, key)?, key))
563        }
564    }
565
566    impl crate::Decryptable<TestIds, TestSymmKey, DataView> for Data {
567        fn decrypt(
568            &self,
569            ctx: &mut KeyStoreContext<TestIds>,
570            key: TestSymmKey,
571        ) -> Result<DataView, crate::CryptoError> {
572            Ok(DataView(self.0.decrypt(ctx, key)?, key))
573        }
574    }
575
576    #[test]
577    fn test_multithread_decrypt_keeps_order() {
578        let store: KeyStore<TestIds> = KeyStore::default();
579
580        // Create a bunch of random keys
581        for n in 0..15 {
582            let mut ctx = store.context_mut();
583            let local_key_id = ctx.make_symmetric_key(SymmetricKeyAlgorithm::Aes256CbcHmac);
584            ctx.persist_symmetric_key(local_key_id, TestSymmKey::A(n))
585                .unwrap();
586        }
587
588        // Create some test data
589        let data: Vec<_> = (0..300usize)
590            .map(|n| DataView(format!("Test {n}"), TestSymmKey::A((n % 15) as u8)))
591            .collect();
592
593        // Encrypt the data
594        let encrypted: Vec<_> = store.encrypt_list(&data).unwrap();
595
596        // Decrypt the data
597        let decrypted: Vec<_> = store.decrypt_list(&encrypted).unwrap();
598
599        // Check that the data is the same, and in the same order as the original
600        for (orig, dec) in data.iter().zip(decrypted.iter()) {
601            assert_eq!(orig.0, dec.0);
602            assert_eq!(orig.1, dec.1);
603        }
604    }
605
606    mod decrypt_list {
607        use super::{decrypt_iter::store_and_items, *};
608
609        #[test]
610        fn decrypt_list_fails_with_a_failing_item() {
611            let (store, items) = store_and_items(120, &[70]);
612
613            let result: Result<Vec<DataView>, _> = store.decrypt_list(&items);
614
615            assert!(result.is_err());
616        }
617
618        #[test]
619        fn decrypt_list_with_failures_keeps_the_order_of_each_side() {
620            // More items than one chunk of `batch_chunk_size`, with failures in more than one
621            // chunk.
622            let failing = [0, 3, 60, 61, 119];
623            let (store, items) = store_and_items(120, &failing);
624
625            let (successes, failures): (Vec<DataView>, Vec<&Data>) =
626                store.decrypt_list_with_failures(&items);
627
628            let expected: Vec<_> = (0..120)
629                .filter(|n| !failing.contains(n))
630                .map(|n| format!("Item {n}"))
631                .collect();
632            let decrypted: Vec<_> = successes.into_iter().map(|view| view.0).collect();
633            assert_eq!(decrypted, expected);
634            let failed: Vec<_> = failures.into_iter().map(std::ptr::from_ref).collect();
635            let expected_failed: Vec<_> = failing
636                .iter()
637                .map(|&n| std::ptr::from_ref(&items[n]))
638                .collect();
639            assert_eq!(failed, expected_failed);
640        }
641    }
642
643    mod decrypt_large_vec {
644        use bitwarden_ffi::LargeVec;
645
646        use super::*;
647        use crate::store::tests::decrypt_iter::store_and_items;
648
649        #[test]
650        fn decrypts_a_rust_vec_in_order_and_hands_back_failed_items_in_place() {
651            let failing = [0, 3, 6];
652            let (store, items) = store_and_items(7, &failing);
653            let expected_keys: Vec<_> = items.iter().map(|item| item.1).collect();
654
655            let output: Vec<_> = store
656                .decrypt_large_vec::<_, _, DataView>(LargeVec::from(items))
657                .map(|result| match result.unwrap() {
658                    Ok(view) => Ok(view.0),
659                    Err(failure) => Err(failure.0.1),
660                })
661                .collect();
662
663            let expected: Vec<_> = (0..7)
664                .map(|n| {
665                    if failing.contains(&n) {
666                        Err(expected_keys[n])
667                    } else {
668                        Ok(format!("Item {n}"))
669                    }
670                })
671                .collect();
672            assert_eq!(output, expected);
673        }
674
675        #[test]
676        fn decrypts_mapped_items() {
677            let (store, items) = store_and_items(4, &[]);
678
679            let output: Vec<_> = store
680                .decrypt_large_vec::<_, _, DataView>(
681                    LargeVec::from(items).map(|item| Data(item.0, item.1)),
682                )
683                .map(|result| match result {
684                    Ok(Ok(view)) => view.0,
685                    _ => panic!("every item decrypts"),
686                })
687                .collect();
688
689            assert_eq!(
690                output,
691                (0..4).map(|n| format!("Item {n}")).collect::<Vec<_>>()
692            );
693        }
694    }
695
696    mod decrypt_iter {
697        use std::cell::Cell;
698
699        use super::*;
700        use crate::{CryptoError, Decryptable, IdentifyKey, store::decrypt_iter_batch_size};
701
702        /// A key slot no test puts a key in, so an item under it fails to decrypt.
703        const MISSING_KEY: TestSymmKey = TestSymmKey::A(99);
704
705        /// A store with a few keys, and `count` items encrypted under them, in order. The items at
706        /// `failing` are put under [MISSING_KEY].
707        pub(super) fn store_and_items(
708            count: usize,
709            failing: &[usize],
710        ) -> (KeyStore<TestIds>, Vec<Data>) {
711            let store: KeyStore<TestIds> = KeyStore::default();
712            for n in 0..3 {
713                let mut ctx = store.context_mut();
714                let local_key_id = ctx.make_symmetric_key(SymmetricKeyAlgorithm::Aes256CbcHmac);
715                ctx.persist_symmetric_key(local_key_id, TestSymmKey::A(n))
716                    .unwrap();
717            }
718            let views: Vec<_> = (0..count)
719                .map(|n| DataView(format!("Item {n}"), TestSymmKey::A((n % 3) as u8)))
720                .collect();
721            let items = store
722                .encrypt_list(&views)
723                .unwrap()
724                .into_iter()
725                .enumerate()
726                .map(|(n, item)| {
727                    if failing.contains(&n) {
728                        Data(item.0, MISSING_KEY)
729                    } else {
730                        item
731                    }
732                })
733                .collect();
734            (store, items)
735        }
736
737        /// An output item of [KeyStore::decrypt_iter] in these tests.
738        type DecryptIterItem = Result<Result<DataView, Box<(Data, CryptoError)>>, &'static str>;
739
740        /// What an output item says, for comparing whole outputs: the decrypted text, the failed
741        /// item's key, or the input error.
742        #[derive(Debug, PartialEq)]
743        enum Outcome {
744            Decrypted(String),
745            Failed(TestSymmKey),
746            InputError(&'static str),
747        }
748
749        fn outcome(item: DecryptIterItem) -> Outcome {
750            match item {
751                Ok(Ok(view)) => Outcome::Decrypted(view.0),
752                Ok(Err(failure)) => Outcome::Failed(failure.0.1),
753                Err(error) => Outcome::InputError(error),
754            }
755        }
756
757        fn decrypted(range: std::ops::Range<usize>) -> Vec<Outcome> {
758            range
759                .map(|n| Outcome::Decrypted(format!("Item {n}")))
760                .collect()
761        }
762
763        #[test]
764        fn yields_nothing_for_no_items() {
765            let (store, _) = store_and_items(0, &[]);
766
767            let output: Vec<_> = store
768                .decrypt_iter::<_, Data, DataView, &str>(std::iter::empty())
769                .collect();
770
771            assert!(output.is_empty());
772        }
773
774        #[test]
775        fn decrypts_in_order_with_the_default_batch_size() {
776            let count = decrypt_iter_batch_size() * 2 + 7;
777            let (store, items) = store_and_items(count, &[]);
778
779            let output: Vec<_> = store
780                .decrypt_iter(items.into_iter().map(Ok))
781                .map(outcome)
782                .collect();
783
784            assert_eq!(output, decrypted(0..count));
785        }
786
787        #[test]
788        fn decrypts_in_order_across_batch_sizes() {
789            // Shorter than a batch, exactly a batch, and longer than a batch with a partial last
790            // batch, for a batch size below and above the minimum chunk size.
791            for batch_size in [1, 7, 100] {
792                for count in [
793                    1,
794                    batch_size - 1,
795                    batch_size,
796                    batch_size + 1,
797                    3 * batch_size + 2,
798                ] {
799                    if count == 0 {
800                        continue;
801                    }
802                    let (store, items) = store_and_items(count, &[]);
803
804                    let output: Vec<_> = store
805                        .decrypt_iter_in_batches(items.into_iter().map(Ok::<_, &str>), batch_size)
806                        .map(outcome)
807                        .collect();
808
809                    assert_eq!(
810                        output,
811                        decrypted(0..count),
812                        "batch {batch_size}, {count} items"
813                    );
814                }
815            }
816        }
817
818        #[test]
819        fn hands_back_failed_items_in_place() {
820            // Failures at the start, on both sides of the batch boundaries at 5 and 10, and at the
821            // end.
822            let (store, items) = store_and_items(12, &[0, 4, 5, 9, 10, 11]);
823
824            let output: Vec<_> = store
825                .decrypt_iter_in_batches(items.into_iter().map(Ok), 5)
826                .map(outcome)
827                .collect();
828
829            let expected: Vec<_> = (0..12)
830                .map(|n| {
831                    if [0, 4, 5, 9, 10, 11].contains(&n) {
832                        Outcome::Failed(MISSING_KEY)
833                    } else {
834                        Outcome::Decrypted(format!("Item {n}"))
835                    }
836                })
837                .collect();
838            assert_eq!(output, expected);
839        }
840
841        #[test]
842        fn passes_input_errors_through_in_place_and_goes_on() {
843            let (store, items) = store_and_items(8, &[]);
844            // Input errors in the middle of a batch, right after a batch boundary, and last.
845            let input: Vec<Result<Data, &str>> = items
846                .into_iter()
847                .enumerate()
848                .flat_map(|(n, item)| match n {
849                    2 => vec![Ok(item), Err("after 2")],
850                    3 => vec![Err("before 3"), Ok(item)],
851                    7 => vec![Ok(item), Err("last")],
852                    _ => vec![Ok(item)],
853                })
854                .collect();
855
856            let output: Vec<_> = store
857                .decrypt_iter_in_batches(input, 3)
858                .map(outcome)
859                .collect();
860
861            let mut expected = decrypted(0..3);
862            expected.push(Outcome::InputError("after 2"));
863            expected.push(Outcome::InputError("before 3"));
864            expected.extend(decrypted(3..8));
865            expected.push(Outcome::InputError("last"));
866            assert_eq!(output, expected);
867        }
868
869        #[test]
870        fn stops_reading_the_input_when_the_caller_stops_at_an_input_error() {
871            let (store, items) = store_and_items(10, &[]);
872            let read = Cell::new(0);
873            let input = items.into_iter().enumerate().map(|(n, item)| {
874                read.set(read.get() + 1);
875                if n == 4 { Err("invalid") } else { Ok(item) }
876            });
877
878            let result: Result<Vec<_>, _> = store.decrypt_iter_in_batches(input, 3).collect();
879
880            assert_eq!(result.err(), Some("invalid"));
881            assert_eq!(read.get(), 5);
882        }
883
884        #[test]
885        fn reads_the_input_one_batch_at_a_time() {
886            let (store, items) = store_and_items(10, &[]);
887            let read = Cell::new(0);
888            let input = items.into_iter().map(|item| {
889                read.set(read.get() + 1);
890                Ok::<_, &str>(item)
891            });
892
893            let mut output = store.decrypt_iter_in_batches(input, 4);
894
895            assert_eq!(
896                read.get(),
897                0,
898                "nothing is read before the first item is asked for"
899            );
900            let mut read_after_each = Vec::new();
901            while output.next().is_some() {
902                read_after_each.push(read.get());
903            }
904            assert_eq!(read_after_each, [4, 4, 4, 4, 8, 8, 8, 8, 10, 10]);
905        }
906
907        #[test]
908        fn holds_no_context_between_items() {
909            let (store, items) = store_and_items(10, &[]);
910
911            let mut output = store.decrypt_iter_in_batches(items.into_iter().map(Ok::<_, &str>), 4);
912
913            // A context holds the store's lock, which would make the write lock unavailable.
914            while output.next().is_some() {
915                assert!(store.inner.try_write().is_ok());
916            }
917        }
918
919        /// A wrapper with its own decryption, as a caller might map each input item into.
920        struct Wrapped(Data);
921
922        impl IdentifyKey<TestSymmKey> for Wrapped {
923            fn key_identifier(&self) -> TestSymmKey {
924                self.0.key_identifier()
925            }
926        }
927
928        impl Decryptable<TestIds, TestSymmKey, DataView> for Wrapped {
929            fn decrypt(
930                &self,
931                ctx: &mut KeyStoreContext<TestIds>,
932                key: TestSymmKey,
933            ) -> Result<DataView, CryptoError> {
934                let view = self.0.decrypt(ctx, key)?;
935                Ok(DataView(format!("Wrapped {}", view.0), view.1))
936            }
937        }
938
939        #[test]
940        fn decrypts_mapped_items_and_hands_back_the_mapped_item() {
941            let (store, items) = store_and_items(5, &[3]);
942
943            let output: Vec<_> = store
944                .decrypt_iter_in_batches(
945                    items.into_iter().map(|item| Ok::<_, &str>(Wrapped(item))),
946                    2,
947                )
948                .map(|item| match item.unwrap() {
949                    Ok(view) => Ok(view.0),
950                    Err(failure) => Err((failure.0).0.1),
951                })
952                .collect();
953
954            assert_eq!(
955                output,
956                [
957                    Ok("Wrapped Item 0".to_owned()),
958                    Ok("Wrapped Item 1".to_owned()),
959                    Ok("Wrapped Item 2".to_owned()),
960                    Err(MISSING_KEY),
961                    Ok("Wrapped Item 4".to_owned()),
962                ]
963            );
964        }
965    }
966}