# community.crypto.gpg_keypair module – Generate or delete GPG private and public keys — Community.Crypto Collection documentation

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

### Collection links

- Issue Tracker
- Repository (Sources)
- Submit a bug report
- Request a feature
- Communication