Crate bitwarden_crypto

Source
Expand description

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

§Pinned heap data

This crate uses a Pin<Box<>> strategy to ensure data is stored on the heap and not moved around. This pattern is commonly used for GenericArray since it’s equivalent to [u8; N] which is a Copy type placed on the stack. To keep the compiler from making stack copies when moving this struct around, we use a Box to keep the values on the heap. We also pin the box to make sure that the contents can’t be pulled out of the box and moved.

Modules§

Macros§

  • key_ids
    Just a small derive_like macro that can be used to generate the key identifier enums. Example usage:

Structs§

  • Aes256CbcHmacKey
    Aes256CbcHmacKey is a symmetric encryption key consisting of two 256-bit keys, one for encryption and one for MAC
  • Aes256CbcKey
    Aes256CbcKey is a symmetric encryption key, consisting of one 256-bit key, used to decrypt legacy type 0 encstrings. The data is not autenticated so this should be used with caution, and removed where possible.
  • 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
  • KeyStore
    An in-memory key store that provides a safe and secure way to store keys and use them for encryption/decryption operations. The store API is designed to work only on key identifiers (KeyId). These identifiers are user-defined types that contain no key material, which means the API users don’t have to worry about accidentally leaking keys.
  • KeyStoreContext
    The context of a crypto operation using super::KeyStore
  • PinKey
    Pin Key.
  • RsaKeyPair
    RSA Key Pair
  • TrustDeviceResponse
  • UserKey
    User Key
  • ZeroizingAllocator
    Allocator wrapper that zeros on free

Enums§

Constants§

Traits§

Functions§