vault

README

vault

Ansible Vault-compatible AES256 encryption for secrets, pure Go CGO=0.

Part of go-ansible — a pure-Go (CGO=0), functional-parity port of Ansible.

Usage

data, _ := os.ReadFile("secrets.yml")
if vault.IsVault(data) {
    plaintext, err := vault.Decrypt(string(data), password)
    // ...
}

ciphertext, err := vault.Encrypt(plaintext, password, "" /* vault ID, optional */)

VaultID and FormatVersion read a vault-encrypted string's header ($ANSIBLE_VAULT;1.1;AES256) without decrypting the body — useful for routing a secret to the right password before attempting to open it.

Documentation

Overview

Package vault implements the Ansible Vault 1.1 file format: AES-256 in CTR mode with a PBKDF2-HMAC-SHA256 derived key and an encrypt-then-MAC HMAC-SHA256 authentication tag, hex-wrapped at 80 columns.

The wire format is fixed by the reference implementation (ansible.parsing.vault.VaultAES256 in ansible-core) and is reproduced here byte-for-byte so files written by this package decrypt with the real `ansible-vault` and vice versa.

Index

• Variables
• func Decrypt(vaultText string, password string) ([]byte, error)
• func Encrypt(plaintext []byte, password string, vaultID string) (string, error)
• func FormatVersion(vaultText string) (string, error)
• func IsVault(data []byte) bool
• func MaybeDecrypt(data []byte, password string) ([]byte, error)
• func UnmarshalYAML(data []byte, password string, out any) error
• func VaultID(vaultText string) (string, error)

Variables

var ErrHMACMismatch = errors.New("vault: HMAC verification failed (wrong password?)")

ErrHMACMismatch is returned when decryption's integrity check fails — almost always a wrong password.

var ErrNotVault = errors.New("vault: not an ansible-vault payload")

ErrNotVault is returned when the input does not carry a recognized vault header.

Functions

func Decrypt

func Decrypt(vaultText string, password string) ([]byte, error)

Decrypt decrypts a full vault text (as produced by Encrypt, or by `ansible-vault encrypt`) with password.

func Encrypt

func Encrypt(plaintext []byte, password string, vaultID string) (string, error)

Encrypt encrypts plaintext under password and returns the full vault text (header line + 80-column-wrapped hex body), ready to write to a file or embed as a YAML block scalar.

vaultID, if non-empty, is appended to the header ($ANSIBLE_VAULT;1.1;AES256;vaultID) exactly as `ansible-vault --vault-id` does.

func FormatVersion

func FormatVersion(vaultText string) (string, error)

FormatVersion reports the vault format version string ("1.1" for everything this package produces or reads).

func IsVault

func IsVault(data []byte) bool

IsVault reports whether data begins with a recognized vault header, with or without a leading vault-id.

func MaybeDecrypt

func MaybeDecrypt(data []byte, password string) ([]byte, error)

MaybeDecrypt returns data unchanged when it is not vault-encrypted, and its plaintext when it is. It exists so a caller that reads YAML files — an inventory, a playbook, a vars file — can support encrypted ones by piping every read through here, which is how real Ansible handles them: any file it loads may be encrypted, and nothing about the call site says in advance whether this one is.

A vault-encrypted file with no password is an error rather than a silent pass-through, since returning the ciphertext as if it were content would surface much later as an unreadable YAML parse.

func UnmarshalYAML

func UnmarshalYAML(data []byte, password string, out any) error

UnmarshalYAML decodes YAML that may carry secrets in either of the two shapes real Ansible accepts, and decodes into out exactly as yaml.Unmarshal would otherwise.

• the whole file encrypted, as ansible-vault encrypt leaves it;

• individual !vault-tagged scalars inside an otherwise-plaintext file, as ansible-vault encrypt_string produces:

  db_password: !vault | $ANSIBLE_VAULT;1.1;AES256 3865...

The second shape is what lets one secret live in a vars file everybody can read. Each tagged scalar is decrypted in place before decoding, so the caller gets a plain value and never sees the ciphertext.

A missing password is an error only if something actually needs decrypting, so a plaintext file still loads with no password at all.

func VaultID

func VaultID(vaultText string) (string, error)

VaultID returns the vault-id label carried by a vault text's header (the part after the cipher name), or "" if none was set.