# hiera-eyaml encrypts each Puppet YAML value on its own, so git diff still works

> hiera-eyaml is a Hiera backend for Puppet that encrypts the value of every key separately inside .eyaml files, using PKCS#7 by default, so a reviewer can read the structure of a secret without holding the private key. It is MIT licensed, it has a command line tool for encrypting, decrypting, editing and rotating keys, and it now lives under the Vox Pupuli umbrella.

**voxpupuli/hiera-eyaml** — A backend for Hiera that provides per-value asymmetric encryption of sensitive data

- Repository: https://github.com/voxpupuli/hiera-eyaml
- Stars: 536 · Forks: 138
- Language: Ruby
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/voxpupuli-hiera-eyaml

## What a Hiera backend does, in one sentence

hiera-eyaml is a backend for Hiera that provides per-value encryption of sensitive data within YAML files, to be used by Puppet.

Hiera is the configuration lookup layer in Puppet, and a backend is the thing that reads the YAML and hands values back. What this backend does differently is that a value in the file can be stored encrypted, and Puppet gets the plaintext back at run time.

The idea is old and the implementation is specific. The documentation records that a few people found that hiera-gpg just was not cutting it for all use cases, with one of the clearest complaints written back in June 2013, and that Tom created an initial version which was refined into what the documentation calls an elegant solution over the following months.

The project now sits under Vox Pupuli, and the documentation says so with a note that it has a new home there, and that this will hopefully mean more frequent feature updates and bug fixes. The releases reflect that move: v5.0.1 from 2026-04-15 and v5.0.0 from 2026-02-21, with the last push on 2026-10-15. The language is Ruby, the licence is MIT, and the repository topics are just hacktoberfest, which tells you it is a small project with a contributor-friendly history.

## Five differences from hiera-gpg, and why the first one matters most

The documentation lists what hiera-eyaml does differently from hiera-gpg, and the first item is the one that changes how a team works.

It only encrypts the values, which allows files to be swiftly reviewed without decryption. A reviewer opening a change to a .eyaml file sees the key names, the structure, and the fact that a value changed, without holding the private key. With a file-level encryption scheme the whole document is a blob until someone with the key opens it, which means review of a secret-bearing file becomes either blocked or rubber-stamped.

The second is that it encrypts the value of each key individually, and the documentation says in parentheses that this means that git diff is meaningful. That is the same property seen from a different angle: a diff of two commits shows which specific key changed, not that the file changed.

The third is the command line tool for encrypting, decrypting, editing and rotating keys, which the documentation says makes it almost as easy as using clear text files.

The fourth is that it uses basic asymmetric encryption, PKCS#7, by default, with two consequences spelled out: it does not require any native libraries that need to be compiled, and it allows users without the private key to encrypt values that the puppet master can decrypt. That last property is what makes the workflow possible, since the people writing the configuration are not the people holding the decryption key.

The fifth is a pluggable encryption framework, with GPG encryption available as a separate hiera-eyaml-gpg project if you need multiple keys and easier key rotation.

## The file format, and what the encrypted value looks like

The Hiera eyaml backend uses YAML formatted files with the .eyaml extension. The encrypted strings are prefixed with the encryption method, wrapped with ENC[] and placed in an eyaml file. You can mix your plain values in as well, or separate them into different files, and encrypted values can occur within arrays, hashes, nested arrays and nested hashes.

Here is what a file looks like:

```yaml
---
plain-property: You can see me

encrypted-property: >
    ENC[PKCS7,Y22exl+OvjDe+drmik2XEeD3VQtl1uZJXFFF2NnrMXDWx0csyqLB/2NOWefv
    NBTZfOlPvMlAesyr4bUY4I5XeVbVk38XKxeriH69EFAD4CahIZlC8lkE/uDh
    jJGQfh052eonkungHIcuGKY/5sEbbZl/qufjAtp/ufor15VBJtsXt17tXP4y
    l5ZP119Fwq8xiREGOL0lVvFYJz2hZc1ppPCNG5lwuLnTekXN/OazNYpf4CMd
    /HjZFXwcXRtTlzewJLc+/gox2IfByQRhsI/AgogRfYQKocZgFb/DOZoXR7wm
    IZGeunzwhqfmEtGiqpvJJQ5wVRdzJVpTnANBA5qxeA==]
```

