dskeymgr
dskeymgr — manage public key infrastructure in private deployments
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.
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.