Chapter 36. Obtaining an IdM certificate for a service using certmonger

36.1. Certmonger overview

What certmonger does

When Identity Management (IdM) is installed with an integrated IdM Certificate Authority (CA), it uses the certmonger service to track and renew system and service certificates. When the certificate is reaching its expiration date, certmonger manages the renewal process by:

  • regenerating a certificate-signing request (CSR) using the options provided in the original request.
  • submitting the CSR to the IdM CA using the IdM API cert-request command.
  • receiving the certificate from the IdM CA.
  • executing a pre-save command if specified by the original request.
  • installing the new certificate in the location specified in the renewal request: either in an NSS database or in a file.
  • executing a post-save command if specified by the original request. For example, the post-save command can instruct certmonger to restart a relevant service, so that the service picks up the new certificate.

Types of certificates certmonger tracks

Certificates can be divided into system and service certificates.

Unlike service certificates (for example, for HTTP, LDAP and PKINIT), which have different keypairs and subject names on different servers, IdM system certificates and their keys are shared by all CA replicas. The IdM system certificates include:

  • IdM CA certificate
  • OCSP signing certificate
  • IdM CA subsystem certificates
  • IdM CA audit signing certificate
  • IdM renewal agent (RA) certificate
  • KRA transport and storage certificates

The certmonger service tracks the IdM system and service certificates that were requested during the installation of IdM environment with an integrated CA. Certmonger also tracks certificates that have been requested manually by the system administrator for other services running on the IdM host. Certmonger does not track external CA certificates or user certificates.

Certmonger components

The certmonger service consists of two main components:

  • The certmonger daemon, which is the engine tracking the list of certificates and launching renewal commands
  • The getcert utility for the command-line interface (CLI), which allows the system administrator to actively send commands to the certmonger daemon.

More specifically, the system administrator can use the getcert utility to:

36.2. Obtaining an IdM certificate for a service using certmonger

To ensure that communication between browsers and the web service running on your Identity Management (IdM) client is secure and encrypted, use a TLS certificate. Obtain the TLS certificate for your web service from the IdM Certificate Authority (CA).

This section describes how to use certmonger to obtain an IdM certificate for a service (HTTP/my_company.idm.example.com@IDM.EXAMPLE.COM) running on an IdM client.

Using certmonger to request the certificate automatically means that certmonger manages and renews the certificate when it is due for a renewal.

For a visual representation of what happens when certmonger requests a service certificate, see Section 36.3, “Communication flow for certmonger requesting a service certificate”.

Prerequisites

  • The web server is enrolled as an IdM client.
  • You have root access to the IdM client on which you are running the procedure.
  • The service for which you are requesting a certificate does not have to pre-exist in IdM.

Procedure

  1. On the my_company.idm.example.com IdM client on which the HTTP service is running, request a certificate for the service corresponding to the HTTP/my_company.idm.example.com@IDM.EXAMPLE.COM principal, and specify that

    • The certificate is to be stored in the local /etc/pki/tls/certs/httpd.pem file
    • The private key is to be stored in the local /etc/pki/tls/private/httpd.key file
    • That an extensionRequest for a SubjectAltName be added to the signing request with the DNS name of my_company.idm.example.com:

      # ipa-getcert request -K HTTP/my_company.idm.example.com -k /etc/pki/tls/private/httpd.key -f /etc/pki/tls/certs/httpd.pem -D my_company.idm.example.com -C "systemctl restart httpd"
      New signing request "20190604065735" added.

      In the command above:

      • The ipa-getcert request command specifies that the certificate is to be obtained from the IdM CA. The ipa-getcert request command is a shortcut for getcert request -c IPA.
      • The -C option instructs certmonger to restart the httpd service after obtaining the certificate.
      • The -D option specifies the SubjectAltName DNS value to be added to the request.
      • To specify that the certificate be issued with a particular profile, use the -T option.
      • To request a certificate using the named issuer from the specified CA, use the -X ISSUER option.
      Note

      RHEL 8 uses a different SSL module in Apache than the one used in RHEL 7. The SSL module relies on OpenSSL rather than NSS. For this reason, in RHEL 8 you cannot use an NSS database to store the HTTPS certificate and the private key.

  2. Optionally, to check the status of your request:

    # ipa-getcert list -f /etc/pki/tls/certs/httpd.pem
    Number of certificates and requests being tracked: 3.
    Request ID '20190604065735':
        status: MONITORING
        stuck: no
        key pair storage: type=FILE,location='/etc/pki/tls/private/httpd.key'
        certificate: type=FILE,location='/etc/pki/tls/certs/httpd.crt'
        CA: IPA
    [...]

    The output shows that the request is in the MONITORING status, which means that a certificate has been obtained. The locations of the key pair and the certificate are those requested.

36.3. Communication flow for certmonger requesting a service certificate

The diagrams in this section show the stages of what happens when certmonger requests a service certificate from Identity Management (IdM) certificate authority (CA) server. The sequence consists of these diagrams:

Figure 36.1, “Unencrypted communication” shows the initial situation: without an HTTPS certificate, the communication between the web server and the browser is unencrypted.

