7.6. Using certutil

The Directory Server has a command-line tool, certutil, which locally creates self-signed CA and client certificates, certificate databases, and keys. The default location for the Directory Server certutil tool is /usr/bin.
certutil can also be downloaded from https://ftp.mozilla.org/pub/security/nss/releases/.

7.6.1. Creating Directory Server Certificates through the Command Line

The following steps outline how to make the databases, key, CA certificate, server/client certificate, and convert the certificates into pkcs12 format.
  1. Open the directory where the Directory Server certificate databases are stored. 
    [root@server ~]# cd /etc/dirsrv/slapd-instance_name
  2. Make a backup copy of all of the filed in the directory as a precaution. If something goes awry with while managing certificates, the databases can then be restored. For example: 
    [root@server ~]# tar -cf /tmp/db-backup.tar *
  3. Create a password file for the security token password. 
    [root@server ~]# vi /tmp/pwdfile

secretpw
    This password locks the server's private key in the key database and is used when the keys and certificates are first created. The password in this file is also the default password to encrypt PK12 files used by pk12util. Because this password is stored in plaintext, the password file should be owned by the user as which Directory Server runs, by default nobody. If a different account was set during the installation, like Red Hat recommends, use this account and group instead for a higher security. The password file must be set as read-only for the Directory Server user and allow no access to anyone else (mode 0400). It's a good idea to have a secure backup of this file.
  4. Set the environment variable for the shell to include the certutil directory path. For example: 
    [root@server ~]# export PATH=/usr/bin/:$PATH
    The command varies depending on the shell.
  5. Create the key and certificate databases databases. 
    [root@server ~]# certutil -N -d . -f /tmp/pwdfile
  6. Generate the self-signed CA certificate. certutil creates the required key pairs and the certificate. This certificate is used to generate the other server certificates and can be exported for use with other servers and clients. 
    [root@server ~]# certutil -S -n "CA certificate" -s "cn=My Org CA cert,dc=example,dc=com" -2 -x -t "CT,," -m 1000 -v 120 -d . -k rsa -f /tmp/pwdfile
  7. Generate the Directory Server client certificate. 
    [root@server ~]# certutil -S -n "Server-Cert" -s "cn=FQDN" -c "CA certificate" -t "u,u,u" -m 1001 -v 120 -d . -k rsa -f /tmp/pwdfile
    The value of the -s argument is very important. The leftmost RDN must be cn=FQDN (where FQDN is the fully-qualified host and domain name of the Directory Server). For example, to issue a certificate for a server with the name ldap.example.com, specify at least -s "cn=ldap.example.com"; it is beneficial to have a more descriptive name to help with server identification, such as "cn=ldap.example.com,ou=DS1". The FQDN must be available for DNS and reverse DNS lookups to Directory Server clients because certificate validation may fail if the clients cannot properly resolve the FQDN, and some clients refuse to connect if a server certificate does not have its FQDN in the subject. Additionally, using the format cn=hostname.domain is essential for Directory Server clients to protect themselves from man in the middle attacks.

    Note

    There should only be one cn in a certificate subject name. To add detail to the subject name, use cn as the RDN and another attribute — like ou, l, or c — for the other subject name elements.
    To provide a subjectAltName, as well as the nickname, use the -8 argument in addition to the -s argument.
    To use the Directory Server behind a DNS round robin or any other scheme which aliases a single server certificate to multiple host names, see the TLS/SSL information about server name wildcards or subjectAltName.
    Server certificates for other servers are created using a similar command as for the Directory Server certificate. Make sure that every -n option (nickname) and -m option (serial number) is unique for every certificate, and make sure that the -s option gives the correct FQDN for the server.

    Note

    Keep careful track on the numbers set with the -m option. The -m option sets the unique identifier for the server certificate, and a CA cannot issue two certificates with the same ID. Keep a log of issued serial numbers so that no number is ever duplicated.
  8. Export the CA certificate for use with other servers and clients. A client usually requires the CA certificate to validate the server certificate in an TLS/SSL connection. Use certutil to export the CA certificate in ASCII/PEM format: 
    [root@server ~]# certutil -d . -L -n "CA certificate" -a > cacert.asc
    The way that the CA certificate is imported is different for every client. For example, certutil can import a CA certificate into another Directory Server certificate database: 
    [root@server ~]# cd /etc/dirsrv/slapd-otherserver
