Ansible Vault
Relevant source files
The following files were used as context for generating this wiki page:Ansible Vault is a feature within the Ansible ecosystem designed to manage sensitive data such as passwords, keys, and other secrets. It provides a mechanism to encrypt data at rest, both within files and as inline variables in playbooks. This allows users to securely store and distribute confidential information alongside their Ansible content, protecting it from unauthorized access while making it available during playbook execution.
The primary interface for Vault is the ansible-vault command-line tool, which supports creating, encrypting, decrypting, editing, and re-keying of files. Vault also integrates directly into Ansible playbooks through the vault filter, enabling dynamic encryption of strings. The system is designed to be simple and agentless, aligning with Ansible's core design principles.
Sources: README.md, lib/ansible/cli/vault.py, lib/ansible/plugins/filter/vault.yml
Core Components
Ansible Vault's functionality is delivered through a combination of a command-line interface, a core library for cryptographic operations, and an editor helper class.
ansible-vault CLI
The ansible-vault command is the main entry point for users to interact with Vault. It is implemented in the VaultCLI class and provides several sub-commands to manage encrypted content.
Sources: lib/ansible/cli/vault.py:36-47
The following table summarizes the available commands:
| Command | Description |
|---|---|
create | Creates a new, encrypted file. |
decrypt | Decrypts vaulted content. Can output to a file or stdout. |
edit | Decrypts a file to a temporary location, opens it in an editor, and re-encrypts it upon saving. |
encrypt | Encrypts existing plaintext files. Can encrypt multiple files at once. |
encrypt_string| Encrypts a string provided on the command line or from stdin and outputs the vaulted string to stdout. |
|rekey| Changes the password of one or more vault-encrypted files. |
|view| Decrypts a file and displays its contents to stdout without saving the plaintext. |
Sources: lib/ansible/cli/vault.py:101-131, test/integration/targets/ansible-vault/runme.sh:220,237,255,274,302
VaultLib
VaultLib is the core cryptographic library that underpins all vault operations. It is responsible for the actual encryption and decryption of data. It handles the details of the cipher (AES256 is used), key derivation from the password, and the formatting of the encrypted output.
Sources: lib/ansible/parsing/vault/init.py:476-483, test/units/parsing/vault/test_vault_editor.py:38-39
VaultEditor
The VaultEditor class provides a high-level API for file-based vault operations. It orchestrates the process of reading, writing, and editing encrypted files by using VaultLib for the crypto and invoking an external editor (defined by the EDITOR environment variable) for modifications.
Key methods in VaultEditor include:
create_file: Creates a new encrypted file.edit_file: Decrypts a file for editing and re-encrypts it.encrypt_file: Encrypts a plaintext file.decrypt_file: Decrypts a file.rekey_file: Changes the password of an encrypted file.
Sources: test/units/parsing/vault/test_vault_editor.py:81-88, lib/ansible/parsing/vault/init.py:209-216
Vault Filter
The vault filter allows for inline encryption of data directly within Jinja2 templates. This is useful for encrypting secrets inside playbooks without storing them in separate files.
Example usage:
vars:
myvaultedkey: "{{ 'my_secret_key' | vault('my_vault_password') }}"
This filter takes the secret to encrypt and a vault password as arguments. It also supports options like providing a salt for reproducible encryption and a vault_id.
Sources: lib/ansible/plugins/filter/vault.yml:1-32
Architecture and Data Flow
Encryption Flow
The following diagram illustrates the process of encrypting a file using ansible-vault encrypt.
This diagram shows how the ansible-vault CLI takes a plaintext file and a password, uses VaultLib to perform the encryption, and writes the formatted encrypted data back to the file.
Sources: lib/ansible/cli/vault.py:113-115, test/units/parsing/vault/test_vault_editor.py:234-241
Editing Flow
Editing an encrypted file involves decrypting it to a temporary file, allowing the user to modify it, and then re-encrypting the result.
This sequence shows the interaction between the user, the vault command, the external editor, and the filesystem during an edit operation. A faux editor script is used in integration tests to simulate this process.
Sources: test/units/parsing/vault/test_vault_editor.py:101-109, test/integration/targets/ansible-vault/faux-editor.py
Vault Data Format
An Ansible Vault encrypted file has a specific format. It starts with a header line, followed by the hex-encoded ciphertext.
The header format is: $ANSIBLE_VAULT;{version};{cipher_name}[;{vault_id}]
$ANSIBLE_VAULT: A magic string identifying the file as vault-encrypted.version: The vault format version.- 1.1: Standard format.
- 1.2: Adds support for a
vault_idin the header.
cipher_name: The encryption algorithm used, which isAES256.vault_id(Optional, in v1.2+): An identifier for the secret used to encrypt the file.
The remainder of the file contains the salt, HMAC, and ciphertext, all concatenated and hex-encoded.
# Example of a v1.1 header
b'$ANSIBLE_VAULT;1.1;AES256'
# Example of a v1.2 header with a vault_id
b'$ANSIBLE_VAULT;1.2;AES256;vault_secrets'
Sources: lib/ansible/parsing/vault/init.py:53-65, test/integration/targets/ansible-vault/runme.sh:65-66, test/units/parsing/vault/test_vault_editor.py:314-316, 338-340
Password Management and Vault IDs
Ansible Vault provides multiple ways to supply passwords for decryption, offering flexibility for different workflows.
| Method | CLI Option / Env Var | Description |
|---|---|---|
| Interactive Prompt | --ask-vault-pass | Prompts the user to enter the password on the command line. |
| Password File | --vault-password-file <path> | Reads the password from the first line of the specified file. The file can also be an executable script. |
| Environment Variable | ANSIBLE_VAULT_PASSWORD_FILE | Specifies the path to a password file via an environment variable. |
| Vault ID List (Environment) | ANSIBLE_VAULT_IDENTITY_LIST | A comma-separated list of vault-id@source pairs. |
| Vault ID (CLI) | --vault-id <name>@<source> | Specifies a named vault secret and its source (password file or script). |
Sources: test/integration/targets/ansible-vault/runme.sh:72, 119, 151, 169, 396
Vault IDs
Vault IDs are labels used to manage multiple vault passwords within a single Ansible run. When decrypting content, Ansible tries passwords from all provided sources until one succeeds. If the encrypted content has a vault_id (v1.2+ format), Ansible can prioritize or exclusively use the password associated with that ID.
- Default ID: If no vault ID is specified during encryption, the content can be decrypted by any provided password.
- Named ID: When a
vault_idis used for encryption, the same ID should be provided for decryption to ensure the correct password is used, especially whenANSIBLE_VAULT_ID_MATCH=1is set to enforce strict matching.
The integration tests demonstrate complex scenarios involving multiple vault IDs, password files, and the ANSIBLE_VAULT_IDENTITY_LIST environment variable to manage secrets for different parts of a playbook.
Sources: test/integration/targets/ansible-vault/runme.sh:137-140, 151-153, 396-397