Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

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:
Copy to Clipboard Toggle word wrap 
# 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:
Copy to Clipboard Toggle word wrap 
# 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.
Copy to Clipboard Toggle word wrap 
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:
    Copy to Clipboard Toggle word wrap 
    # service ipa stop
  2. Update the CA certificate NSS database:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  8. Restart the service:
    Copy to Clipboard Toggle word wrap 
    # service ipa start
  9. Update the CA certificate in LDAP. First, convert the certificate to the DER format:
    Copy to Clipboard Toggle word wrap 
    # openssl x509 -outform DER -in /root/ipa.crt  -out /tmp/ipa.der
  10. Add the certificate to LDAP:
    Copy to Clipboard Toggle word wrap 
    # 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.
    Copy to Clipboard Toggle word wrap 
    # service ipa stop
  2. Update the Apache NSS database:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  8. Restart the service:
    Copy to Clipboard Toggle word wrap 
    # 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.
    Copy to Clipboard Toggle word wrap 
    # service ipa stop
  2. Update the Apache NSS database:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  6. Restart the service:
    Copy to Clipboard Toggle word wrap 
    # 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.
Copy to Clipboard Toggle word wrap 
# 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. Renewing CA Certificates Issued by the IdM CA

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.

28.2.2.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 Signing Certificate of your IdM CA and install the new CA certificate on your first-installed IdM server

  1. Ensure IPA is stopped:
    Copy to Clipboard Toggle word wrap 
    # ipactl status
# ipactl stop
  2. Ensure ntpd is not running:
    Copy to Clipboard Toggle word wrap 
    # service ntpd status
# service ntpd stop
  3. Start the Directory Server and ensure it is running:
    Copy to Clipboard Toggle word wrap 
    # service dirsrv start
# service dirsrv status
  4. Start the Dogtag CA and ensure it is running:
    Copy to Clipboard Toggle word wrap 
    # service pki-cad start
# service pki-cad status
  5. Enter the following command to attempt to renew the Dogtag CA signing certificate directly via the certmonger helper, dogtag-ipa-renew-agent-submit:
    Copy to Clipboard Toggle word wrap 
    # /usr/libexec/certmonger/dogtag-ipa-renew-agent-submit -D 1 -T caCACert | tail -n 1 | xargs /usr/libexec/certmonger/dogtag-ipa-renew-agent-submit -d /etc/httpd/alias -n ipaCert -p /etc/httpd/alias/pwdfile.txt -v -S
  6. Update the CA certificate NSS database:
    Copy to Clipboard Toggle word wrap 
    # certutil -A -d /var/lib/pki-ca/alias -n 'caSigningCert cert-pki-ca' -t CT,C,C -a -i /root/ipa.crt
  7. 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.
  8. Update the Apache NSS database:
    Copy to Clipboard Toggle word wrap 
    # certutil -A -d /etc/httpd/alias -n 'EXAMPLE.COM IPA CA'  -t CT,C,C -a -i /root/ipa.crt
  9. Update the LDAP server instances:
    Copy to Clipboard Toggle word wrap 
    # 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
  10. Update the CA certificate in the file system:
    Copy to Clipboard Toggle word wrap 
    # 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
  11. Update the shared system database:
    Copy to Clipboard Toggle word wrap 
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  12. Restart the service:
    Copy to Clipboard Toggle word wrap 
    # ipactl start
  13. Update the CA certificate in LDAP. First, convert the certificate to the DER format:
    Copy to Clipboard Toggle word wrap 
    # openssl x509 -outform DER -in /root/ipa.crt  -out /tmp/ipa.der
  14. Add the certificate to LDAP:
    Copy to Clipboard Toggle word wrap 
    # 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
  15. Use ipa-getcert list to list all requests tracked by certmonger:
    Copy to Clipboard Toggle word wrap 
    # ipa-getcert list
  16. If the output shows that any of the subsystem certificates are already expired, use ipa-getcert resubmit on each of them one by one to renew the certificates. For more details, see the Dealing with expiring IDM CA certificates on Red Hat Enterprise Linux 6 and 7 Knowledgebase solution.

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.
    Copy to Clipboard Toggle word wrap 
    # service ipa stop
  2. Update the Apache NSS database:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  8. Restart the service:
    Copy to Clipboard Toggle word wrap 
    # 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.
    Copy to Clipboard Toggle word wrap 
    # service ipa stop
  2. Update the Apache NSS database:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # 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:
    Copy to Clipboard Toggle word wrap 
    # certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i /root/ipa.crt
  6. Restart the service:
    Copy to Clipboard Toggle word wrap 
    # 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.
