CA_Certificate_Renewal

CA_Certificate_Renewal#

This page provides manual instructions to renew the IPA CA certificate.

Before you start#

Important: This article is about renewing Certificate Authority (CA) certificate which by default expires in 20 years. In ``getcert list`` its nickname is ‘caSigningCert’. If you want to renew other certificate, e.g., a host or service certificate which typically has expiration period 2 years and is managed by Certmonger please check manually renewal section of Certmonger page

This 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 then your IPA server will not work.

So for example, your CA is set to expire on 12/23, along with all the CA subsystem certificates and likely the server certificates used by Apache and 389-ds.

You come in after Christmas to find that nothing works because the certificates have expired. When you provide your CSR to the external CA, they will need to issue a certificate that is valid from at least Dec 22. It must overlap the old validity time. You will need to reset the system clock on the CA back to the 22nd in order to renew the other certificates, then you can bring time forward.

Procedure in current IPA#

FreeIPA 4.1 introduced integrated CA certificate renewal tools. To manually renew the CA certificate, run:

# ipa-cacert-manage renew

Procedure in IPA < 4.1#

Request renewed certificate#

On a random FreeIPA server with CA installed run:

# getcert start-tracking -d /etc/pki/pki-tomcat/alias -n 'caSigningCert cert-pki-ca' -P <pin> -c dogtag-ipa-ca-renew-agent
# getcert resubmit -i <id> -T ipaCSRExport
# getcert stop-tracking -i <id>

This will get a certificate request file (CSR) in /root/ipa.csr. Sign the CSR file with the external CA and the save the resulting certificate to ipa.crt in PEM format.

Renew CA Certificate on CA Servers#

On all FreeIPA servers with CA installed, run:

# /usr/lib64/ipa/certmonger/stop_pkicad
# certutil -A -d /etc/pki/pki-tomcat/alias -n 'caSigningCert cert-pki-ca' -t CT,C,C -a -i ipa.crt
# /usr/lib64/ipa/certmonger/renew_ca_cert 'caSigningCert cert-pki-ca'

On all FreeIPA servers run:

# certutil -A -d /etc/dirsrv/slapd-REALM -n 'REALM IPA CA' -t CT,,C -f /etc/dirsrv/slapd-REALM/pwdfile.txt -a -i ipa.crt
# certutil -A -d /etc/httpd/alias -n 'REALM IPA CA' -t CT,C,C -f /etc/httpd/alias/pwdfile.txt -a -i ipa.crt
# systemctl restart dirsrv@REALM.service
# systemctl restart httpd

Renew CA Certificate on FreeIPA clients#

On all FreeIPA servers and FreeIPA clients run

# certutil -A -d /etc/pki/nssdb -n 'IPA CA' -t CT,C,C -a -i ipa.crt
# cp ipa.crt /etc/ipa/ca.crt

Procedure in IPA < 4.0#

You need the original CSR in order to obtain a new certificate. You may be able to find this in one of three places:

  1. The external CA may still have a copy of it

  2. In /root/ipa.csr on the initial IPA master

  3. In /etc/pki-ca/CS.cfg in ca.signing.certreq on the initial IPA master. This will need to be converted to PEM format.

You’ll need to know the nickname of your CA in the NSS databases. This is usually ‘” IPA CA”. I will use “EXAMPLE.COM IPA CA”.

You can query the Apache database to find out what this currently is:

# certutil -L -d /etc/httpd/alias

Renew the Certificate#

Give the CSR to your external CA and have them issue you a new certificate. This document assumes that the resulting certificate is saved into /root/ipa.crt and that the external CA certificate chain is saved into /root/external-ca.pem.

You will need to do this renewal on the IPA CA designated for managing renewals.

One way to identify the initial IPA master 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 at the post-save command in this output. It needs to be renew_ca_cert:

# getcert list
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 IPA master CA#

The CA needs to be shut down in order to update its certificate:

# service ipa stop

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

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.

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

Update the LDAP server instances:

# certutil -A -d /etc/dirsrv/slapd-REALM -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

Update the shared system database:

# certutil -A -d /etc/pki/nssdb -n 'EXAMPLE.COM IPA CA'  -t CT,C,C -a -i /root/ipa.crt

Update the CA in the filesystem:

# cat /root/ipa.crt /root/external-ca.pem >/usr/share/ipa/html/ca.crt
# cp /root/ipa.crt /etc/ipa/ca.crt

Restart the world

# service ipa start

Update the CA in LDAP

First convert the certificate to DER form:

# openssl x509 -outform DER -in /root/ipa.crt  -out /tmp/ipa.der

Add 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 new CA on other IPA masters with a CA#

The CA needs to be shut down in order to update its certificate:

# service ipa stop

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

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.

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

Update the LDAP server instances:

# certutil -A -d /etc/dirsrv/slapd-REALM -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

Update the shared system database:

# certutil -A -d /etc/pki/nssdb -n 'EXAMPLE.COM IPA CA'  -t CT,C,C -a -i /root/ipa.crt

Update the CA in the filesystem:

# cat /root/ipa.crt /root/external-ca.pem >/usr/share/ipa/html/ca.crt
# cp /root/ipa.crt /etc/ipa/ca.crt

Restart the world

# service ipa start

Install new CA on other IPA masters without a CA#

Copy the updated CA to the machine. I’m assuming it is in /root/ipa.crt.

Stop the world

# service ipa stop

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

Update the LDAP server instances:

# certutil -A -d /etc/dirsrv/slapd-REALM -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

Update the shared system database:

# certutil -A -d /etc/pki/nssdb -n 'EXAMPLE.COM IPA CA'  -t CT,C,C -a -i /root/ipa.crt

Update the CA in the filesystem:

# cat /root/ipa.crt /root/external-ca.pem >/usr/share/ipa/html/ca.crt
# cp /root/ipa.crt /etc/ipa/ca.crt

Restart the world

# service ipa start

Install the new CA on all IPA client machines#

Retrieve the updated IPA CA, I’ve put it into /root/ipa.crt.

Update the shared system database:

# certutil -A -d /etc/pki/nssdb -n 'EXAMPLE.COM IPA CA'  -t CT,C,C -a -i /root/ipa.crt

Update the CA in the filesystem:

# cp /root/ipa.crt /etc/ipa/ca.crt

Troubleshooting#

See the Troubleshooting Guide.