Cryptography API Reference

This page documents the cryptographic functions and classes used by BWS SDK.

Encrypted Values

bws_sdk.crypto.EncryptedValue(algo, iv, data, mac)

Represents an encrypted value with authentication in Bitwarden's format.

This class handles encrypted data according to Bitwarden's authenticated encryption protocol, which includes the algorithm identifier, initialization vector (IV), encrypted data, and message authentication code (MAC).

Attributes:

Name	Type	Description
iv	bytes	16-byte initialization vector
data	bytes	The encrypted data payload
mac	bytes	32-byte message authentication code
algo	AlgoEnum	The encryption algorithm used

The encrypted value format follows Bitwarden's standard: - Algorithm identifier (optional prefix) - Base64-encoded IV, data, and MAC separated by "|" - Format: "algorithm.iv|data|mac" or "iv|data|mac"

Initialize an EncryptedValue with cryptographic components.

Parameters:

Name	Type	Description	Default
algo	AlgoEnum	The encryption algorithm used	required
iv	bytes	16-byte initialization vector	required
data	bytes	The encrypted data payload	required
mac	bytes	32-byte message authentication code	required

Raises:

Type	Description
ValueError	If any component has invalid length or type

decode(encoded_data) classmethod

Decode an encrypted data string into its components.

Parses a Bitwarden encrypted string format and extracts the algorithm, IV, data, and MAC components. Handles both formats with and without algorithm prefixes.

Parameters:

Name	Type	Description	Default
encoded_data	str	Encrypted string in Bitwarden format	required

Returns:

Type	Description
tuple[AlgoEnum, str, str, str]	tuple[AlgoEnum, str, str, str]: Tuple containing (algorithm, iv, data, mac)

Raises:

Type	Description
ValueError	If the encrypted data format is invalid

Note

Supports two formats: - With algorithm: "algorithm.iv|data|mac" - Without algorithm: "iv|data|mac" (defaults to AES128)

decode_internal(data) staticmethod

Parse the internal format of encrypted data.

Splits encrypted data string into its three components: IV, data, and MAC.

Parameters:

Name	Type	Description	Default
data	str	Encrypted data string in format "iv|data|mac"	required

Returns:

Type	Description
tuple[str, str, str]	tuple[str, str, str]: A tuple containing (iv, data, mac) as base64 strings

Raises:

Type	Description
ValueError	If the data format is invalid (not exactly 3 parts)

decrypt(key)

Decrypt the encrypted value with authentication verification.

Performs authenticated decryption by first verifying the MAC, then decrypting the data using the appropriate algorithm.

Parameters:

Name	Type	Description	Default
key	SymmetricCryptoKey	The symmetric key containing both encryption and MAC components	required

Returns:

Name	Type	Description
bytes	bytes	The decrypted plaintext data

Raises:

Type	Description
HmacError	If MAC verification fails (indicates tampering or wrong key)
ValueError	If decryption fails or data is corrupted
InvalidEncryptionKeyError	If the key is invalid for the algorithm

Note

This method ensures authenticated encryption by verifying the MAC before performing decryption, preventing tampering attacks.

encrypt_aes(key, padded_data, iv) staticmethod

Encrypt data using AES-CBC with PKCS7 padding.

Parameters:

Name	Type	Description	Default
key	bytes	The encryption key for AES	required
padded_data	bytes	The plaintext data to encrypt	required
iv	bytes	The initialization vector for AES	required

Returns:

Name	Type	Description
bytes	bytes	Encrypted data

Note

You must ensure that padded_data is already padded to the AES block size.

from_data(key, data) classmethod

Create an EncryptedValue from raw encrypted data string.

This method decodes the encrypted data string and verifies the MAC using the provided symmetric key. It raises an error if MAC verification fails.

Parameters:

Name	Type	Description	Default
key	SymmetricCryptoKey	The symmetric key for MAC verification	required
data	str	Encrypted data string in Bitwarden format	required

Returns: EncryptedValue: New EncryptedValue instance with verified components

from_str(encrypted_str) classmethod

Create an EncryptedValue from a Bitwarden encrypted string.

Parses a complete Bitwarden encrypted string and creates an EncryptedValue instance with all components decoded from base64.

Parameters:

Name	Type	Description	Default
encrypted_str	str	Complete encrypted string in Bitwarden format	required

Returns:

Name	Type	Description
EncryptedValue	EncryptedValue	New instance with decoded cryptographic components

Raises:

Type	Description
InvalidEncryptedFormat	If the string format is invalid or decoding fails
ValueError	If base64 decoding fails for any component

generate_mac(key, iv, encrypted_data) staticmethod

