community.general.java_cert module – Uses keytool to import/remove certificate to/from java keystore (cacerts)

Note

This module is part of the community.general collection (version 10.1.0).

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.general. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: community.general.java_cert.

Synopsis

• This is a wrapper module around keytool, which can be used to import certificates and optionally private keys to a given java keystore, or remove them from it.

Requirements

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

• openssl

• keytool

Parameters

Parameter	Comments
attributes aliases: attr string added in community.general 8.5.0	The attributes the resulting filesystem object 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.
cert_alias string	Imported certificate alias. The alias is used when checking for the presence of a certificate in the keystore.
cert_content string added in community.general 8.6.0	Content of the certificate used to create the keystore. Exactly one of cert_url, cert_path, cert_content, or pkcs12_path is required to load certificate.
cert_path path	Local path to load certificate from. Exactly one of cert_url, cert_path, cert_content, or pkcs12_path is required to load certificate.
cert_port integer	Port to connect to URL. This will be used to create server URL:PORT. Default: 443
cert_url string	Basic URL to fetch SSL certificate from. Exactly one of cert_url, cert_path, cert_content, or pkcs12_path is required to load certificate.
executable string	Path to keytool binary if not used we search in PATH for it. Default: "keytool"
group string added in community.general 8.5.0	Name of the group that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current group of the current user unless you are root, in which case it can preserve the previous ownership.
keystore_create boolean	Create keystore if it does not exist. Choices: false ← (default) true
keystore_pass string / required	Keystore password.
keystore_path path	Path to keystore.
keystore_type string	Keystore type (JCEKS, JKS).
mode any added in community.general 8.5.0	The permissions the resulting filesystem object should have. For those used to /usr/bin/chmod remember that modes are actually octal numbers. You must give Ansible enough information to parse them correctly. For consistent results, quote octal numbers (for example, '644' or '1777') so Ansible receives a string and can do its own conversion from string into number. Adding a leading zero (for example, 0755) works sometimes, but can fail in loops and some other circumstances. Giving Ansible a number without following either 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 filesystem object does not exist, the default umask on the system will be used when setting the mode for the newly created filesystem object. If mode is not specified and the destination filesystem object does exist, the mode of the existing filesystem object will be used. Specifying mode is the best way to ensure filesystem objects are created with the correct permissions. See CVE-2020-1736 for further details.
owner string added in community.general 8.5.0	Name of the user that should own the filesystem object, as would be fed to chown. When left unspecified, it uses the current user unless you are root, in which case it can preserve the previous ownership. Specifying a numeric username will be assumed to be a user ID and not a username. Avoid numeric usernames to avoid this confusion.
pkcs12_alias string	Alias in the PKCS12 keystore.
pkcs12_password string	Password for importing from PKCS12 keystore.
pkcs12_path path	Local path to load PKCS12 keystore from. Unlike cert_url, cert_path and cert_content, the PKCS12 keystore embeds the private key matching the certificate, and is used to import both the certificate and its private key into the java keystore. Exactly one of cert_url, cert_path, cert_content, or pkcs12_path is required to load certificate.
selevel string added in community.general 8.5.0	The level part of the SELinux filesystem object 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 added in community.general 8.5.0	The role part of the SELinux filesystem object context. When set to _default, it will use the role portion of the policy if available.
setype string added in community.general 8.5.0	The type part of the SELinux filesystem object context. When set to _default, it will use the type portion of the policy if available.
seuser string added in community.general 8.5.0	The user part of the SELinux filesystem object 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	Defines action which can be either certificate import or removal. When state is present, the certificate will always idempotently be inserted into the keystore, even if there already exists a cert alias that is different. Choices: "absent" "present" ← (default)
trust_cacert boolean added in community.general 0.2.0	Trust imported cert as CAcert. Choices: false ← (default) true
unsafe_writes boolean added in community.general 8.5.0	Influence when to use atomic operation to prevent data corruption or inconsistent reads from the target filesystem object. By default this module uses atomic operations to prevent data corruption or inconsistent reads from the target filesystem objects, but sometimes systems are configured or just broken in ways that prevent this. One example is docker mounted filesystem objects, 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 filesystem objects 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: false ← (default) true

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target.
diff_mode	Support: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Import SSL certificate from google.com to a given cacerts keystore
  community.general.java_cert:
    cert_url: google.com
    cert_port: 443
    keystore_path: /usr/lib/jvm/jre7/lib/security/cacerts
    keystore_pass: changeit
    state: present

- name: Remove certificate with given alias from a keystore
  community.general.java_cert:
    cert_url: google.com
    keystore_path: /usr/lib/jvm/jre7/lib/security/cacerts
    keystore_pass: changeit
    executable: /usr/lib/jvm/jre7/bin/keytool
    state: absent

- name: Import trusted CA from SSL certificate
  community.general.java_cert:
    cert_path: /opt/certs/rootca.crt
    keystore_path: /tmp/cacerts
    keystore_pass: changeit
    keystore_create: true
    state: present
    cert_alias: LE_RootCA
    trust_cacert: true

- name: Import trusted CA from the SSL certificate stored in the cert_content variable
  community.general.java_cert:
    cert_content: |
      -----BEGIN CERTIFICATE-----
      ...
      -----END CERTIFICATE-----
    keystore_path: /tmp/cacerts
    keystore_pass: changeit
    keystore_create: true
    state: present
    cert_alias: LE_RootCA
    trust_cacert: true

- name: Import SSL certificate from google.com to a keystore, create it if it doesn't exist
  community.general.java_cert:
    cert_url: google.com
    keystore_path: /tmp/cacerts
    keystore_pass: changeit
    keystore_create: true
    state: present

- name: Import a pkcs12 keystore with a specified alias, create it if it doesn't exist
  community.general.java_cert:
    pkcs12_path: "/tmp/importkeystore.p12"
    cert_alias: default
    keystore_path: /opt/wildfly/standalone/configuration/defaultkeystore.jks
    keystore_pass: changeit
    keystore_create: true
    state: present

- name: Import SSL certificate to JCEKS keystore
  community.general.java_cert:
    pkcs12_path: "/tmp/importkeystore.p12"
    pkcs12_alias: default
    pkcs12_password: somepass
    cert_alias: default
    keystore_path: /opt/someapp/security/keystore.jceks
    keystore_type: "JCEKS"
    keystore_pass: changeit
    keystore_create: true
    state: present

Return Values

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

Key	Description
cmd string	Executed command to get action done. Returned: success Sample: "keytool -importcert -noprompt -keystore"
msg string	Output from stdout of keytool command after execution of given command. Returned: success Sample: "Module require existing keystore at keystore_path '/tmp/test/cacerts'"
rc integer	Keytool command execution return value. Returned: success Sample: 0

Authors

• Adam Hamsik (@haad)

Collection links

• Issue Tracker
• Repository (Sources)
• Ask for help
• Submit a bug report
• Request a feature
• Communication