DS 7.1.7

dskeymgr

dskeymgr — manage public key infrastructure in private deployments

Synopsis

dskeymgr {subcommand} {options}

Description

This utility can be used for provisioning and managing TLS certificates for use in private deployments.

Subcommands easily allow to:

  • Create a deployment CA certificate

  • Distribute the CA certificate to all deployed applications

  • Provision each application with a TLS key pair signed by the deployment CA

  • Rotate the TLS key pairs

Subcommands take several seconds to run because the tool uses a computationally expensive algorithm for hashing the deployment key password.

Options

The dskeymgr command takes the following options:

Utility input/output options:

-n | --no-prompt

Use non-interactive mode. If data in the command is missing, the user is not prompted and the tool will fail. Default: false

General options:

-V | --version

Display Directory Server version information. Default: false

-H | --help

Display this usage information. Default: false

Subcommands

The dskeymgr command supports the following subcommands:

dskeymgr create-deployment-key

Creates a new deployment key.

Options

The dskeymgr create-deployment-key command takes the following options:

-f | --outputFile {outputFile}

Optional path to a file where the deployment key will be written, overwriting the file if it already exists.

-v | --validity {validity}

The duration for which the CA certificate associated with the deployment key will be valid. Examples: '20years', '1days'. Default: 10 y

-w | --deploymentKeyPassword {deploymentKeyPassword}

The deployment key password.

dskeymgr create-tls-key-pair

Creates a TLS key-pair signed by the CA associated with a deployment key and exports it to a keystore or as a PEM file.

Options

The dskeymgr create-tls-key-pair command takes the following options:

-a | --alias {alias}

The TLS key-pair alias, any entry with the same alias will be overwritten. Default: ssl-key-pair

-f | --outputFile {pemFile}

Optional path to a file with a .pem extension. The command writes the key(s) to the file in PEM format, overwriting the file if it exists.

-h | --hostname {hostname}

The hostname(s) that will be added to the TLS certificate alternative name extension. Multiple hostnames may be given by providing this argument multiple times. Hostnames can start with a wildcard. Default: localhost

-k | --deploymentKey {deploymentKey}

The deployment key.

-K | --keyStoreFile {keyStoreFile}

Optional path to an existing PKCS12 keystore file or a path indicating where a new keystore file should be created.

-r | --writableReplica

Indicates that the server using the certificate is specifically allowed to send updates to other servers. Default: false

-s | --subjectDn {subjectDn}

The TLS certificate subject DN.

-v | --validity {validity}

The duration for which the TLS certificate will be valid. Examples: '1days', '12hours', '1d 12h'. Default: 1 y

-w | --deploymentKeyPassword {deploymentKeyPassword}

The deployment key password.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

dskeymgr export-ca-cert

Exports the CA certificate associated with a deployment key to a keystore or as a PEM file.

Options

The dskeymgr export-ca-cert command takes the following options:

-a | --alias {alias}

The CA certificate alias, must not already exist in the keystore. Default: ca-cert

-f | --outputFile {pemFile}

Optional path to a file with a .pem extension. The command writes the key(s) to the file in PEM format, overwriting the file if it exists.

-k | --deploymentKey {deploymentKey}

The deployment key.

-K | --keyStoreFile {keyStoreFile}

Optional path to an existing PKCS12 keystore file or a path indicating where a new keystore file should be created.

-w | --deploymentKeyPassword {deploymentKeyPassword}

The deployment key password.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

dskeymgr export-master-key-pair

Exports the master key pair associated with a deployment key to a keystore or as a PEM file.

Options

The dskeymgr export-master-key-pair command takes the following options:

-a | --alias {alias}

The master key pair alias, must not already exist in the keystore. Default: master-key

-f | --outputFile {pemFile}

Optional path to a file with a .pem extension. The command writes the key(s) to the file in PEM format, overwriting the file if it exists.

-k | --deploymentKey {deploymentKey}

The deployment key.

-K | --keyStoreFile {keyStoreFile}

Optional path to an existing PKCS12 keystore file or a path indicating where a new keystore file should be created.

-w | --deploymentKeyPassword {deploymentKeyPassword}

The deployment key password.

-W | --keyStorePassword {keyStorePassword}

Keystore cleartext password.

Exit Codes

0

The command completed successfully.

> 0

An error occurred.

Examples

The following example shows how to create a deployment key for managing the public key infrastructure of a private deployment:

$ dskeymgr \
 create-deployment-key \
 --deploymentKeyPassword password \
 --validity "10 years"
AFPxL0RlmdMZHeVkkcC3GYFsAHNlNQ5CBVN1bkVDM7FyW2gWxnvQdQ

The following examples show how to use a deployment key to obtain the deployment CA certificate:

  • Export the CA certificate to a file in PEM format:

$ dskeymgr \
 export-ca-cert \
 --deploymentKey AFPxL0RlmdMZHeVkkcC3GYFsAHNlNQ5CBVN1bkVDM7FyW2gWxnvQdQ \
 --deploymentKeyPassword password \
 > ca.pem
  • Export the CA certificate to a PKCS#12 truststore, creating the truststore if it does not exist:

$ dskeymgr \
 export-ca-cert \
 --deploymentKey AFPxL0RlmdMZHeVkkcC3GYFsAHNlNQ5CBVN1bkVDM7FyW2gWxnvQdQ \
 --deploymentKeyPassword password \
 --keyStoreFile keystore \
 --keyStorePassword secret12 \
 --alias ca-cert

The following example shows how to use a deployment key to generate a TLS key pair signed by the deployment CA certificate and add it to a PKCS#12 keystore, creating the keystore if the keystore file does not exist. In this example, the key pair must be used by an application hosted on *.example.com and the application’s entry has the DN cn=test account,cn=service .

$ dskeymgr \
 create-tls-key-pair \
 --deploymentKey AFPxL0RlmdMZHeVkkcC3GYFsAHNlNQ5CBVN1bkVDM7FyW2gWxnvQdQ \
 --deploymentKeyPassword password \
 --subjectDn "cn=test account,cn=service" \
 --hostname "*.example.com" \
 --validity "1 days" \
 --keyStoreFile keystore \
 --keyStorePassword secret12 \
 --alias tls-key-pair

In the example above, the key pair is only valid for one day. When it is about to expire, run the same command again to replace the old key pair having the alias tls-key-pair with a new one.

Copyright © 2010-2023 ForgeRock, all rights reserved.