Red Hat Training

A Red Hat training course is available for Red Hat Linux

28.2. Managing Certificates and Certificate Authorities

Almost every IdM topology will include an integrated Dogtag Certificate System to manage certificates for servers/replicas, hosts, users, and services within the IdM domain.
The Dogtag Certificate System configuration itself may require changes as the domain and the physical machines change.

Note

Using more than one certificate authority (CA) signing certificate within your IdM environment is not supported in Red Hat Enterprise Linux 6. To support this configuration, upgrade your IdM systems to Red Hat Enterprise Linux 7.

28.2.1. Renewing CA Certificates Issued by External CAs

All certificates issued by the IdM servers, such as host and user certificates (including subsystem and server certificates used by internal IdM services), are tracked by the certmonger utility and automatically renewed as they near expiration.
There is one exception: the CA certificate itself. This certificate is not automatically renewed when it expires.

Warning

Make sure to always renew the CA certificate in time before it expires. Note that you must monitor the expiration date of the CA certificate yourself. IdM does not monitor the expiration date automatically in Red Hat Enterprise Linux 6.
The CA certificate must be renewed through the exernal CA which issued it, and then manually updated in the certificate databases (also called NSS databases). This is done using the certutil NSS security utility. [8]

Note

It is not possible to renew the CA certificate using the IdM web UI or IdM command-line utilities.
There are some requirements for renewing the certificate:
  • The external CA which issued the certificate must allow renewals.
  • The CA's private key must not change.
  • The new certificate should have the same subject name as the original certificate.
You need the original CSR (Certificate Signing Request) in order to obtain a new certificate. You may be able to find this in one of three places:
  • The external CA may still have a copy of it,
  • in the /root/ipa.csr file on the first-installed IdM server,
  • in the ca.signing.certreq section of the /etc/pki-ca/CS.cfg file on the first-installed IdM server. This will need to be converted to the PEM format.
You also need to know the nickname of your CA in the NSS databases. It is usually <REALM> IPA CA. We use EXAMPLE.COM IPA CA here. You can query the Apache database to find out the current nickname by running the following command:
# certutil -L -d /etc/httpd/alias

28.2.1.1. The Renewal Procedure

The renewal must take place in the period in which your other certificates are still valid. Your CA needs to be running in order to renew its own subsystem certificates. If you try to renew the CA certificate after it has expired such that its validity dates are past the expiration date of the CA subsystem certificates, your IdM server will not work.

Renew the Certificate

Give the CSR to your external CA and have them issue you a new certificate. We assume that the resulting certificate is saved into the /root/ipa.crt file. We also assume that the /root/external-ca.pem file contains the external CA certificate chain in the PEM format. The renewal needs to be done on the IdM CA designated for managing renewals. One way to identify the first-installed IdM server is to see if the value for subsystem.select is New:
# grep subsystem.select /etc/pki-ca/CS.cfg
subsystem.select=New
An alternative method is to look for the renew_ca_cert post-save command in the output of the getcert list command.
Number of certificates and requests being tracked: 8.
Request ID '20131125153455':
        status: MONITORING
        stuck: no
        key pair storage: type=NSSDB,location='/var/lib/pki-ca/alias',nickname='auditSigningCert cert-pki-ca',token='NSS Certificate DB',pin='455536908955'
        certificate: type=NSSDB,location='/var/lib/pki-ca/alias',nickname='auditSigningCert cert-pki-ca',token='NSS Certificate DB'
        CA: dogtag-ipa-renew-agent
        issuer: CN=Certificate Authority,O=EXAMPLE.COM
        subject: CN=CA Audit,O=EXAMPLE.COM
        expires: 2015-11-15 15:34:12 UTC
        pre-save command: /usr/lib64/ipa/certmonger/stop_pkicad
	post-save command: /usr/lib64/ipa/certmonger/renew_ca_cert "auditSigningCert cert-pki-ca"
	track: yes
        auto-renew: yes
...

