KeyStore Manager user guide

Overview

The KeyStore Manager simplifies the creation and signature of keys in case of TLS communication between nodes in a private cluster.

The KeyStore Manager:

  • Creates a certificate authority (CA).
  • Generates and signs keys for each host participating in the TLS communication.

Each CA has its own keystore file which contains:

  • The CA certificate and private key.
  • For each host, the private key and the certificate signed by the CA.

You can export the keys and their certificates in various formats: OpenSSL (PEM), JKS, and PKCS12.

Do not use the KeyStore manager to manage the CA of a public infrastructure. With KeyStore Manager, the host's private keys and the CA key are stored in the same location. So, the CA administrator has access to the host's private keys and can decipher the TLS communication from the hosts. This simplification is only acceptable when the same person (or group of person) is responsible for generating and signing the keys. This is never the case in a public infrastructure.

It embeds a Java JDK and is built on top of Java keytool utility and Bouncy Castle library (needed to export keys and certificates in OpenSSL format).

The KeyStore Manager installer is available for Windows and Linux. The following links are the version that match this documentation:

The latest releases are available on Sphere.

Prerequisites

KeyStore Manager must be installed in a secured workstation or dedicated server. Do not install it on the same servers that have to be configured for the TLS configuration.

This means that you must not install the KeyStore Manager on any Axway Decision Insight (DI) or Decision Insight Messaging System (DIMS) node.


A Windows 7+, Windows Server 2008 R2+ or Linux (RHEL 5+, Ubuntu LTS 14+, Suse 11+, Oracle Linux+) system is required.

Installation

Execute the installer, either:

  • In GUI mode no special parameters are needed.
  • In console mode, execute the installer with the -c parameter. On Windows execute the following command to install in console mode: start /wait <installer executable> -c

Once the installer is launched:

  1. Accept the Axway license agreement.
  2. Accept the Oracle license agreement.
  3. Choose the installation directory. On Windows to install in C:\Program Files, you must be an Administrator and grant the modification permission when asked by UAC. Else you can install in any writable location.
  4. Validate and let the installation finish.

For a fully secure installation, configure the <installation directory>/var directory so only the current user can access it. You do not need to do this if you plan to store the keys in another location (see Configuration), however, you must still do so for your own CA store directory and export directory:

On a Windows 10 OS:

  1. Navigate to the <installation directory>/var directory.
  2. Right-click on the folder and select Properties.
  3. On the Security tab, click the Advanced button.
  4. Click the Modify the permissions button
  5. Click the Change hyperlink on the line for Owner.
  6. In the Name field, enter the current username , then click OK .
  7. Check the Replace owner on subcontainers and objects checkbox.
  8. Click the Disable inheritance button. 
  9. Select Remove all inherited permissions of this object then click Add
  10. Click the Select a principal hyperlink, enter the current username, then click OK.
  11. Select the Full control checkbox, and click OK
  12. Check the Replace all child object permission entries with inheritable permission entries from this object checkbox. 
  13. Click OK, then Yes. Click OK again.


On Linux, execute the following command: 


chmod -R og-rwx <installation directory>/var

Configuration

The tool can work out of the box. You can still configure some parameters in <installation directory>/conf/keystore_manager.properties, especially the certificate validity days parameter:

Configuration key Default value Description
keystoreManager.caStoreDir <installation directory>/var/data The location of the CA key files.
If changed, you must secure this location the way you did for <installation directory>/var in the Installation section.
keystoreManager.exportDir <installation directory>/var/work The location of the exposed host key files.
If changed, you must secure this location the way you did for <installation directory>/var in the Installation section.
keystoreManager.caStoreType PKCS12 The keystore type for CA key files. It can be PKCS12 or JKS. PKCS12 is recommended since it is more secure and interoperable than JKS.
keystoreManager.privateKeyAlgorithm RSA The private key algorithm. Only RSA is currently supported.
keystoreManager.privateKeySize 2048 The size of the private key that will be generated.
keystoreManager.validityDays 1095 The number of days for certificates validity. The default value is equivalent to 3 years. Change this value based on your needs.
keystoreManager.pemEncryptionAlgorithm AES-256-CBC The private key encryption algorithm to be used when exporting the host key in OpenSSL format. Only AES-256-CBC is currently supported.

Get started in two minutes

Scenario: You want to configure a TLS communication between two filebeat agents (hosted on filebeat1.domain.com and filebeat2.domain.com) and a Lumberjack connector in DI (hosted on adi.domain.com).

For that,  use KeyStore Manager to create a new CA named Lumberjack (the CA name can be freely chosen) with 3 hosts, 2 of them exported in OpenSSL (filebeat1.domain.com and filebeat2.domain.com) and 1 in JKS (adi.domain.com).

The host keys DNS names must match the host names.


The command line examples below are given for Windows.

On Linux, use ./ksm.sh instead of ksm. For more information, see the first paragraph of Usage.

