Manage a GPG keychains, add keys, create keys, retrieve keys from keyservers. Sign, encrypt and sign plus 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.
The type of the primary key to generate. It must be capable of signing. 'RSA' or 'DSA'.
The length of the primary key in bits.
The real name of the user identity which is represented by the key.
A comment to attach to the user id.
An email address for the user.
The type of the secondary key to generate.
The length of the secondary key in bits.
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.
Whether to use a passphrase with the signing key. Passphrase is received from Pillar.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and 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, bare=False)¶Decrypt a message or file
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
The encrypted text to decrypt.
The encrypted filename to decrypt.
The filename where the decrypted data will be written, default is standard out.
Whether to use a passphrase with the signing key. Passphrase is received from Pillar.
Specify the location where GPG keyring and related files are stored.
If True
, return the (armored) decrypted block as a string without the
standard comment/res dict.
CLI Example:
salt '*' gpg.decrypt filename='/path/to/important.file.gpg'
salt '*' gpg.decrypt filename='/path/to/important.file.gpg' use_passphrase=True
salt.modules.gpg.
delete_key
(keyid=None, fingerprint=None, delete_secret=False, user=None, gnupghome=None)¶Get a key from the GPG keychain
The keyid of the key to be deleted.
The fingerprint of the key to be deleted.
Whether to delete a corresponding secret key prior to deleting the public key. Secret keys must be deleted before deleting any corresponding public keys.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and 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, bare=False)¶Encrypt a message or file
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
The fingerprints for those recipient whom the data is being encrypted for.
The text to encrypt.
The filename to encrypt.
The filename where the signed file will be written, default is standard out.
Whether to sign, in addition to encrypt, the data. True
to use
default key or fingerprint to specify a different key to sign with.
Whether to use a passphrase with the signing key. Passphrase is received from Pillar.
Specify the location where GPG keyring and related files are stored.
If True
, return the (armored) encrypted block as a string without
the standard comment/res dict.
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_passphrase=True
salt.modules.gpg.
export_key
(keyids=None, secret=False, user=None, gnupghome=None)¶Export a key from the GPG keychain
The key ID(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 key ID or the fingerprint could be used.
Export the secret key identified by the keyids
information passed.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and related files are stored.
CLI Example:
salt '*' gpg.export_key keyids=3FAD9F1E
salt '*' gpg.export_key keyids=3FAD9F1E secret=True
salt '*' gpg.export_key keyids="['3FAD9F1E','3FBD8F1E']" user=username
salt.modules.gpg.
get_key
(keyid=None, fingerprint=None, user=None, gnupghome=None)¶Get a key from the GPG keychain
The key ID (short or long) of the key to be retrieved.
The fingerprint of the key to be retrieved.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and 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
The key ID (short or long) of the key to be retrieved.
The fingerprint of the key to be retrieved.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and 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
(text=None, filename=None, user=None, gnupghome=None)¶Import a key from text or file
The text containing to import.
The filename containing the key to import.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and related files are stored.
CLI Example:
salt '*' gpg.import_key text='-----BEGIN PGP PUBLIC KEY BLOCK-----\n ... -----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
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and 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
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and 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 to use for searching for GPG keys, defaults to pgp.mit.edu
The keyID(s) to retrieve from the keyserver. Can be specified as a comma separated string or a list.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and related files are stored.
CLI Example:
salt '*' gpg.receive_keys keys='3FAD9F1E'
salt '*' gpg.receive_keys keys="['3FAD9F1E','3FBD9F2E']"
salt '*' gpg.receive_keys keys=3FAD9F1E user=username
salt.modules.gpg.
search_keys
(text, keyserver=None, user=None)¶Search keys from keyserver
Text to search the keyserver for, e.g. email address, keyID or fingerprint.
Keyserver to use for searching for GPG keys, defaults to pgp.mit.edu.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/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
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
The keyid of the key to set the trust level for, defaults to first key in the secret keyring.
The text to sign.
The filename to sign.
The filename where the signed file will be written, default is standard out.
Whether to use a passphrase with the signing key. Passphrase is received from Pillar.
Specify the location where GPG keyring and 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_passphrase=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
The keyid of the key to set the trust level for.
The fingerprint of the key to set the trust level for.
The trust level to set for the specified key, must be one of the following: expired, unknown, not_trusted, marginally, fully, ultimately
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/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, signature=None, trustmodel=None)¶Verify a message or file
The text to verify.
The filename to verify.
Which user's keychain to access, defaults to user Salt is running as.
Passing the user as salt
will set the GnuPG home directory to the
/etc/salt/gpgkeys
.
Specify the location where GPG keyring and related files are stored.
Specify the filename of a detached signature.
New in version 2018.3.0.
pgp
classic
tofu
tofu+pgp
direct
always
auto
New in version 2019.2.0.
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_passphrase=True
salt '*' gpg.verify filename='/path/to/important.file' trustmodel=direct