Table of Contents generated with DocToc
Notice: The default secret key location is now /etc/puppet-decrypt/encryptor_secret_key
Puppet Decrypt is a gem that gives puppet the ability to encrypt and decrypt strings. This is useful for making sure secret data - like database passwords - remains secret. It uses a model similar to jasypt Encrypting Application Configuration Files or Maven Password Encryption. It is a simple alternative to the Secret variables in Puppet with Hiera and GPG approach.
- Store encrypted secret variables and related non-secret variables in the same file.
- Version control friendly - you can easily see when a variable was added, changed, or removed even if you don't know the exact value.
- Works with any data source. Combine it with Hiera, extlookup, external node classifiers, exported resources, or any other source of data.
- Simple administration - no keyring management.
- Uses a shared secret instead of asymetric keypairs. This means that the "master password" is shared by all admins. It is also shared by all machines that need to decrypt the same value (usually machines in the same environment).
- Less integrated with Hiera. You need to wrap calls as decrypt(hiera('my_db_password')).
The shared secret "master password" may seem more difficult to grant and revoke access than the asymetric keypair approach used by hiera-gpg. However both systems are protecting shared secret data! So if you want to fully revoke someone's access you need to change or revoke their decryption key (which is easier with hiera-gpg) AND to change any secrets that key protected (e.g.: your production database passwords).
It should be possible to install via a Gem in Puppet 3+. However, this method is easier, but does seem to have some quirks. If you have any issues, try installing as a module instead.
Add this line to your application's Gemfile:
And then execute:
Or install it yourself as:
$ gem install puppet-decrypt
If installing as a module, you'll need to deal with the Gem prerequisites manually.
$ gem install encryptor
Puppet Decrypt can be installed with the puppet module subcommand, which is included in Puppet 2.7.14 and later.
$ sudo puppet module install devopsy-puppet_decrypt
The command will tell you where it is installing the module; take note:
$ sudo puppet module install devopsy/puppet_decrypt warning: iconv couldn't be loaded, which is required for UTF-8/UTF-16 conversions Preparing to install into /etc/puppet/modules ... Downloading from http://forge.puppetlabs.com ... Installing -- do not interrupt ... /etc/puppet/modules └── devopsy-puppet_decrypt (v0.1.0)
After installing it, you must add the lib directory of the module to your $RUBYLIB. Add the following to your .profile file (replacing /etc/puppet/modules with the directory from the install command, if necessary), then run source ~/.profile to re-load it in the current shell:
You can verify that it is installed and usable by running:
# puppet help crypt
Put the secret key in /etc/puppet-decrypt/encryptor_secret_key on machines where puppet needs to decrypt the value. Make sure the file's read permissions are restricted!
Use the puppet face to encrypt a value
$ puppet crypt encrypt my_secret_value ENC[ANN3I3AWxXWmr5QAW3qgxw==]
Or to decrypt a value
$ puppet crypt decrypt ENC[ANN3I3AWxXWmr5QAW3qgxw==] my_secret_value
Put that value into hiera, extlookup, or any other data source you want. Hiera example:
In your puppet code, load the value normally and then pass it to decrypt.
Or encrypt a secret passing it to encrypt, if you need to save the secret to external storage, for example.
$encrypted_secret_to_save = encrypt($data)
Puppet Decrypt now supports using more than just the default secret key location. You can easily use multiple secret keys for the same project.
For the Puppet face, you just use the --secretkey option to pass an alternate secret key location.
$ echo 'example' > alt_key.txt $ puppet crypt encrypt abc123 --secretkey alt_key ENC[c4S4hMCDv1b7FkZgOBRTOA==] $ puppet crypt decrypt ENC[c4S4hMCDv1b7FkZgOBRTOA==] --secretkey alt_key abc123
There are two ways to use the alternate keys from the function. You can pass it it as part of the string in this format:
If you do that, instead of using the default secret key, it will look for alt_key in the same directory. So instead of /etc/puppet-decrypt/encryptor_secret_key it will use /etc/puppet-decrypt/alt_key.
Alternately, you can pass a hash to the function, containing a value and a secret key, like this:
db_password: value: 'ENC[G6MjBDDFcapYLaKBFJvPSg==]' secretkey: '/any/path/you/another/key'
This has the advantage of letting you place keys in alternate directories, not just /etc/puppet-decrypt.
If you use this alongside hiera, you can just switch the lookup from hiera to hiera-hash:
See features/hiera.feature for complete examples.
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request
- Added an encrypt function (thanks @tioteath!)
- Fixed handling of absolute paths for to the secret key file (thanks @tioteath!)
- Removed unnecessary puts (thanks @tioteath!)
- Improved error handling (thanks @tioteath!)
- Salting to protect against dictionary and rainbow table attacks.
- Fix Ruby 1.8.7 support.
- support alternate secret keys
- override the key as part of the string in the format ENC:another_key[...]
- override the key by passing a hash containing value and secret_key
- Explicitly remove Ruby 1.8.7 support. Previously it would install but not work with Ruby 1.8.7.
- puppet face for encrypting/decrypting secrets
- basic puppet function for decrypting a secret, using a master key