salt.modules.gpg¶

Manage a GPG keychains, add keys, create keys, retrieve keys from keyservers. Sign, encrypt and sign & encrypt text and files.

New in version 2015.5.0.

Note

The python-gnupg library and gpg binary are required to be installed.

salt.modules.gpg.create_key(key_type='RSA', key_length=1024, name_real='Autogenerated Key', name_comment='Generated by SaltStack', name_email=None, subkey_type=None, subkey_length=None, expire_date=None, use_passphrase=False, user=None, gnupghome=None)¶

Create a key in the GPG keychain

Note

GPG key generation requires a lot of entropy and randomness. Difficult to do over a remote connection, consider having another process available which is generating randomness for the machine. Also especially difficult on virtual machines, consider the rng-tools package.

The create_key process takes awhile so increasing the timeout may be necessary, e.g. -t 15.

key_type: The type of the primary key to generate. It must be capable of signing. 'RSA' or 'DSA'.
key_length: The length of the primary key in bits.
name_real: The real name of the user identity which is represented by the key.
name_comment: A comment to attach to the user id.
name_email: An email address for the user.
subkey_type: The type of the secondary key to generate.
subkey_length: The length of the secondary key in bits.
expire_date: The expiration date for the primary and any secondary key. You can specify an ISO date, A number of days/weeks/months/years, an epoch value, or 0 for a non-expiring key.
use_passphrase: Whether to use a passphrase with the signing key. Passphrase is received from pillar.
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt -t 15 '*' gpg.create_key

salt.modules.gpg.decrypt(user=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None)¶

Decrypt a message or file

user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
text: The encrypted text to decrypt.
filename: The encrypted filename to decrypt.
output: The filename where the decrypted data will be written, default is standard out.
use_passphrase: Whether to use a passphrase with the signing key. Passphrase is received from pillar.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.decrypt filename='/path/to/important.file.gpg'

salt '*' gpg.decrypt filename='/path/to/important.file.gpg' use_pasphrase=True

salt.modules.gpg.delete_key(keyid=None, fingerprint=None, delete_secret=False, user=None, gnupghome=None)¶

Get a key from the GPG keychain

keyid: The keyid of the key to be deleted.
fingerprint: The fingerprint of the key to be deleted.
delete_secret: Whether to delete a corresponding secret key prior to deleting the public key. Secret keys must be deleted before deleting any corresponding public keys.
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.delete_key keyid=3FAD9F1E

salt '*' gpg.delete_key fingerprint=53C96788253E58416D20BCD352952C84C3252192

salt '*' gpg.delete_key keyid=3FAD9F1E user=username

salt '*' gpg.delete_key keyid=3FAD9F1E user=username delete_secret=True

salt.modules.gpg.encrypt(user=None, recipients=None, text=None, filename=None, output=None, sign=None, use_passphrase=False, gnupghome=None)¶

Encrypt a message or file

user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
recipients: The fingerprints for those recipient whom the data is being encrypted for.
text: The text to encrypt.
filename: The filename to encrypt.
output: The filename where the signed file will be written, default is standard out.
sign: Whether to sign, in addition to encrypt, the data. True to use default key or fingerprint to specify a different key to sign with.
use_passphrase: Whether to use a passphrase with the signing key. Passphrase is received from pillar.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.encrypt text='Hello there.  How are you?'

salt '*' gpg.encrypt filename='/path/to/important.file'

salt '*' gpg.encrypt filename='/path/to/important.file' use_pasphrase=True

salt.modules.gpg.export_key(keyids=None, secret=False, user=None, gnupghome=None)¶

Export a key from the GPG keychain

keyids: The keyid(s) of the key(s) to be exported. Can be specified as a comma separated string or a list. Anything which GnuPG itself accepts to identify a key - for example, the keyid or the fingerprint could be used.
secret: Export the secret key identified by the keyid information passed.
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.export_key keyids=3FAD9F1E

salt '*' gpg.export_key keyids=3FAD9F1E secret=True

salt '*' gpg.export_key keyid="['3FAD9F1E','3FBD8F1E']" user=username

salt.modules.gpg.get_key(keyid=None, fingerprint=None, user=None, gnupghome=None)¶

Get a key from the GPG keychain

keyid: The keyid of the key to be retrieved.
fingerprint: The fingerprint of the key to be retrieved.
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.get_key keyid=3FAD9F1E

