Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

9.3. Managing the NSS Database Used by Directory Server

To use TLS encryption or certificate-based authentication, you must manage the certificates in a Network Security Services (NSS) database. When you created the instance, the dscreate utility automatically created this database in the /etc/dirsrv/slapd-instance_name/ directory and protected it with a strong password. The utility stored the password in the /etc/dirsrv/slapd-instance_name/pwdfile.txt file. Note that Directory Server does not use this file. The dscreate utility only created this file to provide the password to the administrator. For details about changing the password, see Section 9.3.10, “Changing the Password of the NSS Database”.
This section describes the most frequent actions about managing the Directory Server's NSS database.

9.3.1. Creating a Certificate Signing Request
Copy link

The Certificate Signing Request (CSR) is a request to the Certificate Authority (CA) to sign the key of the server. This section describes how to create the CSR including the private key.

Note

Directory Server supports only creating a private key and CSR directly in the NSS database using the certutil utility.
To create the key and a CSR, use the dsctl tls generate-server-cert-csr command: 
# dsctl instance_name tls generate-server-cert-csr -s "certificate_subject"
Copy to Clipboard Toggle word wrap
The dsctl tls generate-server-cert-csr command stores the CSR in the /etc/dirsrv/slapd-instance_name/Server-Cert.csr file and the private key in the Directory Server's network security services (NSS) database.

Example 9.1. Creating a Private Key and CSR for a Single Host Name

The following command generates a bit private key for the server.example.com host: 
# dsctl instance_name tls generate-server-cert-csr -s "CN=server.example.com,O=example_organization,OU=IT,ST=North Carolina,C=US"
Copy to Clipboard Toggle word wrap
The string specified in the -s parameter must be a valid subject name according to RFC 1485. The CN field is required, and you must set it to the Fully-qualified Domain Name (FQDN) of the server. The other fields are optional.

Example 9.2. Creating a Private Key and CSR for a Multi-homed Host

If a Directory Server host has multiple names, create a CSR with all host names in the SAN extension of the CSR. The following command generates a bit private key and a CSR for the server.example.com and server.example.net host names: 
# dsctl instance_name tls generate-server-cert-csr -s "CN=server.example.com,O=example_organization,OU=IT,ST=North Carolina,C=US" server.example.com server.example.net
Copy to Clipboard Toggle word wrap
If you specify the host names as the last parameters, the command adds the SAN extension with the DNS:server.example.com, DNS:server.example.net entries to the CSR. The string specified in the -s parameter must be a valid subject name according to RFC 1485. The CN field is required, and you must set it to one of the FQDNs of the server. The other fields are optional.
After you have generated the CSR, submit it to the CA to get a certificate issued. For further details, see your CA's documentation.

9.3.2. Installing a CA Certificate
Copy link

To enable Directory Server to trust the Certificate Authority (CA) you must install the certificate of the CA into the Network Security Services (NSS) database. During this process, you must set which certificates issued by the CA should be trusted:
Expand
Table 9.1. CA Trust Options
Web Console Option dsconf and certutil Option Description
(C) Trusted CA C,, The server verifies that certificates, used to establish an encrypted connection to a replication partner, have been issued by a trusted CA.
(T) Trusted CA Client Auth T,, The server trusts this CA certificate for issuing client certificates suitable for TLS EXTERNAL binds.
You can set both options for a CA. When you use certutil, pass the -T "CT,," parameter to the utility.
To install a CA certificate:
  1. Import the CA certificate. For example, to import the CA certificate stored in the /root/ca.crt file and store it in the database with the Example CA nick name: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate add --file /root/ca.crt --name "Example CA"
    Copy to Clipboard Toggle word wrap
  2. Set the trust options. For example, to set the CT,, trust flags: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate set-trust-flags "Example CA" --flags "CT,,"
    Copy to Clipboard Toggle word wrap
To install a CA certificate using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Server Settings menu, and select the Security entry.
  4. Open the Certificate Management tab, and select the Trusted Certificate Authorities sub-tab.
  5. Click Add CA Certificate.
  6. Enter the path to the CA certificate file and a nickname for the certificate.
    Adding a CA Certificate
    View larger image
    Adding a CA Certificate

    Figure 9.1. Adding a CA Certificate

    Note

    The CA certificate must be stored locally on the Directory Server host and must be readable by the dirsrv user.
  7. Click Add Certificate.
  8. Click Actions next to the imported CA certificate, and select Edit Trust Flags.
  9. Select (C) - Trusted CA and (T) - Trusted CA Client Auth in the SSL column.
    Adding Trust Flags of a CA Certificate
    View larger image
    Adding Trust Flags of a CA Certificate

    Figure 9.2. Adding Trust Flags of a CA Certificate