Command-line example

Note: A password can be also prompted interactively if not specified in parameters.

# cd <installation directory>\bin
# ksm createCA Lumberjack -password CASecretPassword
# ksm createHostKey -ca Lumberjack -password CASecretPassword adi -dns adi.domain.com
# ksm createHostKey -ca Lumberjack -password CASecretPassword filebeat1 -dns filebeat1.domain.com
# ksm createHostKey -ca Lumberjack -password CASecretPassword filebeat2 -dns filebeat2.domain.com
# ksm exportHostKey -ca Lumberjack -password CASecretPassword -format JKS -exportpassword adiKeyPWD adi 
# ksm exportHostKey -ca Lumberjack -password CASecretPassword -format OpenSSL -exportpassword filebeat1KeyPWD filebeat1
# ksm exportHostKey -ca Lumberjack -password CASecretPassword -format OpenSSL -exportpassword filebeat2KeyPWD filebeat2

Shell example

Note: A password can also be directly specified in the command parameters:

# cd <installation directory>\bin
# ksm
! > createCA Lumberjack
Lumberjack > createHostKey adi -dns adi.domain.com
Lumberjack > createHostKey filebeat1 -dns filebeat1.domain.com
Lumberjack > createHostKey filebeat2 -dns filebeat2.domain.com
Lumberjack > exportHostKey -format JKS adi
Lumberjack > exportHostKey -format OpenSSL filebeat1
Lumberjack > exportHostKey -format OpenSSL filebeat2
Lumberjack > exit

The results

After the execution of these commands, the following files are available:

Path File Description
<installation directory>/var/data Lumberjack.p12 The CA keystore file. Do not use it to configure the TLS configuration.
<installation directory>/var/work/Lumberjack/adi/jks
  • Lumberjack_truststore.jks
  • adi_keystore.jks

The truststore and keystore to be used for the ADI Lumberjack TLS configuration.
Both files are protected by the export password used when exporting the host keys.

<installation directory>/var/work/Lumberjack/filebeat1/openssl
  • Lumberjack.crt
  • filebeat1.crt
  • filebeat1.key
  • The CA certificate
  • The private key certificate
  • The private key, protected by the export password used when exporting the host keys

Theses files must be configured in the Filebeat configuration file on filebeat1.domain.com

<installation directory>/var/work/Lumberjack/filebeat2/openssl
  • Lumberjack.crt
  • filebeat2.crt
  • filebeat2.key
  • The CA certificate
  • The private key certificate
  • The private key, protected by the export password used when exporting the host keys

Theses files must be configured in the Filebeat configuration file on filebeat1.domain.com


Later, you can use the KeyStore Manager to create and manage a new CA or on the existing CA to add new host key, or re-export existing host keys.

Usage

KeyStore manager can be used in the following ways:

  • By command line, using command line arguments:
    • on Windows 

      cd /D <installation dir>\bin
      ksm <command> [<command options>]
    • on Linux 

      cd <installation dir>/bin
      ./ksm.sh <command> [<command options>]
  • With an interactive shell in console in which you can enter many commands and their options. Launch the ksm.bat or ksm.sh without any arguments. Either from the command line or:
    • on Windows, from the Explorer, double click the ksm.bat file in <installation dir>.
    • on Linux, from a graphical file manager, double click the ksm.sh file in  <installation dir> .

Interactive shell

On the interactive shell, you have two different states:

  • No CA is open, this is the initial state:
    • The shell prompt is: ! >
    • You can execute the Managing CA commands.
  • A CA is open:
    • The shell prompt is: <Name of the CA> >
    • You can execute the Managing host keys commands and use the closeCA command to go back to the initial state (no CA open).

From both states, at any time, you can:

  • Ask for help with the help command.
  • Print the tool version with the version command.
  • Exit from the shell with using the exit command or on Linux pressing Control+D on the command prompt.


In interactive shell, arguments can be quoted with ".

For example, to create a CA with password 123 456:

createCA MyCA -password "123 456"


Use double quote inside a quoted argument to get a single quote char.

For example, to create a CA with password 123"456:

createCA MyCA -password "123""456"

Commands

Help

You can request commands help at any time with the help  command.

Command line example:

# ksm help
(help output)

Shell example:

! > help
(help output)

Version

You can request the tool version at any time with the version command.

Command line example:

# ksm version
KeyStore Manager, version (version)
Java, version (version)
Bouncy Castle, version (version)

Shell example:

! > version
KeyStore Manager, version (version)
Java, version (version)
Bouncy Castle, version (version)


Managing CA

You can create and list CAs. For each CA, a corresponding file is created in the CA store directory (by default <installation directory>/var/data). Each of these files is protected by the associated CA password and contains the CA private key and all the hosts private keys signed by this CA.

The commands and arguments are the same when using command line or interactive shell.

Create a new CA