Two things in that example are worth reading closely. The plain-property key is right there in the clear, next to the encrypted one, which is the point of a per-value scheme: the reviewer sees the file structure and knows which key is sensitive. And the encrypted value uses the folded block scalar syntax, the greater-than sign, so the long base64 blob is wrapped across lines instead of being one enormous line.

The prefix inside the brackets names the method, PKCS7 here, so a file can in principle mix methods and the reader can tell them apart.

## The command line tool, which is the part you use daily

The eyaml tool covers the whole lifecycle, and the documentation is organised around four verbs.

Creating keys is the first step:

```bash
    $ eyaml createkeys
```

That creates a public and private key with default names in the default location, which the documentation gives as ./keys.

Encryption needs only the public key, so you can distribute that to the people creating Hiera properties:

```bash
    $ eyaml encrypt -f filename            # Encrypt a file
    $ eyaml encrypt -s 'hello there'       # Encrypt a string
    $ eyaml encrypt -p                     # Encrypt a password (prompt for it)
```

The -l parameter passes a label for the encrypted value:

```bash
    $ eyaml encrypt -l 'some_easy_to_use_label' -s 'yourSecretString'
```

Decryption needs the private key, and the same tool tests it:

```bash
    $ eyaml decrypt -f filename               # Decrypt a file
    $ eyaml decrypt -s 'ENC[PKCS7,.....]'     # Decrypt a string
```

And editing is the mode the documentation calls perhaps the most common use of eyaml, where a file mixes encrypted and non-encrypted properties. Edit mode opens a decrypted copy of the file in your editor and encrypts the modified values when you exit. The documentation also names the plain command, eyaml edit important.eyaml, and explains that this tool makes editing your encrypted files as simple as clear text files.

The presence of an edit mode is the design decision that makes the whole approach tolerable in daily use. A scheme that only encrypts and decrypts forces you to round-trip the file through the tool for every change, and people stop doing that. Editing in place keeps the file in its encrypted form on disk the rest of the time.

## Where the keys live, and the permissions that matter

Since the point of using this module is to securely store sensitive information, the documentation is emphatic that the keys need secure storage.

The reasoning is about the deployment model. If you are using Hiera with Puppet, your puppetmaster needs access to these keys to perform decryption when the puppet agent runs on a remote node. So a suggested location might be to store them in /etc/puppetlabs/puppet/eyaml or /var/lib/puppet/keys, depending on your setup.

The permissions are spelled out in a way that is worth copying verbatim in spirit. The folder should allow the puppet user, normally puppet, execute access to the keys directory, read only access to the keys themselves, and restrict everyone else:

```bash
    $ chown -R puppet:puppet /etc/puppetlabs/puppet/eyaml
    $ chmod -R 0500 /etc/puppetlabs/puppet/eyaml
    $ chmod 0400 /etc/puppetlabs/puppet/eyaml/*.pem
    $ ls -lha /etc/puppetlabs/puppet/eyaml
```

The listing that follows shows the expected result, with the private and public key files both at 1.7K and 1.1K and mode 0400.

There is also a way to keep the secret off the disk entirely. You can load the keypair into an environment variable and use the pkcs7_private_key_env_var and pkcs7_public_key_env_var options to specify the environment variable names, which the documentation says avoids writing the secret key to disk. That is the option to prefer if your secret management setup can inject environment variables into the agent.

## Installing it, and the two audiences it has to satisfy

There are two distinct audiences, and the installation instructions cover both.

The ordinary case is a machine that already runs Puppet with Hiera. The Vox Pupuli hiera module can manage the installation and configuration of hiera-eyaml, so the module is the recommended route. The direct routes are RubyGems with gem install hiera-eyaml, and an apt package on Ubuntu 18.04 and later with sudo apt install hiera-eyaml.

