salt.renderers.gpg¶

New Key Pair¶

To create a new GPG key pair for encrypting data, log in to the master as root and run the following:

# mkdir -p /etc/salt/gpgkeys
# chmod 0700 /etc/salt/gpgkeys
# gpg --homedir /etc/salt/gpgkeys --gen-key

Do not supply a password for the keypair and use a name that makes sense for your application.

The new keys can be seen and verified using --list-secret-keys:

# gpg --homedir /etc/salt/gpgkeys --list-secret-keys
/etc/salt/gpgkeys/pubring.kbx
-----------------------------
sec   rsa4096 2002-05-12 [SC] [expires: 2012-05-10]
      2DC47B416EE8C3484450B450A4D44406274AF44E
uid           [ultimate] salt-master (gpg key for salt) <salt@cm.domain.tld>
ssb   rsa4096 2002-05-12 [E] [expires: 2012-05-10]

In the example above, our KEY-ID is 2DC47B416EE8C3484450B450A4D44406274AF44E.

Export Public Key¶

To export a public key suitable for public distribution:

# gpg --homedir /etc/salt/gpgkeys --armor --export <KEY-ID> > exported_pubkey.asc

Import Public Key¶

Users wishing to import the public key into their local keychain may run:

$ gpg --import exported_pubkey.asc

Export (Save) Private Key¶

This key protects all gpg-encrypted pillar data and should be backed up to a safe and secure location. This command will generate a backup of secret keys in the /etc/salt/gpgkeys directory to the gpgkeys.secret file:

# gpg --homedir /etc/salt/gpgkeys --export-secret-keys --export-options export-backup -o gpgkeys.secret

Salt does not support password-protected private keys, which means this file is essentially a clear-text password (just add --armor). Fortunately, it is trivial to pass this export back to gpg to be encrypted with symmetric key:

# gpg --homedir /etc/salt/gpgkeys --export-secret-keys --export-options export-backup | gpg --symmetric -o gpgkeys.gpg

Import (Restore) Private Key¶

To import/restore a private key, create a directory with the correct permissions and import using gpg.

# mkdir -p /etc/salt/gpgkeys
# chmod 0700 /etc/salt/gpgkeys
# gpg --homedir /etc/salt/gpgkeys --import gpgkeys.secret

If the export was encrypted using a symmetric key, then decrypt first with:

# gpg --decrypt gpgkeys.gpg | gpg --homedir /etc/salt/gpgkeys --import

Adjust trust level of imported keys¶

In some cases, importing existing keys may not be enough and the trust level of the key needs to be adjusted. This can be done by editing the key. The KEY-ID and the actual trust level of the key can be seen by listing the already imported keys.

If the trust-level is not ultimate it needs to be changed by running

gpg --homedir /etc/salt/gpgkeys --edit-key <KEY-ID>

This will open an interactive shell for the management of the GPG encryption key. Type trust to be able to set the trust level for the key and then select 5 (I trust ultimately). Then quit the shell by typing save.

Replacing Newlines¶

To pass encrypted pillar data on the CLI, the ciphertext must have its newlines replaced with a literal backslash-n (\n), as newlines are not supported within Salt CLI arguments. There are a number of ways to do this:

With awk or Perl:

# awk
ciphertext=`echo -n "supersecret" | gpg --armor --batch --trust-model always --encrypt -r user@domain.com | awk '{printf "%s\\n",$0} END {print ""}'`
# Perl
ciphertext=`echo -n "supersecret" | gpg --armor --batch --trust-model always --encrypt -r user@domain.com | perl -pe 's/\n/\\n/g'`

With Python:

import subprocess

secret, stderr = subprocess.Popen(
    ['gpg', '--armor', '--batch', '--trust-model', 'always', '--encrypt',
     '-r', 'user@domain.com'],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE).communicate(input='supersecret')

if secret:
    print(secret.replace('\n', r'\n'))
else:
    raise ValueError('No ciphertext found: {0}'.format(stderr))

ciphertext=`python /path/to/script.py`

The ciphertext can be included in the CLI pillar data like so:

salt myminion state.sls secretstuff pillar_enc=gpg pillar="{secret_pillar: '$ciphertext'}"

The pillar_enc=gpg argument tells Salt that there is GPG-encrypted pillar data, so that the CLI pillar data is passed through the GPG renderer, which will iterate recursively though the CLI pillar dictionary to decrypt any encrypted values.

Encrypting the Entire CLI Pillar Dictionary¶

If several values need to be encrypted, it may be more convenient to encrypt the entire CLI pillar dictionary. Again, this can be done in several ways:

With awk or Perl:

# awk
ciphertext=`echo -n "{'secret_a': 'CorrectHorseBatteryStaple', 'secret_b': 'GPG is fun!'}" | gpg --armor --batch --trust-model always --encrypt -r user@domain.com | awk '{printf "%s\\n",$0} END {print ""}'`
# Perl
ciphertext=`echo -n "{'secret_a': 'CorrectHorseBatteryStaple', 'secret_b': 'GPG is fun!'}" | gpg --armor --batch --trust-model always --encrypt -r user@domain.com | perl -pe 's/\n/\\n/g'`

With Python:

import subprocess

pillar_data = {'secret_a': 'CorrectHorseBatteryStaple',
               'secret_b': 'GPG is fun!'}

secret, stderr = subprocess.Popen(
    ['gpg', '--armor', '--batch', '--trust-model', 'always', '--encrypt',
     '-r', 'user@domain.com'],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE).communicate(input=repr(pillar_data))

if secret:
    print(secret.replace('\n', r'\n'))
else:
    raise ValueError('No ciphertext found: {0}'.format(stderr))

ciphertext=`python /path/to/script.py`

With the entire pillar dictionary now encrypted, it can be included in the CLI pillar data like so:

salt myminion state.sls secretstuff pillar_enc=gpg pillar="$ciphertext"

Configuration¶

The default behaviour of this renderer is to log a warning if a block could not be decrypted; in other words, it just returns the ciphertext rather than the encrypted secret.

This behaviour can be changed via the gpg_decrypt_must_succeed configuration option. If set to True, any gpg block that cannot be decrypted raises a SaltRenderError exception, which registers an error in _errors during rendering.

In the Chlorine release, the default behavior will be reversed and an error message will be added to _errors by default.