[root@server ~]# certutil -A -d . -n "CA certificate" -t "CT,," -a -i cacert.asc
  9. Use pk12util to export other server certificates and keys created with certutil so that they can be used on a remote server. 
    [root@server ~]# pk12util -d . -o ldap1.p12 -n Server-Cert -w /tmp/pwdfile -k /tmp/pwdfile
    The -w argument is the password used to encrypt the .p12 file for transport. The -k argument specifies the password for the key database containing the server certificate being exported to .p12.
  10. If the Directory Server will run with TLS/SSL enabled, then create a password file (pin.txt) for the server to use so it will not prompt you for a password every time it restarts. Creating the password file is described in Section 7.4.4, “Creating a Password File for the Directory Server”.
The certificates created by certutil are automatically available in the Encryption tab of the Console. There is no need to import them because they are already in the certificate database.

7.6.2. certutil Usage

certutil can be used for a variety of tasks to manage certificates and keys, such as generating certificate requests and removing certificates from the certificate database. Some of the most common options are listed in Table 7.1, “certutil Options”. For the full list of commands and arguments, run certutil -H from the command line.

Table 7.1. certutil Options

Options Description
-x Creates a self-signed CA certificate.
-S Creates a server or client certificate.
-R Generates a certificate request.
-N Creates new security databases.
-L Lists all of the certificates in the database.
-A Adds a certificate to the certificate database.
-n Gives the name of the certificate.
-d Certificate database directory; this is the directory for the subsystem instance.
-m The serial number for the certificate.
-k The key type to use; the only option is rsa.
-g The key size. The recommended size for RSA keys is 2048.
-s The subject name of the certificate.
-t The trust arguments for the certificate, meaning the purposes for which the certificate is allowed to be used.
-v The validity period, in months.
numbers 1-8 These set the available certificate extensions. Only eight can be specified through the certutil tool:
  • Key Usage: 1
  • Basic Constraints: 2
  • Certificate Authority Key ID: 3
  • CRL Distribution Point: 4
  • Netscape Certificate Type: 5
  • Extended Key Usage: 6
  • Email Subject Alternative Name: 7
  • DNS Subject Alternative Name: 8
-a Outputs the certificate request to an ASCII file instead of binary.
-o The output file to which to save the certificate request.
-i An input file containing a certificate.
-f The path to a password file for the security databases password.
Table 7.2, “certutil Examples” has some of the common uses for the certutil command.

Table 7.2. certutil Examples

Example Description
certutil -L -d . Lists the certificates in the database.
certutil -N -d . Creates new key (key3.db) and certificate (cert8.db) databases.
certutil -S -n "CA certificate" -s "cn=My Org CA cert,dc=example,dc=com" -2 -x -t "CT,," -m 1000 -v 120 -d . -k rsa Creates a self-signed CA certificate.
certutil -S -n "Server-Cert" -s "cn=FQDN" -c "CA certificate" -t "u,u,u" -m 1001 -v 120 -d . -k rsa Creates a client certificate.
certutil -L -d . -n "cert_name" "Pretty prints" the specified certificate; the cert_name can specify either a CA certificate or a client certificate.
certutil -L -d . -n "cert_name" > certfile.asc Exports the specified certificate out of the database to ASCII (PEM) format.
certutil -L -d . -n "cert_name" -r > certfile.bin Exports the specified certificate out of the database to binary format; this can be used with Directory Server attributes such as usercertificate;binary.