Copy to Clipboard Toggle word wrap 
# 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.3. 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.
    Copy to Clipboard Toggle word wrap 
    # /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. Copy to Clipboard Toggle word wrap 
      # mkdir /tmp/signdb

# certutil -N -d /tmp/signdb
    2. Import the PKCS #12 file for the signing certificate into that directory. Copy to Clipboard Toggle word wrap 
      # pk12util -i /path/to/pkcs12.p12 -d /tmp/signdb
    3. Make a temporary signing directory, and copy the IdM JavaScript file to that directory. Copy to Clipboard Toggle word wrap 
      # 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. Copy to Clipboard Toggle word wrap 
      # signtool -d /tmp/signdb -k Signing_cert_nickname -Z /usr/share/ipa/html/configure.jar -e .html /tmp/sign

28.2.4. 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:
Copy to Clipboard Toggle word wrap 
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:
Copy to Clipboard Toggle word wrap 
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.
    Copy to Clipboard Toggle word wrap 
    [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.
    Copy to Clipboard Toggle word wrap 
    [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.
      Copy to Clipboard Toggle word wrap 
      [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.
      Copy to Clipboard Toggle word wrap 
      [root@server ~]# /sbin/restorecon  /var/lib/certmonger/cas/ca_renewal
    3. Restart certmonger.
      Copy to Clipboard Toggle word wrap 
      [root@server ~]# service certmonger restart
    4. Check that the CA is listed to retrieve certificates. This is printed in the CA configuration.
      Copy to Clipboard Toggle word wrap 
      [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.
      Copy to Clipboard Toggle word wrap 
      [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.
      Copy to Clipboard Toggle word wrap 
      [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:
      Copy to Clipboard Toggle word wrap 
      [root@server ~]# service pki-cad stop
    2. Open the CA configuration file.
      Copy to Clipboard Toggle word wrap 
      [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.
      Copy to Clipboard Toggle word wrap 
      ca.crl.MasterCRL.enableCRLCache=false
ca.crl.MasterCRL.enableCRLUpdates=false
    4. Start CA service:
      Copy to Clipboard Toggle word wrap 
      [root@server ~]# service pki-cad start
  5. Configure Apache to redirect CRL requests to the new master.
    1. Open the CA proxy configuration.
      Copy to Clipboard Toggle word wrap 
      [root@server ~]# vim /etc/httpd/conf.d/ipa-pki-proxy.conf
    2. Uncomment the RewriteRule on the last line:
      Copy to Clipboard Toggle word wrap 
      RewriteRule ^/ipa/crl/MasterCRL.bin https://server.example.com/ca/ee/ca/getCRL?op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
    3. Restart Apache:
      Copy to Clipboard Toggle word wrap 
      [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.
    Copy to Clipboard Toggle word wrap 
    [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.
    Copy to Clipboard Toggle word wrap 
    [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.
    Copy to Clipboard Toggle word wrap 
    [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:
      Copy to Clipboard Toggle word wrap 
      [root@server ~]# service pki-cad stop
    2. Open the CA configuration file.
      Copy to Clipboard Toggle word wrap 
      [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.
      Copy to Clipboard Toggle word wrap 
      ca.crl.MasterCRL.enableCRLCache=true
ca.crl.MasterCRL.enableCRLUpdates=true
    4. Start CA service:
      Copy to Clipboard Toggle word wrap 
      [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.
      Copy to Clipboard Toggle word wrap 
      [root@server ~]# vim /etc/httpd/conf.d/ipa-pki-proxy.conf
    2. Comment out the RewriteRule argument on the last line:
      Copy to Clipboard Toggle word wrap 
      #RewriteRule ^/ipa/crl/MasterCRL.bin https://server.example.com/ca/ee/ca/getCRL?op=getCRL&crlIssuingPoint=MasterCRL [L,R=301,NC]
    3. Restart Apache:
      Copy to Clipboard Toggle word wrap 
      [root@server ~]# service httpd restart

28.2.5. 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:
Copy to Clipboard Toggle word wrap 
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.5.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:
    Copy to Clipboard Toggle word wrap 
    semodule -i revoker.pp
  • Generate a new SELinux policy to allow access based on the SELinux error logs for the mod_revocator connection attempt.
    Copy to Clipboard Toggle word wrap 
    audit2allow -a -M revoker

28.2.5.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.
    Copy to Clipboard Toggle word wrap 
    [root@server ~]# service pki-ca stop
  2. Open the CS.cfg file.
    Copy to Clipboard Toggle word wrap 
    [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. Copy to Clipboard Toggle word wrap 
    [root@server ~]# service pki-ca start

28.2.5.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.
    Copy to Clipboard Toggle word wrap 
    [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. Copy to Clipboard Toggle word wrap 
    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.
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, Inc.