Skip to content

Latest commit

 

History

History
406 lines (317 loc) · 15.9 KB

ANSIBLE.adoc

File metadata and controls

406 lines (317 loc) · 15.9 KB

SmallMind Ansible

The smallmind-ansible module is a pure-Java implementation of the Ansible Vault encryption format. It lets Java applications read, write, and verify the $ANSIBLE_VAULT text files that the ansible-vault command-line tool produces, without shelling out to Python or Ansible itself.

The module is small by design: six classes, one dependency (smallmind-nutsnbolts), and no framework assumptions. It exists so that Java services — deployment tooling, configuration loaders, credential rotation jobs, CI helpers — can participate in the same "secrets-at-rest" workflow that operations teams already use with Ansible.

Ansible Vault is the de-facto standard for storing secrets alongside infrastructure-as-code. A typical shop ends up with dozens of vault files checked in beside their playbooks: group_vars/prod/secrets.yml, individual token files, encrypted certificates, and the like. The secret lives exactly one place, and whoever holds the vault password can read it.

This convention breaks down the moment a non-Ansible consumer needs access. A Java service that wants to load a production database password from a vault-encrypted YAML file has historically had three unappealing options:

  1. Decrypt the file with ansible-vault at deployment time and ship plaintext.

  2. Bundle a Python interpreter and call ansible-vault as a subprocess.

  3. Migrate all secrets to a separate vault system (HashiCorp Vault, AWS KMS, etc.), duplicating infrastructure and creating a second source of truth.

smallmind-ansible closes that gap. It implements the vault 1.1 and 1.2 binary format byte-for-byte, so a file written by ansible-vault encrypt on a developer laptop can be opened by a Java process in production — and vice versa. The secret stays in one place, managed by the tooling ops already trusts, while Java services read it natively.

  • Encrypts arbitrary byte streams into $ANSIBLE_VAULT;1.1;AES256 or $ANSIBLE_VAULT;1.2;AES256;<label> text, identical to what ansible-vault encrypt would emit for the same plaintext and password.

  • Decrypts any $ANSIBLE_VAULT 1.1 or 1.2 file, validating the HMAC authentication tag before returning plaintext, and distinguishing a wrong password from a structurally broken file.

  • Parses --vault-id command-line specifications of the form label@source, so Java tooling can accept the same arguments Ansible does.

  • It does not parse YAML or the !vault inline tag. Callers pass raw bytes in and get raw bytes out; layering it into a YAML loader is the caller’s job.

  • It does not prompt for passwords, read password files from disk, or manage vault-id-to-password mappings. VaultId exposes the parsed spec so the caller decides how to resolve it — file read, keyring lookup, KMS call, etc.

  • It does not support formats other than AES256. Ansible has only ever shipped AES256 as a vault cipher; the codec hard-fails on anything else, matching upstream behavior.

Class Role

VaultCodec

Static entry point. Reads and writes the $ANSIBLE_VAULT text format. This is the class most users should touch.

VaultTumbler

Low-level cryptographic engine. Derives keys via PBKDF2WithHmacSHA256, encrypts with AES/CTR/PKCS7Padding, and authenticates with HMAC-SHA256. Use it directly only when you already hold the raw binary fields (e.g., reading from a format other than the $ANSIBLE_VAULT text wrapper).

VaultCake

Immutable value object carrying the three binary pieces of a vault payload: salt, HMAC tag, and ciphertext. Produced by VaultTumbler.encrypt and consumed by VaultCodec during serialization.

VaultId

Parser for the label@source syntax used by Ansible’s --vault-id command-line flag. Splits the spec into a label (for format-1.2 headers) and a password source (a file path or the literal string prompt).

VaultCodecException

Checked exception for structural failures: unknown header, unsupported cipher, truncated body, JCA algorithm unavailable, etc.

VaultPasswordException

Subclass of VaultCodecException raised specifically when the HMAC comparison fails — i.e., the password is wrong. Callers who want to distinguish "wrong password" from "corrupt file" should catch this first.

Understanding the format makes the API obvious. An Ansible vault file is ASCII text with a one-line header followed by a hex-encoded body.

Format 1.1, no label
$ANSIBLE_VAULT;1.1;AES256
3336363...                            <-- body, wrapped at 80 chars
6264613...
...
Format 1.2, with label
$ANSIBLE_VAULT;1.2;AES256;production
3336363...
...

The body is the concatenation of three fields separated by the literal two-character token 0a (the hex representation of a newline):

<double-hex(salt)> 0a <double-hex(hmac)> 0a <double-hex(ciphertext)>

