# 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.

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 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.decrypt(user=None, text=None, filename=None, output=None, use_passphrase=False, gnupghome=None, bare=False)

  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.delete_key(keyid=None, fingerprint=None, delete_secret=False, user=None, gnupghome=None, use_passphrase=True)

  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.

    New in version 3003.

  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

  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?' recipients=recipient@example.com

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

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

salt.modules.gpg.export_key(keyids=None, secret=False, user=None, gnupghome=None, use_passphrase=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.

    New in version 3003.

  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

  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_secret_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.import_key(text=None, filename=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.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 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_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 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.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 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.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 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

  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.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 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

  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