DS 7.2.0

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 ID 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-id

dskeymgr create-deployment-id {options}

Creates a new deployment ID.

Options

In addition to the global dskeymgr options, the dskeymgr create-deployment-id subcommand takes the following options:

-f | --outputFile {outputFile}

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

-v | --validity {validity}

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

-w | --deploymentIdPassword[:env|:file] {deploymentIdPassword}

The deployment ID password.

dskeymgr create-tls-key-pair

dskeymgr create-tls-key-pair {options}

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

Options

In addition to the global dskeymgr options, the dskeymgr create-tls-key-pair subcommand 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 | --deploymentId {deploymentId}

The deployment ID.

-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 | --deploymentIdPassword[:env|:file] {deploymentIdPassword}

The deployment ID password.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

dskeymgr export-ca-cert

dskeymgr export-ca-cert {options}

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

Options

In addition to the global dskeymgr options, the dskeymgr export-ca-cert subcommand 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 | --deploymentId {deploymentId}

The deployment ID.

-K | --keyStoreFile {keyStoreFile}

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

-w | --deploymentIdPassword[:env|:file] {deploymentIdPassword}

The deployment ID password.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

dskeymgr export-master-key-pair

dskeymgr export-master-key-pair {options}

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

Options

In addition to the global dskeymgr options, the dskeymgr export-master-key-pair subcommand 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 | --deploymentId {deploymentId}

The deployment ID.

-K | --keyStoreFile {keyStoreFile}

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

-w | --deploymentIdPassword[:env|:file] {deploymentIdPassword}

The deployment ID password.

-W | --keyStorePassword[:env|:file] {keyStorePassword}

Keystore password which will be used as the cleartext configuration value.

dskeymgr show-deployment-id

dskeymgr show-deployment-id deployment-id

Displays the deployment ID details.

Exit codes

0

The command completed successfully.

> 0

An error occurred.

Examples

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

$ dskeymgr \
 create-deployment-id \
 --deploymentIdPassword password \
 --validity "10 years"
AFPxL0RlmdMZHeVkkcC3GYFsAHNlNQ5CBVN1bkVDM7FyW2gWxnvQdQ

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

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

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

$ dskeymgr \
 export-ca-cert \
 --deploymentId AFPxL0RlmdMZHeVkkcC3GYFsAHNlNQ5CBVN1bkVDM7FyW2gWxnvQdQ \
 --deploymentIdPassword password \
 --keyStoreFile keystore \
 --keyStorePassword secret12 \
 --alias ca-cert

The following example shows how to use a deployment ID 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 \
 --deploymentId AFPxL0RlmdMZHeVkkcC3GYFsAHNlNQ5CBVN1bkVDM7FyW2gWxnvQdQ \
 --deploymentIdPassword 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.

The following example shows how to display important information about a deployment ID:

$ dskeymgr show-deployment-id AFPxL0RlmdMZHeVkkcC3GYFsAHNlNQ5CBVN1bkVDM7FyW2gWxnvQdQ

Not before: 2019-06-27T12:42:29Z
Not after: 2029-06-24T12:42:29Z
Version: 0
Serial number: 33B1725B6816C67BD075
Provider name: SunEC
Copyright © 2010-2022 ForgeRock, all rights reserved.