Cryptographic keys

DS servers use cryptographic keys for encryption, signing, and securing network connections.

Deployment IDs

A deployment ID is a random string generated using the dskeymgr command. It is a deployment identifier, not a key, but it is used with a password to generate keys.

A deployment ID password is a secret string at least 8 characters long that you choose.

The two are a pair. You must have the deployment ID password to use the deployment ID.

Each deployment requires a single, unique deployment ID and its password. DS uses the pair to:

Protect the keys to encrypt and decrypt backup files and directory data.
Generate the TLS key pairs to protect secure connections, unless you provide your own.

Store your deployment ID and password in a safe place, and reuse them when configuring other servers in the same deployment.

The DS setup and dskeymgr commands use the pair to generate the following:

(Required) A shared master key for the deployment.

DS replicas share secret keys for data encryption and decryption. DS servers encrypt backend data, backup files, and passwords, and each replica must be able to decrypt data encrypted on another peer replica.

To avoid exposing secret keys, DS servers encrypt secret keys with a shared master key. DS software uses a deployment ID and its password to derive the master key.
(Optional) A private PKI for trusted, secure connections.

A PKI serves to secure network connections from clients and other DS servers. The PKI is a trust network, requiring trust in the CA that signs public key certificates.

Building a PKI can be complex. You can use self-signed certificates, but you must distribute each certificate to each server and client application. You can pay an existing CA to sign certificates, but that has a cost, and leaves control of trust with a third party. You can set up a CA or certificate management software, but that can be a significant effort and cost. As a shortcut to setting up a private CA, DS software uses deployment IDs and passwords.

DS software uses the deployment ID and its password to generate key pairs without storing the CA private key.

DS derives other keys from the deployment ID and password.

Initially, you start without a deployment ID.

Use the dskeymgr create-deployment-id command to create a new deployment ID prior to installation.

You provide the deployment ID password of your choice when generating the deployment ID, and you use both when setting up DS servers.

Save the deployment ID wherever is convenient.

Keep the deployment ID password secret.
DS software uses the deployment ID and password together to generate a CA key pair.

Every time you use the same deployment ID and password, you get the same CA key.

Protect the deployment ID password with the same care you would use to protect the CA private key.
DS software generates a server key pair used for secure communications in a new PKCS#12 keystore.
DS software signs the server certificate with the CA key.
DS software derives the shared master key for protecting secret keys, storing the master key in the PKCS#12 keystore.
DS software writes the CA certificate to the PKCS#12 keystore.
DS software discards the CA private key temporarily held in memory.

You can use the dskeymgr command with an existing deployment ID and password to add keys to keystores, or to export them in PEM file format.

This private CA alternative, using a deployment ID and password instead, is not appropriate for signing server certificates in some situations:

External applications you do not control must be able to trust the server certificates.

In this case, use server certificates signed by a well-known CA.
Your deployment requires high security around CA private keys.

If the CA private key needs to be stored in an HSM that it never leaves, you cannot achieve the same level of security with a deployment ID and password. The deployment ID and password must be provided to sign a certificate, and cannot remain secure in an HSM. Furthermore, the CA private key used to sign the certificate is present in memory during the operation.

Secret keys and key pairs

DS software uses two types of cryptographic keys:

Symmetric keys (also known as secret keys)
Asymmetric key pairs (public/private key pairs)

	Symmetric (Secret) Keys	Asymmetric Key Pairs
Content	Single key, such as a random array of bits.	Pair of keys, one public, the other private.
Encryption	A single key serves to encrypt and to decrypt.	Data encrypted with a public key can only be decrypted with the private key, and vice versa.
Generation	Easier to generate, can be a random array of bits.	Harder to generate a matched pair of keys.
Speed	Faster.	Slower.
Distribution	Must be kept secret. Each party must have a copy. Secure channels must be established to exchange secret keys.	Public key can be shared with any party. Private key must be kept secret by owner. No secure channel is required to distribute public keys. Proving that a public key is valid and belongs to the issuer requires a trust network, such as a public key infrastructure (PKI).
Uses	Encrypting shared data. DS servers use secret keys for data confidentiality, and for encrypted backup files.	Public key encryption: Encrypt a message with a public key; only the private key owner can decrypt the message. Digital signatures: Sign a message with the private key; any party can verify the signature with the public key. DS software uses public/private key pairs to establish secure connections. DS servers can use public keys to authenticate clients.

