Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
H

hiera-eyaml

> 编程语言
Open source

A backend for Hiera that provides per-value asymmetric encryption of sensitive data

533 stars0 likes2 views
WebsiteGitHub

About

A backend for Hiera that provides per-value asymmetric encryption of sensitive data

Hiera eyaml

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


:new: hiera-eyaml is now part of Vox Pupuli

hiera-eyaml has a new home https://github.com/voxpupuli/hiera-eyaml.

Hopefully this will mean more frequent feature updates and bug fixes!

Advantages over hiera-gpg

A few people found that hiera-gpg just wasn't cutting it for all use cases, one of the best expressed frustrations was written back in June 2013. So Tom created an initial version and this was refined into an elegant solution over the following months.

Unlike hiera-gpg, hiera-eyaml:

  • only encrypts the values (which allows files to be swiftly reviewed without decryption)
  • encrypts the value of each key individually (this means that git diff is meaningful)
  • includes a command line tool for encrypting, decrypting, editing and rotating keys (makes it almost as easy as using clear text files)
  • uses basic asymmetric encryption (PKCS#7) by default (doesn't require any native libraries that need to be compiled & allows users without the private key to encrypt values that the puppet master can decrypt)
  • has a pluggable encryption framework (e.g. GPG encryption (hiera-eyaml-gpg) can be used if you have the need for multiple keys and easier key rotation)

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. Encrypted values can occur within arrays, hashes, nested arrays and nested hashes.

For instance:

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==]

To edit this you can use the command eyaml edit important.eyaml which will decrypt the file, fire up an editor with the decrypted values and re-encrypt any edited values when you exit the editor. This tool makes editing your encrypted files as simple as clear text files.

Setup

Puppet module

The Vox Pupuli hiera module can manage the installation and configuration of hiera-eyaml.

Installing hiera-eyaml

RubyGems

$ gem install hiera-eyaml

Apt (Ubuntu 18.04+)

$ sudo apt install hiera-eyaml

Installing hiera-eyaml for puppetserver

All commands need to be executed as root. Puppet Enterprise vendors hiera-eyaml already, so you don't need to install it there.

bash
puppetserver gem install hiera-eyaml

or via puppet:

bash
puppet resource package hiera-eyaml ensure=installed provider=puppetserver_gem

or via Puppet DSL:

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

Generate keys

The first step is to create a pair of keys:

$ eyaml createkeys

This creates a public and private key with default names in the default location. (./keys)

Storing the keys securely when using Puppet

Since the point of using this module is to securely store sensitive information, it's important to store these keys securely. If using Hiera with Puppet, Your puppetmaster will need to access these keys to perform decryption when the puppet agent runs on a remote node. So for this reason, a suggested location might be to store them in /etc/puppetlabs/puppet/eyaml or /var/lib/puppet/keys depending on your setup.

The permissions for this 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:

$ 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
-r-------- 1 puppet puppet 1.7K Sep 24 16:24 private_key.pkcs7.pem
-r-------- 1 puppet puppet 1.1K Sep 24 16:24 public_key.pkcs7.pem

You may also 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 to avoid writing the secret key to disk.

Basic usage

Encryption

To encrypt something, you only need the public_key, so distribute that to people creating hiera properties

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

Use the -l parameter to pass in a label for the encrypted value,

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

Decryption

To decrypt something, you need the private_key.

To test decryption you can use the eyaml tool

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

Editing files with a mixture of eyaml-encrypted and plain-text content

This is, perhaps, the most common use of eyaml where you have created a few eyaml files, with a mixture of encrypted and non-encrypted properties, you can edit the encrypted values in place, using the special edit mode of the eyaml utility. Edit mode opens a decrypted copy of the eyaml file in your $EDITOR and will encrypt and modified values when you exit the editor.

$ eyaml edit filename.eyaml         # Edit an eyaml file in place

When editing eyaml files, you will see that the unencrypted plaintext is marked to allow the eyaml tool to identify each encrypted block, along with the encryption method. This is used to make sure that the block is encrypted again only if the clear text value has changed, and is encrypted using the original encryption mechanism (see plugable encryption later).

A decrypted file might look like this:

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