CommandcreateCA <CA name>

  • Options:
    • -password <CA password> : the password to be used to protect the CA keystore file. If this option is not specified, the password will be prompted interactively. The password must be at least six-character long.

This command creates a new CA and generates a private key for it. The new CA file is  <installation directory>/var/data/<CA name>.p12 .

In the interactive shell, the state changes automatically on CA open state on the newly created CA.

Command line example: create a new CA named MyCA and protected by password changeit:

# ksm createCA MyCA -password changeit
Creating a new CA 'MyCA'
    Generating keypair...
CA 'MyCA' successfully created


Shell example: create a new CA name MyCA and protected by a password that will be entered by the user:

! > createCA MyCA
CA keystore password:
Confirm password:
Creating a new CA 'MyCA'
    Generating keypair...
CA 'MyCA' successfully created
MyCA >

List the CA

  • Command: listCA

Command line example:

# ksm listCA
MyCA

Shell example:

! > listCA
MyCA

Open a CA (shell only)

  • Command: openCA <Name of the CA>
  • Options
    • -password <secret> : the password used to protect the CA keystore file. If this option is not specified, the password will be prompted interactively

If the CA exists and the password is correct, this will change the shell state to CA open state.

Managing host keys

You can list, create, delete and export an host key. For each created host key, a new private key is generated in the CA keystore. When created, the host key is automatically signed by the CA key.

The commands and arguments are the same when using command line or interactive shell, but

  • for command line you must systematically add the following options:
    • -ca <CA name> : the name of the CA on which execute the host key command
    • -password <CA password> : the password used to protect the CA keystore file. If this option is not specified, the password will be prompted interactively
  • for interactive shell, the shell must be in CA open state

Create a new host key

  • Command: createHostKey <hostname> [-dns <dns name>] [-ip <ip address>]

Create a new host key in the CA keystore. Only one host can be specified on a single command. The parameter hostname is used as the certificate CN (Common Name). Many -dns or -ip parameters can be specified, they must match the host DNS names or IP addresses. At least one of them is required. They are used to create the certificate SAN (Subject Alternative Name) extension.

Command line example:

# ksm createHostKey -ca MyCA -password 123456 MyHost -ip 192.168.0.1 -ip 192.168.0.2 -dns myhost.domain.com
Creating a new host 'MyHost'
    Generating keypair...
    Creating certificate signing request...
    Generating certificate signing response...
    Importing certificate signing response...
Certificate reply was installed in keystore
Host 'MyHost' successfully created

Shell example:

MyCA > createHostKey MyHost -ip 192.168.0.1 -ip 192.168.0.2 -dns myhost.domain.com
Creating a new host 'MyHost'
    Generating keypair...
    Creating certificate signing request...
    Generating certificate signing response...
    Importing certificate signing response...
Certificate reply was installed in keystore
Host 'MyHost' successfully created

Delete a host key

  • Command: deleteHostKey <host name>

Delete an host key in the CA keystore. One or many host can be specified.

Command line example:

# ksm deleteHostKey -ca MyCA -password 123456 192.168.0.1
Deleting host '192.168.0.1'
Host '192.168.0.1' successfully deleted

Shell example:

MyCA > deleteHostKey 192.168.0.1
Deleting host '192.168.0.1'
Host '192.168.0.1' successfully deleted

Export an host key

  • Command: exportHostKey <host name>
  • Options
    • -format <type>: where type can be
      • JKS : the Java KeyStore format. This is the standard Java format to store keys and certificates, but tends to be deprecated in favor of PKCS12
      • PKCS12 : this is a standard and normalized format used to store keys and certificates. It is supported by Java, Microsoft Windows and many others tools.
      • OpenSSL : this is the format used by every tools based on OpenSSL or related.
    • -exportpassword <export password>: the password to be used to protect the exported private key. If this option is not specified, the password will be prompted interactively

Export the host keys and certificate in the required format. One or many hosts can be specified in a single call. The exported files are located in <installation dir>/var/work/<CA name>/<host name>/<export format>.

Depending on the export format, the following files are available:

Format File Description
PKCS12 <CA name>_truststore.p12 The trust store that contains the CA certificate. The store is protected by the export password.
<host name>_keystore.p12 The trust store that contains the host private key and it's certificate signed by the CA. The store is protected by the export password.

JKS <CA name>_truststore.jks The trust store that contains the CA certificate. The store is protected by the export password.
<host name>_keystore.jks The trust store that contains the host private key and it's certificate signed by the CA. The store is protected by the export password.

OpenSSL <CA name>.crt The CA certificate in PEM format. There is no password protection on it.
<host name>.crt The host key certificate in PEM format. There is no password protection on it.
<host name>.key The host private key in PEM format. This file is protected by the export password.


List the host keys

CommandlistHostKey

Lists the host keys of a CA.

Command line example:

# ksm listHostKey -ca MyCA -password <CA password>
192.168.0.1

Shell example:

MyCA > listHostKey
192.168.0.1

Related Links