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.

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
• Sensitive
  Wrapper for sensitive values which makes a best effort to enforce zeroization of the inner value on drop. The inner value exposes a Sensitive::expose method which returns a reference to the inner value. Care must be taken to avoid accidentally exposing the inner value through copying or cloning.
• SymmetricCryptoKey
  A symmetric encryption key. Used to encrypt and decrypt EncString
• TrustDeviceResponse
• UserKey
  User Key

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
• Decryptable
  Deprecated: please use LocateKey and KeyDecryptable instead
• Encryptable
  Deprecated: please use LocateKey and KeyDecryptable instead
• 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_bytes
  Generate random bytes that are cryptographically secure
• pbkdf2

Type Aliases

• Decrypted
  Type alias for a Sensitive value to denote decrypted data.
• DecryptedString
• DecryptedVec
• SensitiveString
  Important: This type does not protect against reallocations made by the String. This means that if you insert any characters past the capacity, the data will be copied to a new allocation and the old allocation will not be zeroized. To avoid this, use String::with_capacity to preallocate the capacity you need.
• SensitiveVec
  Important: This type does not protect against reallocations made by the Vec. This means that if you insert any elements past the capacity, the data will be copied to a new allocation and the old allocation will not be zeroized. To avoid this, use Vec::with_capacity to preallocate the capacity you need.