Vault
How Volant reads Ansible Vault data, where it gets the passwords, and why they never leave the controller process.
Volant reads and writes the vault 1.1 and 1.2 formats of ansible-core 2.19.12. The results, error messages and exit codes match ansible-core.
Where the passwords come from
Section titled “Where the passwords come from”| Source | Notes |
|---|---|
-J, --ask-vault-pass |
Asked on the terminal, echo off. |
--vault-password-file, --vault-pass-file |
A file, or an executable that prints the password. Repeatable. |
--vault-id LABEL@SOURCE |
The source is a file, an executable or prompt. Repeatable. |
[defaults] vault_password_file, vault_identity_list |
The same, from ansible.cfg. |
ANSIBLE_VAULT_PASSWORD_FILE, ANSIBLE_VAULT_IDENTITY_LIST |
The same, from the environment. |
Every password is tried on every vaulted value, whatever its label.
What is decrypted
Section titled “What is decrypted”- Inline
!vaultvalues in a playbook or a vars file. They load as ciphertext and decrypt when a template reads them. A decrypted value keeps the trust ansible-core gives it. - Whole vaulted files:
vars_files,include_vars,group_varsandhost_varsfiles. A vaulted file that cannot be read fails with ansible-core’s message. - The
vaultandunvaultfilters, thevault_encryptedandvaulted_filetests, and theunvaultlookup. - A vaulted
srcofcopy,templateandscript, and a vaulted archive ofunarchive. The run decrypts it into a private temporary directory before the plugin reads it.decrypt: falseoncopyorunarchivekeeps the ciphertext.
A !vault value that no secret opens fails the task that reads it, with the three blocks ansible-core prints. debug: var=x exits 2, with the cause at the line where the value is written. is vault_encrypted answers for the variables of the current host.
Secrets stay on the controller
Section titled “Secrets stay on the controller”A vault password lives in memory in the controller process. It is never written to a command line, to the environment of a child process, to a log, to a result or to the agent link. The connection and escalation passwords follow the same rule, and Connections says how the SSH password reaches ssh.
Filters, tests and lookups that run in Python never see the vault password. The vault ones run in the controller process for that reason. See Filters, tests and lookups that need Python.
A value that came back from a managed host is never decrypted with the run’s secrets, and never templated again. See Values from hosts are never templated.
Encrypting and viewing files
Section titled “Encrypting and viewing files”volant vault encrypt, decrypt and view work on the same files as ansible-vault: a file encrypted by one is read by the other, with the default id and with a label.
encryptreplaces each file with its vault text anddecryptwith its plaintext. Both leave the result at mode0600and print nothing; on a terminal they sayEncryption successfulorDecryption successfulon standard error. A file without a final newline comes back without one.- The header is
$ANSIBLE_VAULT;1.1;AES256for the default id and$ANSIBLE_VAULT;1.2;AES256;LABELfor another.--vault-id LABEL@SOURCEsets the label. With more than one--vault-id,--encrypt-vault-id(orvault_encrypt_identity,ANSIBLE_VAULT_ENCRYPT_IDENTITY) picks the one that encrypts; without it the command exits 5. --output FILEwrites there and leaves the source alone,--output -writes to standard output, and no file name, or-, reads standard input.viewprints each file’s plaintext. On a terminal it goes through the pager:PAGER, elseANSIBLE_PAGER, else[defaults] pager, elseless.- Without any password source the command asks for it.
encryptasks twice, asNew Vault password:andConfirm New Vault password:. -vprints the configuration file in use and-vvthe version. The extra lines of-vvvvare not printed.
Creating, editing and rekeying files
Section titled “Creating, editing and rekeying files”volant vault create, edit and rekey work on the same files as ansible-vault.
createtakes one file name. It refuses with exit code 5 unless standard output is a terminal or--skip-tty-checkis given, and with exit code 1 when the file exists. A missing directory is created, with a warning. The editor can leave the file empty: the result is a valid vault file holding an empty text.editdecrypts each file, opens the editor and encrypts the result with the secret that opened the file and the label it had. When the text did not change, the file is not rewritten. A changed file keeps its mode.- The editor is
EDITOR, elseANSIBLE_EDITOR, else[defaults] editor, elsevi, split into words as a shell would split it, with the file name added. Its exit status is not looked at, as in ansible-vault. - The editor works on a copy with mode
0600in a private directory underANSIBLE_LOCAL_TEMP([defaults] local_tmp, else~/.ansible/tmp). The copy is overwritten and removed on every way out, including a failing editor and SIGTERM or SIGHUP. Ctrl-C goes to the editor. rekeydecrypts each file with the old secrets and writes it again with the new one, keeping its mode. The new secret comes from--new-vault-password-file, from--new-vault-id LABEL@SOURCE, or from the promptsNew Vault password:andConfirm New Vault password:. It printsRekey successfulon standard error, whatever standard output is.
Encrypting strings
Section titled “Encrypting strings”volant vault encrypt_string turns a value into a !vault | block for a vars file. Every line of the ciphertext is indented by ten spaces, and each block ends with a newline:
mykey: !vault | $ANSIBLE_VAULT;1.1;AES256 66313561363937653234366564623639...-n NAMEnames the string at the same place and--stdin-name NAMEnames standard input. Without a name the block starts with!vault |.--vault-id LABEL@SOURCEgives a1.2header with the label.- With no string, or with
-, the text is read from standard input to its end. Empty input exits 5. - With more than one string, standard error carries one comment line per string, and a note when there are fewer names than strings. Standard output holds only the blocks.
-pasks for a variable name, then the string, which is not echoed unless--show-inputis given. It cannot be combined with reading standard input.- On a terminal,
Encryption successfulgoes to standard error before the blocks. --output FILEwrites the blocks to the file, at mode0600.
Known gaps
Section titled “Known gaps”- The
wrap_objectargument of thevaultfilter is refused as not supported yet. Itssaltargument works as in Ansible: the same salt always gives the same text. - At
-vvvvv,vault view,decryptandrekeydo not print ansible-core’s trace of each secret they try (Trying secret FileVaultSecret(...) for vault_id=...). The secrets are tried in the same order.
The command line page has the options.