Symmetric (Secret) Keys

Asymmetric Key Pairs

Content

Single key, such as a random array of bits.

Pair of keys, one public, the other private.

Encryption

A single key serves to encrypt and to decrypt.

Data encrypted with a public key can only be decrypted with the private key, and vice versa.

Generation

Easier to generate, can be a random array of bits.

Harder to generate a matched pair of keys.

Speed

Faster.

Slower.

Distribution

Must be kept secret.

Each party must have a copy.

Secure channels must be established to exchange secret keys.

Public key can be shared with any party.

Private key must be kept secret by owner.

No secure channel is required to distribute public keys.

Proving that a public key is valid and belongs to the issuer requires a trust network, such as a public key infrastructure (PKI).

Uses

Encrypting shared data.

DS servers use secret keys for data confidentiality, and for encrypted backup files.

Public key encryption: Encrypt a message with a public key; only the private key owner can decrypt the message.
Digital signatures: Sign a message with the private key; any party can verify the signature with the public key.

DS software uses public/private key pairs to establish secure connections. DS servers can use public keys to authenticate clients.

Asymmetric keys

DS software stores asymmetric key pairs and trusted certificates in keystores or PEM files. In the DS server configuration, key manager providers reference Java keystores or PEM files. (Except for some ForgeRock Common Audit event handlers that manage their own keystores.) Trust manager providers also reference Java keystores or PEM files. Components that access keys reference key manager providers for their certificates and private keys, and trust manager providers for trusted certificates. This enables, but does not require, reuse:

Different components reuse the same key pairs.

DS servers use keystores or PEM files for server keys and trusted certificates. By default, each server stores keys in a file-based keystore, /path/to/opendj/config/keystore. The cleartext password is stored in a keystore.pin file next to the keystore file. This password serves as the password for the keystore and each private key.

The password for the keystore and for private keys must be the same. DS servers do not support using different passwords for the keystore and private keys.

By default, the keystore file holds these keys based on the deployment ID and password:

The CA certificate
The shared master key
A key pair for secure communications

Symmetric keys

DS servers encrypt data using symmetric keys. Servers generate symmetric keys when needed and store them, encrypted with the shared master key, with the data they encrypt. As long as servers have the same shared master key, any server can recover symmetric keys needed to decrypt data.

Symmetric keys for (deprecated) reversible password storage schemes are the exception to this rule. When you configure a reversible password storage scheme, enable the adminRoot backend, and configure a replication domain for cn=admin data.

Public key infrastructure

A public key infrastructure (PKI) is a set of procedures, roles, and policies required to enable parties to trust each other. A PKI makes it possible to trust that a public key belongs to its owner by enabling the following steps:

Each party in the PKI trusts one or more certificate authorities (CAs).

Trusting a CA means trusting that it owns its public key, that it maintains its private key secret, and that it only signs another party’s certificate according to standard operating procedures.

The decision to trust a CA is a prerequisite for other operations, such as negotiating secure connections.

Trusting a CA equates to storing a trusted copy of the CA’s certificate. The trusted copy is used to verify CA signatures.
Other trusted parties get their keys certified in one of the following ways:
- A party wanting to use public key cryptography requests a CA-signed certificate for its key pair:
  - The owner generates a key pair with a public key to share and a private key to keep secret.
    
    This key pair is generated for the public key subject (or owner).
  - The owner makes a certificate signing request to a trusted CA. The request includes the public key.
  - The CA verifies that the party making the request is indeed the party making the request. If so, the CA signs the certificate request, resulting in the signed public key certificate. The CA responds to the owner with the signed certificate as the response to the request.
    
    Notice that the certificate is a digital document that certifies ownership of the public key. The certificate includes the public key and other information, such as the validity period, who the subject (owner) is, and the digital signature of the issuer CA who signed the certificate.
