1. Usage

1.1. Supported environments

The easy-vault package is supported in these environments:

  • Operating Systems: Linux, macOS / OS-X, native Windows, Linux subsystem in Windows, UNIX-like environments in Windows.

  • Python: 2.7, 3.4, and higher

1.2. Installation

The following command installs the easy-vault package and its prerequisite packages into the active Python environment:

$ pip install easy-vault

1.3. Managing the vault file

The easy-vault package comes with a command named “easy-vault” that is used to encrypt or decrypt the vault file in place:

$ easy-vault encrypt VAULTFILE
$ easy-vault decrypt VAULTFILE

This command displays self-explanatory help, e.g.:

$ easy-vault --help
$ easy-vault encrypt --help
$ easy-vault decrypt --help
$ easy-vault check-keyring --help
$ easy-vault check-encrypted --help

1.4. Accessing the secrets in a program

The easy-vault package provides programmatic access to the vault file, regardless of whether the vault file is currently encrypted or decrypted. See the API Reference for details.

The following Python code demonstrates how to access the secrets in a vault file in YAML format:

import easy_vault

vault_file = 'examples/vault.yml'  # Path name of Ansible vault file

password = easy_vault.get_password(vault_file)
vault = easy_vault.EasyVault(vault_file, password)
try:
    vault_obj = vault.get_yaml()
except easy_vault.EasyVaultException as exc:
    . . . # handle error
easy_vault.set_password(vault_file, password)

myserver_nick = 'myserver1'        # Nickname of a secret in the vault file

myserver_secrets = vault_obj['secrets'][myserver_nick]

session = MySession(               # A fictitious session class
    host=myserver_secrets['host'],            # 10.11.12.13
    username=myserver_secrets['username'],    # myuser1
    password=myserver_secrets['password'])    # mypass1

# Do something in the server session
. . .

Here is the vault file ‘examples/vault.yml’ that is used in the example code:

# Example Ansible vault file

secrets:

  myserver1:
    host: 10.11.12.13
    username: myuser1
    password: mypass1

  myserver2:
    host: 10.11.12.14
    username: myuser2
    password: mypass2

The vault file does not need to be in YAML format; there are access functions for accessing its raw content as a Byte string and as a Unicode string, too.

1.5. Keyring service

The easy-vault package accesses the keyring service of the local system via the keyring package. That package supports a number of different keyring services and can be configured to use alternate keyring services.

By default, the following keyring services are active and will be used by the keyring package: