2. API Reference

This section describes the API of the easy-vault package. The API is kept stable using the compatibility rules defined for semantic versioning.

Any functions not described in this section are considered internal and may change incompatibly without warning.

2.1. EasyVault class

class easy_vault.EasyVault(filepath, password=None)[source]

A vault file that can be encrypted and decrypted.

An object of this class is tied to a single vault file and a single vault password.

There are no requirements for the format of the vault file. It may be a text file or a binary file (but the typical case for a vault file would be a text file, e.g. in YAML format).

There is no size limit to the vault file. However, because the complete vault file is read into memory in one chunk, this implementation is not well suited for handling huge files. It is really meant for vault files: Files that keep secrets, but not huge data.

The password may be provided or not (None). If the password is provided, it is converted to a symmetric key which is then used for encrypting and decrypting the vault file itself and for decrypting the vault file content upon access. If the password is not provided, encryption and decryption of the vault file is rejected and access to the vault file content requires that the vault file is in the decrypted state.

The encryption package used by this class is pluggable. The default implementation uses the symmetric key support from the cryptography package.

Users who whish to use a different encryption package can do so by subclassing this class and implementing the following methods to use a different encryption package:

Parameters
  • filepath (unicode string) – Path name of the vault file.

  • password (unicode string) – Password for encrypting and decrypting the vault file, or None if not provided.

Raises

TypeError – Type error in arguments or in return of pluggable encryption function.

Attributes:

filepath

Path name of the vault file.

password_provided

Indicates whether a vault password was provided.

Methods:

is_encrypted()

Test whether the vault file is encrypted by easy-vault.

encrypt()

Encrypt the vault file.

decrypt()

Decrypt the vault file.

get_bytes()

Get the decrypted content of the vault file as a Byte sequence.

get_text()

Get the decrypted content of the vault file as a Unicode string.

get_yaml()

Get the decrypted content of a YAML-formatted vault file as a YAML object.

generate_key(password)

Encryption implementation: Calculate a symmetric key from a password.

encrypt_data(clear_data, key)

Encryption implementation: Encrypt clear data with a symmetric key.

decrypt_data(encrypted_data, key)

Encryption implementation: Decrypt encrypted data with a symmetric key.

property filepath

Path name of the vault file.

Type

unicode string)

property password_provided

Indicates whether a vault password was provided.

Type

bool

is_encrypted()[source]

Test whether the vault file is encrypted by easy-vault.

This is done by checking for the unique easy-vault header in the first line of the vault file.

This method does not require a vault password to be provided.

Returns

Boolean indicating whether the vault file is encrypted by easy-vault.

Return type

bool

Raises

EasyVaultFileError – I/O error with the vault file.

encrypt()[source]

Encrypt the vault file.

The vault file must be decrypted (i.e. not encrypted by easy-vault).

This method requires a vault password to be provided.

Raises
decrypt()[source]

Decrypt the vault file.

The vault file must be encrypted by easy-vault.

This method requires a vault password to be provided.

Raises
get_bytes()[source]

Get the decrypted content of the vault file as a Byte sequence.

The vault file may be in the encrypted or decrypted state and remains unchanged.

If the vault file is in the encrypted state, the object this method is called on must have been created with a vault password.

Returns

Decrypted content of the vault file, as a Byte sequence.

Return type

byte string

Raises
get_text()[source]

Get the decrypted content of the vault file as a Unicode string.

The vault file may be in the encrypted or decrypted state and remains unchanged.

If the vault file is in the encrypted state, the object this method is called on must have been created with a vault password.

Returns

Decrypted content of the vault file, as a Unicode string.

Return type

unicode string

Raises
get_yaml()[source]

Get the decrypted content of a YAML-formatted vault file as a YAML object.

The vault file may be in the encrypted or decrypted state and remains unchanged.

If the vault file is in the encrypted state, the object this method is called on must have been created with a vault password.

Returns

Top-level object of the YAML-formatted vault file.

Return type

dict or list

Raises
static generate_key(password)[source]

Encryption implementation: Calculate a symmetric key from a password.

The key must match the requirements of the encryption package that is used in the encrypt_data() and decrypt_data() methods.

Using this method repeatedly on the same password must result in the same key.

This method can be overwritten by users to use a different encryption package. Its default implementation uses the cryptography package, and calculates the key as a 256-bit key using 10000 iterations of SHA256 on the password, using a fixed salt.

Parameters

password (unicode string) – Password for encrypting and decrypting the vault file.

Returns

The calculated key.

Return type

byte string

static encrypt_data(clear_data, key)[source]

Encryption implementation: Encrypt clear data with a symmetric key.

This method can be overwritten by users to use a different encryption package. Its default implementation uses the cryptography.fernet encryption package.

Parameters
  • clear_data (byte string) – The clear data to be encrypted.

  • key (byte string) – The symmetric key to be used for the encryption.

Returns

The encrypted data.

Return type

byte string

decrypt_data(encrypted_data, key)[source]

Encryption implementation: Decrypt encrypted data with a symmetric key.

This method can be overwritten by users to use a different encryption package. Its default implementation uses the cryptography.fernet encryption package.

Parameters
  • encrypted_data (byte string) – The encrypted data to be decrypted.

  • key (byte string) – The encryption key to be used.

Returns

The clear data.

Return type

byte string

Raises

EasyVaultDecryptError – Error decrypting the vault file.

2.2. Keyring class

class easy_vault.Keyring[source]

Access to the keyring service of the local system for storing vault passwords.

