You are viewing docs from the master branch, some of these features are not yet released.

salt.modules.gpg¶

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

New in version 2015.5.0.

Note

The python-gnupg library and gpg binary are required to be installed. Be aware that the alternate gnupg and pretty-bad-protocol libraries are not supported.

Changed in version 3008.0: When gnupghome is not set explicitly, this module now tries to respect a custom GNUPGHOME environmental variable. If a user is not passed, the current process' environment is queried, otherwise the user's configured shell environment is taken as a reference in the same way the cmd modules operate.

class salt.modules.gpg.FixedVerify(gpg)¶

This is a workaround for https://github.com/vsajip/python-gnupg/issues/214. It ensures invalid or otherwise unverified signatures are not merged into sig_info in any way.

https://github.com/vsajip/python-gnupg/commit/ee94a7ecc1a86484c9f02337e2bbdd05fd32b383

handle_status(key, value)¶

Handle status messages from the gpg child process. These are lines of the format

[GNUPG:] <key> <value>

Parameters:

key (str) -- Identifies what the status message is.
value (str) -- Identifies additional data, which differs depending on the 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, keyring=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. The passphrase is retrieved from the Pillar key gpg_passphrase.
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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, keyring=None)¶

Decrypt a message or a 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 /etc/salt/gpgkeys.
text: The encrypted text to decrypt.
filename: The path of the encrypted file to decrypt.
output: Instead of printing to standard out, write the output to this path.
use_passphrase: Whether to use a passphrase with the signing key. The passphrase is retrieved from Pillar value gpg_passphrase.
gnupghome: Specify the location where the GPG keyring and related files are stored.
bare: If True, return the (armored) decrypted block as a string without the standard comment/res dict.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, use_passphrase=True, keyring=None)¶

Delete 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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
use_passphrase: Whether to use a passphrase with the signing key. The passphrase is retrieved from the Pillar key gpg_passphrase. Note that this defaults to True here, contrary to the rest of the module functions that provide this parameter.

New in version 3003.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, always_trust=False, gnupghome=None, bare=False, keyring=None)¶

Encrypt a message or a 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 /etc/salt/gpgkeys.
recipients: The key ID, fingerprint, user ID or email address associated with the recipients key can be used.
text: The text to encrypt.
filename: The path of the file to encrypt.
output: Instead of printing to standard out, write the output to this path.
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. The passphrase is retrieved from the Pillar key gpg_passphrase.
always_trust: Skip key validation and assume that used keys are fully trusted.

New in version 3006.0.
gnupghome: Specify the location where the GPG keyring and related files are stored.
bare: If True, return the (armored) encrypted block as a string without the standard comment/res dict.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

CLI Example:

salt '*' gpg.encrypt text='Hello there.  How are you?' recipients=recipient@example.com

salt '*' gpg.encrypt filename='/path/to/important.file' recipients=recipient@example.com

salt '*' gpg.encrypt filename='/path/to/important.file' sign=True use_passphrase=True \
                     recipients=recipient@example.com

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

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, fingerprint, user ID or email address 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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
use_passphrase: Whether to use a passphrase to export the secret key. The passphrase is retrieved from the Pillar key gpg_passphrase.

New in version 3003.
output: Instead of printing to standard out, write the output to this path.

New in version 3006.0.
bare: If True, return the (armored) exported key block as a string without the standard comment/res dict.

New in version 3006.0.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, keyring=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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, keyring=None)¶

Get a secret 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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, keyring=None, select=None)¶

Import a key from text or a file

text: The text containing the key to import.
filename: The path of the file 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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.
select: Limit imported keys to a (list of) known identifier(s). This can be anything which GnuPG uses to identify keys like fingerprints, key IDs or email addresses.

New in version 3008.0.

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, keyring=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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

CLI Example:

salt '*' gpg.list_keys

salt.modules.gpg.list_secret_keys(user=None, gnupghome=None, keyring=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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

CLI Example:

salt '*' gpg.list_secret_keys

salt.modules.gpg.read_key(path=None, text=None, fingerprint=None, keyid=None, user=None, gnupghome=None)¶

New in version 3008.0.

Read key(s) from the filesystem or a string.

CLI Example:

salt '*' gpg.read_key /tmp/my-shiny-key.asc

path: The path to the key file to read. Either this or text is required.
text: The string to read the key from. Either this or path is required.

Note

Requires python-gnupg v0.5.1.
fingerprint: Only return key information if it matches this fingerprint.
keyid: Only return key information if it matches this keyid.
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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.

Important

This can accidentally decrypt data on GnuPG versions below 2.1 if the file is not a keyring.

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

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

keyserver: Keyserver to use for searching for GPG keys, defaults to keys.openpgp.org
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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, gnupghome=None)¶

Search for keys on a 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 keys.openpgp.org.
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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.

New in version 3007.0.

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, keyring=None)¶

Sign a message or a 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 /etc/salt/gpgkeys.
keyid: The keyid of the key to use for signing, defaults to the first key in the secret keyring.
text: The text to sign.
filename: The path of the file to sign.
output: Instead of printing to standard out, write the output to this path.
use_passphrase: Whether to use a passphrase with the signing key. The passphrase is retrieved from the Pillar key gpg_passphrase.
gnupghome: Specify the location where the GPG keyring and related files are stored.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, gnupghome=None, keyring=None)¶

Set the trust level for a key in the 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 /etc/salt/gpgkeys.
gnupghome: Specify the location where the GPG keyring and related files are stored.

New in version 3007.0.
keyring: Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.0.

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, signed_by_any=None, signed_by_all=None, keyring=None)¶

Verify a message or a file

text

The text to verify.

filename

The path of the file 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 /etc/salt/gpgkeys.

gnupghome

Specify the location where the GPG keyring and related files are stored.

signature

Specify the path 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.

signed_by_any

A list of key fingerprints from which any valid signature will mark verification as passed. If none of the provided keys signed the data, verification will fail. Optional. Note that this does not take into account trust.

New in version 3007.0.

signed_by_all

A list of key fingerprints whose signatures are required for verification to pass. If a single provided key did not sign the data, verification will fail. Optional. Note that this does not take into account trust.

New in version 3007.0.

keyring

Limit the operation to this specific keyring, specified as a local filesystem path.

New in version 3007.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' trustmodel=direct

Generated on October 23, 2024 at 09:06:04 UTC.

You are viewing docs built from a recent snapshot of the master branch. Switch to docs for the latest stable release, 3007.1.

saltproject.io