From 6dfe36ac7c650458a3c2715ac3f694ebb8c336b3 Mon Sep 17 00:00:00 2001 From: "Endi S. Dewata" Date: Thu, 23 Jan 2025 13:06:25 -0600 Subject: [PATCH] Update cert renewal doc The IPA-specific content in Offline System Certificate Renewal has been moved into a separate page: https://github.com/dogtagpki/freeipa/wiki/Renewing-System-Certificates --- .../Offline_System_Certificate_Renewal.md | 117 +++--------------- 1 file changed, 20 insertions(+), 97 deletions(-) diff --git a/docs/admin/Offline_System_Certificate_Renewal.md b/docs/admin/Offline_System_Certificate_Renewal.md index 02ae619bac5..b7f44857a93 100644 --- a/docs/admin/Offline_System_Certificate_Renewal.md +++ b/docs/admin/Offline_System_Certificate_Renewal.md @@ -9,101 +9,28 @@ used to renew the certificates before they expire. There are 2 ways to renew the 1. [Automated Renewal Process](#Automated-Renewal-Process) - supports LDAPS/LDAPI configuration 2. [Manual Renewal Process](#Manual-Renewal-Process) - supports LDAP/LDAPS/LDAPI configuration -This tool's behavior is different in an **IPA environment** and **standalone PKI environment** - -**NOTE:** If you have a **non-secure** LDAP setup and if you **don't know the agent username/password**, you cannot use this tool +**NOTE:** For IPA follow [this page](https://github.com/dogtagpki/freeipa/wiki/Renewing-System-Certificates) instead. ## Automated Renewal Process -### IPA Environment (Uses LDAPI) - -#### Reason for using LDAPI mechanism: - -This tool was designed with a mindset of "one-stop solution" for sysadmins to bring up a PKI server that failed -due to expired system certificates. In an IPA environment, LDAPI is used for the following reasons: +**NOTE:** If you have a **non-secure** LDAP setup and if you **don't know the agent username/password**, use the manual process instead. -- DS certificate may be expired -- We need to set/reset password for some accounts using `ldappasswd` which need confidentiality. Therefore we cannot use LDAPS/STARTTLS - -#### Assumptions: - -- Valid CA certificate -- `cert-fix` must be run as `root` -- The password of the specified agent account will be reset. If needed, it can be changed back afterwards (manually; successful execution of `cert-fix` proves that the operator has privileges to do this) -- The password of the `pkidbuser` account will be reset - -#### Usage: - -1. Determine the `serial number` of the IPA RA, DS LDAP and HTTPD certificates - ```` - # keytool -printcert -file /var/lib/ipa/ra-agent.pem - # certutil -L -n Server-Cert -d /etc/dirsrv/slapd-REALM - # keytool -printcert -file /var/lib/ipa/certs/httpd.crt - ```` - -2. Ensure DS is running - ```` - # systemctl status dirsrv@REALM - ```` - -3. Run the following command providing **all** the certs that needs to be renewed. Command should complete without error. - - ```` - # pki-server cert-fix \ - --ldapi-socket /var/run/slapd-REALM.socket \ - --agent-uid admin \ - --cert sslserver \ - --cert subsystem \ - --cert ca_ocsp_signing \ - --cert ca_audit_signing \ - --extra-cert $IPA_RA_SERIAL \ - --extra-cert $DS_SERIAL \ - --extra-cert $HTTPD_SERIAL - ```` - -4. Verify that there is no `internaldb` field in `/var/lib/pki/pki-tomcat/conf/password.conf` - -5. Verify that `CS.cfg` has `internaldb.ldapauth.authtype=SslClientAuth` - -6. Copy `/var/lib/pki/pki-tomcat/conf/certs/$IPA_RA_SERIAL-renewed.crt` to `/var/lib/ipa/ra-agent.pem` - -7. Remove old DS cert and import DS renewed cert into DS NSSDB and provide the pin from `/etc/dirsrv/slapd-REALM/pin.txt` - ```` - # certutil -D -n Server-Cert \ - -d /etc/dirsrv/slapd-REALM/ - - # certutil -A -n Server-Cert \ - -d /etc/dirsrv/slapd-REALM/ \ - -t ',,' \ - -a -i /var/lib/pki/pki-tomcat/conf/certs/${DS_SERIAL}-renewed.crt - ```` -8. Copy `/var/lib/pki/pki-tomcat/conf/certs/$HTTPD_SERIAL` to `/var/lib/ipa/certs/httpd.crt` - -9. `ipactl restart` should succeed - -10. Verify that PKI operations succeed - ```` - # pki -U https://:8443 ca-cert-find - ```` - -### Standalone PKI environment (Uses LDAPS) - -#### Assumptions: +### Prerequisite - Valid CA certificate - TLS configured Directory Server -- If Dogtag was configured to use TLS certificate authentication to bind to LDAP, a Valid DS service certificate -- `cert-fix` must be run as `root` -- The password of the specified agent account will be reset. If needed, it can be changed back afterwards (manually; successful execution of `cert-fix` proves that the operator has privileges to do this) +- If Dogtag was configured to use TLS certificate authentication to bind to LDAP, a valid DS service certificate +- `pki-server cert-fix` must be run as `root` +- The password of the specified agent account will be reset. If needed, it can be changed back afterwards (manually; successful execution of `pki-server cert-fix` proves that the operator has privileges to do this) - The password of the `pkidbuser` account will be reset -#### Usage: +### Usage One line tool that fixes all certificates: # pki-server cert-fix \ - --ldap-url \ - --agent-uid + --ldap-url \ + --agent-uid For all available options, you can type: @@ -111,10 +38,6 @@ For all available options, you can type: ## Manual Renewal Process -**NOTE:** The steps listed here are for a *PKI standalone environment*. For the *IPA Environment*, it's suggested to use -the **IPA specific `ipa-cert-fix` tool** to simplify the process. It uses [`pki-server cert-fix`](#ipa-environment-uses-ldapi) -behind the scenes. - ### Initialization It is recommended to run the following steps to ensure that `CS.cfg` and NSS database are synchronized and that the server can operate without any issues. @@ -187,21 +110,21 @@ There are 2 different scenarios based on value of `internaldb.ldapauth.authtype` 1. Use a **valid admin cert** OR **agent's username/password** to renew required system certs using PKI tool. For **`sslserver`** cert provide the `serial number` from the **original SSL server cert** to avoid placing request for unintended cert. ```` # pki-server cert-create --renew \ - -n \ - -d \ - -c \ - \ - --serial + -n \ + -d \ + -c \ + \ + --serial ```` **OR** ```` # pki-server cert-create --renew \ - -u \ - -w \ - \ - --serial + -u \ + -w \ + \ + --serial ```` **OR** @@ -223,7 +146,7 @@ There are 2 different scenarios based on value of `internaldb.ldapauth.authtype` # pki-server cert-import ```` - *Note:* Make sure the **Audit Log** has the trust flags: ***"u,u,Pu"*** by running the following command: + **Note:** Make sure the audit signing certificates have `u,u,Pu` trust flags by running the following command: ```` # certutil -L -d /var/lib/pki/pki-tomcat/alias/ @@ -242,7 +165,7 @@ There are 2 different scenarios based on value of `internaldb.ldapauth.authtype` ```` # pki-server selftest-enable ```` -6. Restore the CS.cfg values that you modified earlier in [Configuring LDAP](#Configuring-LDAP) section +6. Restore the `CS.cfg` values that you modified earlier in [Configuring LDAP](#Configuring-LDAP) section 7. Start server with new renewed system certificates. ````