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:
-
Decrypt the file with
ansible-vaultat deployment time and ship plaintext. -
Bundle a Python interpreter and call
ansible-vaultas a subprocess. -
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;AES256or$ANSIBLE_VAULT;1.2;AES256;<label>text, identical to whatansible-vault encryptwould emit for the same plaintext and password. -
Decrypts any
$ANSIBLE_VAULT1.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-idcommand-line specifications of the formlabel@source, so Java tooling can accept the same arguments Ansible does.
-
It does not parse YAML or the
!vaultinline 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.
VaultIdexposes 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 |
|---|---|
|
Static entry point. Reads and writes the |
|
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 |
|
Immutable value object carrying the three binary pieces of a vault payload:
salt, HMAC tag, and ciphertext. Produced by |
|
Parser for the |
|
Checked exception for structural failures: unknown header, unsupported cipher, truncated body, JCA algorithm unavailable, etc. |
|
Subclass of |
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.
$ANSIBLE_VAULT;1.1;AES256 3336363... <-- body, wrapped at 80 chars 6264613... ...
$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:
-
A 32-byte random salt is generated per encryption (or read from the file on decryption).
-
PBKDF2WithHmacSHA256(password, salt, iterations=10000, output=640 bits)produces 80 bytes of key material. -
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.
-
The plaintext is encrypted with
AES/CTR/PKCS7Paddingunder the AES key and IV. -
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’tAES256, 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 passwordPdecrypts cleanly underansible-vault decrypt(orview, oredit) 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
AES256is implemented, because onlyAES256has ever shipped in Ansible. An unknown cipher string in the header produces aVaultCodecExceptionrather than a silent fallback. -
Iteration count. Fixed at 10,000, matching Ansible’s hard-coded value. If upstream ever bumps this, the constant in
VaultTumblerwill need to change correspondingly. -
Thread safety.
VaultCodecis stateless (all methods static) and safe for concurrent use.VaultTumbleris not thread-safe — it holds ajavax.crypto.Macinstance, which is stateful. Use oneVaultTumblerper encryption or decryption operation.
The module depends on exactly one other SmallMind module:
-
smallmind-nutsnbolts— forHexCodec(the double-hex encoding),EncryptionUtility(the JCACipherwrapper used for AES/CTR/PKCS7Padding),FormattedException(the base class forVaultCodecException), andCommandLineException(thrown byVaultIdon 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.