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

Note

This plugin is part of the community.general collection (version 3.8.1).

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.

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

Synopsis
Requirements
Parameters
Notes
See Also
Examples
Return Values

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	Choices/Defaults	Comments
attributes 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. aliases: attr
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 3.0.0 of community.general		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	Choices: no ← yes	Keystore is created even if it already exists.
group string		Name of the group that should own jks file.
keystore_type string added in 3.3.0 of community.general	Choices: jks pkcs12	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 doesn't already exist, or is overwritten to match the given type in case of mismatch.
mode raw		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 0.2.0 of community.general		Passphrase used to read the private key, if required.
private_key_path path added in 3.0.0 of community.general		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 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.
ssl_backend string added in 3.1.0 of community.general	Choices: openssl ← cryptography	Backend for loading private keys and certificates.
unsafe_writes boolean added in 2.2 of ansible.builtin	Choices: no ← yes	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.

Notes

Note

certificate and private_key require that their contents are available on the controller (either inline in a playbook, or with the 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.

Examples

- name: Create a keystore for the given certificate/private key pair (inline)
  community.general.java_keystore:
    name: example
    certificate: |
      -----BEGIN CERTIFICATE-----
      h19dUZ2co2fI/ibYiwxWk4aeNE6KWvCaTQOMQ8t6Uo2XKhpL/xnjoAgh1uCQN/69
      MG+34+RhUWzCfdZH7T8/qDxJw2kEPKluaYh7KnMsba+5jHjmtzix5QIDAQABo4IB
      -----END CERTIFICATE-----
    private_key: |
      -----BEGIN RSA PRIVATE KEY-----
      DBVFTEVDVFJJQ0lURSBERSBGUkFOQ0UxFzAVBgNVBAsMDjAwMDIgNTUyMDgxMzE3
      GLlDNMw/uHyME7gHFsqJA7O11VY6O5WQ4IDP3m/s5ZV6s+Nn6Lerz17VZ99
      -----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	Returned	Description
cmd string	changed and failure	Executed command to get action done Sample: /usr/bin/openssl x509 -noout -in /tmp/user/1000/tmp8jd_lh23 -fingerprint -sha256
err string	failure	Output from stderr of keytool/openssl command after error of given command. Sample: Keystore password is too short - must be at least 6 characters
msg string	changed and failure	Output from stdout of keytool/openssl command after execution of given command or an error. Sample: Unable to find the current certificate fingerprint in ...
rc integer	changed and failure	keytool/openssl command execution return value Sample: 0

Authors

Guillaume Grossetie (@Mogztter)
quidame (@quidame)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/java_keystore_module.html