Figure 36.1. Unencrypted communication

84 RHEL IdM 0420 1


Figure 36.2, “Certmonger requesting a service certificate” shows the system administrator using certmonger to manually request an HTTPS certificate for the Apache web server. Note that when requesting a web server certificate, certmonger does not communicate directly with the CA. It proxies through IdM.

Figure 36.2. Certmonger requesting a service certificate

84 RHEL IdM 0420 2


Figure 36.3, “IdM CA issuing the service certificate” shows an IdM CA issuing an HTTPS certificate for the web server.

Figure 36.3. IdM CA issuing the service certificate

84 RHEL IdM 0420 3


Figure 36.4, “Certmonger applying the service certificate” shows certmonger placing the HTTPS certificate in appropriate locations on the IdM client and, if instructed to do so, restarting the httpd service. The Apache server subsequently uses the HTTPS certificate to encrypt the traffic between itself and the browser.

Figure 36.4. Certmonger applying the service certificate

84 RHEL IdM 0420 4


Figure 36.5, “Certmonger requesting a new certificate when the old one is nearing expiration” shows certmonger automatically requesting a renewal of the service certificate from the IdM CA before the expiration of the certificate. The IdM CA issues a new certificate.

Figure 36.5. Certmonger requesting a new certificate when the old one is nearing expiration

84 RHEL IdM 0420 5


36.4. Viewing the details of a certificate request tracked by certmonger

The certmonger service monitors certificate requests. When a request for a certificate is successfully signed, it results in a certificate. Certmonger manages certificate requests including the resulting certificates. This section describes how to view the details of a particular certificate request managed by certmonger.

Procedure

  • If you know how to specify the certificate request, list the details of only that particular certificate request. You can, for example, specify:

    • The request ID
    • The location of the certificate
    • The certificate nickname

      For example, to view the details of the certificate whose request ID is 20190408143846, using the -v option to view all the details of errors in case your request for a certificate was unsuccessful:

      # getcert list -i 20190408143846 -v
      Number of certificates and requests being tracked: 16.
      Request ID '20190408143846':
      	status: MONITORING
      	stuck: no
      	key pair storage: type=NSSDB,location='/etc/dirsrv/slapd-IDM-EXAMPLE-COM',nickname='Server-Cert',token='NSS Certificate DB',pinfile='/etc/dirsrv/slapd-IDM-EXAMPLE-COM/pwdfile.txt'
      	certificate: type=NSSDB,location='/etc/dirsrv/slapd-IDM-EXAMPLE-COM',nickname='Server-Cert',token='NSS Certificate DB'
      	CA: IPA
      	issuer: CN=Certificate Authority,O=IDM.EXAMPLE.COM
      	subject: CN=r8server.idm.example.com,O=IDM.EXAMPLE.COM
      	expires: 2021-04-08 16:38:47 CEST
      	dns: r8server.idm.example.com
      	principal name: ldap/server.idm.example.com@IDM.EXAMPLE.COM
      	key usage: digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment
      	eku: id-kp-serverAuth,id-kp-clientAuth
      	pre-save command:
      	post-save command: /usr/libexec/ipa/certmonger/restart_dirsrv IDM-EXAMPLE-COM
      	track: yes
      	auto-renew: yes

    The output displays several pieces of information about the certificate, for example:

    • the certificate location; in the example above, it is the NSS database in the /etc/dirsrv/slapd-IDM-EXAMPLE-COM directory
    • the certificate nickname; in the example above, it is Server-Cert
    • the file storing the pin; in the example above, it is /etc/dirsrv/slapd-IDM-EXAMPLE-COM/pwdfile.txt
    • the Certificate Authority (CA) that will be used to renew the certificate; in the example above, it is the IPA CA
    • the expiration date; in the example above, it is 2021-04-08 16:38:47 CEST
    • the status of the certificate; in the example above, the MONITORING status means that the certificate is valid and it is being tracked
    • the post-save command; in the example above, it is the restart of the LDAP service
  • If you do not know how to specify the certificate request, list the details of all the certificates that certmonger is monitoring or attempting to obtain:

    # getcert list

Additional information

  • To view the different options how to specify the certificate request displayed, see the getcert list man page.

36.5. Starting and stopping certificate tracking

This section describes how you can use the getcert stop-tracking and getcert start-tracking commands to monitor certificates. The two commands are provided by the certmonger service. Enabling certificate tracking is especially useful if you have imported a certificate issued by the Identity Management (IdM) certificate authority (CA) onto the machine from a different IdM client. Enabling certificate tracking can also be the final step of the following provisioning scenario:

  1. On the IdM server, you create a certificate for a system that does not exist yet.
  2. You create the new system.
  3. You enroll the new system as an IdM client.
  4. You import the certificate and the key from the IdM server on to the IdM client.
  5. You start tracking the certificate using certmonger to ensure that it gets renewed when it is due to expire.