Install the new CA certificate on your first-installed IdM server

  1. The CA needs to be shut down in order to update its certificate:
    # service ipa stop
  2. Update the CA certificate NSS database:
    # certutil -A -d /var/lib/pki-ca/alias -n 'caSigningCert cert-pki-ca' -t CT,C,C -a -i /root/ipa.crt
  3. Replace the value of ca.signing.cert in /etc/pki-ca/CS.cfg. This is the base64 value of the certificate. You can obtain this by removing the BEGIN/END blocks from ipa.crt and compressing it into a single line.
  4. Update the Apache NSS database:
    # certutil -A -d /etc/httpd/alias -n 'EXAMPLE.COM IPA CA'  -t CT,C,C -a -i /root/ipa.crt
  5. Update the LDAP server instances:
    # certutil -A -d /etc/dirsrv/slapd-EXAMPLE-COM -n 'EXAMPLE.COM IPA CA' -t CT,C,C -a -i /root/ipa.crt
    # certutil -A -d /etc/dirsrv/slapd-PKI-IPA -n 'EXAMPLE.COM IPA CA' -t CT,C,C -a -i /root/ipa.crt
  6. Update the CA certificate in the file system:
    # cp /root/ipa.crt /etc/ipa/ca.crt
    # cat /root/ipa.crt /root/external-ca.pem >/etc/httpd/alias/cacert.asc
    # cp /etc/httpd/alias/cacert.asc /usr/share/ipa/html/ca.crt
  7. Update the shared system database:
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  8. Restart the service:
    # service ipa start
  9. Update the CA certificate in LDAP. First, convert the certificate to the DER format:
    # openssl x509 -outform DER -in /root/ipa.crt  -out /tmp/ipa.der
  10. Add the certificate to LDAP:
    # kinit admin
    # ldapmodify -Y GSSAPI
    SASL/GSSAPI authentication started
    SASL username: admin@EXAMPLE.COM
    SASL SSF: 56
    SASL data security layer installed.
    dn: cn=CAcert,cn=ipa,cn=etc,dc=example,dc=com
    changetype: modify
    replace: cacertificate;binary
    cacertificate;binary:<file:///tmp/ipa.der

Install the new CA certificate on other IdM servers with a CA

  1. Copy the updated certificate to the machine and stop the service. Let's assume the file is /root/ipa.crt.
    # service ipa stop
  2. Update the Apache NSS database:
    # certutil -A -d /var/lib/pki-ca/alias -n 'caSigningCert cert-pki-ca' -t CT,C,C -a -i /root/ipa.crt
  3. Replace the value of ca.signing.cert in /etc/pki-ca/CS.cfg. This is the base64 value of the certificate. You can obtain this by removing the BEGIN/END blocks from ipa.crt and compressing it into a single line.
  4. Update the Apache NSS database:
    # certutil -A -d /etc/httpd/alias -n 'EXAMPLE.COM IPA CA'  -t CT,C,C -a -i /root/ipa.crt
  5. Update the LDAP server instances:
    # certutil -A -d /etc/dirsrv/slapd-EXAMPLE-COM -n 'EXAMPLE.COM IPA CA' -t CT,C,C -a -i /root/ipa.crt
    # certutil -A -d /etc/dirsrv/slapd-PKI-IPA -n 'EXAMPLE.COM IPA CA' -t CT,C,C -a -i /root/ipa.crt
  6. Update the CA certificate in the file system:
    # cp /root/ipa.crt /etc/ipa/ca.crt
    # cat /root/ipa.crt /root/external-ca.pem >/etc/httpd/alias/cacert.asc
    # cp /etc/httpd/alias/cacert.asc /usr/share/ipa/html/ca.crt
  7. Update the shared system database:
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  8. Restart the service:
    # service ipa start

