9.3. Managing the NSS Database Used by Directory Server
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 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. 9.3.1.1. Creating a Certificate Signing Request Using the Command Line To create the key and a CSR, use the dsctl tls generate-server-cert-csr command: 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: 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: 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 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 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. 9.3.2.1. Installing a CA Certificate Using the Command Line To install a CA certificate: 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: Set the trust options. For example, to set the CT,, trust flags: 9.3.2.2. Installing a CA Certificate Using the Web Console To install a CA certificate using the web console: Open the Directory Server user interface in the web console. See Section 1.4, "Logging Into Directory Server Using the Web Console" . Select the instance. Open the Server Settings menu, and select the Security entry. Open the Certificate Management tab, and select the Trusted Certificate Authorities sub-tab. Click Add CA Certificate . Enter the path to the CA certificate file and a nickname for the 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. Click Add Certificate . Click Actions to the imported CA certificate, and select Edit Trust Flags . Select (C) - Trusted CA and (T) - Trusted CA Client Auth in the SSL column. Figure 9.2. Adding Trust Flags of a CA Certificate 9.3.3. Importing a Private Key and Server 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: Note that the dsctl tls import-server-key-cert command requires the paths in the following order: Path to the server certificate. Path to the private key file. 9.3.4. Installing a Server Certificate 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" 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.2, "Installing a CA Certificate" . 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: 9.3.4.2. Installing a Server Certificate Using the Web Console To install a server certificate using the web console: Install the CA certificate. See Section 9.3.2, "Installing a CA Certificate" . Open the Directory Server user interface in the web console. See Section 1.4, "Logging Into Directory Server Using the Web Console" . Select the instance. Open the Server Settings menu, and select the Security entry. Open the Certificate Management tab, and select the TLS Certificates sub-tab. Click Add Server Certificate . Enter the path to the server certificate file and a nickname for the 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. Click Add Certificate . 9.3.5. Generating and Installing a Self-signed 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: Generate a noise file with random data. For example, to generate a file with a size of 4096 bits: Create the self-signed certificate and add it to the NSS database: Red Hat Enterprise Linux automatically replaces the USDHOSTNAME variable with the Fully Qualified Domain Name (FQDN) and USDRANDOM with a randomly-generated number. For further details about the parameters used in the commands, see the certutil (1) man page. Optionally, verify that the generated certificate is self-signed: 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 the server certificate: If you do not use attribute encryption: 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" 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" . Stop the instance: 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. Start the instance: 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 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: Optionally, display the certificates in the database: Remove the certificate. For example, to remove the certificate with the Server-Cert nickname: 9.3.7.2. Removing a Certificate Using the Web Console To remove a certificate using the web console: Open the Directory Server user interface in the web console. See Section 1.4, "Logging Into Directory Server Using the Web Console" . Select the instance. Open the Server Settings menu, and select the Security entry. Open the Certificate Management tab, and select the TLS Certificates sub-tab. Click Actions to the certificate, and select Delete Certificate . Click Yes . 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: Remove the private key. For example, to remove the private key with the example-cert nickname: 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 --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 : The --flags trust_options parameter sets which certificates issued by the CA should be trusted. See Table 9.1, "CA Trust Options" . 9.3.9.2. Changing the CA Trust Options Using the Web Console To change the trust options of a CA using the web console: Open the Directory Server user interface in the web console. See Section 1.4, "Logging Into Directory Server Using the Web Console" . Select the instance. Open the Server Settings menu, and select the Security entry. Open the Certificate Management tab. On the Trusted Certificate Authorities sub-tab, click Actions to the imported CA certificate, and select Edit Trust Flags . Select the trust flags. For example: Figure 9.4. Setting the Trust Flags of a CA Certificate Click Save . 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:
dsctl instance_name tls generate-server-cert-csr -s " certificate_subject " dsctl instance_name tls generate-server-cert-csr -s "CN= server.example.com ,O= example_organization ,OU= IT ,ST= North Carolina ,C= US " 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 dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate add --file /root/ca.crt --name "Example CA" dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate set-trust-flags " Example CA " --flags "CT,," dsctl instance_name tls import-server-key-cert /root/server.crt /root/server.key dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate add --file /root/instance_name.crt --name "Server-Cert" --primary-cert openssl rand -out /tmp/noise.bin 4096 certutil -S -x -d /etc/dirsrv/slapd- instance_name / -z /tmp/noise.bin -n "Server-Cert" -s "CN=USDHOSTNAME" -t "CT,C,C" -m USDRANDOM --keyUsage digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment certutil -L -d /etc/dirsrv/slapd- instance_name / -n "Server-Cert" | egrep "Issuer|Subject" Issuer: "CN= server.example.com " Subject: "CN= server.example.com " dsctl instance_name stop dsctl instance_name start 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: ,, dsconf -D "cn=Directory Manager" ldap://server.example.com security certificate del Server-Cert 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 certutil -d /etc/dirsrv/slapd- instance_name / -F -n " example-cert " dsconf -D "cn=Directory Manager" ldap://server.example.com security ca-certificate set-trust-flags " example-CA " --flags "T,," 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.