Docs4dev
Docs
ansible / latest / collections / community / general / java_keystore_module.html

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

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

See Also

See also

community.crypto.openssl_pkcs12

The official documentation on the community.crypto.openssl_pkcs12 module.

community.general.java_cert

The official documentation on the community.general.java_cert module.

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