Install the new CA certificate on other IdM masters without a CA

  1. Copy the updated certificate to the machine and stop the service. Let's assume the file is /root/ipa.crt.
    # service ipa stop
  2. Update the Apache NSS database:
    # certutil -A -d /etc/httpd/alias -n 'EXAMPLE.COM IPA CA'  -t CT,C,C -a -i /root/ipa.crt
  3. Update the LDAP server instances:
    # certutil -A -d /etc/dirsrv/slapd-EXAMPLE-COM -n 'EXAMPLE.COM IPA CA' -t CT,C,C -a -i /root/ipa.crt
    # certutil -A -d /etc/dirsrv/slapd-PKI-IPA -n 'EXAMPLE.COM IPA CA' -t CT,C,C -a -i /root/ipa.crt
  4. Update the CA certificate in the file system:
    # cp /root/ipa.crt /etc/ipa/ca.crt
    # cat /root/ipa.crt /root/external-ca.pem >/etc/httpd/alias/cacert.asc
    # cp /etc/httpd/alias/cacert.asc /usr/share/ipa/html/ca.crt
  5. Update the shared system database:
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  6. Restart the service:
    # service ipa start

Install the new CA certificate on all IdM client machines

Retrieve the updated IdM CA certificate. Let's assume the file is /tmp/ipa.crt.
# certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /tmp/ipa.crt
# cp /tmp/ipa.crt /etc/ipa/ca.crt

28.2.2. Configuring Alternate Certificate Authorities

IdM creates a Dogtag Certificate System certificate authority (CA) during the server installation process. To use an external CA, it is possible to create the required server certificates and then import them into the 389 Directory Server and the HTTP server, which require IdM server certificates.

Note

Save an ASCII copy of the CA certificate as /usr/share/ipa/html/ca.crt. This allows users to download the correct certificate when they configure their browsers.
  1. Use the ipa-server-certinstall command to install the certificate.
    # /usr/sbin/ipa-server-certinstall -d /path/to/pkcs12.p12
  2. To keep using browser autoconfiguration in Firefox, regenerate the /usr/share/ipa/html/configure.jar file.
    1. Create a directory, and then create the new security databases in that directory.
      # mkdir /tmp/signdb
      
      # certutil -N -d /tmp/signdb
    2. Import the PKCS #12 file for the signing certificate into that directory.
      # pk12util -i /path/to/pkcs12.p12 -d /tmp/signdb
    3. Make a temporary signing directory, and copy the IdM JavaScript file to that directory.
      # mkdir /tmp/sign
      # cp /usr/share/ipa/html/preferences.html /tmp/sign
    4. Use the object signing certificate to sign the JavaScript file and to regenerate the configure.jar file.
      # signtool -d /tmp/signdb -k Signing_cert_nickname -Z /usr/share/ipa/html/configure.jar -e .html /tmp/sign

28.2.3. Changing Which Server Generates CRLs

The master CA is the authoritative CA; it has the root CA signing key and generates CRLs which are distributed among the other servers and replicas in the topology. In general, the first IdM server installed owns the master CA in the PKI hierarchy. All subsequent replica databases are cloned (or copied) directly from that master database as part of running ipa-replica-install.

Note

