Skip to main content
Version: 4.5.x LTS

Configuring Key Material and Certificates

Introduction to Keystores and Truststores​

Within nevisAdmin 4, keystore and truststore are defined as follows:

A keystore contains:

  • Exactly one private key.
  • A certificate that must match the private key.
  • The corresponding certificate chain - up to and including a certificate authority (CA) trusted by clients.

A truststore contains:

  • One or multiple trusted certificates - their use case does not matter.

Patterns often have dedicated references to other patterns that provide the keystore/truststore objects. This involves the following patterns:

  • nevisKeybox Store
  • PEM Key Store Provider / PEM Trust Store Provider
  • Automatic Key Store / Automatic Trust Store (this is the default if no pattern is assigned)

The automatic keystore/truststore and the PEM keystore/truststore use the same directory structure, which is defined by nevisAdmin 4. The nevisKeybox store has its own nevisKeybox directory layout.

If no pattern is assigned, key management will automatically create a keystore/truststore during deployment.

nevisKeybox-Based Remote Key Management

You can also use the nevisKeybox Store pattern for the creation of keystores and truststores. The pattern provides the necessary configuration for using key material from an existing nevisKeybox instance already available on the deployment hosts.

Pros:

  • A powerful solution based on the existing nevisKeybox command line interface.
  • Builds on established concepts. The master for the nevisKeybox content is nevisKeybox.

Cons:

  • nevisAdmin 4 does NOT deploy into nevisKeybox. Manual tasks are required on all target hosts.

nevisKeybox Store pattern - Pros and Cons​

This solution is suitable for the migration of existing hosts and for complex setups that are not yet covered by the automatic or PEM-based approaches.

How to use nevisKeybox for nevisProxy frontend HTTPS​

PEM-Based Centralized Key Management

The PEM Key Store and PEM Trust Store patterns support the upload of key material in PEM format into nevisAdmin 4. The keys are automatically converted into JKS and PKCS12. The key material will be deployed using the same folder structure as for the automatic key management.

Pros:

  • Complete deployment of a keystore/truststore.
  • Use the same content on multiple hosts.

Cons:

  • JKS and P12 files are created during generation. As these files contain timestamps, they change on each deployment.
  • Using variables to provide PEM content is prone to errors. Support for simple upload of PEM files in the inventory is planned for future releases.
  • As nevisAdmin 4 is the master of the entire keystore content, the private key will be deployed as well.

PEM Key/Trust Store pattern - Pros and Cons​

Consider using this pattern when you need a simple solution for the complete deployment of a keystore/truststore and do not mind the limitations.

How to upload trusted certificates in PEM format​

Automatic Key Management

For testing, nevisAdmin 4 can automatically generate and distribute key material to all relevant components.

Pros:

  • The key is created on the target host and never leaves the host.
  • There is no work required for testing setups.
  • One shot deployment if the entire project is deployed.

Cons:

  • Does not support sharing the same key on multiple hosts.
  • In version 4.1 there are still some missing features and limited configuration options.
  • Partial deployment of a project can lead to incomplete truststore content.

Turn on Automatic Key Management for Testing​

To enable automatic key management, set the following global variable in your inventory.

vars:
 __nevisadmin_pki_automatic_enabled: true

Only use automatic key management for testing, because the generated key material does not work in some deployment scenarios. For production environments, use nevisKeybox-based or PEM-based key management.

By default, it is not required to add keystore/truststore patterns to your configuration. The required keystores and truststore will be generated automatically.

As of nevisAdmin version 4.5, you can use the following variables to force users to assign Automatic Key Store / Automatic Trust Store patterns wherever a keystore/truststore is used (instead of relying on implicit generation):

vars:
 __nevisadmin_pki_automatic_enabled: true
 __nevisadmin_pki_automatic_allowed_mode: explicit

Advanced Use Case: Explicitly Assign Automatic Key Management Pattern​

The Automatic Key Store / Automatic Trust Store patterns can be used to explicitly configure automatic key management.

Only use this feature if the default (no pattern) does not work for you.

Explicit configuration is useful when you work with specific generic patterns, such as the Generic Authentication Realm pattern. For such patterns, nevisAdmin 4 cannot automatically find out how to link a keystore to truststores. The explicit configuration ensures that any certificate issued for this keystore is automatically trusted.