You are reading an unmaintained version of the Ansible documentation. Unmaintained Ansible versions can contain unfixed security vulnerabilities (CVE). Please upgrade to a maintained version. See the latest Ansible documentation.

community.crypto.openssl_publickey – Generate an OpenSSL public key from its private key.

Note

This plugin is part of the community.crypto collection (version 1.9.8).

You might already have this collection installed if you are using the ansible package. 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.

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

Synopsis
Requirements
Parameters
See Also
Examples
Return Values

Synopsis 

This module allows one to (re)generate OpenSSL public keys from their private keys.
Keys are generated in PEM or OpenSSH format.
The module can use the cryptography Python library, or the pyOpenSSL Python library. By default, it tries to detect which one is available. This can be overridden with the select_crypto_backend option. When format is OpenSSH, the cryptography backend has to be used. Please note that the PyOpenSSL backend was deprecated in Ansible 2.9 and will be removed in community.crypto 2.0.0.

Requirements 

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

Either cryptography >= 1.2.3 (older versions might work as well)
Or pyOpenSSL >= 16.0.0
Needs cryptography >= 1.4 if format is OpenSSH

Parameters 

Parameter	Comments
attributes aliases: attr string added in 2.3 of ansible.builtin	The attributes the resulting file or directory should have. To get supported flags look at the man page for chattr on the target system. This string should contain the attributes in the same order as the one displayed by lsattr. The `=` operator is assumed as default, otherwise `+` or `-` operators need to be included in the string.
backup boolean	Create a backup file including a timestamp so you can get the original public key back if you overwrote it with a different one by accident. Choices: no ← (default) yes
force boolean	Should the key be regenerated even it it already exists. Choices: no ← (default) yes
format string	The format of the public key. Choices: OpenSSH PEM ← (default)
group string	Name of the group that should own the file/directory, as would be fed to chown.
mode raw	The permissions the resulting file or directory should have. For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must either add a leading zero so that Ansible’s YAML parser knows it is an octal number (like `0644` or `01777`) or quote it (like `'644'` or `'1777'`) so Ansible receives a string and can do its own conversion from string into number. Giving Ansible a number without following one of these rules will end up with a decimal number which will have unexpected results. As of Ansible 1.8, the mode may be specified as a symbolic mode (for example, `u+rwx` or `u=rw,g=r,o=r`). If `mode` is not specified and the destination file does not exist, the default `umask` on the system will be used when setting the mode for the newly created file. If `mode` is not specified and the destination file does exist, the mode of the existing file will be used. Specifying `mode` is the best way to ensure files are created with the correct permissions. See CVE-2020-1736 for further details.
owner string	Name of the user that should own the file/directory, as would be fed to chown.
path path / required	Name of the file in which the generated TLS/SSL public key will be written.
privatekey_content string added in 1.0.0 of community.crypto	The content of the TLS/SSL private key from which to generate the public key. Either privatekey_path or privatekey_content must be specified, but not both. If state is `present`, one of them is required.
privatekey_passphrase string	The passphrase for the private key.
privatekey_path path	Path to the TLS/SSL private key from which to generate the public key. Either privatekey_path or privatekey_content must be specified, but not both. If state is `present`, one of them is required.
return_content boolean added in 1.0.0 of community.crypto	If set to `yes`, will return the (current or generated) public key’s content as publickey. Choices: no ← (default) yes
select_crypto_backend string	Determines which crypto backend to use. The default choice is `auto`, which tries to use `cryptography` if available, and falls back to `pyopenssl`. If set to `pyopenssl`, will try to use the pyOpenSSL library. If set to `cryptography`, will try to use the cryptography library. Choices: auto ← (default) cryptography pyopenssl
selevel string	The level part of the SELinux file context. This is the MLS/MCS attribute, sometimes known as the `range`. When set to `_default`, it will use the `level` portion of the policy if available.
serole string	The role part of the SELinux file context. When set to `_default`, it will use the `role` portion of the policy if available.
setype string	The type part of the SELinux file context. When set to `_default`, it will use the `type` portion of the policy if available.
seuser string	The user part of the SELinux file context. By default it uses the `system` policy, where applicable. When set to `_default`, it will use the `user` portion of the policy if available.
state string	Whether the public key should exist or not, taking action if the state is different from what is stated. Choices: absent present ← (default)
unsafe_writes boolean added in 2.2 of ansible.builtin	Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target file. By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target files, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted files, which cannot be updated atomically from inside the container and can only be written in an unsafe manner. This option allows Ansible to fall back to unsafe methods of updating files when atomic operations fail (however, it doesn’t force Ansible to perform unsafe writes). IMPORTANT! Unsafe writes are subject to race conditions and can lead to data corruption. Choices: no ← (default) yes