This section describes how to import both a private key and Certificate Signing Request (CSR), if you did not create them in the NSS database using an external tool.
If you created the private key and CSR in the NSS database, follow the procedure described in Section 9.3.4, “Installing a Server Certificate”.
To import the certificate from the /root/server.crt and the private key from the /root/server.key file, enter: 
# dsctl instance_name tls import-server-key-cert /root/server.crt /root/server.key
Copy to Clipboard Toggle word wrap
Note that the dsctl tls import-server-key-cert command requires the paths in the following order:
  1. Path to the server certificate.
  2. Path to the private key file.

9.3.4. Installing a Server Certificate
Copy link

After the Certificate Authority (CA) issued the requested certificate, you must install it in the Network Security Services (NSS) database.
If you created the private key and certificate signing request not in the NSS database, follow the procedure described in Section 9.3.3, “Importing a Private Key and Server Certificate”
To install a server certificate in the Directory Server's NSS database, use the certutil utility. For example:
  1. Install the CA certificate. See Section 9.3.2, “Installing a CA Certificate”.
  2. Import the server certificate. For example to import the certificate stored in the /root/instance_name.crt file, and set it as the primary certificate the instance uses: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate add --file /root/instance_name.crt --name "Server-Cert" --primary-cert
    Copy to Clipboard Toggle word wrap
To install a server certificate using the web console:
  1. Install the CA certificate. See Section 9.3.2, “Installing a CA Certificate”.
  2. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  3. Select the instance.
  4. Open the Server Settings menu, and select the Security entry.
  5. Open the Certificate Management tab, and select the TLS Certificates sub-tab.
  6. Click Add Server Certificate.
  7. Enter the path to the server certificate file and a nickname for the certificate.
    Adding a Server Certificate
    View larger image
    Adding a Server Certificate

    Figure 9.3. Adding a Server Certificate

    Note

    The server certificate must be stored locally on the Directory Server host and must be readable by the dirsrv user.
  8. Click Add Certificate.
When you created the instance with TLS enabled using the dscreate utility, dscreate automatically created and installed a self-signed certificate. However, if you did not enable TLS during instance creation, you can manually create and install a self-signed certificate.

Note

You can only perform this operation using the command line.
To create and install a self-signed certificate:
  1. Generate a noise file with random data. For example, to generate a file with a size of 4096 bits: 
    # openssl rand -out /tmp/noise.bin 4096
    Copy to Clipboard Toggle word wrap
  2. Create the self-signed certificate and add it to the NSS database: 
    # certutil -S -x -d /etc/dirsrv/slapd-instance_name/ -z /tmp/noise.bin \
     -n "Server-Cert" -s "CN=$HOSTNAME" -t "CT,C,C" -m $RANDOM \
     --keyUsage digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
    Copy to Clipboard Toggle word wrap
    Red Hat Enterprise Linux automatically replaces the $HOSTNAME variable with the Fully Qualified Domain Name (FQDN) and $RANDOM with a randomly-generated number. For further details about the parameters used in the previous commands, see the certutil(1) man page.
  3. Optionally, verify that the generated certificate is self-signed: 
    # certutil -L -d /etc/dirsrv/slapd-instance_name/ -n "Server-Cert" | egrep "Issuer|Subject"
        Issuer: "CN=server.example.com"
        Subject: "CN=server.example.com"
    Copy to Clipboard Toggle word wrap
    The output of this command must display the FQDN of the Directory Server host for both the issuer and subject of the certificate.

9.3.6. Renewing a Certificate
Copy link

If a certificate will expire in the near future, you must renew it in time to continue establishing secure connections.
To renew the server certificate:
  • If you do not use attribute encryption:
    1. Create a new Certificate Signing Request (CSR) with the same options, such as key size, host name, and subject. For details about creating a CSR, see Section 9.3.1.1, “Creating a Certificate Signing Request Using the Command Line”
    2. After you received the issued certificate from your CA, install it in the database using the same nickname. See Section 9.3.2.1, “Installing a CA Certificate Using the Command Line”.
    3. Stop the instance: 
      # dsctl instance_name stop
      Copy to Clipboard Toggle word wrap
    4. Edit the /etc/dirsrv/slapd-instance_name/dse.ldif file and remove the following entries including their attributes:
      • cn=AES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config
      • cn=3DES,cn=encrypted attribute keys,cn=database_name,cn=ldbm database,cn=plugins,cn=config

      Important

      Remove the entries for all databases. If any entry that contains the nsSymmetricKey attribute is left in the /etc/dirsrv/slapd-instance_name/dse.ldif file, Directory Server will fail to start.
    5. Start the instance: 
      # dsctl instance_name start
      Copy to Clipboard Toggle word wrap
    Directory Server will automatically use the newer issued certificate.
  • If you use attribute encryption, see Section 10.5, “Updating the TLS Certificates Used for Attribute Encryption”.

