Menu Close

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

Red Hat Certificate System supports two ways to upgrade from RHCS 9 on RHEL 7 to RHCS 10 on RHEL 8:

21.1. Migrating a CA Using the Existing CA Files

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, “Setting up the CA on the New Host”
  3. Section 21.1.3, “Importing the Data into the New CA”
  4. Section 21.1.4, “Reassigning Users to Default Groups”

Important

In case a HSM is in use, if the signing certificate has been renewed and reissued using the same keys, multiple certificates could exist in the HSM with the same nickname. This could cause pkispawn to fail to retrieve the correct certificate and prevent a successful migration. Therefore, before you start the migration, make sure you delete any old, duplicate certificate entries in the HSM.

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 certutil tool.
  1. Use the following procedure to export the CRT and CSR from the old CA:
    1. Generate the CRT: 
      # certutil -L -d /var/lib/instance_name/alias/ -n "caSigningCert cert-instance_name" -a > ca_signing.crt
    2. Generate the CSR: 
      	# echo "-----BEGIN NEW CERTIFICATE REQUEST-----" > ca_signing.csr
	# sed -n "/^ca.signing.certreq=/ s/^[^=]*=// p" < /var/lib/instance_name/conf/CS.cfg >> ca_signing.csr
	# echo "-----END NEW CERTIFICATE REQUEST-----" >> ca_signing.csr
  2. 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
  3. Use the following procedure to back up the database:
    1. 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
    2. 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

      Note

      The db2ldif command runs as the DB user, so it needs a destination folder where it has writing permissions.
  4. Transfer the exported files (ca_signing.crt, ca_signing.csr, old_ca.ldif, and ca_rootca_signing.crt if this is an intermediate CA) to the RHEL 8 machine that will host the new CA instance.

21.1.2. Setting up the CA on the New Host

