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 8.5.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.

Aliases: system.java_cert

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_path

path

Local path to load certificate from.

Exactly one of cert_url, cert_path, 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, 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 and cert_path, 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, 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 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)