Encrypt Secrets in Hiera

You should never store sensitive information like license keys, private keys, authentication tokens, passwords, or password-equivalents in a revision control system like git.
For sensitive information data. encrypt it on your development machine, with a public key that only the PuppetMaster can decrypt. The encrypted version of the data can then be safely managed in git.

To setup your development machine for encrypted hiera data

Install hiera-eyaml

To install the eyaml command to perform the encryption, you will need to setup the puppet development tools on a workstation.

NOTE: Puppet has it’s own version of Ruby (and therefore Gem) which is NOT the one in your default path. You MUST run Puppet’s Gem for this to work.

$ sudo /opt/puppetlabs/puppet/bin/gem install hiera-eyaml

It should download and install the following gems:

  • hiera-eyaml
  • highline
  • trollop

Configure and Use

Now as non-priv user or as root (it will work as either), configure eyaml for your user by making the directory, creating a config.yaml file, adding the line to point to the public key, either cat or cp the public_key to the directory, and verify its SHA256 checksum.

This example assumes a linux environment using bash. Depending on your path and other environment settings, you may need to use absolute paths on your system, and change the references to your home directory (~).

mkdir ~/.eyaml
cd ~/.eyaml
cat >> config.yaml << ENDOFYAMLCONFIG
---
pkcs7_public_key: "~/.eyaml/build_public_key.pkcs7.pem"
ENDOFYAMLCONFIG

cat > "~/.eyaml/build_public_key.pkcs7.pem" << ENDOFKEY
-----BEGIN CERTIFICATE-----
MIIC2TCCAcGgAwIBAgIBATANBgkqhkiG9w0BAQUFADAAMCAXDTE3MDkxODE0NDYy
MFoYDzIwNjcwOTA2MTQ0NjIwWjAAMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIB
CgKCAQEAyZj6oCjgyAunuY0UwGWxpKwnU00iWQ152yDe0p+s+fy4SXmgcjEtCXZH
TxeLBQ3AOZ+SluYoPWUmHVGq8C6QNxhv6vBLYWoTz7zJPbxyJ3bELs3LVrz+lDIs
KaXJXH5w9Nfbn7gx2Ng3s5qNx3EsITjoTeAEYDrIuEvtVOjJHnYFv8AEqx9uIn8o
T9EWhM+0eRynhTWHzYTabJmESnvfUdy46YLAzafRQsB5mkQcHXDnPmdCT35DmZQd
zQ9W0lrBtqPODXVXsDRUWZR9PM8zp/3fC9ObSIG+VutOMRUQtDzsPw+CCkwcz9ri
4DV339m1AOe+w0BMsVQy8/LE0OYBcwIDAQABo1wwWjAPBgNVHRMBAf8EBTADAQH/
MB0GA1UdDgQWBBRg6MJh570+khvWwD85lhQKWybtfjAoBgNVHSMEITAfgBRg6MJh
570+khvWwD85lhQKWybtfqEEpAIwAIIBATANBgkqhkiG9w0BAQUFAAOCAQEAcMim
VgLAZ7PLh5JWJAHOSB+viVM/UfFA69GfSwWn434/qvA6N/5tFelQZx1OoSZs+siz
vHiFVPbIRTiCzyPJa1oTglMiNg/4PkMRl5NX+jYkkcWMzjYBDgH4nNWdU3Fu1zrL
L6jR277NzOk5NMiP2mK2XOlI0e7O8p7Cr6Xj/8Ncr/RIEN4wQFrca5gtS6dHQMzi
oEJuEnP5EH9Yu1p2mRatFCkvvjfam8JplyJIspX2A76DYxVcep81rvFdoFbhOqQ1
UZqh8nHUNTGfi3gfGiPo0WzRO2qXr9HkquMtumfNN4DHzt40i9jG/bRYvqUJ8hBD
VcFE4KUHj1tkUA88QA==
-----END CERTIFICATE-----
ENDOFKEY

Now encrypt a block/string of text:

$ /opt/puppetlabs/puppet/bin/eyaml encrypt -o block -s 'This is a test'
[hiera-eyaml-core] Loaded config from /home/jaklein/.eyaml/config.yaml
    ENC[PKCS7,MIIBeQYJKoZIhvcNAQcDoIIBajCCAWYCAQAxggEhMIIBHQIBADAFMAACAQEw
    DQYJKoZIhvcNAQEBBQAEggEAKw+YB/g+cMme9gbd8y6CcsR54ldKerC6DSnX
    K1sF9FJSGEEBNqzDxEQ7wNnyrYLtZHE8lvNf8WPnmtMuUpCSyWn7DfHXtkRI
    qqk6coLIKY4gEhCRzE/M1CPpVj6Q7XjizHuPX/kYotvGCb3Jc5OQHXVF2yM3
    LphiN4CyFvjuP3LdnjeID0CyWVKBYrZtNNU2NCKcrfeUnkJzfg1LNdeJkrLO
    JlqfzLyRE7cim0T8l3hrr/Lg4WTx4YeN43+672neWy2lcKAKGIz4DEMu9vWW
    ZaNJZvdHxggshUJnji8YeDUL+cI9tcWLXooh4Iik3VifJIgQARYL76MZD4k0
    PgPvvzA8BgkqhkiG9w0BBwEwHQYJYIZIAWUDBAEqBBAwoLZRpl4bNlVSlBJ5
    ZvWIgBCa50jHGK3UADdJxHMDCRpf]

NOTE: Use object type “block” for large things like cert keys, you can use “string” for smaller items

The ciphertext is everything from and including the 'ENC[PKCS7' piece all the way to the end 'DCRpf]'

Once you are done editing the eyaml file, you should probably check to see if you maintained proper YAML syntax.

$ /opt/puppetlabs/puppet/bin/ruby -e "require 'yaml'; YAML.load_file('secure.eyaml')"

Then git push that feature branch to NCSU github.

$ git push origin making_change_to_yaml

Then create a Pull Request through the Github Web UI.

hiera-eyaml Reference Materials

hiera-eyaml code and docs: https://github.com/TomPoulton/hiera-eyaml

“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.”

See also …

“Encrypt Your Data Using Hiera-Eyaml” from Puppet Labs: https://puppetlabs.com/blog/encrypt-your-data-using-hiera-eyaml

Wikipedia for PKCS: https://en.wikipedia.org/wiki/PKCS

Tags:
Edit me