The second case is puppetserver, and it is the more awkward one, because all the commands need to be executed as root and because the gem has to be installed into the puppetserver's own Ruby environment rather than the system one. There are three documented ways. The puppetserver gem subcommand, the equivalent Puppet resource with the puppetserver_gem provider, and the Puppet DSL form of the same thing:

```puppet
package { 'hiera-eyaml':
  ensure   => 'installed',
  provider => 'puppetserver_gem',
}
```

One note applies to Puppet Enterprise, which vendors hiera-eyaml already, so you do not need to install it there.

The repository layout reflects a gem with a plugin ecosystem rather than a single library. There is a lib directory, a bin directory, a features directory holding the Cucumber tests, a sublime_text directory, a Rakefile, a Gemfile, a hiera-eyaml.gemspec, a PLUGINS.md documenting the pluggable encryption framework, a HISTORY.md and a CHANGELOG.md. The rubocop configuration with a todo file suggests the same linting discipline most Ruby projects maintain.

## Conclusion

Adopt hiera-eyaml if you run Puppet and need secrets in Hiera YAML that a reviewer can see the shape of without being able to read the value. Do not adopt it if you need multiple recipients with separate keys, because the documentation points at a separate GPG plugin for that case rather than solving it in the core tool. Before you deploy it, check three things: where the key pair lives and who can read the private one, since the puppet user needs execute access to the directory and read access to the keys and nothing else, that your private key is not on disk if you would rather it were not, since the tool can read the keypair from environment variables instead, and that your editors are configured, because the edit mode writes decrypted values to a temporary file.

## FAQ

### What does hiera-eyaml do for Puppet?

It is a Hiera backend that provides per-value encryption of sensitive data within YAML files, using the .eyaml extension. The encrypted strings are prefixed with the method, wrapped with ENC[] and placed in the file, and can appear inside arrays, hashes and nested structures.

### How does hiera-eyaml differ from hiera-gpg?

It only encrypts the values rather than the file, so files can be reviewed without decryption, it encrypts each key's value individually so that git diff stays meaningful, it ships a command line tool for encrypting, decrypting, editing and rotating keys, it uses PKCS#7 asymmetric encryption by default so no native libraries are needed, and its encryption framework is pluggable.

### How do I encrypt and decrypt values with eyaml?

Use eyaml encrypt with -f for a file, -s for a string or -p to be prompted for a password, adding -l for a label. Decryption needs the private key and takes the same -f and -s options. To edit a mixed file in place, use the edit mode, which opens a decrypted copy in your editor and re-encrypts the modified values when you exit.

### Where should the eyaml key pair be stored?

The documentation suggests /etc/puppetlabs/puppet/eyaml or /var/lib/puppet/keys, with the puppet user given execute access to the directory and read-only access to the keys and everyone else restricted. You can also avoid writing the secret key to disk by loading it into an environment variable and setting the pkcs7_private_key_env_var and pkcs7_public_key_env_var options.

### How do I install hiera-eyaml?

The Vox Pupuli hiera Puppet module can manage the installation, or you can use RubyGems with gem install hiera-eyaml, or the apt package on Ubuntu 18.04 and later. For puppetserver the commands must run as root and the gem must go into the server's own Ruby, via the puppetserver gem command, a resource with the puppetserver_gem provider, or the Puppet DSL.

## Sources

- [Issues](https://github.com/voxpupuli/hiera-eyaml/issues)
- [License: MIT](https://github.com/voxpupuli/hiera-eyaml/blob/master/LICENSE)
- [README](https://github.com/voxpupuli/hiera-eyaml/blob/master/README.md)
- [Releases](https://github.com/voxpupuli/hiera-eyaml/releases)
- [voxpupuli/hiera-eyaml on GitHub](https://github.com/voxpupuli/hiera-eyaml)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/voxpupuli-hiera-eyaml