community.crypto.gpg_keypair module – Generate or delete GPG private and public keys

Note

This module is part of the community.crypto collection (version 2.20.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.crypto. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.crypto.gpg_keypair.

New in community.crypto 2.20.0

Synopsis

  • This module allows one to generate or delete GPG private and public keys using GnuPG (gpg).

Requirements

The below requirements are needed on the host that executes this module.

  • gpg >= 2.1

Parameters

Parameter

Comments

comment

string

Specifies a comment for the key’s user id.

email

string

Specifies an email for the key’s user id.

expire_date

string

Sets the expire date for the key.

If expire_date=0, the key never expires.

If expire_date=<n>, the key expires in n days.

If expire_date=<n>w, the key expires in n weeks.

If expire_date=<n>m, the key expires in n months.

If expire_date=<n>y, the key expires in n years.

If left unspecified, any created GPG keys never expire.

fingerprints

list / elements=string

Specifies keys to match against.

Default: []

force

boolean

If force=True, key generation is executed using the module’s options, even a matching key is found.

This parameter does not override check_mode.

This parameter is ignored if state=absent.

Choices:

  • false ← (default)

  • true

key_curve

string

For ECC keys, this specifies the curve used to generate the keys.

If key_type=EDDSA, key_curve=ed25519 is required.

If key_curve=ed25519 is only supported if key_type=EDDSA.

This is required if key_type=ECDSA or key_type=EDDSA and it is ignored if key_type=RSA or key_type=DSA.

Choices:

  • "nistp256"

  • "nistp384"

  • "nistp521"

  • "brainpoolP256r1"

  • "brainpoolP384r1"

  • "brainpoolP512r1"

  • "secp256k1"

  • "ed25519"

key_length

integer

For non-ECC keys, this specifies the number of bits in the key to create.

For RSA keys, the minimum is 1024, the maximum is 4096, and the default is 3072.

For DSA keys, the minimum is 768, the maximum is 3072, and the default is 2048.

As per gpg’s behavior, values below the allowed ranges will be set to the respective defaults, and values above will saturate at the maximum.

key_type

string

Specifies the type of key to create.

Choices:

  • "RSA"

  • "DSA"

  • "ECDSA"

  • "EDDSA"

key_usage

list / elements=string

Specifies usage(s) for key.

cert is given to all primary keys regardess, however can be used to only give vert usage to a key.

If not usage is specified, all of valid usages for the given key type are assigned.

key_usage=encrypt is only supported is key_type=RSA.

Choices:

  • "encrypt"

  • "sign"

  • "auth"

  • "cert"

Default: []

name

string

Specifies a name for the key’s user id.

passphrase

string

Passphrase used to decrypt an existing private key or encrypt a newly generated private key.

state

string

Whether the private and public keys should exist or not, taking action if the state is different from what is stated.

Choices:

  • "present" ← (default)

  • "absent"

subkeys

list / elements=dictionary

List of subkeys with their own respective key types, lengths, curves, and usages.

Default: []

subkey_curve

string

Similar to key_curve.

cv25519 is supported if subkey_type is ECDH.

This is required if subkey_type is ECDSA, EDDSA, or ECDH and it is ignored if subkey_type is RSA, DSA, or ELG.

Choices:

  • "nistp256"

  • "nistp384"

  • "nistp521"

  • "brainpoolP256r1"

  • "brainpoolP384r1"

  • "brainpoolP512r1"

  • "secp256k1"

  • "ed25519"

  • "cv25519"

subkey_length

integer

Similar to key_length.

For ELG subkeys, the minimum length is 1024 bits, the maximum length is 4096 bits, and the default length is 3072 bits.

subkey_type

string

Similar to key_type.

Also supports ECDH and ELG keys.

Choices:

  • "RSA"

  • "DSA"

  • "ECDSA"

  • "EDDSA"

  • "ECDH"

  • "ELG"

subkey_usage

list / elements=string

Similar to key_usage.

encrypt is supported if subkey_type is RSA, ECDH, or ELG.

If subkey_type is ECDH or ELG, only encrypt is supported.

Choices:

  • "encrypt"

  • "sign"

  • "auth"

Default: []

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

  • If a user-id is provided, the module’s options are matched against all keys with said user-id.

  • If a fingerprint is provided but no user-id is provided, the module’s options are matched against the fingerprint(s).

  • If neither a fingerprint or user-id is provided, the module’s options are matched against all keys.

Examples

- name: Generate the default GPG keypair
  community.crypto.gpg_keypair:

- name: Generate the default GPG keypair with a passphrase
  community.crypto.gpg_keypair:
    passphrase: '{{ passphrase }}'

- name: Generate a RSA GPG keypair with the default RSA size (2048 bits)
  community.crypto.gpg_keypair:
    key_type: RSA

- name: Generate a RSA GPG keypair with custom size (4096 bits)
  community.crypto.gpg_keypair:
    key_type: RSA
    key_length: 4096

- name: Generate an ECC GPG keypair
  community.crypto.gpg_keypair:
    key_type: EDDSA
    key_curve: ed25519

- name: Generate a GPG keypair and with a subkey
  community.crypto.gpg_keypair:
    subkeys:
        - { subkey_type: ECDH, subkey_curve: cv25519 }

- name: Generate a GPG keypair with custom user-id
  community.crypto.gpg_keypair:
    name: name
    comment: comment
    email: name@email.com

- name: Delete a GPG keypair matching a specified fingerprint
  community.crypto.gpg_keypair:
    state: absent
    fingerprints:
      - ABC123...

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

changed

boolean

Indicates if changes were made to GPG keyring.

Returned: success

Sample: true

fingerprints

list / elements=string

Fingerprint(s) of matching, created, or deleted primary key(s).

Returned: success

Sample: ["ABC123..."]

Authors

  • Austin Lucas Lake (@austinlucaslake)