java_ks

Manage arbitrary Java keystore files

Project URL RSS Feed Report issues

Module Stats

4,082,018 downloads

632 latest version

5.0 quality score

Version information

released Nov 27th 2024

Passed malware scan

This version is compatible with:

Puppet Enterprise 2023.8.x, 2023.7.x, 2023.6.x, 2023.5.x, 2023.4.x, 2023.3.x, 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x
Puppet >= 7.0.0 < 9.0.0
, , , , , , , , , , ,

Start using this module

Installation method

Add this module to your Puppetfile:

mod 'puppetlabs-java_ks', '5.1.0'

Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add puppetlabs-java_ks

Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install puppetlabs-java_ks --version 5.1.0

Tags: java, mcollective, ssl, certs, activemq, keystore, composite-namevars

Documentation

puppetlabs/java_ks — version 5.1.0 Nov 27th 2024

java_ks

Overview
Module Description
- Beginning with the module
Setup
Usage
Reference
Limitations
License
Development

Overview

The java_ks module uses a combination of keytool and openssl to manage entries in a Java keystore.

Module Description

The java_ks module contains a type called java_ks and a single provider named keytool. Their purpose is to enable importation of arbitrary, already generated and signed certificates into a Java keystore for use by various applications.

Setup

Beginning with the module

To get started with java_ks, declare each java_ks resource you need.

java_ks { 'puppetca:truststore':
  ensure       => latest,
  certificate  => '/etc/puppet/ssl/certs/ca.pem',
  target       => '/etc/activemq/broker.ts',
  password     => 'puppet',
  trustcacerts => true,
}

Usage

You must specify a target in some way. You can specify target after the colon in the title or by using the target attribute in the resource. If you declare both, it will prefer the attribute.

java_ks { 'puppetca:keystore':
  ensure       => latest,
  certificate  => '/etc/puppet/ssl/certs/ca.pem',
  target       => '/etc/activemq/broker.ks',
  password     => 'puppet',
  trustcacerts => true,
}

java_ks { 'broker.example.com:/etc/activemq/broker.ks':
  ensure              => latest,
  certificate         => '/etc/puppet/ssl/certs/broker.example.com.pe-internal-broker.pem',
  private_key         => '/etc/puppet/ssl/private_keys/broker.example.com.pe-internal-broker.pem',
  password            => 'albatros',
  password_fail_reset => true,
}

For use cases where you want to fetch the certificate data from a secure store, like vault, you can use the _content attributes. Here is an example:

java_ks { 'broker.example.com:/etc/activemq/broker.ks':
  ensure              => latest,
  certificate_content => $certificate_data_fetched_from_secure_store,
  private_key_content => $private_key_data_fetched_from_secure_store,
  password            => 'albatros',
  password_fail_reset => true,
}

NOTE: Sensitive fields like password, certificate_content and private_key_content can be deferred using the Deferred function. This will ensure sensitive values are not present in the Catalog.

You can see an example of its use below.

