Crate bitwarden_crypto 

Bitwarden Cryptographic primitives

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.

Generally you should not find yourself needing to edit this crate! Everything written here requires additional care and attention to ensure that the cryptographic primitives are secure.

Example:

use bitwarden_crypto::{SymmetricCryptoKey, KeyEncryptable, KeyDecryptable, CryptoError};

async fn example() -> Result<(), CryptoError> {
  let key = SymmetricCryptoKey::generate(rand::thread_rng());

  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. 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.

Structs

AsymmetricCryptoKey

An asymmetric encryption key. Contains both the public and private key. Can be used to both encrypt and decrypt AsymmetricEncString.

AsymmetricPublicCryptoKey

An asymmetric public encryption key. Can only encrypt AsymmetricEncString, usually accompanied by a AsymmetricCryptoKey

DeviceKey

Device Key

MasterKey

Master Key.

PinKey

Pin Key.

RsaKeyPair

RSA Key Pair

SymmetricCryptoKey

A symmetric encryption key. Used to encrypt and decrypt EncString

TrustDeviceResponse

UserKey

User Key

ZeroizingAllocator

Custom allocator that zeroizes memory before deallocating it

Enums

AsymmetricEncString

Encrypted string primitive

CryptoError

EncString

Encrypted string primitive

HashPurpose

Kdf

Key Derivation Function for Bitwarden Account

Constants

EFF_LONG_WORD_LIST

EFF’s Long Wordlist from https://www.eff.org/dice

Traits

AsymmetricEncryptable

Trait to allow both AsymmetricCryptoKey and AsymmetricPublicCryptoKey to be used to encrypt AsymmetricEncString.

CryptoKey

KeyContainer

KeyDecryptable

KeyEncryptable

LocateKey

Functions

default_argon2_iterations

Default Argon2 iterations

default_argon2_memory

Default Argon2 memory

default_argon2_parallelism

Default Argon2 parallelism

default_pbkdf2_iterations

Default PBKDF2 iterations

derive_shareable_key

Derive a shareable key using hkdf from secret and name.

fingerprint

Computes a fingerprint of the given fingerprint_material using the given public_key.

generate_random_alphanumeric

Generate a random alphanumeric string of a given length

generate_random_bytes

Generate random bytes that are cryptographically secure

pbkdf2

Derive pbkdf2 of a given password and salt