Chapter 21. Upgrading from Certificate System 9 to Certificate System 10

Users are recommended to upgrade to the most recent version of Red Hat Certificate System to get security and bug fixes through the Errata-Support channel. Currently, the most recent versions are RHCS 9.7 on RHEL 7.9 and RHCS 10.4 on RHEL 8.6.

21.1. Migrating a CA

A Certificate System migration using the existing certificate files requires the following steps:
  1. Section 21.1.1, “Exporting Data from the Previous System”
  2. Section 21.1.2, “Verifying the PKCS12 file”
  3. Section 21.1.3, “Setting up the CA on the New Host”
  4. Section 21.1.4, “Importing the Old Data into the New CA”
  5. Section 21.1.5, “Reassigning Users to Default Groups”

21.1.1. Exporting Data from the Previous System

Before you set up the new Certificate System instance, export the data of the current certificate authority (CA) using the steps below. In this example, the CA's instance name is <pki-rootCA> and is located at /var/lib/pki/<instance_name>.
  1. Export the CA signing certificate and key. 
    # grep internal= /var/lib/pki/<instance_name>/conf/password.conf | awk -F= '{print $2;}' > internal.txt
# echo <Secret.123> > password.txt
# PKCS12Export -d /var/lib/pki/<instance_name>/alias -p internal.txt -o ca.p12 -w password.txt
  2. Export the Certificate Signing Requests (CSR). 
    # echo "-----BEGIN NEW CERTIFICATE REQUEST-----" > ca_signing.csr
# sed -n "/^ca.signing.certreq=/ s/^[^=]*=// p" < /var/lib/pki/<instance_name>/ca/conf/CS.cfg >> ca_signing.csr
# echo "-----END NEW CERTIFICATE REQUEST-----" >> ca_signing.csr
  3. If the old CA is an intermediate CA (with a single root CA in the chain), extract the root CA from the NSS database: 
    # certutil -L -d /var/lib/pki/<instance_name>/alias/ -n root_CA_nickname -a > ca_rootca_signing.crt
  4. Back up the internal LDAP database.
    • Find the name of the CA database by checking the value of internaldb.database in the CA's CS.cfg: 
      # grep internaldb.database /etc/pki/<instance_name>/ca/CS.cfg
internaldb.database=<CS_database_name>
    • Export this database to a .ldif file using the instance-specific script generated by setup-ds.pl when the instance was created: 
      # cd /usr/lib64/dirsrv/<instance_name>
# ./db2ldif -n "<CS_database_name>" -a /tmp/old_ca.ldif
      The db2ldif command runs as the DB user, so it needs a destination folder with writing permissions.
  5. Transfer the old_ca.ldif, ca.p12, ca_signing.csr files to the new CA machine. If the CA being migrated is also an intermediate CA, transfer the ca_rootca_signing.crt as well.

21.1.2. Verifying the PKCS12 file

On the new CA, a new database instance runs on the standard port (389). The PKCS12 file contains all the system certificates for the old system. Verify that the file includes the CA signing certificate and the key.

Note

In FIPS mode, you must run the pki pkcs12 commands with an NSS database. For more information, see the pki-pkcs12 CLI.
  1. Find the CA signing certificate and the key. 
    $ echo "<Secret.123>" > password.txt
$ pki pkcs12-cert-find --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-key-find --pkcs12-file ca.p12 --pkcs12-password-file password.txt
  2. Verify the presence of the trust flags of the CA signing certificate. If the flags are not "CTu,Cu,Cu" or they are missing, add them. 
    $ pki pkcs12-cert-mod "<caSigningCert cert-pki-rootCA>" \ --pkcs12-file ca.p12 --pkcs12-password-file password.txt \ --trust-flags "CTu,Cu,Cu"
  3. Remove other certificates and keys. 
    $ pki pkcs12-cert-del "<Server-Cert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-cert-del "<subsystemCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-cert-del "<ocspSigningCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
$ pki pkcs12-cert-del "<auditSigningCert cert-pki-rootCA>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt
  4. If the CA being migrated is also an intermediate CA, remove the root CA certificate from the PKCS#12 file. 
    $ pki pkcs12-cert-del "<Top-level Root CA Signing Certificate>" --pkcs12-file ca.p12 --pkcs12-password-file password.txt

21.1.3. Setting up the CA on the New Host

After you have exported the data from the existing instance, create and set up the certificate authority (CA) on the new host.
  1. Create a configuration file for pkispawn, for example CA.cfg, using the parameters of the old CA. This instance runs on the standard port (389). 
    [DEFAULT]