An object of this class is tied to the keyring service and can store and retrieve multiple vault passwords.

The keyring items that are created have a fixed service/app name that starts with ‘easy_vault’. There is one keyring item for each vault file.

For details on the keyring service, see section Keyring service.

Methods:

get_password(filepath)

Get the password for a vault file from the keyring service.

set_password(filepath, password)

Set the password for a vault file in the keyring service.

delete_password(filepath)

Delete the password for a vault file in the keyring service.

is_available()

Indicate whether the keyring service is available on the local system.

check_available()

Check whether the keyring service is available on the local system.

keyring_service()

Return the service/app name that is used for the keyring item.

keyring_username(filepath)

Return the user/account name that is used for the keyring item.

get_password(filepath)[source]

Get the password for a vault file from the keyring service.

If the keyring service does not store a password for the vault file, None is returned.

Parameters

filepath (unicode string) – Path name of the vault file. It will be normalized to identify the keyring item for the vault file.

Returns

Password for the vault file, or None.

Return type

unicode string

Raises
set_password(filepath, password)[source]

Set the password for a vault file in the keyring service.

Parameters
  • filepath (unicode string) – Path name of the vault file. It will be normalized to identify the keyring item for the vault file.

  • password (unicode string) – Password for the vault file.

Raises
delete_password(filepath)[source]

Delete the password for a vault file in the keyring service.

Parameters

filepath (unicode string) – Path name of the vault file. It will be normalized to identify the keyring item for the vault file.

Returns

Indicates whether the password existed.

Return type

bool

Raises
is_available()[source]

Indicate whether the keyring service is available on the local system.

This function reports this only as a boolean. If information about the reasons for not being available is needed, use the check_available() method instead.

Returns

Keyring service is available on the local system.

Return type

bool

static check_available()[source]

Check whether the keyring service is available on the local system.

If available, the method returns.

If not available, an exception is raised with a message that provides some information about the keyring configuration.

Raises

KeyringNotAvailable – No keyring service available.

static keyring_service()[source]

Return the service/app name that is used for the keyring item.

That name is fixed within easy-vault and starts with ‘easy_vault’.

Returns

keyring service/app name.

Return type

unicode string

static keyring_username(filepath)[source]

Return the user/account name that is used for the keyring item.

That name is calculated from the normalized vault file path, such that each different vault file uses a different item in the keyring service.

Parameters

filepath (unicode string) – Path name of the vault file. It will be normalized to identify the keyring item for the vault file.

Returns

keyring user/account name.

Return type

unicode string

2.3. Password functions

easy_vault.get_password(filepath, use_keyring=True, use_prompting=True, verbose=False, echo=<built-in function print>)[source]

Get the password for a vault file from the keyring service and if not found there, by interactively prompting for it.

The use of the keyring service and the use of password prompting can be individually disabled, but at least one of them must be enabled.

Note that the function may still return no password, in case prompting is disabled and the keyring service did not have an item for the vault file stored.

This is a convenience function that uses the password methods of the Keyring class.

Parameters
  • filepath (unicode string) – Path name of the vault file. It will be normalized to identify the keyring item for the vault file.

  • use_keyring (bool) – Enable the use of the keyring service for getting the password.

  • use_prompting (bool) – Enable the use of password prompting for getting the password.

  • verbose (bool) – Print additional messages about where the password comes from.

  • echo (function) – Print function to be used for the additional messages in verbose mode.

Returns

Password for the vault file, or None.

Return type

unicode string

Raises
easy_vault.set_password(filepath, password, use_keyring=True, verbose=False, echo=<built-in function print>)[source]

Set the password for a vault file in the keyring service.

For consistency with get_password(), the use of the keyring service can be disabled, in which case the function does nothing.

This is a convenience function that uses the password methods of the Keyring class.

Parameters
  • filepath (unicode string) – Path name of the vault file. It will be normalized to identify the keyring item for the vault file.

  • password (unicode string) – Password for the vault file.

  • use_keyring (bool) – Enable the use of the keyring service for setting the password.

  • verbose (bool) – Print additional messages about changes to the password in the keyring service.

  • echo (function) – Print function to be used for the additional messages in verbose mode.

Raises

2.4. Exception classes

class easy_vault.EasyVaultException[source]

Base exception for all exceptions raised by the EasyVault class.

Derived from Exception.

class easy_vault.EasyVaultFileError[source]

Exception indicating file I/O errors with a vault file or with a temporary file (that is used when writing the vault file).

Derived from EasyVaultException.

class easy_vault.EasyVaultDecryptError[source]

Exception indicating that an encrypted vault file could not be decrypted.

Derived from EasyVaultException.

class easy_vault.EasyVaultEncryptError[source]

Exception indicating that a decrypted vault file could not be encrypted.

Derived from EasyVaultException.

class easy_vault.EasyVaultYamlError[source]

Exception indicating that a vault file in YAML format has a format issue.

Derived from EasyVaultException.

class easy_vault.KeyringException[source]

Base exception for all exceptions raised by the Keyring class.

Derived from Exception.

class easy_vault.KeyringNotAvailable[source]

Exception indicating that the keyring service is not available.

Derived from KeyringException.

class easy_vault.KeyringError[source]

Exception indicating that an error happend in the keyring service.

Derived from KeyringException.

2.5. Package version

easy_vault.__version__ = '0.7.0'

The full version of this package including any development levels, as a string.

Possible formats for this version string are:

  • “M.N.P.dev1”: Development level 1 of a not yet released version M.N.P

  • “M.N.P”: A released version M.N.P