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
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:
On macOS: Keychain
On Linux: depends
On Windows: Credential Locker