Show Table of Contents
9.3. Managing the NSS Database Used by Directory Server
When you set up TLS encryption or certificate-based authentication, you must manage the certificates which are stored in a Network Security Services (NSS). This section describes the most frequent actions about managing the Directory Server's NSS database.
9.3.1. Creating the NSS Database for a Directory Server Instance
Directory Server stores the certificates in an NSS database in the
/etc/dirsrv/slapd-instance_name/
directory. Before you can manage the certificates, you must create the database.
Note
For security reasons, Red Hat recommends setting a strong password on the database.
9.3.1.1. Creating the NSS Database Using the Command Line
To create the NSS database using the command line:
- Create the NSS database and set a password:
# certutil -d /etc/dirsrv/slapd-instance_name/ -N 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:
- Set the permissions:
# chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/*.db # chown dirsrv:dirsrv /etc/dirsrv/slapd-instance_name/pkcs11.txt # chmod 600 /etc/dirsrv/slapd-instance_name/*.db # chmod 600 /etc/dirsrv/slapd-instance_name/pkcs11.txt
9.3.1.2. Creating the NSS Database Using the Console
Directory Server automatically creates the NSS database when you open the Manage Certificates task entry in the Directory Server Console the first time.
To open the Manage Certificates task entry:
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates, and set a password to protect the database.
9.3.2. Creating a Certificate Signing Request
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.
9.3.2.1. Creating a Certificate Signing Request Using the Command Line
To create the key and a CSR, use the
certutil
utility:
# certutil -d instance_directory -R -g key_size -a \ -o output_file -8 FQDN -s "certificate_subject"
For example, to generate a 4096 bit private key for the server.example.com host and to store the CSR in the
/root/instance_name.csr
file:
# certutil -d /etc/dirsrv/slapd-instance_name/ -R -g 4096 -a \ -o /root/instance_name.csr -8 server.example.com \ -s "CN=server.example.com,O=example_organization,OU=IT,ST=North Carolina,C=US"
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.
For further details about using
certutil
, see the certutil(1) man page.
After you generated the CSR, submit it to the CA to get a certificate issued. For further details, see your CA's documentation.
9.3.2.2. Creating a Certificate Signing Request Using the Console
To create the keys and a CSR using the Console:
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- On the Server Certs tab, click the button.
- Select if you want to request the certificate manually or from one of the displayed CAs and click.
- Enter the requested information and click.
Important
Enter the Fully-qualified Domain Name (FQDN) of the server into the Server name field. - Select the key size and signing algorithm. Click.For security reasons:
- an RSA key size of
2048
bits or higher - a strong signing algorithm, such as
SHA-256
or higher
- Enter the password of the Network Security Services (NSS) database and click Done.If you use an Hardware Security Module (HSM) to store the certificates, the device is plugged in, and the module has been installed as described in Section 9.7, “Using Hardware Security Modules”, then the module is available in the Active Encryption Token menu.
- Copy the CSR to the clipboard or save it into a file.
- Click.
After you generated the CSR, submit it to the CA to get a certificate issued. For further details, see your CA's documentation.
9.3.3. Installing a CA Certificate
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:
Table 9.1. CA Trust Options
Console Option | certutil Option | Description |
---|---|---|
Accepting connections from clients (Client Authentication) | T,, | The server trusts this CA certificate for issuing client certificates suitable for TLS EXTERNAL binds. |
Accepting connections to other servers (Server Authentication) | C,, | The server verifies that certificates, used to establish an encrypted connection to a replication partner, have been issued by a trusted CA. |
You can set both options for a CA. When you use
certutil
, pass the -T "CT,,"
parameter to the utility.
9.3.3.1. Installing a CA Certificate Using the Command Line
To install a CA certificate in the Directory Server's NSS database, use the
certutil
utility. For example, to import the CA certificate stored in the /etc/pki/CA/nss/ca.crt
file:
# certutil -d /etc/dirsrv/slapd-instance_name/ -A -n "certificate_nickname" \ -t "C,," -i /etc/pki/CA/nss/ca.crt
The
-t trust_options
parameter sets which certificates issued by the CA should be trusted. See Table 9.1, “CA Trust Options”.
For further details about the parameters used in the previous command, see the certutil(1) man page.
9.3.3.2. Installing a CA Certificate Using the Console
To install a CA certificate using the Directory Server Console:
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Select the CA Certs tab and click the button.
- Either select the file that contains the server certificate or paste the certificate into the field. Click.
- Verify the certificate details and click.
- Verify the certificate nickname and click.
- Set which certificates issued by the CA should be trusted. You can select one or both of the options. See Table 9.1, “CA Trust Options”.
9.3.4. Installing a Certificate
After the Certificate Authority (CA) issued the requested certificate, you must install it in the Network Security Services (NSS) database.
9.3.4.1. Installing a Server Certificate Using the Command Line
To install a server certificate in the Directory Server's NSS database, use the
certutil
utility. For example:
- Install the CA certificate. See Section 9.3.3, “Installing a CA Certificate”.
- Import the certificate. For example to import the certificate stored in the
/root/instance_name.crt
file:# certutil -d /etc/dirsrv/slapd-instance_name/ -A \ -n "server-cert" -t ",," -a -i /root/instance_name.crt
- Optionally, verify the certificate:
# certutil -d /etc/dirsrv/slapd-instance_name/ -V -n "server-cert" -u V
For further details about the parameters used in the previous
certutil
commands, see the certutil(1) man page.
9.3.4.2. Installing a Certificate Using the Console
To install a server certificate using the Console:
- Install the CA certificate. See Section 9.3.3, “Installing a CA Certificate”.
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Click thebutton.
- Select the file that contains the server certificate or, alternatively, paste the certificate into the field. Click.
- Verify the certificate details and click.
- Set a certificate nickname and click.
Note
The Directory Server Console does not support installing a certificate that uses the same nickname as an existing one. To work around the problem, install the certificate using the command line. See Section 9.3.4.1, “Installing a Server Certificate Using the Command Line”. - Enter the password of the NSS database and click.
9.3.5. Generating and Installing a Self-signed Certificate
In certain situations, administrators want to use a self-signed certificate for encrypted connections to Directory Server.
Note
You can only perform this operation using the command line.
To create and install a self-signed certificate:
- Verify if the Network Security Services (NSS) database is already initialized:
# certutil -d /etc/dirsrv/slapd-instance_name -L
If the command fails, initalize the database. For details, see Section 9.3.1, “Creating the NSS Database for a Directory Server Instance”. - 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
- 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
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. - 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"
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
If a certificate will expire in the near future, you must renew it in time to continue establishing secure connections.
9.3.6.1. Renewing a Certificate Using the Command Line
To renew a certificate:
- 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.2.1, “Creating a Certificate Signing Request Using the Command Line”
- After you received the issued certificate from your CA, install it in the database using the same nickname. See Section 9.3.3.1, “Installing a CA Certificate Using the Command Line”.
Directory Server will automatically use the newer issued certificate.
9.3.6.2. Renewing a Certificate Using the Console
The process for renewing is similar to generating a Certificate Signing Request (CSR). Follow the procedure in Section 9.3.3.2, “Installing a CA Certificate Using the Console”, but click the instead of the button in the Manage Certificates task.
9.3.7. Removing a Certificate
If a certificate is no longer needed, for example, because it has been exposed, remove it from the database.
9.3.7.1. Removing a Certificate Using the Command Line
To remove a certificate using the command line:
- Remove the private key. See Section 9.3.8, “Removing a Private Key”.
- Optionally, display the certificates in the database:
# certutil -d /etc/dirsrv/slapd-instance_name/ -L Certificate Nickname Trust Attributes SSL,S/MIME,JAR/XPI Example CA CT,, server-cert u,u,u
- Remove the certificate. For example, to remove the certificate with the server-cert nickname:
# certutil -d /etc/dirsrv/slapd-instance_name/ -D -n "server-cert"
9.3.7.2. Removing a Certificate Using the Console
To remove a certificate using the Console:
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- On the Server Certs tab, select the certificate and click the button.
- Clickto confirm.
9.3.8. Removing a Private Key
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.
9.3.8.1. Removing a Private Key Using the Command Line
To remove a private key:
- Remove all certificates based on the key you want to delete. See Section 9.3.7, “Removing a Certificate”.
- 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
- 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"
9.3.8.2. Removing a Private Key Using the Console
Removing a private key using the Console is not supported. However, if you request a new certificate using the Console according to Section 9.3.2.2, “Creating a Certificate Signing Request Using the Console”, the Console automatically generates a new private key and uses it.
9.3.9. Changing the CA Trust Options
In certain situations you need to update the trust option of a Certificate Authority (CA). This section describes this procedure.
9.3.9.1. Changing the CA Trust Options Using the Command Line
To change the trust options of a CA, pass the new options in the
-t
parameter to the certutil
utility.
For example, to set that Directory Server trusts only client authentication certificates issued by the CA named
example-CA
:
# certutil -d /etc/dirsrv/slapd-instance_name/ -M -t "T,," -n "example-CA"
The
-t trust_options
parameter sets which certificates issued by the CA should be trusted. See Table 9.1, “CA Trust Options”.
For further details about the parameters and trust options, see the certutil(1) man page.
9.3.9.2. Changing the CA Trust Options Using the Console
To change the trust options of a CA using the Console:
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Select the CA Certs tab.
- Select the CA to edit, click the Table 9.1, “CA Trust Options”.button, and set which certificates issued by the CA should be trusted. You can select one or both of the options. See
9.3.10. Changing the Password of the NSS Database
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”.
9.3.10.1. Changing the Password of the NSS Database Using the Command Line
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.
9.3.10.2. Changing the Password of the NSS Database Using the Console
To change the password of the NSS database using the Console:
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Click the Change Password button.
- Enter the current and the new password and click
9.3.11. Adding a Certificate Revocation List
If a Certificate Authority (CA) revokes a certificate, the CA adds the certificate to its Certificate Revocation Lists (CRL). Directory Server can use this list to identify which certificates are no longer trusted by the CA and to deny access.
9.3.11.1. Adding a Certificate Revocation List Using the Command Line
To add a CRL using
certutil
, pass the -4 URL_to_CRL_file
parameter to the utility when you install the CA certificate.
For details about installing a CA certificate, see Section 9.3.3.1, “Installing a CA Certificate Using the Command Line”.
9.3.11.2. Adding a Certificate Revocation List Using the Console
To add a CRL using the Console:
- Open the Directory Server Console.
- On the Tasks tab, click Manage Certificates.
- Select the Revoked Certs tab and click the button.
- Enter the path to the file, select the list format, and click.