cipher-property : >
    DEC(1)::PKCS7[You can't see me]!

environments:
    development:
        host: localhost
        password: password
    production:
        host: prod.org.com
        password: >
            DEC(2)::PKCS7[securepassword]!

things:
    - thing 1
    -   - nested thing 1.0
        - >
            DEC(3)::PKCS7[secure nested thing 1.1]!
    -   - nested thing 2.0
        - nested thing 2.1

Whilst editing you can delete existing values and add new one using the same format (as below). Note that it is important to omit the number in brackets for new values. If any duplicate IDs are found then the re-encryption process will be abandoned by the eyaml tool.

some_new_key: DEC::PKCS7[a new value to encrypt]!

Encrypting an entire file

While not as common, sometimes you need to encrypt an entire file. Maybe this file is binary data that isn't meant for loading into an editor. One example might be a Kerberos keytab file. No problem! Just encrypt the entire file:

$ eyaml encrypt -f filename

As with encrypting short strings on the command-line, the encrypted equivalent will be sent to stdout as an ASCII text string and thus now plays nice with your editor. Notice that the file itself, however, remains unchanged. The output is presented in two blocks: once as a single, long string and once in a nice line-wrapped form. Copy the one of your preference, starting with the ENC[ and ending at the matching ]. Paste this into your Puppet or Hiera file just like any other eyaml string and your done. If the file is rather large, you may wish to use a helper like xclip to copy the stdout directly to your clipboard.

Encrypting multiline values

The following step-by-step example shows you how to encrypt multiline values.

  • Copy the YAML text below to a file named multiline_example.eyaml
---
accounts::key_sets:
  dummy:
    private: |
      ---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
      Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20200911"
      P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
      1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
      JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
      2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
      QEPM5xLW0unCsQ==
      ---- END SSH2 ENCRYPTED PRIVATE KEY ----
  • Use edit to ...
    • replace '|' with '>',
    • prepend DEC::PKCS7[ before the first line,
    • remove all whitespaces used for indentation,
    • and append ]! to the last line of the multiline value.

eyaml edit multiline_example.eyaml

---
accounts::key_sets:
  dummy:
    private: >
      DEC::PKCS7[---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20170123"
P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
QEPM5xLW0unCsQ==
---- END SSH2 ENCRYPTED PRIVATE KEY ----]!
…
  • Output of eyaml decrypt -f multiline_example.eyaml:
---
accounts::key_sets:
  dummy:
    private: |
  ---- BEGIN SSH2 ENCRYPTED PRIVATE KEY ----
  Comment: "dummy-key-hiera-eyaml-issue-rsa-key-20200911"
  P2/56wAAANwAAAA3aWYtbW9kbntzaWdue3JzYS1wa2NzMS1zaGExfSxlbmNyeXB0e3JzYS
  1wa2NzMXYyLW9hZXB9fQAAAARub25lAAAAjQAAAIkAAAAGJQAAAP93ZtrMIRZutZ/SZUyw
  JWwyI4YxNvr5tBt9UnSJ7K0+rQAAAQDohO1ykUahsogS+ymM6o9WEmdROJZpWShCqdv8Dj
  2roQAAAIDG1G8hY90Xlz/YiFhDZLLWAAAAgOzMWTfAlHbJ4AdEhG5uU/EAAACA+1/AlcSr
  QEPM5xLW0unCsQ==
  ---- END SSH2 ENCRYPTED PRIVATE KEY ----
  • The output does NOT have to be valid YAML for usage with Puppet.

Hiera

To use eyaml with hiera and puppet, first configure hiera.yaml to use the eyaml backend.

Eyaml works with Hiera 3.x, as well as with Hiera 5 (Puppet 4.9.3 and later).

With Hiera 5

In Hiera 5, each hierarchy level has one designated backend, as well as its own independent configuration for that backend.

Hierarchy levels that use eyaml must set the following keys:

  • name.

  • lookup_key (must be set to eyaml_lookup_key).

  • path/paths/glob/globs (choose one).

  • datadir (can be omitted if you've set a default).

  • options — a hash of eyaml-specific settings; by default, this should include pkcs7_private_key and pkcs7_public_key, or pkcs7_public_key_env_var and pkcs7_private_key_env_var, but alternate encryption plugins use alternate options. Anything from the old :eyaml config section (except datadir) goes here.

    You do not need to specify key names as :symbols; normal strings are fine.

…

Unlike with Hiera 3, there's no default file extension for eyaml files, so you can specify your own file extension directly in the path name.

For more details, see the hiera.yaml (version 5) reference page.

With Hiera 3

In Hiera 3, hierarchy levels don't have a backend assigned to them, and Hiera loops through the entire hierarchy for each backend. Options for t

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rubyhacktoberfest

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言