Merge branch 'km/cose' into km/cose-content-format

Author: quexten

Cargo.lock

@@ -13,6 +13,7 @@ rust-version = "1.75"
 homepage = "https://bitwarden.com"
 repository = "https://github.com/bitwarden/sdk-internal"
 license-file = "LICENSE"
+readme = "DISCLAIMER.md"
 keywords = ["bitwarden"]
 
 # Define dependencies that are expected to be consistent across all crates

Cargo.toml

@@ -0,0 +1,4 @@
+This is an internal crate for the Bitwarden SDK. Do not depend on this directly and use the
+[`bitwarden`](https://crates.io/crates/bitwarden) crate instead.
+
+This crate does not follow semantic versioning and the public interface may change at any time.

DISCLAIMER.md

@@ -8,6 +8,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+readme.workspace = true
 homepage.workspace = true
 repository.workspace = true
 license-file.workspace = true

crates/bitwarden-cli/Cargo.toml

@@ -1,6 +1,3 @@
 # Bitwarden Cli
 
-This is an internal crate for the Bitwarden SDK do not depend on this directly and use the
-[`bitwarden`](https://crates.io/crates/bitwarden) crate instead.
-
-This crate does not follow semantic versioning and the public interface may change at any time.
+Common utilities for the Bitwarden Password Manager CLI and Secrets Manager CLI.

crates/bitwarden-cli/README.md

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 mod color;
 
 pub use color::{install_color_eyre, Color};

crates/bitwarden-cli/src/lib.rs

@@ -3,15 +3,16 @@ name = "bitwarden-core"
 description = """
 Internal crate for the bitwarden crate. Do not use.
 """
-keywords = ["bitwarden"]
 
 version.workspace = true
 authors.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+readme.workspace = true
 homepage.workspace = true
 repository.workspace = true
 license-file.workspace = true
+keywords.workspace = true
 
 [features]
 internal = ["dep:zxcvbn"]

crates/bitwarden-core/Cargo.toml

@@ -1,6 +1,7 @@
 # Bitwarden Core
 
-This is an internal crate for the Bitwarden SDK do not depend on this directly and use the
-[`bitwarden`](https://crates.io/crates/bitwarden) crate instead.
+Contains core functionality used by the feature crates.
 
-This crate does not follow semantic versioning and the public interface may change at any time.
+<div class="warning">
+Generally you should <b>not</b> find yourself needing to edit this crate! When possible, please use the feature crates instead.
+</div>

crates/bitwarden-core/README.md

@@ -54,9 +54,8 @@ pub(crate) fn auth_request_decrypt_user_key(
     user_key: AsymmetricEncString,
 ) -> Result<SymmetricCryptoKey, EncryptionSettingsError> {
     let key = AsymmetricCryptoKey::from_der(&STANDARD.decode(private_key)?)?;
-    let mut key: Vec<u8> = user_key.decapsulate_key_unsigned(&key)?;
-
-    Ok(SymmetricCryptoKey::try_from(key.as_mut_slice())?)
+    let key: SymmetricCryptoKey = user_key.decapsulate_key_unsigned(&key)?;
+    Ok(key)
 }
 
 /// Decrypt the user key using the private key generated previously.
@@ -69,8 +68,8 @@ pub(crate) fn auth_request_decrypt_master_key(
     use bitwarden_crypto::MasterKey;
 
     let key = AsymmetricCryptoKey::from_der(&STANDARD.decode(private_key)?)?;
-    let mut master_key: Vec<u8> = master_key.decapsulate_key_unsigned(&key)?;
-    let master_key = MasterKey::try_from(master_key.as_mut_slice())?;
+    let master_key: SymmetricCryptoKey = master_key.decapsulate_key_unsigned(&key)?;
+    let master_key = MasterKey::try_from(&master_key)?;
 
     Ok(master_key.decrypt_user_key(user_key)?)
 }
@@ -102,7 +101,7 @@ pub(crate) fn approve_auth_request(
     let key = ctx.dangerous_get_symmetric_key(SymmetricKeyId::User)?;
 
     Ok(AsymmetricEncString::encapsulate_key_unsigned(
-        &key.to_encoded(),
+        key,
         &public_key,
     )?)
 }
@@ -117,15 +116,20 @@ fn test_auth_request() {
         96, 31, 114, 127, 212, 187, 167, 110, 205, 116, 198, 243, 218, 72, 137, 53, 248, 43, 255,
         67, 35, 61, 245, 93,
     ];
+    let secret = secret.to_vec();
 
     let private_key =
         AsymmetricCryptoKey::from_der(&STANDARD.decode(&request.private_key).unwrap()).unwrap();
 
-    let encrypted = AsymmetricEncString::encapsulate_key_unsigned(secret, &private_key).unwrap();
+    let encrypted = AsymmetricEncString::encapsulate_key_unsigned(
+        &SymmetricCryptoKey::try_from(secret.clone()).unwrap(),
+        &private_key,
+    )
+    .unwrap();
 
     let decrypted = auth_request_decrypt_user_key(request.private_key, encrypted).unwrap();
 
-    assert_eq!(&decrypted.to_encoded(), secret);
+    assert_eq!(decrypted.to_encoded(), secret);
 }
 
 #[cfg(test)]

crates/bitwarden-core/src/auth/auth_request.rs

@@ -20,8 +20,7 @@ pub(super) fn make_register_tde_keys(
     let user_key = UserKey::new(SymmetricCryptoKey::generate());
     let key_pair = user_key.make_key_pair()?;
 
-    let admin_reset =
-        AsymmetricEncString::encapsulate_key_unsigned(&user_key.0.to_encoded(), &public_key)?;
+    let admin_reset = AsymmetricEncString::encapsulate_key_unsigned(&user_key.0, &public_key)?;
 
     let device_key = if remember_device {
         Some(DeviceKey::trust_device(&user_key.0)?)

crates/bitwarden-core/src/auth/tde.rs

@@ -111,7 +111,7 @@ impl EncryptionSettings {
 
         // Decrypt the org keys with the private key
         for (org_id, org_enc_key) in org_enc_keys {
-            ctx.decrypt_symmetric_key_with_asymmetric_key(
+            ctx.decapsulate_key_unsigned(
                 AsymmetricKeyId::UserPrivateKey,
                 SymmetricKeyId::Organization(org_id),
                 &org_enc_key,

crates/bitwarden-core/src/client/encryption_settings.rs

@@ -1,3 +1,5 @@
+#![doc = include_str!("../README.md")]
+
 #[cfg(feature = "uniffi")]
 uniffi::setup_scaffolding!();
 #[cfg(feature = "uniffi")]

crates/bitwarden-core/src/lib.rs

@@ -375,7 +375,7 @@ pub(super) fn enroll_admin_password_reset(
     let key = ctx.dangerous_get_symmetric_key(SymmetricKeyId::User)?;
 
     Ok(AsymmetricEncString::encapsulate_key_unsigned(
-        &key.to_encoded(),
+        key,
         &public_key,
     )?)
 }
@@ -737,7 +737,8 @@ mod tests {
         let private_key = "MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQCzLtEUdxfcLxDj84yaGFsVF5hZ8Hjlb08NMQDy1RnBma06I3ZESshLYzVz4r/gegMn9OOltfV/Yxlyvida8oW6qdlfJ7AVz6Oa8pV7BiL40C7b76+oqraQpyYw2HChANB1AhXL9SqWngKmLZwjA7qiCrmcc0kZHeOb4KnKtp9iVvPVs+8veFvKgYO4ba2AAOHKFdR0W55/agXfAy+fWUAkC8mc9ikyJdQWaPV6OZvC2XFkOseBQm9Rynudh3BQpoWiL6w620efe7t5k+02/EyOFJL9f/XEEjM/+Yo0t3LAfkuhHGeKiRST59Xc9hTEmyJTeVXROtz+0fjqOp3xkaObAgMBAAECggEACs4xhnO0HaZhh1/iH7zORMIRXKeyxP2LQiTR8xwN5JJ9wRWmGAR9VasS7EZFTDidIGVME2u/h4s5EqXnhxfO+0gGksVvgNXJ/qw87E8K2216g6ZNo6vSGA7H1GH2voWwejJ4/k/cJug6dz2S402rRAKh2Wong1arYHSkVlQp3diiMa5FHAOSE+Cy09O2ZsaF9IXQYUtlW6AVXFrBEPYH2kvkaPXchh8VETMijo6tbvoKLnUHe+wTaDMls7hy8exjtVyI59r3DNzjy1lNGaGb5QSnFMXR+eHhPZc844Wv02MxC15zKABADrl58gpJyjTl6XpDdHCYGsmGpVGH3X9TQQKBgQDz/9beFjzq59ve6rGwn+EtnQfSsyYT+jr7GN8lNEXb3YOFXBgPhfFIcHRh2R00Vm9w2ApfAx2cd8xm2I6HuvQ1Os7g26LWazvuWY0Qzb+KaCLQTEGH1RnTq6CCG+BTRq/a3J8M4t38GV5TWlzv8wr9U4dl6FR4efjb65HXs1GQ4QKBgQC7/uHfrOTEHrLeIeqEuSl0vWNqEotFKdKLV6xpOvNuxDGbgW4/r/zaxDqt0YBOXmRbQYSEhmO3oy9J6XfE1SUln0gbavZeW0HESCAmUIC88bDnspUwS9RxauqT5aF8ODKN/bNCWCnBM1xyonPOs1oT1nyparJVdQoG//Y7vkB3+wKBgBqLqPq8fKAp3XfhHLfUjREDVoiLyQa/YI9U42IOz9LdxKNLo6p8rgVthpvmnRDGnpUuS+KOWjhdqDVANjF6G3t3DG7WNl8Rh5Gk2H4NhFswfSkgQrjebFLlBy9gjQVCWXt8KSmjvPbiY6q52Aaa8IUjA0YJAregvXxfopxO+/7BAoGARicvEtDp7WWnSc1OPoj6N14VIxgYcI7SyrzE0d/1x3ffKzB5e7qomNpxKzvqrVP8DzG7ydh8jaKPmv1MfF8tpYRy3AhmN3/GYwCnPqT75YYrhcrWcVdax5gmQVqHkFtIQkRSCIftzPLlpMGKha/YBV8c1fvC4LD0NPh/Ynv0gtECgYEAyOZg95/kte0jpgUEgwuMrzkhY/AaUJULFuR5MkyvReEbtSBQwV5tx60+T95PHNiFooWWVXiLMsAgyI2IbkxVR1Pzdri3gWK5CTfqb7kLuaj/B7SGvBa2Sxo478KS5K8tBBBWkITqo+wLC0mn3uZi1dyMWO1zopTA+KtEGF2dtGQ=";
         let private_key =
             AsymmetricCryptoKey::from_der(&STANDARD.decode(private_key).unwrap()).unwrap();
-        let decrypted: Vec<u8> = encrypted.decapsulate_key_unsigned(&private_key).unwrap();
+        let decrypted: SymmetricCryptoKey =
+            encrypted.decapsulate_key_unsigned(&private_key).unwrap();
 
         let key_store = client.internal.get_key_store();
         let ctx = key_store.context();
@@ -746,7 +747,7 @@ mod tests {
             .dangerous_get_symmetric_key(SymmetricKeyId::User)
             .unwrap();
 
-        assert_eq!(&decrypted, &expected.to_encoded())
+        assert_eq!(decrypted, *expected);
     }
 
     #[test]

crates/bitwarden-core/src/mobile/crypto.rs

@@ -8,6 +8,7 @@ version.workspace = true
 authors.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+readme.workspace = true
 homepage.workspace = true
 repository.workspace = true
 license-file.workspace = true
@@ -43,7 +44,6 @@ rayon = ">=1.8.1, <2.0"
 rsa = ">=0.9.2, <0.10"
 schemars = { workspace = true }
 serde = { workspace = true }
-serde_bytes = "0.11.15"
 sha1 = ">=0.10.5, <0.11"
 sha2 = ">=0.10.6, <0.11"
 subtle = ">=2.5.0, <3.0"

crates/bitwarden-crypto/Cargo.toml

@@ -1,6 +1,60 @@
-# Bitwarden Crypto
+# Bitwarden Cryptographic primitives
 
-This is an internal crate for the Bitwarden SDK do not depend on this directly and use the
-[`bitwarden`](https://crates.io/crates/bitwarden) crate instead.
+This crate contains the cryptographic primitives used throughout the SDK. The general aspiration is
+for this crate to handle all the difficult cryptographic operations and expose higher level concepts
+to the rest of the SDK.
 
-This crate does not follow semantic versioning and the public interface may change at any time.
+<div class="warning">
+Generally you should <b>not</b> find yourself needing to edit this crate! Everything written
+here requires additional care and attention to ensure that the cryptographic primitives are
+secure.
+</div>
+
+## Example:
+
+```rust
+use bitwarden_crypto::{SymmetricCryptoKey, TypedKeyEncryptable, KeyDecryptable, CryptoError};
+
+async fn example() -> Result<(), CryptoError> {
+  let key = SymmetricCryptoKey::generate();
+
+  let data = "Hello, World!".to_owned();
+  let encrypted = data.clone().encrypt_with_key(&key)?;
+  let decrypted: String = encrypted.decrypt_with_key(&key)?;
+
+  assert_eq!(data, decrypted);
+  Ok(())
+}
+```
+
+## Development considerations
+
+This crate is expected to provide long term support for cryptographic operations. To that end, the
+following considerations should be taken into account when making changes to this crate:
+
+- Limit public interfaces to the bare minimum.
+- Breaking changes should be rare and well communicated.
+- Serializable representation of keys and encrypted data must be supported indefinitely as we have
+  no way to update all data.
+
+### Conventions:
+
+- Pure Functions that deterministically "derive" keys from input are prefixed with `derive_`.
+- Functions that generate non deterministically keys are prefixed with `make_`.
+
+### Differences from `clients`
+
+There are some noteworthy differences compared to the other Bitwarden
+[clients](https://github.com/bitwarden/clients). These changes are made in an effort to introduce
+conventions in how we name things, improve best practices and abstracting away internal complexity.
+
+- `CryptoService.makeSendKey` & `AccessService.createAccessToken` are replaced by the generic
+  `derive_shareable_key`
+- MasterKey operations such as `makeMasterKey` and `hashMasterKey` are moved to the MasterKey
+  struct.
+
+## Crate features
+
+- `no-memory-hardening` - Disables memory hardening which ensures that allocated memory is zeroed on
+  drop. This feature primarily exists in case you do not want to use the standard allocator, and we
+  advise to still define a `global_allocator` using the [`ZeroizingAllocator`].

crates/bitwarden-crypto/README.md

@@ -1,15 +1,16 @@
-/**
- * This file contains private-use constants for COSE encoded key types and algorithms.
- */
-use coset::iana;
+//! This file contains private-use constants for COSE encoded key types and algorithms.
+//! Standardized values from <https://www.iana.org/assignments/cose/cose.xhtml> should always be preferred
+//! unless there is a specific reason to use a private-use value.
+
 use serde::{Deserialize, Serialize};
 #[cfg(feature = "wasm")]
 use tsify_next::Tsify;
 
+// XChaCha20 <https://datatracker.ietf.org/doc/html/draft-irtf-cfrg-xchacha-03> is used over ChaCha20
+// to be able to randomly generate nonces, and to not have to worry about key wearout. Since
+// the draft was never published as an RFC, we use a private-use value for the algorithm.
 pub(crate) const XCHACHA20_POLY1305: i64 = -70000;
 
-pub(crate) const SYMMETRIC_KEY: i64 = iana::SymmetricKeyParameter::K as i64;
-
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
 #[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
 pub enum ContentFormat {