salt '*' gpg.get_key fingerprint=53C96788253E58416D20BCD352952C84C3252192

salt '*' gpg.get_key keyid=3FAD9F1E user=username

salt.modules.gpg.get_secret_key(keyid=None, fingerprint=None, user=None, gnupghome=None)¶

Get a key from the GPG keychain

keyid: The keyid of the key to be retrieved.
fingerprint: The fingerprint of the key to be retrieved.
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.get_secret_key keyid=3FAD9F1E

salt '*' gpg.get_secret_key fingerprint=53C96788253E58416D20BCD352952C84C3252192

salt '*' gpg.get_secret_key keyid=3FAD9F1E user=username

salt.modules.gpg.import_key(user=None, text=None, filename=None, gnupghome=None)¶

Import a key from text or file

user

Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.

text

The text containing to import.

filename

The filename containing the key to import.

gnupghome

Specify the location where GPG related files are stored.

CLI Example:
salt '*' gpg.import_key text='-----BEGIN PGP PUBLIC KEY BLOCK-----

... -----END PGP PUBLIC KEY BLOCK-----': salt '*' gpg.import_key filename='/path/to/public-key-file'

salt.modules.gpg.list_keys(user=None, gnupghome=None)¶

List keys in GPG keychain

user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.list_keys

salt.modules.gpg.list_secret_keys(user=None, gnupghome=None)¶

List secret keys in GPG keychain

user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.list_secret_keys

salt.modules.gpg.receive_keys(keyserver=None, keys=None, user=None, gnupghome=None)¶

Receive key(s) from keyserver and add them to keychain

keyserver: Keyserver to use for searching for GPG keys, defaults to pgp.mit.edu
keys: The keyID(s) to retrieve from the keyserver. Can be specified as a comma separated string or a list.
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.

CLI Example:

salt '*' gpg.receive_key keys='3FAD9F1E'

salt '*' gpg.receive_key keys="['3FAD9F1E','3FBD9F2E']"

salt '*' gpg.receive_key keys=3FAD9F1E user=username

salt.modules.gpg.search_keys(text, keyserver=None, user=None)¶

Search keys from keyserver

text: Text to search the keyserver for, e.g. email address, keyID or fingerprint.
keyserver: Keyserver to use for searching for GPG keys, defaults to pgp.mit.edu
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.

CLI Example:

salt '*' gpg.search_keys user@example.com

salt '*' gpg.search_keys user@example.com keyserver=keyserver.ubuntu.com

salt '*' gpg.search_keys user@example.com keyserver=keyserver.ubuntu.com user=username

salt.modules.gpg.sign(user=None, keyid=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None)¶

Sign message or file

user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
keyid: The keyid of the key to set the trust level for, defaults to first key in the secret keyring.
text: The text to sign.
filename: The filename to sign.
output: The filename where the signed file will be written, default is standard out.
use_passphrase: Whether to use a passphrase with the signing key. Passphrase is received from pillar.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.sign text='Hello there.  How are you?'

salt '*' gpg.sign filename='/path/to/important.file'

salt '*' gpg.sign filename='/path/to/important.file' use_pasphrase=True

salt.modules.gpg.trust_key(keyid=None, fingerprint=None, trust_level=None, user=None)¶

Set the trust level for a key in GPG keychain

keyid: The keyid of the key to set the trust level for.
fingerprint: The fingerprint of the key to set the trust level for.
trust_level: The trust level to set for the specified key, must be one of the following: expired, unknown, not_trusted, marginally, fully, ultimately
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.

CLI Example:

salt '*' gpg.trust_key keyid='3FAD9F1E' trust_level='marginally'
salt '*' gpg.trust_key fingerprint='53C96788253E58416D20BCD352952C84C3252192' trust_level='not_trusted'
salt '*' gpg.trust_key keys=3FAD9F1E trust_level='ultimately' user='username'

salt.modules.gpg.verify(text=None, user=None, filename=None, gnupghome=None)¶

Verify a message or file

text: The text to verify.
filename: The filename to verify.
user: Which user's keychain to access, defaults to user Salt is running as. Passing the user as 'salt' will set the GPG home directory to /etc/salt/gpgkeys.
gnupghome: Specify the location where GPG related files are stored.

CLI Example:

salt '*' gpg.verify text='Hello there.  How are you?'

salt '*' gpg.verify filename='/path/to/important.file'

salt '*' gpg.verify filename='/path/to/important.file' use_pasphrase=True