java_ks { 'broker.example.com:/etc/activemq/broker.ks':
  ensure              => latest,
  certificate_content => Deferred('sprintf', [$certificate_data_fetched_from_secure_store],
  private_key_content => Deferred('sprintf', [$private_key_data_fetched_from_secure_store],
  password            => Deferred('sprint', ['albatros']),
  password_fail_reset => true,
}

We recommend using the data type Senstive for the attributes certificate_content and private_key_content. But These attributes also support a regular String data type. The _content attributes are mutual exclusive with their file-based variants.

You can also use Hiera by passing params to the java_ks::config class:

java_ks::config::params:
  'broker.example.com:/etc/activemq/broker.ks':
    ensure: latest
    certificate: '/etc/puppet/ssl/certs/broker.example.com.pe-internal-broker.pem'
    private_key: '/etc/puppet/ssl/private_keys/broker.example.com.pe-internal-broker.pem'
    password: true

Certificates

To have a Java application server use a specific certificate for incoming connections, use the certificate parameter. You will need to simultaneously import the private key accompanying the signed certificate you want to use. As long as you provide the path to the key and the certificate, the provider will do the conversion for you.

Namevars

The java_ks module supports multiple certificates with different keystores but the same alias by implementing Puppet's composite namevar functionality. Titles map to namevars via $alias:$target (alias of certificate, colon, on-disk path to the keystore). If you create dependencies on these resources you need to remember to use the same title syntax outlined for generating the composite namevars.

Note about composite namevars: The way composite namevars currently work, you must have the colon in the title. This is true even if you define name and target parameters. The title can be foo:bar, but the name and target parameters must be broker.example.com and /etc/activemq/broker.ks. If you follow convention, it will do as you expect and correctly create an entry in the broker.ks keystore with the alias of broker.example.com.

Reference

For information on the classes and types, see the REFERENCE.md.

Limitations

The java_ks module uses the keytool and openssl commands. It should work on all systems with these commands.

Java 7 is supported as of 1.0.0.

Developed against IBM Java 6 on AIX. Other versions may be unsupported.

For an extensive list of supported operating systems, see metadata.json

License

This codebase is licensed under the Apache2.0 licensing, however due to the nature of the codebase the open source dependencies may also use a combination of AGPL, BSD-2, BSD-3, GPL2.0, LGPL, MIT and MPL Licensing.

Development

Puppet modules on the Puppet Forge are open projects, and community contributions are essential for keeping them great. We can’t access the huge number of platforms and myriad hardware, software, and deployment configurations that Puppet is intended to serve.

We want to keep it as easy as possible to contribute changes so that our modules work in your environment. There are a few guidelines that we need contributors to follow so that we can have a chance of keeping on top of things. For more information, see our module contribution guide.

Reference

Classes

java_ks::config: java_ks configuration

Resource types

java_ks: Manages the entries in a java keystore, and uses composite namevars to accomplish the same alias spread across multiple target keystores.

Classes

`java_ks::config`

java_ks configuration

Parameters

The following parameters are available in the java_ks::config class:

params

`params`

Data type: Hash

A hash containing the parameters required for the java config.

Default value: {}

Resource types

`java_ks`

Manages the entries in a java keystore, and uses composite namevars to accomplish the same alias spread across multiple target keystores.

Properties

The following properties are available in the java_ks type.

`ensure`

Valid values: present, absent, latest

Has three states: present, absent, and latest. Latest will compare the on disk SHA1 fingerprint of the certificate to that in keytool to determine if insync? returns true or false. We redefine insync? for this parameter to accomplish this.

Default value: present

`password`

The password used to protect the keystore. If private keys are subsequently also protected this password will be used to attempt unlocking. Must be six or more characters in length. Cannot be used together with :password_file, but you must pass at least one of these parameters.

Parameters

The following parameters are available in the java_ks type.

certificate
certificate_content
chain
destkeypass
keytool_timeout
name
password_fail_reset
password_file
path
private_key
private_key_content
private_key_type
provider
source_alias
source_password
storetype
target
trustcacerts

`certificate`

A file containing a server certificate, followed by zero or more intermediate certificate authorities. All certificates will be placed in the keystore. This will autorequire the specified file.

`certificate_content`

A string containing a server certificate, followed by zero or more intermediate certificate authorities. All certificates will be placed in the keystore.

`chain`

The intermediate certificate authorities, if they are to be taken from a file separate from the server certificate. This will autorequire the specified file.

`destkeypass`

The password used to protect the key in keystore.

`keytool_timeout`

Timeout for the keytool command in seconds.

Default value: 120

`name`

namevar

The alias that is used to identify the entry in the keystore. This will be converted to lowercase.

`password_fail_reset`

Valid values: true, false

If the supplied password does not succeed in unlocking the keystore file, then delete the keystore file and create a new one. Default: false.

Default value: false

`password_file`

The path to a file containing the password used to protect the keystore. This cannot be used together with :password, but you must pass at least one of these parameters.

`path`

The search path used for command (keytool, openssl) execution. Paths can be specified as an array or as a '

`private_key`

If you want an application to be a server and encrypt traffic, you will need a private key. Private key entries in a keystore must be accompanied by a signed certificate for the keytool provider. This parameter allows you to specify the file name containing the private key. This will autorequire the specified file.

`private_key_content`

`private_key_type`

Valid values: rsa, dsa, ec

The type of the private key. Usually the private key is of type RSA key but it can also be an Elliptic Curve key (EC) or DSA. Valid options: , , . Defaults to

Default value: rsa

`provider`

The specific backend to use for this java_ks resource. You will seldom need to specify this --- Puppet will usually discover the appropriate provider for your platform.

`source_alias`

The source certificate alias

`source_password`

The source keystore password

`storetype`

Valid values: jceks, pkcs12, jks

Optional storetype Valid options: , ,

`target`

namevar

Destination file for the keystore. This will autorequire the parent directory of the file.

`trustcacerts`

Valid values: true, false

Certificate authorities aren't by default trusted so if you are adding a CA you need to set this to true. Defaults to :false.

Default value: false

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

Modules

Discover

Contribute

Puppet

Premium features

Downloads

Resources

About Forge

Getting Started

java_ks

Version information

This version is compatible with:

Start using this module

Documentation

java_ks

Table of Contents

Overview

Module Description

Setup

Beginning with the module

Usage

Certificates

Namevars

Reference

Limitations

License

Development

Reference

Table of Contents

Classes

Resource types

Classes

java_ks::config

Parameters

params

Resource types

java_ks

Properties

ensure

password

Parameters

certificate

certificate_content

chain

destkeypass

keytool_timeout

name

password_fail_reset

password_file

path

private_key

private_key_content

private_key_type

provider

source_alias

source_password

storetype

target

trustcacerts

Changelog

v5.1.0 - 2024-11-26

v5.0.0 - 2023-05-22

Changed

Added

v4.4.2 - 2023-04-18

Fixed

v4.4.1 - 2022-11-21

Fixed

v4.4.0 - 2022-10-03

Added

Fixed

v4.3.1 - 2022-05-24

Fixed

v4.3.0 - 2022-04-05

Added

Fixed

v4.2.0 - 2021-08-25

Added

v4.1.0 - 2021-06-28

Added

`java_ks::config`

`params`

`java_ks`

`ensure`

`password`

`certificate`

`certificate_content`

`chain`

`destkeypass`

`keytool_timeout`

`name`

`password_fail_reset`

`password_file`

`path`

`private_key`

`private_key_content`

`private_key_type`

`provider`

`source_alias`

`source_password`

`storetype`

`target`

`trustcacerts`