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}