Module safe 

Bitwarden-crypto safe module

The safe module provides high-level cryptographic tools for building secure protocols and features. When developing new features, use this module first before considering lower-level primitives from other parts of bitwarden-crypto.

Usage examples of all safe APIs are provided in the crate’s examples directory.

Password-protected key envelope

Use the password protected key envelope to protect a symmetric key with a password. Examples include:

• locking a vault with a PIN/Password
• protecting exports with a password

Internally, the module uses a KDF to protect against brute-forcing, but it does not expose this to the consumer. The consumer only provides a password and key.

Data envelope

Use the data envelope to protect a struct (document) of data. Examples include:

• protecting a vault item
• protecting metadata (name, etc.) of a collection
• protecting a vault report

The serialization of the data and the creation of a content encryption key is handled internally. Calling the API with a decrypted struct, the content encryption key ID and the encrypted data are returned.

Guidelines for developers

When adding a new primitive there are a few considerations to make:

• Does this serve a new purpose that is not already fulfilled better otherwise
  • Replacing insecure functionality is a valid reason here
• Is it easy to use for developers that are not cryptography experts
• Does the API prevent (accidental) mis-use by developers that are not cryptography experts
  • Avoid exposing many settings/configurations to API consumers
• Is the format extensible and cover the use-case adequately
• Does the new object have adequate security analysis performed?
• Do we have cryptographic modularity?
  • That is, can we switch to new primitives / algorithms easily?

Further, each new object should be validated against existing known attack classes.

Namespaces

An important one here is covered by namespacing. When items are signed / encrypted under the same key, these may be swapped. If the context or type of these objects is different, the consuming code may misinterpret these, leading to security vulnerabilities. Analysis here is complex. Therefore, a simpler approach is strong cryptographic namespace separation, which prevents this by adding metadata about where an object appropriately can be used.

The namespace partitioning happens in two layers, the object layer and the content layer. The authenticated data of each safe object contains a object namespace key value pair, which allows the decrypting code to correctly identify whether an object that is being decrypted is actually the correct object type (e.g. a DataEnvelope). For each object type, there is then another layer of partitioning, since these objects can be used in many places. For instance, a DataEnvelope may have the partitioning vault item, account settings, and so on. This content namespace is also stored in the authenticated data of the safe object.

Modules

data_envelope 🔒

helpers 🔒

password_protected_key_envelope 🔒

Password protected key envelope is a cryptographic building block that allows sealing a symmetric key with a low entropy secret (password, PIN, etc.).

symmetric_key_envelope 🔒

Wrapped symmetric key envelope for sealing a symmetric key with another symmetric key.

Macros

generate_versioned_sealable

Generates a versioned enum that implements SealableData.

Structs

DataEnvelope

DataEnvelope allows sealing structs entire structs to encrypted blobs.

PasswordProtectedKeyEnvelope

A password-protected key envelope can seal a symmetric key, and protect it with a password. It does so by using a Key Derivation Function (KDF), to increase the difficulty of brute-forcing the password.

SymmetricKeyEnvelope

A symmetric key protected by another symmetric key

Enums

DataEnvelopeError

Error type for DataEnvelope operations.

DataEnvelopeNamespace

Data envelopes are domain-separated within bitwarden, to prevent cross protocol attacks.

PasswordProtectedKeyEnvelopeError

Errors that can occur when sealing or unsealing a key with the PasswordProtectedKeyEnvelope.

PasswordProtectedKeyEnvelopeNamespace

The content-layer separation namespace for password protected key envelopes.

SymmetricKeyEnvelopeError

Errors that can occur when sealing or unsealing a symmetric key with envelope operations.

SymmetricKeyEnvelopeNamespace

Content namespace for the symmetric key envelope

Traits

SealableData

Marker trait for data that can be sealed in a DataEnvelope.

SealableVersionedData

Marker trait for data that can be sealed in a DataEnvelope.