Examples 

- name: Generate an OpenSSL public key in PEM format
  community.crypto.openssl_publickey:
    path: /etc/ssl/public/ansible.com.pem
    privatekey_path: /etc/ssl/private/ansible.com.pem

- name: Generate an OpenSSL public key in PEM format from an inline key
  community.crypto.openssl_publickey:
    path: /etc/ssl/public/ansible.com.pem
    privatekey_content: "{{ private_key_content }}"

- name: Generate an OpenSSL public key in OpenSSH v2 format
  community.crypto.openssl_publickey:
    path: /etc/ssl/public/ansible.com.pem
    privatekey_path: /etc/ssl/private/ansible.com.pem
    format: OpenSSH

- name: Generate an OpenSSL public key with a passphrase protected private key
  community.crypto.openssl_publickey:
    path: /etc/ssl/public/ansible.com.pem
    privatekey_path: /etc/ssl/private/ansible.com.pem
    privatekey_passphrase: ansible

- name: Force regenerate an OpenSSL public key if it already exists
  community.crypto.openssl_publickey:
    path: /etc/ssl/public/ansible.com.pem
    privatekey_path: /etc/ssl/private/ansible.com.pem
    force: yes

- name: Remove an OpenSSL public key
  community.crypto.openssl_publickey:
    path: /etc/ssl/public/ansible.com.pem
    state: absent

Return Values 

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

Key	Description
backup_file string	Name of backup file created. Returned: changed and if backup is `yes` Sample: “/path/to/publickey.pem.2019-03-09@11:22~”
filename string	Path to the generated TLS/SSL public key file. Returned: changed or success Sample: “/etc/ssl/public/ansible.com.pem”
fingerprint dictionary	The fingerprint of the public key. Fingerprint will be generated for each hashlib.algorithms available. Requires PyOpenSSL >= 16.0 for meaningful output. Returned: changed or success Sample: {“md5”: “84:75:71:72:8d:04:b5:6c:4d:37:6d:66:83:f5:4c:29”, “sha1”: “51:cc:7c:68:5d:eb:41:43:88:7e:1a:ae:c7:f8:24:72:ee:71:f6:10”, “sha224”: “b1:19:a6:6c:14:ac:33:1d:ed:18:50:d3:06:5c:b2:32:91:f1:f1:52:8c:cb:d5:75:e9:f5:9b:46”, “sha256”: “41:ab:c7:cb:d5:5f:30:60:46:99:ac:d4:00:70:cf:a1:76:4f:24:5d:10:24:57:5d:51:6e:09:97:df:2f:de:c7”, “sha384”: “85:39:50:4e:de:d9:19:33:40:70:ae:10:ab:59:24:19:51:c3:a2:e4:0b:1c:b1:6e:dd:b3:0c:d9:9e:6a:46:af:da:18:f8:ef:ae:2e:c0:9a:75:2c:9b:b3:0f:3a:5f:3d”, “sha512”: “fd:ed:5e:39:48:5f:9f:fe:7f:25:06:3f:79:08:cd:ee:a5:e7:b3:3d:13:82:87:1f:84:e1:f5:c7:28:77:53:94:86:56:38:69:f0:d9:35:22:01:1e:a6:60:…:0f:9b”}
format string	The format of the public key (PEM, OpenSSH, …). Returned: changed or success Sample: “PEM”
privatekey string	Path to the TLS/SSL private key the public key was generated from. Will be `none` if the private key has been provided in privatekey_content. Returned: changed or success Sample: “/etc/ssl/private/ansible.com.pem”
publickey string added in 1.0.0 of community.crypto	The (current or generated) public key’s content. Returned: if state is `present` and return_content is `yes`

Authors

Yanis Guenane (@Spredzy)
Felix Fontein (@felixfontein)

community.crypto.openssl_publickey – Generate an OpenSSL public key from its private key.

Synopsis

Requirements

Parameters

See Also

Examples

Return Values