"Double-hex" means each raw byte is hex-encoded (one byte → two ASCII characters), and then the resulting ASCII string is itself hex-encoded a second time (each ASCII character → two more characters). It’s an artifact of Ansible’s original implementation, and VaultCodec handles it transparently. The resulting string is line-wrapped at 80 columns to match `ansible-vault’s own output exactly.

Ansible Vault uses an encrypt-then-MAC construction with PBKDF2 key derivation:

  1. A 32-byte random salt is generated per encryption (or read from the file on decryption).

  2. PBKDF2WithHmacSHA256(password, salt, iterations=10000, output=640 bits) produces 80 bytes of key material.

  3. The key material is partitioned: bytes 0–31 are the AES-256 key, bytes 32–63 are the HMAC-SHA256 key, bytes 64–79 are the 16-byte AES-CTR initialization vector.

  4. The plaintext is encrypted with AES/CTR/PKCS7Padding under the AES key and IV.

  5. HMAC-SHA256 is computed over the ciphertext (not the plaintext — this is the standard encrypt-then-MAC order) and stored alongside it.

Decryption reverses this: the salt is read from the file, the same 80 bytes of key material are re-derived, the HMAC is recomputed and compared against the stored tag, and only on match is the ciphertext decrypted.

Because the HMAC key is itself derived from the password, a wrong password produces a wrong HMAC key, which produces a mismatched tag on the very first check. That is why VaultTumbler.decrypt raises VaultPasswordException on HMAC mismatch — in this construction, HMAC failure essentially always means the password is wrong, not that the ciphertext is damaged.

The most common reason to pull this module into a Java project: a service needs to read a secret from a vault file that the operations team writes with ansible-vault.

import java.io.FileInputStream;
import java.io.InputStream;
import java.nio.charset.StandardCharsets;
import org.smallmind.ansible.VaultCodec;
import org.smallmind.ansible.VaultPasswordException;

public class SecretLoader {

  public static String loadSecret(String vaultPath, String password) throws Exception {

    try (InputStream in = new FileInputStream(vaultPath)) {
      byte[] plaintext = VaultCodec.decrypt(in, password);
      return new String(plaintext, StandardCharsets.UTF_8);
    } catch (VaultPasswordException wrongPassword) {
      throw new IllegalStateException("Vault password is incorrect for " + vaultPath, wrongPassword);
    }
  }
}

The same file can be decrypted interactively by an operator running ansible-vault view <vaultPath> with the same password. That symmetry is the point.

A Java credential-rotation job might generate a new token, encrypt it with the team’s vault password, and write the result into a repository that Ansible also consumes.

import java.io.ByteArrayInputStream;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;
import org.smallmind.ansible.VaultCodec;

public class SecretWriter {

  public static void writeSecret(String targetPath, String plaintext, String password) throws Exception {

    byte[] bytes = plaintext.getBytes(StandardCharsets.UTF_8);
    String vaultText = VaultCodec.encrypt(new ByteArrayInputStream(bytes), password);
    Files.writeString(Paths.get(targetPath), vaultText);
  }
}

An operator checking this file into git, then running ansible-vault view <targetPath> with the same password, will see the original plaintext. That is the end-to-end compatibility test.

Ansible supports multiple vault passwords per playbook by tagging each encrypted file with a label. Playbook execution matches each vault file against the labels supplied via --vault-id and uses the correctly-labeled password.

// Produces: $ANSIBLE_VAULT;1.2;AES256;production\n...
String productionVault = VaultCodec.encrypt(inputStream, password, "production");

// Produces: $ANSIBLE_VAULT;1.1;AES256\n... (no label)
String unlabeledVault = VaultCodec.encrypt(inputStream, password);

On decryption, VaultCodec.decrypt accepts both formats transparently — the label is parsed out of the header but not returned. Callers that need the label should read the first line of the file themselves before delegating to decrypt, or parse the input more structurally.

Command-line utilities written in Java that want to feel like ansible-vault can accept the same label@source argument syntax and let VaultId validate it:

import org.smallmind.ansible.VaultId;
import org.smallmind.nutsnbolts.command.CommandLineException;

public class VaultIdResolver {

  public static String resolvePassword(String vaultIdArg) throws Exception {

    VaultId vaultId;

    try {
      vaultId = new VaultId(vaultIdArg);
    } catch (CommandLineException invalid) {
      System.err.println("Invalid --vault-id: " + invalid.getMessage());
      System.exit(2);
      return null;
    }

    String source = vaultId.getFileOrPrompt();

    if ("prompt".equals(source)) {
      return new String(System.console().readPassword("Vault password (%s): ", vaultId.getId()));
    } else {
      return Files.readString(Paths.get(source)).strip();
    }
  }
}

The resolver is intentionally left to the caller: different environments want different password sources (files, keyrings, KMS, environment variables), and VaultId only promises to split the spec cleanly.

If you have a storage backend that already handles framing and you only need the cryptographic primitive — say, you are embedding encrypted blobs into a database column and do not want the text-format wrapper at all — you can skip VaultCodec and work with VaultTumbler and VaultCake directly:

import org.smallmind.ansible.VaultCake;
import org.smallmind.ansible.VaultTumbler;

// Encrypting
VaultTumbler tumbler = new VaultTumbler(password);
VaultCake cake = tumbler.encrypt(plaintextBytes);
// Now persist cake.getSalt(), cake.getHmac(), cake.getEncrypted() however you like.

// Decrypting (reuse the stored salt so PBKDF2 produces the same keys)
VaultTumbler forDecrypt = new VaultTumbler(password, storedSalt);
byte[] plaintext = forDecrypt.decrypt(storedHmac, storedCiphertext);

This is also the path to take if you ever need to interoperate with a format variant that is structurally different but cryptographically identical to Ansible’s, which occasionally happens when a secondary tool adopts Ansible’s primitives but wraps them in its own envelope.

The exception hierarchy is intentionally narrow:

VaultCodecException
 └── VaultPasswordException

Everything the module throws is a VaultCodecException (or a subclass), plus the expected IOException from stream I/O. The distinction that matters at runtime is:

  • VaultPasswordException — the password is wrong. This is actionable by prompting the user again, falling back to a secondary vault id, or reporting an authentication failure. It is not a reason to suspect file corruption or a bug in the module.

  • VaultCodecException (base class, not the subclass) — the file is not a recognizable vault: header doesn’t start with $ANSIBLE_VAULT, version isn’t 1.1 or 1.2, cipher isn’t AES256, body is truncated at a field boundary, or the JCA provider on the current JVM doesn’t support one of the required algorithms.

The usual catch order is therefore the more-specific subclass first:

try {
  byte[] plaintext = VaultCodec.decrypt(inputStream, password);
  // ...
} catch (VaultPasswordException bad) {
  // Prompt again, or fail with a clear "wrong password" message.
} catch (VaultCodecException malformed) {
  // The file isn't a valid vault. Don't retry — report and move on.
} catch (IOException io) {
  // Disk, network, etc.
}
  • Round-trip with ansible-vault. A file written by this module with password P decrypts cleanly under ansible-vault decrypt (or view, or edit) with the same password. The reverse holds as well. The byte-level format match is the whole reason the module exists; any divergence is a bug.

  • Version support. Formats 1.1 (no label) and 1.2 (with label) are supported for both encryption and decryption. Format 1.0 has been obsolete for most of Ansible’s history and is not supported. No known format 1.3 or higher exists at the time of writing.

  • Cipher support. Only AES256 is implemented, because only AES256 has ever shipped in Ansible. An unknown cipher string in the header produces a VaultCodecException rather than a silent fallback.

  • Iteration count. Fixed at 10,000, matching Ansible’s hard-coded value. If upstream ever bumps this, the constant in VaultTumbler will need to change correspondingly.

  • Thread safety. VaultCodec is stateless (all methods static) and safe for concurrent use. VaultTumbler is not thread-safe — it holds a javax.crypto.Mac instance, which is stateful. Use one VaultTumbler per encryption or decryption operation.

The module depends on exactly one other SmallMind module:

  • smallmind-nutsnbolts — for HexCodec (the double-hex encoding), EncryptionUtility (the JCA Cipher wrapper used for AES/CTR/PKCS7Padding), FormattedException (the base class for VaultCodecException), and CommandLineException (thrown by VaultId on malformed specs).

No third-party runtime dependencies. All cryptographic work goes through the standard JCA (javax.crypto.*), so any Java 8+ JVM with a default provider is sufficient.

Module name (for requires): org.smallmind.ansible

The jar ships an explicit module descriptor that exports org.smallmind.ansible and re-exports org.smallmind.nutsnbolts (requires transitive), because VaultCodecException and VaultId expose its exception types. A module that requires org.smallmind.ansible needs nothing else. See Module Path And Classpath for the repository-wide rules.

smallmind-ansible exists so that Java services can participate natively in an Ansible-centric secrets workflow. It is a narrow, focused module: VaultCodec for the text format, VaultTumbler for the crypto primitives, VaultCake as the value carrier between them, VaultId for argument parsing, and two exception types to distinguish "wrong password" from every other structural failure. If you are reaching for a Python subprocess just to read a $ANSIBLE_VAULT file from Java, this module is the thing you actually wanted.