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.21.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
python-dateutil >= 2.7.0

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. Also excepts dates in ISO formats. If left unspecified, any created GPG keys never expire. This module will fail if an unsupported format for `expire_date` is provided. This module will fail if `expire_date` is provided, the python-dateutil package is not found, and `install_dateutil=false`. This module will fail if `expire_date` is provided, the python-dateutil package is not found, `install_dateutil=true`, and check_mode is true.
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` `true` ← (default)
install_dateutil string	Specifies whether or not to try to install python-dateutil package if not found.
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 parameter is required if `key_type=ECDSA` or `key_type=EDDSA`. This parameter is ignored if `key_type=RSA` or `key_type=DSA`. This module will fail if an unsupported `key_curve` is provided for the given `key_type`. Choices: `"nistp256"` `"nistp384"` `"nistp521"` `"brainpoolP256r1"` `"brainpoolP384r1"` `"brainpoolP512r1"` `"secp256k1"` `"ed25519"`
key_size aliases: key_length integer	For non-ECC keys, this specifies the number of bits in the key to create. If `key_type=RSA`, the minimum is `1024`, the maximum is `4096`, and the default is `3072`. IF `key_type=DSA`, 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 `key_usage` is not specified, all of valid usages for the given `key_type` are assigned. `key_usage=encr` is only supported if `key_type=RSA`. This module will fail if an unsupported `key_usage` is provided for the given `key_type`. Choices: `"encr"` `"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. This module will fail if `state=present`, and neither `name`, `comment`, or `email` are provided. This module will fail if `state=present`, and neither `name`, `comment`, `email`, `fingerprints` are provided. Choices: `"present"` ← (default) `"absent"`
subkeys list / elements=dictionary	List of subkeys with their own respective key types, lengths, curves, and usages. Default: `[]`
key_curve string	Similar to `key_curve`. `subkeys[].key_curve=cv25519` is supported if `subkeys[].key_type=ECDH`. This parameter is required if `subkeys[].key_type` is `ECDSA`, `EDDSA`, or `ECDH`. This parameter is ignored if `subkeys[].key_type` is `RSA`, `DSA`, or `ELG`. This module will fail if an unsupported `subkeys[].key_curve` is provided for the given `subkeys[].key_type`. Choices: `"nistp256"` `"nistp384"` `"nistp521"` `"brainpoolP256r1"` `"brainpoolP384r1"` `"brainpoolP512r1"` `"secp256k1"` `"ed25519"` `"cv25519"`
key_size aliases: key_length integer	Similar to `key_size`. If `subkeys[].key_type=ELG`, the minimum is `1024` bits, the maximum is `4096` bits, and the default is `3072` bits.
key_type string	Similar to `key_type`. Also supports ECDH and ELG keys. Choices: `"RSA"` `"DSA"` `"ECDSA"` `"EDDSA"` `"ECDH"` `"ELG"`
key_usage list / elements=string	Similar to `key_usage`. `encr` is supported if `subkeys[].key_type` is `RSA`, `ECDH`, or `ELG`. If `subkeys[].key_type` is `ECDH` or `ELG`, only `encr` is supported. This module will fail if an unsupported `subkeys[].key_usage` is provided for the given `subkeys[].key_type`. Choices: `"encr"` `"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.
Matched parameters only include those in which an user has specified.
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_size: 4096

-~/.local/share/nvim/swap/ 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:
        - { key_type: ECDH, key_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)

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

Synopsis

Requirements

Parameters

Attributes

Notes

Examples

Return Values