salt.modules.gpg
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.
-
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 GnuPG home directory to the/etc/salt/gpgkeys
. - gnupghome
-
Specify the location where GPG keyring and related files are stored.
CLI Example:
salt -t 15 '*' gpg.create_key
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)
-
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 GnuPG home directory to the/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 keyring and related files are stored.
- bare
-
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.decrypt(user=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None, bare=False)
-
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 GnuPG home directory to the/etc/salt/gpgkeys
. - gnupghome
-
Specify the location where GPG keyring and related files are stored.
- use_passphrase
-
Whether to use a passphrase with the signing key. Passphrase is received from Pillar.
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.delete_key(keyid=None, fingerprint=None, delete_secret=False, user=None, gnupghome=None, use_passphrase=True)
-
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 GnuPG home directory to the/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 keyring and related files are stored.
- bare
-
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?' [email protected] salt '*' gpg.encrypt filename='/path/to/important.file' [email protected] salt '*' gpg.encrypt filename='/path/to/important.file' use_passphrase=True \ [email protected]
salt.modules.gpg.encrypt(user=None, recipients=None, text=None, filename=None, output=None, sign=None, use_passphrase=False, gnupghome=None, bare=False)
-
Export a key from the GPG keychain
- keyids
-
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.
- secret
-
Export the secret key identified by the
keyids
information passed. - user
-
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
. - gnupghome
-
Specify the location where GPG keyring and related files are stored.
- use_passphrase
-
Whether to use a passphrase with the signing key. Passphrase is received from Pillar.
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.export_key(keyids=None, secret=False, user=None, gnupghome=None, use_passphrase=False)
-
Get a key from the GPG keychain
- keyid
-
The key ID (short or long) 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 GnuPG home directory to the/etc/salt/gpgkeys
. - gnupghome
-
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_key(keyid=None, fingerprint=None, user=None, gnupghome=None)
-
Get a key from the GPG keychain
- keyid
-
The key ID (short or long) 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 GnuPG home directory to the/etc/salt/gpgkeys
. - gnupghome
-
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.get_secret_key(keyid=None, fingerprint=None, user=None, gnupghome=None)
-
Import a key from text or file
- text
-
The text containing to import.
- filename
-
The filename containing the key to import.
- user
-
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
. - gnupghome
-
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.import_key(text=None, filename=None, 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 GnuPG home directory to the/etc/salt/gpgkeys
. - gnupghome
-
Specify the location where GPG keyring and related files are stored.
CLI Example:
salt '*' gpg.list_keys
salt.modules.gpg.list_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 GnuPG home directory to the/etc/salt/gpgkeys
. - gnupghome
-
Specify the location where GPG keyring and related files are stored.
CLI Example:
salt '*' gpg.list_secret_keys
salt.modules.gpg.list_secret_keys(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 GnuPG home directory to the/etc/salt/gpgkeys
. - gnupghome
-
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.receive_keys(keyserver=None, keys=None, user=None, gnupghome=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 GnuPG home directory to the/etc/salt/gpgkeys
.
CLI Example:
salt '*' gpg.search_keys [email protected] salt '*' gpg.search_keys [email protected] keyserver=keyserver.ubuntu.com salt '*' gpg.search_keys [email protected] keyserver=keyserver.ubuntu.com user=username
salt.modules.gpg.search_keys(text, keyserver=None, user=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 GnuPG home directory to the/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 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.sign(user=None, keyid=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=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 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.trust_key(keyid=None, fingerprint=None, trust_level=None, user=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 GnuPG home directory to the/etc/salt/gpgkeys
. - gnupghome
-
Specify the location where GPG keyring and related files are stored.
- signature
-
Specify the filename of a detached signature.
New in version 2018.3.0.
- trustmodel
-
- Explicitly define the used trust model. One of:
-
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
salt.modules.gpg.verify(text=None, user=None, filename=None, gnupghome=None, signature=None, trustmodel=None)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.gpg.html