Procedure

  • To disable the monitoring of a certificate with the Request ID of 20190408143846:

    # getcert stop-tracking -i 20190408143846

    For more options, see the getcert stop-tracking man page.

  • To enable the monitoring of a certificate stored in the /tmp/some_cert.crt file, whose private key is stored in the /tmp/some_key.key file:

    # getcert start-tracking -c IPA -f /tmp/some_cert.crt -k /tmp/some_key.key

    Certmonger cannot automatically identify the CA type that issued the certificate. For this reason, add the -c option with the IPA value to the getcert start-tracking command if the certificate was issued by the IdM CA. Omitting to add the -c option results in certmonger entering the NEED_CA state.

    For more options, see the getcert start-tracking man page.

Note

The two commands do not manipulate the certificate. For example, getcert stop-tracking does not delete the certificate or remove it from the NSS database or from the filesystem but simply removes the certificate from the list of monitored certificates. Similarly, getcert start-tracking only adds a certificate to the list of monitored certificates.

36.6. Renewing a certificate manually

When a certificate is near its expiration date, the certmonger daemon automatically issues a renewal command using the certificate authority (CA) helper, obtains a renewed certificate and replaces the previous certificate with the new one.

It is also possible to manually renew a certificate in advance by using the getcert resubmit command. This way, you can update the information the certificate contains, e.g. by adding a Subject Alternative Name (SAN).

This section describes how to renew a certificate manually.

Procedure

  • To renew a certificate with the Request ID of 20190408143846:

    # getcert resubmit -i 20190408143846

    To obtain the Request ID for a specific certificate, use the getcert list command. For details, see the getcert list man page.

36.7. Making certmonger resume tracking of IdM certificates on a CA replica

This procedure shows how to make certmonger resume the tracking of Identity Management (IdM) system certificates that are crucial for an IdM deployment with an integrated certificate authority after the tracking of certificates was interrupted. The interruption may have been caused by the IdM host being unenrolled from IdM during the renewal of the system certificates or by replication topology not working properly. The procedure also shows how to make certmonger resume the tracking of the IdM service certificates, namely the HTTP, LDAP and PKINIT certificates.

Prerequisites

  • The host on which you want to resume tracking system certificates is an IdM server that is also an IdM certificate authority (CA) but not the IdM CA renewal master.

Procedure

  1. Get the PIN for the subsystem CA certificates:

    # grep 'internal=' /var/lib/pki/pki-tomcat/conf/password.conf
  2. Add tracking to the subsystem CA certificates, replacing [internal PIN] in the commands below with the PIN obtained in the previous step:

    # getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "caSigningCert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "caSigningCert cert-pki-ca"'
    
    # getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "auditSigningCert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "auditSigningCert cert-pki-ca"'
    
    # getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "ocspSigningCert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "ocspSigningCert cert-pki-ca"'
    
    # getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "subsystemCert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "subsystemCert cert-pki-ca"'
    
    # getcert start-tracking -d /etc/pki/pki-tomcat/alias -n "Server-Cert cert-pki-ca" -c 'dogtag-ipa-ca-renew-agent' -P [internal PIN] -B /usr/libexec/ipa/certmonger/stop_pkicad -C '/usr/libexec/ipa/certmonger/renew_ca_cert "Server-Cert cert-pki-ca"'
  3. Add tracking for the remaining IdM certificates, the HTTP, LDAP, IPA renewal agent and PKINIT certificates:

    # getcert start-tracking -f /var/lib/ipa/certs/httpd.crt -k /var/lib/ipa/private/httpd.key -p /var/lib/ipa/passwds/idm.example.com-443-RSA -c IPA -C /usr/libexec/ipa/certmonger/restart_httpd
    
    # getcert start-tracking -d /etc/dirsrv/slapd-IDM-EXAMPLE-COM -n "Server-Cert" -c IPA -p /etc/dirsrv/slapd-IDM-EXAMPLE-COM/pwdfile.txt -C '/usr/libexec/ipa/certmonger/restart_dirsrv "IDM-EXAMPLE-COM"'
    
    # getcert start-tracking -f /var/lib/ipa/ra-agent.pem -k /var/lib/ipa/ra-agent.key -c dogtag-ipa-ca-renew-agent -B /usr/libexec/ipa/certmonger/renew_ra_cert_pre -C /usr/libexec/ipa/certmonger/renew_ra_cert
    
    # getcert start-tracking -f /var/kerberos/krb5kdc/kdc.crt -k /var/kerberos/krb5kdc/kdc.key -c dogtag-ipa-ca-renew-agent -B /usr/libexec/ipa/certmonger/renew_ra_cert_pre -C /usr/libexec/ipa/certmonger/renew_kdc_cert
  4. Restart certmonger:

    # systemctl restart certmonger
  5. Wait for one minute after certmonger has started and then check the statuses of the new certificates:

    # getcert list

Additional resources

  • If your IdM system certificates have all expired, follow the procedure described in this Knowledge Centered Support (KCS) solution to manually renew IdM system certificates on the IdM CA master that is also the CA renewal master and the CRL generation master. Then follow the procedure described in this KCS solution to manually renew IdM system certificates on all the other CA servers in the topology.