bitwarden_crypto/lib.rs
1//! # Bitwarden Cryptographic primitives
2//!
3//! This crate contains the cryptographic primitives used throughout the SDK. The general
4//! aspiration is for this crate to handle all the difficult cryptographic operations and expose
5//! higher level concepts to the rest of the SDK.
6//!
7//! <div class="warning">
8//! Generally you should <b>not</b> find yourself needing to edit this crate! Everything written
9//! here requires additional care and attention to ensure that the cryptographic primitives are
10//! secure. </div>
11//!
12//! ## Example:
13//!
14//! ```rust
15//! use bitwarden_crypto::{SymmetricCryptoKey, KeyEncryptable, KeyDecryptable, CryptoError};
16//!
17//! async fn example() -> Result<(), CryptoError> {
18//! let key = SymmetricCryptoKey::generate(rand::thread_rng());
19//!
20//! let data = "Hello, World!".to_owned();
21//! let encrypted = data.clone().encrypt_with_key(&key)?;
22//! let decrypted: String = encrypted.decrypt_with_key(&key)?;
23//!
24//! assert_eq!(data, decrypted);
25//! Ok(())
26//! }
27//! ```
28//!
29//! ## Development considerations
30//!
31//! This crate is expected to provide long term support for cryptographic operations. To that end,
32//! the following considerations should be taken into account when making changes to this crate:
33//!
34//! - Limit public interfaces to the bare minimum.
35//! - Breaking changes should be rare and well communicated.
36//! - Serializable representation of keys and encrypted data must be supported indefinitely as we
37//! have no way to update all data.
38//!
39//! ### Conventions:
40//!
41//! - Pure Functions that deterministically "derive" keys from input are prefixed with `derive_`.
42//! - Functions that generate non deterministically keys are prefixed with `make_`.
43//!
44//! ### Differences from `clients`
45//!
46//! There are some noteworthy differences compared to the other Bitwarden
47//! [clients](https://github.com/bitwarden/clients). These changes are made in an effort to
48//! introduce conventions in how we name things, improve best practices and abstracting away
49//! internal complexity.
50//!
51//! - `CryptoService.makeSendKey` & `AccessService.createAccessToken` are replaced by the generic
52//! `derive_shareable_key`
53//! - MasterKey operations such as `makeMasterKey` and `hashMasterKey` are moved to the MasterKey
54//! struct.
55//!
56//! ## Crate features
57//!
58//! - `no-memory-hardening` - Disables memory hardening which ensures that allocated memory is
59//! zeroed on drop. This feature primarily exists in case you do not want to use the standard
60//! allocator, and we advise to still define a `global_allocator` using the
61//! [`ZeroizingAllocator`].
62
63#[cfg(not(feature = "no-memory-hardening"))]
64#[global_allocator]
65static ALLOC: ZeroizingAllocator<std::alloc::System> = ZeroizingAllocator(std::alloc::System);
66
67mod aes;
68mod enc_string;
69pub use enc_string::{AsymmetricEncString, EncString};
70mod error;
71pub use error::CryptoError;
72pub(crate) use error::Result;
73mod fingerprint;
74pub use fingerprint::fingerprint;
75mod keys;
76pub use keys::*;
77mod rsa;
78pub use crate::rsa::RsaKeyPair;
79mod util;
80pub use util::{generate_random_alphanumeric, generate_random_bytes, pbkdf2};
81mod wordlist;
82pub use wordlist::EFF_LONG_WORD_LIST;
83mod allocator;
84pub use allocator::ZeroizingAllocator;
85
86#[cfg(feature = "uniffi")]
87uniffi::setup_scaffolding!();
88
89#[cfg(feature = "uniffi")]
90mod uniffi_support;