Once you have exported the data from the existing instance in Section 21.1.1, “Exporting Data from the Previous System”, 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. For more information on the pkispawn parameters, see see Table 21.1, “pkispawn Parameter Descriptions” that follows this procedure. 
    [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_hsm_enable=True
	pki_hsm_libfile=path_to_HSM_library
	pki_hsm_modulename=HSM_module_name
	pki_token_name=HSM_token_name
	pki_token_password=HSM_token_password
	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_ca_signing_token=HSM_token_name
	pki_ds_base_dn=o=pki-tomcat-CA
	pki_ds_database=instance_name-CA
	pki_serial_number_range_start=4e
	pki_request_number_range_start=30
	pki_master_crl_enable=False
	pki_cert_chain_path=rootca_signing.crt
	pki_cert_chain_nickname=caSigningCert cert-pki-ca
  2. Run pkispawn on the new host to create the new CA instance: 
    # pkispawn -s CA -f ca.cfg -vv

Table 21.1. pkispawn Parameter Descriptions

Parameters and Settings
Description
pki_instance_name
If you do not give a different name to the new instance, then you need to make sure to define the nicknames for all the system certificates so that there are no conflicts in the HSM with the old system certificates. In practice, you will probably want to define all the nicknames in any case. The CA signing cert nickname should be the same as the old CA.
pki_hsm_* and pki_token_*
These parameters enable communication with the HSM.
pki_existing=True
Sets to use the existing CA mechanism.
pki_ca_signing_nickname
The CA signing nickname must be exactly the same as used in the previous installation, otherwise the installer cannot find the signing key.
pki_ca_signing_*
Sets the paths to the certificate signing request (CSR) and the certificate files copied from the existing machine.
pki_ds_base_dn
Sets the Directory Server base distinguished name (DN). The value must be the same as on the previous CA, so that you can easily import the old data. You can find this value on the previous host in the internaldb.basedn parameter in the /var/lib/instance_name/conf/CS.cfg file of the old CA.
pki_serial_number_range_start
The serial number is critical. The value must be higher than the last number used in the previous CA. To display which numbers are already used, see the old CA's agent interface. This parameter is set in hex format without the leading 0x prefix. The value used in the examples (4e) is 78 in decimal.
pki_request_number_range_start
The request number is critical. The value must be higher than the last number used in the previous CA. To display which numbers are already used, see the old CA's agent interface. The value is set in decimal format.
pki_master_crl_enable=False
Prevents the initial creation and publishing of a certificate revocation list (CRL) during the setup. Instead, the CRL will be imported from the old data during the database migration.
pki_cert_chain_path and pki_cert_chain_nickname
Set these parameters only if the old CA is an intermediate CA. In this case, set the parameters to the path to the root CA certificate file and the nickname to use when storing the certificate in the network security services (NSS) database.
For further details and parameter descriptions, see the pkispawn(8) man page.

21.1.3. Importing the Data into the New CA

After you have created the new CA instance in Section 21.1.2, “Setting up the CA on the New Host”, import the data into the new CA database:
  1. When migrating from a previous version, it can be necessary to manually clean up the LDAP data interchange format (LDIF) file created in Section 21.1.1, “Exporting Data from the Previous System”. Syntax checking is now enabled by default, therefore old data may include entries which would be invalid in new databases. For example:
    • You must set values of boolean attributes either to TRUE or FALSE (all capitalized).

      Important

      Do not automatically update all occurrences to uppercase by using a search and replace utility. Some attributes in the LDIF file contain these strings, but are not using the boolean type. Updating these attributes' values can cause the import to fail. Typically, boolean attributes are only used in the cn=CAList,ou=Security Domain,CS_instance_name security domain database entries.
    • The syntax validation does not allow empty strings. The solution is simply to remove the line corresponding to that attribute.
      Empty strings often appear in userType and userState attributes in cmsUser entries in ou=People,CS_instance_name.
    During the import, other entries may fail the syntax check as well. It is therefore important to verify the log file after the operation. Optionally, you can import the LDIF file into a temporary, empty database to find out which entries failed to be imported; or do a test import into an empty database beforehand.
  2. Shut down the CA service: 
    # systemctl stop pki-tomcatd@instance_name.service
  3. Optionally, back up the CA database on the new host: 
    # db2bak
    The backup is stored in the /var/lib/dirsrv/instance_name/bak/host_name-time_stamp/ directory.
  4. Run the ldapdeletecommand to remove the certificate entry for the signing certificate from the new RHEL 8 internal database, using the serial number of the imported signing certificate. Removing the entry from the new database ensures that this entry will be imported from the old data, so that the CRL attributes in that entry will point to the correct entries. 
    # ldapdelete -x -w password -D 'cn=Directory Manager' "cn={serial_number},ou=certificateRepository,ou=ca,o=pki-tomcat-CA"
  5. Import the data into the new database, using the ldapmodify utility. For example: 
    # 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. For example:
    • Top level entries. For example: o=pki-tomcat-CA.
    • Default groups. For example: cn=Certificate Manager Agents,ou=groups,o=pki-tomcat-CA.
      Because the standard groups are not updated, the users are not automatically added to these groups. After the import, you must add members to each default group manually. See Section 21.1.4, “Reassigning Users to Default Groups”.
    • Default access control lists (ACL) for the CA.
    • Signing certificate: this entry was created as part of importing the old signing certificate and key.
    As mentioned earlier, certain entries may fail syntax validation. Verify the output in the import.log file and search for failed actions, such as ldap_add: Invalid syntax (21). For further details, see Step 1.
  6. Remove the directory entry for the old security domain. For example: 
    # 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-tomcat@instance_name

21.1.4. Reassigning Users to Default Groups

As mentioned in Section 21.1.3, “Importing the Data into the New CA”, members of the default groups are not restored during the data import.
Add members to the default groups manually, using the ldapmodify utility or the pki utility. For example:
  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 Certificate Manager Agents, Administrators, and Security Domain Administrators groups: 
    # pki -n "PKI Administrator for example.com" -c password \
	     user-membership-add user_name "Certificate Manager Agents"

	# 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"