community.general.java_keystore module – Create a Java keystore in JKS format

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

Synopsis

• Bundle a x509 certificate and its private key into a Java Keystore in JKS format.

Requirements

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

• openssl in PATH (when ssl_backend=openssl)

• keytool in PATH

• cryptography >= 3.0 (when ssl_backend=cryptography)

Parameters

Parameter	Comments
attributes aliases: attr string	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.
certificate string	Content of the certificate used to create the keystore. If the fingerprint of the provided certificate does not match the fingerprint of the certificate bundled in the keystore, the keystore is regenerated with the provided certificate. Exactly one of certificate or certificate_path is required.
certificate_path path added in community.general 3.0.0	Location of the certificate used to create the keystore. If the fingerprint of the provided certificate does not match the fingerprint of the certificate bundled in the keystore, the keystore is regenerated with the provided certificate. Exactly one of certificate or certificate_path is required.
dest path / required	Absolute path of the generated keystore.
force boolean	Keystore is created even if it already exists. Choices: false ← (default) true
group string	Name of the group that should own jks file.
keystore_type string added in community.general 3.3.0	Type of the Java keystore. When this option is omitted and the keystore doesn’t already exist, the behavior follows keytool‘s default store type which depends on Java version; pkcs12 since Java 9 and jks prior (may also be pkcs12 if new default has been backported to this version). When this option is omitted and the keystore already exists, the current type is left untouched, unless another option leads to overwrite the keystore (in that case, this option behaves like for keystore creation). When keystore_type is set, the keystore is created with this type if it does not already exist, or is overwritten to match the given type in case of mismatch. Choices: "jks" "pkcs12"
mode any	Mode the file should be.
name string / required	Name of the certificate in the keystore. If the provided name does not exist in the keystore, the module will re-create the keystore. This behavior changed in community.general 3.0.0, before that the module would fail when the name did not match.
owner string	Name of the user that should own jks file.
password string / required	Password that should be used to secure the keystore. If the provided password fails to unlock the keystore, the module will re-create the keystore with the new passphrase. This behavior changed in community.general 3.0.0, before that the module would fail when the password did not match.
private_key string	Content of the private key used to create the keystore. Exactly one of private_key or private_key_path is required.
private_key_passphrase string added in community.general 0.2.0	Passphrase used to read the private key, if required.
private_key_path path added in community.general 3.0.0	Location of the private key used to create the keystore. Exactly one of private_key or private_key_path is required.
selevel string	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	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	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	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.
ssl_backend string added in community.general 3.1.0	Backend for loading private keys and certificates. Choices: "openssl" ← (default) "cryptography"
unsafe_writes boolean	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: none	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Notes

Note

• certificate and private_key require that their contents are available on the controller (either inline in a playbook, or with the ansible.builtin.file lookup), while certificate_path and private_key_path require that the files are available on the target host.

• By design, any change of a value of options keystore_type, name or password, as well as changes of key or certificate materials will cause the existing dest to be overwritten.

See Also

See also

community.crypto.openssl_pkcs12

Generate OpenSSL PKCS#12 archive.

community.general.java_cert

Uses keytool to import/remove certificate to/from java keystore (cacerts).

Examples

- name: Create a keystore for the given certificate/private key pair (inline)
  community.general.java_keystore:
    name: example
    certificate: |
      -----BEGIN CERTIFICATE-----
      h19dUZ2co2f...
      -----END CERTIFICATE-----
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      DBVFTEVDVFJ...
      -----END RSA PRIVATE KEY-----
    password: changeit
    dest: /etc/security/keystore.jks

- name: Create a keystore for the given certificate/private key pair (with files on controller)
  community.general.java_keystore:
    name: example
    certificate: "{{ lookup('file', '/path/to/certificate.crt') }}"
    private_key: "{{ lookup('file', '/path/to/private.key') }}"
    password: changeit
    dest: /etc/security/keystore.jks

- name: Create a keystore for the given certificate/private key pair (with files on target host)
  community.general.java_keystore:
    name: snakeoil
    certificate_path: /etc/ssl/certs/ssl-cert-snakeoil.pem
    private_key_path: /etc/ssl/private/ssl-cert-snakeoil.key
    password: changeit
    dest: /etc/security/keystore.jks

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: changed and failure Sample: "/usr/bin/openssl x509 -noout -in /tmp/user/1000/tmp8jd_lh23 -fingerprint -sha256"
err string	Output from stderr of keytool/openssl command after error of given command. Returned: failure Sample: "Keystore password is too short - must be at least 6 characters "
msg string	Output from stdout of keytool/openssl command after execution of given command or an error. Returned: changed and failure Sample: "Unable to find the current certificate fingerprint in ..."
rc integer	keytool/openssl command execution return value Returned: changed and failure Sample: 0

Authors

• Guillaume Grossetie (@Mogztter)

• quidame (@quidame)

Collection links

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