Skip to content

Commit 0b95464

Browse files
quextencoroiu
andauthored
Add docs to purecrypto functions (#268)
## 🎟️ Tracking <!-- Paste the link to the Jira or GitHub issue or otherwise describe / point to where this change is coming from. --> ## 📔 Objective Adds docs to most functions on purecrypto, and renames generate to make to be in-line with the crate standard. ## ⏰ Reminders before review - Contributor guidelines followed - All formatters and local linters executed and passed - Written new unit and / or integration tests where applicable - Protected functional changes with optionality (feature flags) - Used internationalization (i18n) for all UI strings - CI builds passed - Communicated to DevOps any deployment requirements - Updated any necessary documentation (Confluence, contributing docs) or informed the documentation team ## 🦮 Reviewer guidelines <!-- Suggested interactions but feel free to use (or not) as you desire! --> - 👍 (`:+1:`) or similar for great changes - 📝 (`:memo:`) or ℹ️ (`:information_source:`) for notes or general info - ❓ (`:question:`) for questions - 🤔 (`:thinking:`) or 💭 (`:thought_balloon:`) for more open inquiry that's not quite a confirmed issue and could potentially benefit from discussion - 🎨 (`:art:`) for suggestions / improvements - ❌ (`:x:`) or ⚠️ (`:warning:`) for more significant problems or concerns needing attention - 🌱 (`:seedling:`) or ♻️ (`:recycle:`) for future improvements or indications of technical debt - ⛏ (`:pick:`) for minor or nitpick changes --------- Co-authored-by: Andreas Coroiu <[email protected]>
1 parent d5efd04 commit 0b95464

File tree

2 files changed

+35
-14
lines changed

2 files changed

+35
-14
lines changed

.vscode/settings.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@
88
"cloc",
99
"COSE",
1010
"dealloc",
11+
"Decapsulates",
12+
"decapsulation",
1113
"decryptable",
1214
"dylib",
1315
"encryptable",
@@ -20,7 +22,9 @@
2022
"repr",
2123
"reprompt",
2224
"reqwest",
25+
"rotateable",
2326
"schemars",
27+
"spki",
2428
"totp",
2529
"uniffi",
2630
"wordlist",

crates/bitwarden-wasm-internal/src/pure_crypto.rs

Lines changed: 31 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,6 @@ impl PureCrypto {
7575
.to_buffer()
7676
}
7777

78-
// Userkey encryption with password
7978
pub fn decrypt_user_key_with_master_password(
8079
encrypted_user_key: String,
8180
master_password: String,
@@ -102,16 +101,16 @@ impl PureCrypto {
102101
Ok(result.to_string())
103102
}
104103

105-
// Generate userkey
106-
pub fn generate_user_key_aes256_cbc_hmac() -> Vec<u8> {
104+
pub fn make_user_key_aes256_cbc_hmac() -> Vec<u8> {
107105
SymmetricCryptoKey::make_aes256_cbc_hmac_key().to_encoded()
108106
}
109107

110-
pub fn generate_user_key_xchacha20_poly1305() -> Vec<u8> {
108+
pub fn make_user_key_xchacha20_poly1305() -> Vec<u8> {
111109
SymmetricCryptoKey::make_xchacha20_poly1305_key().to_encoded()
112110
}
113111

114-
// Key wrap
112+
/// Wraps (encrypts) a symmetric key using a symmetric wrapping key, returning the wrapped key
113+
/// as an EncString.
115114
pub fn wrap_symmetric_key(
116115
key_to_be_wrapped: Vec<u8>,
117116
wrapping_key: Vec<u8>,
@@ -137,6 +136,8 @@ impl PureCrypto {
137136
.to_string())
138137
}
139138

139+
/// Unwraps (decrypts) a wrapped symmetric key using a symmetric wrapping key, returning the
140+
/// unwrapped key as a serialized byte array.
140141
pub fn unwrap_symmetric_key(
141142
wrapped_key: String,
142143
wrapping_key: Vec<u8>,
@@ -159,6 +160,11 @@ impl PureCrypto {
159160
Ok(key.to_encoded())
160161
}
161162

163+
/// Wraps (encrypts) an SPKI DER encoded encapsulation (public) key using a symmetric wrapping
164+
/// key. Note: Usually, a public key is - by definition - public, so this should not be
165+
/// used. The specific use-case for this function is to enable rotateable key sets, where
166+
/// the "public key" is not public, with the intent of preventing the server from being able
167+
/// to overwrite the user key unlocked by the rotateable keyset.
162168
pub fn wrap_encapsulation_key(
163169
encapsulation_key: Vec<u8>,
164170
wrapping_key: Vec<u8>,
@@ -176,6 +182,8 @@ impl PureCrypto {
176182
.to_string())
177183
}
178184

185+
/// Unwraps (decrypts) a wrapped SPKI DER encoded encapsulation (public) key using a symmetric
186+
/// wrapping key.
179187
pub fn unwrap_encapsulation_key(
180188
wrapped_key: String,
181189
wrapping_key: Vec<u8>,
@@ -192,6 +200,8 @@ impl PureCrypto {
192200
.decrypt(&mut context, SymmetricKeyId::Local("wrapping_key"))
193201
}
194202

203+
/// Wraps (encrypts) a PKCS8 DER encoded decapsulation (private) key using a symmetric wrapping
204+
/// key,
195205
pub fn wrap_decapsulation_key(
196206
decapsulation_key: Vec<u8>,
197207
wrapping_key: Vec<u8>,
@@ -209,6 +219,8 @@ impl PureCrypto {
209219
.to_string())
210220
}
211221

222+
/// Unwraps (decrypts) a wrapped PKCS8 DER encoded decapsulation (private) key using a symmetric
223+
/// wrapping key.
212224
pub fn unwrap_decapsulation_key(
213225
wrapped_key: String,
214226
wrapping_key: Vec<u8>,
@@ -225,7 +237,9 @@ impl PureCrypto {
225237
.decrypt(&mut context, SymmetricKeyId::Local("wrapping_key"))
226238
}
227239

228-
// Key encapsulation
240+
/// Encapsulates (encrypts) a symmetric key using an asymmetric encapsulation key (public key)
241+
/// in SPKI format, returning the encapsulated key as a string. Note: This is unsigned, so
242+
/// the sender's authenticity cannot be verified by the recipient.
229243
pub fn encapsulate_key_unsigned(
230244
shared_key: Vec<u8>,
231245
encapsulation_key: Vec<u8>,
@@ -238,6 +252,9 @@ impl PureCrypto {
238252
.to_string())
239253
}
240254

255+
/// Decapsulates (decrypts) a symmetric key using an decapsulation key (private key) in PKCS8
256+
/// DER format. Note: This is unsigned, so the sender's authenticity cannot be verified by the
257+
/// recipient.
241258
pub fn decapsulate_key_unsigned(
242259
encapsulated_key: String,
243260
decapsulation_key: Vec<u8>,
@@ -364,13 +381,13 @@ DnqOsltgPomWZ7xVfMkm9niL2OA=
364381

365382
#[test]
366383
fn test_make_aes256_cbc_hmac_key() {
367-
let key = PureCrypto::generate_user_key_aes256_cbc_hmac();
384+
let key = PureCrypto::make_user_key_aes256_cbc_hmac();
368385
assert_eq!(key.len(), 64);
369386
}
370387

371388
#[test]
372389
fn test_make_xchacha20_poly1305_key() {
373-
let key = PureCrypto::generate_user_key_xchacha20_poly1305();
390+
let key = PureCrypto::make_user_key_xchacha20_poly1305();
374391
assert!(key.len() > 64);
375392
}
376393

@@ -381,7 +398,7 @@ DnqOsltgPomWZ7xVfMkm9niL2OA=
381398
let kdf = Kdf::PBKDF2 {
382399
iterations: NonZero::try_from(600000).unwrap(),
383400
};
384-
let user_key = PureCrypto::generate_user_key_aes256_cbc_hmac();
401+
let user_key = PureCrypto::make_user_key_aes256_cbc_hmac();
385402
let encrypted_user_key = PureCrypto::encrypt_user_key_with_master_password(
386403
user_key.clone(),
387404
master_password.to_string(),
@@ -401,8 +418,8 @@ DnqOsltgPomWZ7xVfMkm9niL2OA=
401418

402419
#[test]
403420
fn test_wrap_unwrap_symmetric_key() {
404-
let key_to_be_wrapped = PureCrypto::generate_user_key_aes256_cbc_hmac();
405-
let wrapping_key = PureCrypto::generate_user_key_aes256_cbc_hmac();
421+
let key_to_be_wrapped = PureCrypto::make_user_key_aes256_cbc_hmac();
422+
let wrapping_key = PureCrypto::make_user_key_aes256_cbc_hmac();
406423
let wrapped_key =
407424
PureCrypto::wrap_symmetric_key(key_to_be_wrapped.clone(), wrapping_key.clone())
408425
.unwrap();
@@ -414,7 +431,7 @@ DnqOsltgPomWZ7xVfMkm9niL2OA=
414431
fn test_wrap_encapsulation_key() {
415432
let decapsulation_key = AsymmetricCryptoKey::from_pem(PEM_KEY).unwrap();
416433
let encapsulation_key = decapsulation_key.to_public_der().unwrap();
417-
let wrapping_key = PureCrypto::generate_user_key_aes256_cbc_hmac();
434+
let wrapping_key = PureCrypto::make_user_key_aes256_cbc_hmac();
418435
let wrapped_key =
419436
PureCrypto::wrap_encapsulation_key(encapsulation_key.clone(), wrapping_key.clone())
420437
.unwrap();
@@ -426,7 +443,7 @@ DnqOsltgPomWZ7xVfMkm9niL2OA=
426443
#[test]
427444
fn test_wrap_decapsulation_key() {
428445
let decapsulation_key = AsymmetricCryptoKey::from_pem(PEM_KEY).unwrap();
429-
let wrapping_key = PureCrypto::generate_user_key_aes256_cbc_hmac();
446+
let wrapping_key = PureCrypto::make_user_key_aes256_cbc_hmac();
430447
let wrapped_key = PureCrypto::wrap_decapsulation_key(
431448
decapsulation_key.to_der().unwrap(),
432449
wrapping_key.clone(),
@@ -439,7 +456,7 @@ DnqOsltgPomWZ7xVfMkm9niL2OA=
439456

440457
#[test]
441458
fn test_encapsulate_key_unsigned() {
442-
let shared_key = PureCrypto::generate_user_key_aes256_cbc_hmac();
459+
let shared_key = PureCrypto::make_user_key_aes256_cbc_hmac();
443460
let decapsulation_key = AsymmetricCryptoKey::from_pem(PEM_KEY).unwrap();
444461
let encapsulation_key = decapsulation_key.to_public_der().unwrap();
445462
let encapsulated_key =

0 commit comments

Comments
 (0)