Field-level encryption

class couchbase.encryption.CryptoManager

The interface field-level encryption is built on.

A crypto manager encrypts and decrypts field values, and mangles the names of encrypted fields so a reader can tell them apart.

abstract decrypt(encrypted: dict[str, Any]) → bytes

Decrypt a value with the decrypter its alg key names.

Parameters:

encrypted (dict[str, Any]) – An encrypted value, which must have an alg key.

Returns:

The decrypted value.

Return type:

bytes

Raises:

DecryptionFailureException – If the value could not be decrypted.

abstract demangle(field_name: str) → str

Demangles provided JSON field name.

Parameters:

field_name (str) – JSON field name to be demangled.

Returns:

The demangled field name.

Return type:

str

abstract encrypt(plaintext: str | bytes | bytearray, encrypter_alias: str | None = None) → dict[str, Any]

Encrypt a value with the encrypter registered under an alias.

Parameters:
  • plaintext (str | bytes | bytearray) – The value to encrypt.

  • encrypter_alias (str, optional) – The alias of the encrypter to use. Defaults to None, which uses the default encrypter.

Returns:

An EncryptionResult as a dict.

Return type:

dict[str, Any]

Raises:

EncryptionFailureException – If the value could not be encrypted.

abstract is_mangled(field_name: str) → bool

Checks if provided JSON field name has been mangled.

Parameters:

field_name (str) – JSON field name to check if mangled.

Returns:

True if the field is mangled, False otherwise.

Return type:

bool

abstract mangle(field_name: str) → str

Mangles provided JSON field name.

Parameters:

field_name (str) – JSON field name to be mangled.

Returns:

The mangled field name.

Return type:

str

class couchbase.encryption.Decrypter(keyring: Keyring, alg: str | None = None)

The interface a decrypter for one algorithm implements.

Parameters:
  • keyring (Keyring) – Where the decrypter finds its keys.

  • alg (str, optional) – The name of the algorithm the decrypter handles.

algorithm() → str | None

Get the name of the algorithm the decrypter handles.

Returns:

The name of the algorithm, or None if none was given.

Return type:

str | None

abstract decrypt(encrypted: EncryptionResult) → bytes

Decrypt an encrypted value.

The decrypter’s algorithm should match the value’s alg.

Parameters:

encrypted (EncryptionResult) – The value to decrypt.

Returns:

The decrypted value.

Return type:

bytes

Raises:
property keyring: Keyring

Where the decrypter finds its keys.

class couchbase.encryption.Encrypter(keyring: Keyring, key: str)

The interface an encrypter for one algorithm and key implements.

Parameters:
  • keyring (Keyring) – Where the encrypter finds its key.

  • key (str) – The ID of the key it encrypts with.

abstract encrypt(plaintext: str | bytes | bytearray) → EncryptionResult

Encrypt a value.

Parameters:

plaintext (str | bytes | bytearray) – The value to encrypt.

Returns:

The ciphertext and everything needed to decrypt it.

Return type:

EncryptionResult

Raises:

InvalidCryptoKeyException – If the encrypter’s key is not valid for its algorithm.

property key: str

The ID of the key the encrypter encrypts with.

property keyring: Keyring

Where the encrypter finds its key.

class couchbase.encryption.EncryptionResult(alg: str = '', kid: str | None = None, ciphertext: str | None = None, **kwargs: Any)

An encrypted value and what is needed to decrypt it, stored in place of the plain field.

Parameters:
  • alg (str) – The name of the algorithm that encrypted the value.

  • kid (str, optional) – The ID of the key that encrypted it.

  • ciphertext (str, optional) – The encrypted value, base64 encoded. A value that is not valid base64 is left out.

  • **kwargs – Any other entries the algorithm needs, stored as given.

Raises:

InvalidArgumentException – If alg is empty.

algorithm() → str

Get the name of the algorithm that encrypted the value.

Returns:

The alg entry.

Return type:

str

asdict() → dict

Get every entry.

Returns:

The entries, as stored in the document.

Return type:

dict

get(key: str) → Any

Get an entry.

Parameters:

key (str) – The entry’s name.

Returns:

The entry’s value.

Return type:

Any

Raises:

CryptoKeyNotFoundException – If the entry is missing or empty.

get_with_base64_decode(key: str) → bytes

Get an entry, base64 decoded.

Parameters:

key (str) – The entry’s name.

Returns:

The decoded value.

Return type:

bytes

Raises:

CryptoKeyNotFoundException – If the entry is missing or empty.

classmethod new_encryption_result_from_dict(values: dict[str, Any]) → EncryptionResult

Create an encrypted value from its dict form.

Parameters:

values (dict[str, Any]) – The entries, which must include alg.

Returns:

The encrypted value.

Return type:

EncryptionResult

put(key: str, val: Any) → None

Set an entry.

Parameters:
  • key (str) – The entry’s name.

  • val (Any) – Its value.

put_and_base64_encode(key: str, val: bytes) → None

Set an entry to bytes, base64 encoded.

Parameters:
  • key (str) – The entry’s name.

  • val (bytes) – The bytes to encode.

Raises:

ValueError – If val is not bytes.

class couchbase.encryption.Key(id: str, bytes_: bytes | bytearray)

An encryption key.

Parameters:
  • id (str) – The key’s ID, which an encrypted value records.

  • bytes (bytes | bytearray) – The key itself. The repr hides it.

property bytes: bytes

The key itself.

property id: str

The key’s ID, which an encrypted value records.

class couchbase.encryption.Keyring

The interface a store of encryption keys implements.

abstract get_key(key_id: str) → Key

Get a key by its ID.

Parameters:

key_id (str) – The key’s ID.

Returns:

The key.

Return type:

Key

Raises:

CryptoKeyNotFoundException – If the keyring has no key with that ID.