- A party registers for an account with a service provider that uses certificate-based authentication.
  
  The service provider, acting as a CA, issues a key pair including a certificate to the account owner over a secure channel. The service provider stores a copy of the certificate with the owner’s account.
The owner stores the signed certificate, and shares it when necessary with other parties for public key encryption and signature verification.

It stores the private key in a safe manner and never shares it.
Another party wanting to trust the certificate must verify that the certificate is valid.

Certificate verification involves checking certificate information such as the following:
- Whether the current time is in the range of the validity dates.
- Whether the owner’s subject identifier in the certificate matches some externally verifiable attribute of the owner, such as the DNS record of the host FQDN or the owner’s email address.
- Whether the certificate has been signed by a trusted party.
  
  A public CA does not sign certificates with its root certificate directly. Instead, the CA issues signing certificates to itself, and uses them to sign other certificates. Trust is verified for the certificate chain, whereby the root certificate signature on the signing certificate makes it possible to trust the signing certificate. The signing certificate signature on the owner’s certificate makes it possible to trust the owner’s certificate.
- Whether the party providing the certificate with the public key can prove that is has the corresponding private key.
  
  For example, the verifier supplies a nonce for the party to sign with the private key, and verifies the signature with the public key in the certificate.
Ultimately, the chain of verification must:
- End by determining that the issuer’s signature is valid and trusted, and that the party providing the certificate is authenticated.
- Fail at some point, in which case, the signature cannot be trusted.
  
  This does not mean that the certificate is invalid. It does mean, however, that the party that wants to use the public key cannot be certain that it belongs to the owner, and so, cannot trust the public key.
  
  This can happen when the party trying to use the public key does not have a means to trust the issuer who signed the certificate. For example, it has no trusted copy of the issuer’s certificate.

Trusted certificates

Secure connections between server and client applications are based on TLS. TLS depends on the use of digital certificates. By default, DS servers present their certificates when establishing a secure connection. This process fails if the client cannot trust the server certificate.

By default, DS client tools prompt you if they do not recognize the server certificate. DS servers have no one to prompt, so they refuse to accept a connection with an untrusted certificate. For ease of use, your deployment should enable secure connections without user interaction.

Automating trust is based on configuring applications to trust the CAs who sign the certificates. To achieve this, operating systems, JVMs, and web browsers ship with many trusted public CA certificates. On one hand, this prevents end users from having to understand PKI before using secure connections. On the other hand, it also introduces some risk. When public CAs are installed by default, the user must trust:

The software distribution mechanism used to obtain the original software and subsequent updates.
The software distributor to vet each CA and make sure the CA remains worthy of trust.
The CAs to perform their CA duties correctly.
The whole process to be safe from serious bugs.

Stronger security requires that you take more control. You can do this by using a private CA to distribute keys used for private communications.

Use	Private CA	Public CA	Rationale
Private connections			You control both parties making the connection.
Public connections			Your service publishes information over HTTPS or LDAPS to unknown end user clients. Your service connects as a client to public HTTPS or LDAPS services.
Mutual TLS			When your private CA signs the client certificate, store certificate information for authentication on the client’s entry in the directory.
Replication			Replication messages are private to your service.
Service administration			Service administration is private to your service.

Use

Private CA

Public CA

Rationale

Private connections

You control both parties making the connection.

Public connections

Your service publishes information over HTTPS or LDAPS to unknown end user clients.

Your service connects as a client to public HTTPS or LDAPS services.

Mutual TLS

When your private CA signs the client certificate, store certificate information for authentication on the client’s entry in the directory.

Replication

Replication messages are private to your service.

Service administration

Service administration is private to your service.

Directory Services 7.4.3