The only reason to replace the master server is if the master server is being taken offline. There has to be a root CA which can issue CRLs and ultimately validate certificate checks.
As explained in Section 1.3.1, “About IdM Servers and Replicas”, all servers and replicas work together to share data. This arrangement is the server topology.
Servers (created with ipa-server-install) is almost always created to host certificate authority services[9]. These are the original CA services. When a replica is created (with ipa-replica-install), it is based on the configuration of an existing server. A replica can host CA services, but this is not required.
After they are created, servers and replicas are equal peers in the server topology. They are all read-write data masters and replicate information to each other through multi-master replication. Servers and replicas which host a CA are also equal peers in the topology. They can all issue certificates and keys to IdM clients, and they all replicate information amongst themselves.
The only difference between a server and a replica is which IdM instance issues the CRL.
When the first server is installed, it is configured to issue CRLs. In its CA configuration file (/var/lib/pki-ca/conf/CS.cfg), it has CRL generation enabled:
ca.crl.issuingPointId.enableCRLCache=true
ca.crl.issuingPointId.enableCRLUpdates=true
ca.listenToCloneModifications=false
All replicas point to that master CA as the source for CRL information and disable the CRL settings:
ca.crl.issuingPointId.enableCRLUpdates=false
There must be one instance somewhere in the IdM topology which issues CRLs. If the original server is going to be taken offline or decommissioned, a replica needs to be configured to take its place. Promoting a replica to a master server changes its configuration and enables it to issue CRLs and function as the root CA.
To move CRL generation from a server to a replica, first decommission the original master CA.
  1. Identify which server instance is the master CA server. Both CRL generation and renewal operations are handled by the same CA server. So, the master CA can be identified by having the renew_ca_cert certificate being tracked by certmonger.
    [root@server ~]# getcert list -d /var/lib/pki-ca/alias -n "subsystemCert cert-pki-ca" | grep post-save
    	post-save command: /usr/lib64/ipa/certmonger/renew_ca_cert "subsystemCert cert-pki-ca"
  2. On the original master CA, disable tracking for all of the original CA certificates.
    [root@server ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "auditSigningCert cert-pki-ca"
    Request "20131127184547" removed.
    [root@server ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "ocspSigningCert cert-pki-ca"
    Request "20131127184548" removed.
    [root@server ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "subsystemCert cert-pki-ca"
    Request "20131127184549" removed.
    [root@server ~]# getcert stop-tracking -d /etc/httpd/alias -n ipaCert
    Request "20131127184550" removed.
  3. Reconfigure the original master CA to retrieve renewed certificates from a new master CA.
    1. Copy the renewal helper into the certmonger directory, and set the appropriate permissions.
      [root@server ~]# cp /usr/share/ipa/ca_renewal /var/lib/certmonger/cas/ca_renewal
      [root@server ~]# chmod 0600 /var/lib/certmonger/cas/ca_renewal
    2. Update the SELinux configuration.
      [root@server ~]# /sbin/restorecon  /var/lib/certmonger/cas/ca_renewal
    3. Restart certmonger.
      [root@server ~]# service certmonger restart
    4. Check that the CA is listed to retrieve certificates. This is printed in the CA configuration.
      [root@server ~]# getcert list-cas
      ...	
      CA 'dogtag-ipa-retrieve-agent-submit':
              is-default: no
              ca-type: EXTERNAL
      	helper-location: /usr/libexec/certmonger/dogtag-ipa-retrieve-agent-submit
    5. Get the CA certificate database PIN.
      [root@server ~]# grep internal= /var/lib/pki-ca/conf/password.conf
    6. Configure certmonger track the certificates for external renewal. This requires the database PIN.
      [root@server ~]# getcert start-tracking -c dogtag-ipa-retrieve-agent-submit -d /var/lib/pki-ca/alias -n "auditSigningCert cert-pki-ca" -B /usr/lib64/ipa/certmonger/stop_pkicad -C '/usr/lib64/ipa/certmonger/restart_pkicad "auditSigningCert cert-pki-ca"' -T "auditSigningCert cert-pki-ca" -P database_pin
      New tracking request "20131127184743" added.
      [root@server ~]# getcert start-tracking -c dogtag-ipa-retrieve-agent-submit -d /var/lib/pki-ca/alias -n "ocspSigningCert cert-pki-ca" -B /usr/lib64/ipa/certmonger/stop_pkicad -C '/usr/lib64/ipa/certmonger/restart_pkicad "ocspSigningCert cert-pki-ca"' -T "ocspSigningCert cert-pki-ca" -P database_pin
      New tracking request "20131127184744" added.
      [root@server ~]# getcert start-tracking -c dogtag-ipa-retrieve-agent-submit -d /var/lib/pki-ca/alias -n "subsystemCert cert-pki-ca" -B /usr/lib64/ipa/certmonger/stop_pkicad -C '/usr/lib64/ipa/certmonger/restart_pkicad "subsystemCert cert-pki-ca"' -T "subsystemCert cert-pki-ca" -P database_pin
      New tracking request "20131127184745" added.
      [root@server ~]# getcert start-tracking -c dogtag-ipa-retrieve-agent-submit -d /etc/httpd/alias -n ipaCert -C /usr/lib64/ipa/certmonger/restart_httpd -T ipaCert -p /etc/httpd/alias/pwdfile.txt
      New tracking request "20131127184746" added.
  4. Stop CRL generation on the original master CA.
    1. Stop CA service:
      [root@server ~]# service pki-cad stop
    2. Open the CA configuration file.
      [root@server ~]# vim /var/lib/pki-ca/conf/CS.cfg
    3. Change the values of the ca.crl.MasterCRL.enableCRLCache and ca.crl.MasterCRL.enableCRLUpdates parameters to false to disable CRL generation.
      ca.crl.MasterCRL.enableCRLCache=false
      ca.crl.MasterCRL.enableCRLUpdates=false
    4. Start CA service:
      [root@server ~]# service pki-cad start
  5. Configure Apache to redirect CRL requests to the new master.
    1. Open the CA proxy configuration.
      [root@server ~]# vim /etc/httpd/conf.d/ipa-pki-proxy.conf
    2. Uncomment the RewriteRule on the last line:
      RewriteRule ^/ipa/crl/MasterCRL.bin https://server.example.com/ca/ee/ca/getCRL?op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
    3. Restart Apache:
      [root@server ~]# service httpd restart
Then, set up a replica as a new master:
  1. Stop tracking the CA's certificates to change the renewal settings. As a clone, the CA was configured to retrieve its renewed certificates from the master; as the master CA, it will issue the renewed certificates.
    [root@server ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "auditSigningCert cert-pki-ca"
    Request "20131127163822" removed.
    [root@server ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "ocspSigningCert cert-pki-ca" 
    Request "20131127163823" removed.
    [root@server ~]# getcert stop-tracking -d /var/lib/pki-ca/alias -n "subsystemCert cert-pki-ca"
    Request "20131127163824" removed.
    [root@server ~]# getcert stop-tracking -d /etc/httpd/alias -n ipaCert
    Request "20131127164042" removed.
  2. Get the PIN for the CA certificate database.
    [root@server ~]# grep internal= /var/lib/pki-ca/conf/password.conf
  3. Set up the certificates to be tracked in certmonger using the renewal agent profile.
    [root@server ~]# getcert start-tracking -c dogtag-ipa-renew-agent -d /var/lib/pki-ca/alias -n "auditSigningCert cert-pki-ca" -B /usr/lib64/ipa/certmonger/stop_pkicad -C '/usr/lib64/ipa/certmonger/renew_ca_cert "auditSigningCert cert-pki-ca"' -P database_pin
    New tracking request "20131127185430" added.
    [root@server ~]# getcert start-tracking -c dogtag-ipa-renew-agent -d /var/lib/pki-ca/alias -n "ocspSigningCert cert-pki-ca" -B /usr/lib64/ipa/certmonger/stop_pkicad -C '/usr/lib64/ipa/certmonger/renew_ca_cert "ocspSigningCert cert-pki-ca"' -P database_pin
    New tracking request "20131127185431" added.
    [root@server ~]# getcert start-tracking -c dogtag-ipa-renew-agent -d /var/lib/pki-ca/alias -n "subsystemCert cert-pki-ca" -B /usr/lib64/ipa/certmonger/stop_pkicad -C '/usr/lib64/ipa/certmonger/renew_ca_cert "subsystemCert cert-pki-ca"' -P database_pin
    New tracking request "20131127185432" added.
    [root@server ~]# getcert start-tracking -c dogtag-ipa-renew-agent -d /etc/httpd/alias -n ipaCert -C /usr/lib64/ipa/certmonger/renew_ra_cert -p /etc/httpd/alias/pwdfile.txt
    New tracking request "20131127185433" added.
  4. Configure the new master CA to generate CRLs.
    1. Stop CA service:
      [root@server ~]# service pki-cad stop
    2. Open the CA configuration file.
      [root@server ~]# vim /var/lib/pki-ca/conf/CS.cfg
    3. Change the values of the ca.crl.MasterCRL.enableCRLCache and ca.crl.MasterCRL.enableCRLUpdates parameters to true to enable CRL generation.
      ca.crl.MasterCRL.enableCRLCache=true
      ca.crl.MasterCRL.enableCRLUpdates=true
    4. Start CA service:
      [root@server ~]# service pki-cad start
  5. Configure Apache to disable redirect CRL requests. As a clone, all CRL requests were routed to the original master. As the new master, this instance will respond to CRL requests.
    1. Open the CA proxy configuration.
      [root@server ~]# vim /etc/httpd/conf.d/ipa-pki-proxy.conf
    2. Comment out the RewriteRule argument on the last line:
      #RewriteRule ^/ipa/crl/MasterCRL.bin https://server.example.com/ca/ee/ca/getCRL?op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
    3. Restart Apache:
      [root@server ~]# service httpd restart

28.2.4. Configuring OCSP Responders

A certificate is created with a validity period, meaning it has a point where it expires and is no longer valid. The expiration date is contained in the certificate itself, so a client always checks the validity period in the certificate to see if the certificate is still valid.
However, a certificate can also be revoked before its validity period is up, but this information is not contained in the certificate. A CA publishes a certificate revocation list (CRL), which contains a complete list of every certificate that was issued by that CA and subsequently revoked. A client can check the CRL to see if a certificate within its validity period has been revoked and is, therefore, invalid.
Validity checks are performed using the online certificate status protocol (OCSP), which sends a request to an OCSP responder. Each CA integrated with the IdM server uses an internal OCSP responder, and any client which runs a validity check can check the IdM CA's internal OCSP responder.
Every certificate issued by the IdM CA puts its OCSP responder service URL in the certificate. For example:
http://ipaserver.example.com:9180/ca/ocsp

Note

For the IdM OCSP responder to be available, port 9180 needs to be open in the firewall.

28.2.4.1. Using an OSCP Responder with SELinux

Clients can use the Identity Management OCSP responder to check certificate validity or to retrieve CRLs. A client can be a number of different services, but is most frequently an Apache server and the mod_revocator module (which handles CRL and OCSP operations).
The Identity Management CA has an OCSP responder listening over port 9180, which is also the port available for CRL retrieval. This port is protected by default SELinux policies to prevent unauthorized access. If an Apache server attempts to connect to the OCSP port, then it may be denied access by SELinux.
The Apache server, on the local machine, must be granted access to port 9180 for it to be able to connect to the Identity Management OCSP responder. There are two ways to work around this by changing the SELinux policies:
  • Edit the SELinux policy to allow Apache servers using the mod_revocator module to connect to port 9180:
    semodule -i revoker.pp
  • Generate a new SELinux policy to allow access based on the SELinux error logs for the mod_revocator connection attempt.
    audit2allow -a -M revoker

28.2.4.2. Changing the CRL Update Interval

The CRL file is automatically generated by the Dogtag Certificate System CA every four hours. This interval can be changed by editing the Dogtag Certificate System configuration.
  1. Stop the CA server.
    [root@server ~]# service pki-ca stop
  2. Open the CS.cfg file.
    [root@server ~]# vim /var/lib/pki-ca/conf/CS.cfg
  3. Change the ca.crl.MasterCRL.autoUpdateInterval to the new interval setting.
  4. Restart the CA server.
    [root@server ~]# service pki-ca start

28.2.4.3. Changing the OCSP Responder Location

Each IdM server generates its own CRL. Likewise, each IdM server uses its own OCSP responder, with its own OCSP responder URL in the certificates it issues.
A DNS CNAME can be used by IdM clients, and then from there be redirected to the appropriate IdM server OCSP responder.
  1. Open the certificate profile.
    [root@server ~]# vim /var/lib/pki-ca/profiles/ca/caIPAserviceCert.cfg
  2. Change the policyset.serverCertSet.9.default.params.crlDistPointsPointName_0 parameter to the DNS CNAME hostname.
  3. Restart the CA server.
    service pki-ca restart
That change must be made on every IdM server, with the crlDistPointsPointName_0 parameter set to the same hostname.


[8] For more information about certutil, see the Mozilla NSS developer documentation.
[9] The only exception to this is if system certificates are manually loaded during the installation for a CA-less installation. Otherwise, a Dogtag Certificate System instance is installed and configured.