Skip to content

linuxfabrik.lfops.gpg_key

Find or create a GPG private key

Synopsis

  • Ensures that a GPG private key matching the given attributes exists on the host. Lists all secret keys via gpg and matches them against the supplied options. If a matching key is found, it is returned as is; otherwise a new one is generated.
  • The uid of an existing key is parsed back into its name_real, name_comment and name_email parts and compared against the parameters; key type, key length and (if present) subkey type and subkey length must match as well.
  • When the key has subkeys, at least one subkey must match subkey_type and subkey_length; GPG's unattended generator can only create a single subkey per key but more can be added later, hence the partial match.
  • The passphrase is never used to decide whether a key matches, since it is not visible in the secret key listing.
  • On success, the module returns the matched or newly generated key (the same dict shape as python-gnupg's list_keys(,https://gnupg.readthedocs.io/en/latest/#listing-keys)) plus the ASCII-armored exports of the private and public key.
  • Internally relies on https://github.com/vsajip/python-gnupg.

Available since LFOps 1.0.0.

Requirements

  • GNU Privacy Guard command line tool gpg on the host where the module runs.
  • No separate python-gnupg install is required: a copy of the library is bundled with the collection and shipped together with the module.

Optional Parameters

gnupghome

  • Path to the GnuPG home directory. When unset, falls back to whatever gpg itself uses (typically $HOME/.gnupg). The directory is created with mode 0o700 if it does not exist.
  • Type: Path.

gpgbinary

  • Name of, or path to, the gpg executable.
  • Type: String.
  • Default: gpg

key_length

  • Key length in bits. Used both as a match criterion against existing keys and as the bit length for newly generated keys.
  • Type: Number.
  • Default: 1024

key_type

  • Key algorithm. Used both as a match criterion (compared against the human-readable algorithm name RSA, DSA, Elgamal, ECDH, ECDSA) and as the algorithm for newly generated keys.
  • Type: String.
  • Default: RSA

name_comment

  • Comment portion of the GPG user ID (the text in parentheses).
  • Type: String.
  • Default: Generated by Ansible.

name_email

  • Email portion of the GPG user ID (the text in angle brackets).
  • Type: String.
  • Default: info@example.com

name_real

  • Real-name portion of the GPG user ID (the text before the comment / email).
  • Type: String.
  • Default: Autogenerated Key

passphrase

  • Passphrase for the secret key. When empty (the default), the generated key is unprotected (no_protection). Never used to decide whether an existing key matches.
  • Type: String.

subkey_length

  • Length in bits of the (single) subkey to generate, and to match against existing subkeys. Only meaningful together with subkey_type.
  • Type: Number.

subkey_type

  • Algorithm of the (single) subkey to generate, and to match against existing subkeys. Only meaningful together with subkey_length.
  • Type: String.

Examples

- name: 'Generate a GPG key by using the defaults'
  linuxfabrik.lfops.gpg_key:
  register: gpg_key

- ansible.builtin.debug:
    var: gpg_key

- name: 'Generate gpg key'
  linuxfabrik.lfops.gpg_key:
    name_real: 'My name'
    name_email: '{{ ansible_facts["user_id"] }}@{{ ansible_facts["nodename"] }}'
    key_type: 'RSA'
    key_length: 4096
    passphrase: 'secret-passphrase'
    subkey_type: 'RSA'
    subkey_length: 4096
  register: gpg_key

Return Values

ascii_armored_private_key

  • ASCII-armored export of the private key.
  • Type: String.
  • Returned: success.
  • Sample: -----BEGIN PGP PRIVATE KEY BLOCK-----\n\n...\n-----END PGP PRIVATE KEY BLOCK-----\n

ascii_armored_public_key

  • ASCII-armored export of the public key.
  • Type: String.
  • Returned: success.
  • Sample: -----BEGIN PGP PUBLIC KEY BLOCK-----\n\n...\n-----END PGP PUBLIC KEY BLOCK-----\n

key

  • The matched or newly generated GPG key, in the dict shape returned by python-gnupg's list_keys(,https://gnupg.readthedocs.io/en/latest/#listing-keys).
  • Type: Dictionary.
  • Returned: success.

Notes

  • Only a small subset of the available GPG options is exposed (single name/email/comment, key type, key length, optional one subkey, optional passphrase). Issues and pull requests for additional options are welcome.
  • If multiple keys match the supplied options, the module fails because it cannot decide which one to return.
  • In check mode, the module reports changed=true when no matching key is found, but it does not generate one.

Authors

  • Linuxfabrik GmbH, Zurich, Switzerland, https://www.linuxfabrik.ch