9.3.7. Removing a Certificate
Copy link

If a certificate is no longer needed, for example, because it has been exposed, remove it from the database.
To remove a certificate using the command line:
  1. Optionally, display the certificates in the database: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate list

Certificate Name: Server-Cert
Subject DN: CN=server.example.com
Issuer DN: CN=Example CA
Expires: 2022-07-29 11:10:14
Trust Flags: ,,
    Copy to Clipboard Toggle word wrap
  2. Remove the certificate. For example, to remove the certificate with the Server-Cert nickname: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate del Server-Cert
    Copy to Clipboard Toggle word wrap
To remove a certificate using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Server Settings menu, and select the Security entry.
  4. Open the Certificate Management tab, and select the TLS Certificates sub-tab.
  5. Click Actions next to the certificate, and select Delete Certificate.
  6. Click Yes.

9.3.8. Removing a Private Key
Copy link

If a private key is no longer needed, for example, because you created a stronger key, remove it from the database.

Warning

If you remove a private key, certificates based on this key are no longer working.
To remove a private key:
  1. Remove all certificates based on the key you want to delete. See Section 9.3.7, “Removing a Certificate”.
  2. Optionally, display the keys in the database: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -K
certutil: Checking token "NSS Certificate DB" in slot "NSS User Private Key and Certificate Services"
Enter Password or Pin for "NSS Certificate DB":
< 0> rsa      7a2fb6c269d83c4036eac7e4edb6aaf2ed08bc4a   Server-Cert
< 1> rsa      662b826aa3dd4ca7fd7e6883558cf3866c42f4e2   example-cert
    Copy to Clipboard Toggle word wrap
  3. Remove the private key. For example, to remove the private key with the example-cert nickname: 
    # certutil -d /etc/dirsrv/slapd-instance_name/ -F -n "example-cert"
    Copy to Clipboard Toggle word wrap

9.3.9. Changing the CA Trust Options
Copy link

In certain situations you need to update the trust option of a Certificate Authority (CA). This section describes this procedure.
To change the trust options of a CA, pass the new options in the --flags parameter to the dsconf security ca-certificate set-trust-flags command.
For example, to set that Directory Server trusts only client authentication certificates issued by the CA named example-CA: 
# dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate set-trust-flags "example-CA" --flags "T,,"
Copy to Clipboard Toggle word wrap
The --flags trust_options parameter sets which certificates issued by the CA should be trusted. See Table 9.1, “CA Trust Options”.
To change the trust options of a CA using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Server Settings menu, and select the Security entry.
  4. Open the Certificate Management tab.
  5. On the Trusted Certificate Authorities sub-tab, click Actions next to the imported CA certificate, and select Edit Trust Flags.
  6. Select the trust flags. For example:
    Setting the Trust Flags of a CA Certificate
    View larger image
    Setting the Trust Flags of a CA Certificate

    Figure 9.4. Setting the Trust Flags of a CA Certificate

  7. Click Save.

9.3.10. Changing the Password of the NSS Database
Copy link

In certain situations, administrators want to change the password of the Network Security Services (NSS) database. This section describes this process.

Important

If you use a password file to enable Directory Server to automatically open the Network Security Services (NSS) database, you must update the file after you set the new password. See Section 9.4.1.5, “Creating a Password File for Directory Server”.
To change the password of the NSS database: 
# certutil -d /etc/dirsrv/slapd-instance_name -W
Enter Password or Pin for "NSS Certificate DB":
Enter a password which will be used to encrypt your keys.
The password should be at least 8 characters long,
and should contain at least one non-alphabetic character.

Enter new password: 
Re-enter password: 
Password changed successfully.
Copy to Clipboard Toggle word wrap
Back to top
Red Hat logoGithubredditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust. Explore our recent updates.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

Theme

© 2025 Red Hat