Generate a message authentication code for the encrypted data.

Creates an HMAC-SHA256 of the IV and encrypted data using the provided key. This MAC is used to verify the integrity and authenticity of the encrypted data.

Parameters:

Name	Type	Description	Default
key	bytes	The MAC key for HMAC generation	required

Returns:

Name	Type	Description
bytes	bytes	32-byte HMAC-SHA256 digest

Note

The MAC is computed over the concatenation of IV + encrypted_data.

to_str()

Convert the EncryptedValue to a Bitwarden encrypted string.

Constructs the encrypted string format used by Bitwarden, including the algorithm identifier, base64-encoded IV, data, and MAC.

Returns:

Name	Type	Description
str	str	Encrypted string in Bitwarden format

Symmetric Keys

bws_sdk.crypto.SymmetricCryptoKey(key)

Symmetric encryption key with separate encryption and MAC components.

This class handles symmetric encryption keys used in Bitwarden's cryptographic protocol. It automatically splits provided keys into encryption and MAC components and provides methods for key derivation.

Attributes:

Name	Type	Description
key	bytes	The encryption key component
mac_key	bytes	The MAC (Message Authentication Code) key component

Note

The class supports two key sizes: - 64 bytes: key[:32] for encryption, key[32:64] for MAC - 32 bytes: key[:16] for encryption, key[16:32] for MAC

Initialize a SymmetricCryptoKey from raw key bytes.

Parameters:

Name	Type	Description	Default
key	bytes	Raw key material (32 or 64 bytes)	required

Raises:

Type	Description
InvalidEncryptionKeyError	If key length is not 32 or 64 bytes

__eq__(other)

Check equality between SymmetricCryptoKey instances.

Parameters:

Name	Type	Description	Default
other	object	Another object to compare with	required

Returns:

Name	Type	Description
bool	bool	True if both keys have identical key and mac_key components

Raises:

Type	Description
ValueError	If the other object is not a SymmetricCryptoKey instance

derive_symkey(secret, name, info=None) classmethod

Derive a symmetric key using HMAC and HKDF-Expand.

This function derives a shareable key using HMAC and HKDF-Expand from a secret and name, matching the Rust implementation behavior used by Bitwarden clients.

Parameters:

Name	Type	Description	Default
secret	bytes	A 16-byte secret for key derivation	required
name	str	The key name used in the derivation process	required
info	str | None	Optional info parameter for HKDF	None

Returns:

Name	Type	Description
SymmetricCryptoKey	SymmetricCryptoKey	A new SymmetricCryptoKey instance with derived key material

Raises:

Type	Description
ValueError	If the secret is not exactly 16 bytes
InvalidEncryptionKeyError	If key derivation fails

Note

The derivation process: 1. Creates HMAC with "bitwarden-{name}" as the key 2. Uses the secret as the message 3. Applies HKDF-Expand to get 64 bytes of key material

from_encryption_key(encryption_key) classmethod

Create a SymmetricCryptoKey from a BWS access token encryption key.

This method derives a symmetric key specifically for BWS access token purposes using the standard Bitwarden key derivation process.

Parameters:

Name	Type	Description	Default
encryption_key	bytes	A 16-byte encryption key from a BWS access token	required

Returns:

Name	Type	Description
SymmetricCryptoKey	SymmetricCryptoKey	A derived key suitable for BWS operations

Raises:

Type	Description
ValueError	If the encryption_key is not exactly 16 bytes
InvalidEncryptionKeyError	If key derivation fails

to_base64()

Convert the key to a base64-encoded string.

Concatenates the encryption key and MAC key, then base64-encodes the result.

Returns:

Name	Type	Description
str	str	Base64-encoded representation of the combined key material

Utility Functions

Cryptographic utilities for the BWS SDK.

This module provides cryptographic functionality for the BWS SDK, including symmetric encryption/decryption, key derivation, and encrypted value handling. It implements the same cryptographic protocols used by the Bitwarden client applications.

Classes:

Name	Description
SymmetricCryptoKey	Handles symmetric encryption keys with MAC keys
AlgoEnum	Enumeration of supported encryption algorithms
EncryptedValue	Represents and handles encrypted data with metadata

AlgoEnum

Bases: Enum

Enumeration of supported encryption algorithms.

This enum defines the encryption algorithms supported by Bitwarden's cryptographic protocol. Each algorithm is identified by a string value that corresponds to the algorithm identifier used in encrypted data.

Values

AES128: AES-128 encryption algorithm (identifier: "1") AES256: AES-256 encryption algorithm (identifier: "2")

Note

Currently, the BWS SDK primarily uses AES-128 for compatibility with existing Bitwarden client implementations.