pki_instance_name=<new_instance_name>
pki_admin_password=<caadmin_password>
pki_client_pkcs12_password=<pkcs12_file_password>
pki_ds_password=<DS_password>
pki_ds_ldap_port=389
pki_existing=True

[CA]
pki_ca_signing_csr_path=<path/to/ca_signing.csr>
pki_ca_signing_cert_path=<path/to/ca_signing.crt>
pki_ca_signing_nickname=<caSigningCert cert-nickname>
pki_ds_base_dn=<o=pki-tomcat-CA>
pki_ds_database=<instance_name-CA>
pki_serial_number_range_start=<starting_number_for_cert_serial_numbers>
pki_request_number_range_start=<starting_number_for_request_IDs>
pki_master_crl_enable=False
    If the old CA is an intermediate CA, add the following two lines to the configuration file. They correspond to the path to the root CA certificate and the nickname to use when storing the certificate in the NSS database. 
    pki_cert_chain_path=<rootca_signing.crt>
pki_cert_chain_nickname=<caSigningCert cert-pki-ca>
    For details and parameter descriptions, see the pkispawn(8) man page.
  2. Run pkispawn on the new host to create the new CA instance: 
    # pkispawn -s CA -f ca.cfg -v

Note

For instructions on how to set up a new DS instance for the new CA, see Installing Red Hat Directory Server.

21.1.4. Importing the Old Data into the New CA

After you have created the new CA instance, import the data into the new CA database:
  1. Stop the CA service. 
    # systemctl stop pki-tomcatd@<instance_name>.service
  2. Optional: Back up the CA database on the new host. 
    # dsctl -v idm-qe-01 db2bak
    The backup is stored in the /var/lib/dirsrv/<instance_name>/bak/<host_name-time_stamp>/ directory.
  3. Remove the certificate entry for the signing certificate from the new RHEL 8 internal database. 
    # ldapdelete -x -w <password< -D 'cn=Directory Manager' "cn=<serial_number<,ou=certificateRepository,ou=ca,o=pki-tomcat-CA"
    The entry is now imported from the old data, so that the CRL attributes in that entry point to the correct entries.
  4. Import the data into the new database: 
    # ldapmodify -x -W <password> -D 'cn=Directory Manager' -a -c -f <path/to/old_ca.ldif>
    The ldapmodify utility only adds new entries and does not update existing entries, created when you installed the CA.
  5. Optional: Verify the output in the import.log file. You can search for failed actions, such as ldap_add: Invalid syntax (21).
  6. Remove the directory entry for the old security domain. 
    # ldapmodify -W <password> -x -D "cn=Directory Manager"
dn: cn=<server.example.com:9445>,cn=CAList,ou=Security Domain,<o=pki-tomcat-CA>
changetype: delete
  7. Enable the ca.crl.MasterCRL.enable parameter in the /etc/pki/<instance_name>/ca/CS.cfg file, to have the CA act as the certificate revocation list (CRL) master: 
    ca.crl.MasterCRL.enable=true
  8. Restart the CA service: 
    # systemctl start pki-tomcatd@<instance_name>

21.1.5. Reassigning Users to Default Groups

Add members to the default groups manually, using the ldapmodify or pki utility.
  1. Set up the client: 
    # pki -c <password> client-init
Client initialized

    # pk12util -i ~/.dogtag/<instance_name>/ca_admin_cert.p12 -d ~/.dogtag/nssdb/
Enter Password or Pin for "NSS Certificate DB":
Enter password for PKCS12 file:
pk12util: PKCS12 IMPORT SUCCESSFUL
...
  2. Add the user account to the Administrators and Security Domain Administrators groups: 
    # pki -n "<PKI Administrator for example.com>" -c <password> \
user-membership-add <user_name> "Certificate Manager Agents"
    The default (bootstrap) admin users in RHCS 9 and RHCS 10 have the same default roles, that is the same group membership. However, if you have a non-default admin user or have customized the admin roles in RHCS 9, those changes might not be migrated properly. In this case, reconfigure the roles in RHCS 10: 
    # pki -n "<PKI Administrator for example.com>" -c <password> \
user-membership-add <user> "Administrators"
# pki -n "<PKI Administrator for example.com>" -c <password> \
user-membership-add <user> "Security Domain Administrators"
If you want to make sure the certificate has been migrated successfully, check its existence on the new host by running the ca-cert-find command.