Chapter 15. Detailed Example of a Certificate System Migration

Chapter 15. Detailed Example of a Certificate System Migration

15.1. CA Migration
15.2. DRM Migration
15.3. OCSP Migration

This chapter contains a detailed example of a full Certificate System migration.

 

OLD INSTALLATION

NEW INSTALLATION

Version

Certificate Management System 6.1 (SP 4), including hot-fixes

Certificate System 7.2

Platform

Solaris 8

Red Hat Enterprise Linux 4 (AS)

Subsystems

CA, DRM, OCSP, RA

CA, DRM, OCSP

Server Instances

admin-serv, slapd-ds, cert-ca, slapd-ca-db, cert-drm, slapd-drm-db, cert-ocsp, slapd-ocsp-db, cert-ra, slapd-ra-db

slapd-DS-instance, rhpki-ca, rhpki-kra, rhpki-ocsp

Machine Name

alpha.example.com

server.example.com

HSM Information

N/A - uses security databases

Epsilon HSM Token Name: epsilon

Slot Names: rho for the CA, tau for the DRM, and phi for the OCSP

library path: /var/lib

library name: libepsilon.so

Server Root

/usr/netscape/servers

/var/lib/instance_id

User

cmsuser

pkiuser

Group

cmsgroup

pkiuser

Password Cache passwords

  • CA: diamond

  • DRM: emerald

  • OCSP: sapphire

  • CA: diamond

  • DRM: emerald

  • OCSP: sapphire

Password.conf

used by the CA, DRM, and OCSP

used by the CA, DRM, and OCSP

Backup Facility

Professional backup facility

Professional backup facility

Table 15.1. Example System Configurations

NOTE

In this example, all of the Certificate System 6.1 (SP 4) servers are located on a single machine called alpha.example.com and are all migrated to Certificate System 7.2 instances located on a single machine called server.example.com. It is strongly recommended that real deployments separate the subsystems across multiple machines.

Additionally, each subsystem uses a simple password; real deployments should use more robust, cryptographically stronger passwords containing uppercase letters, lowercase letters, numbers, and other special characters.

This example migration follows all migration steps described previously between Certificate Management System 6.1 (SP4) and Certificate System 7.2, based on the configurations in Table 15.1, “Example System Configurations”. The migration of each subsystem must be completed before beginning the next subsystem migration.

15.1. CA Migration

15.1.1. Step 1: Preparing the Old Certificate System

No upgrade path exists for the Registration Authority (RA) subsystem because this subsystem is no longer supported. To preserve the data in the RA subsystem, flush all data in RA request queues by processing it on the CA subsystem. Then stop the RA subsystem and database so that no further data can be gathered by it.

  1. Stop the RA instance. 

    cd /usr/netscape/servers/cert-ra

./stop-cert

  2. Stop the corresponding RA internal database instance. 

    cd /usr/netscape/servers/slapd-ra-db

./stop-slapd

As indicated in the server configuration table, this example assumes that a professional backup system is used to back up the entire Certificate Management System 6.1 (SP4) system, rather than the included backup facilities.

Before running the backup tools, stop all of the Certificate Management System 6.1 (SP4) servers.

  1. Stop the OCSP, DRM, and CA instances. 

    cd /usr/netscape/servers/cert-ocsp

./stop-cert

cd /usr/netscape/servers/cert-drm

./stop-cert

cd /usr/netscape/servers/cert-ca

./stop-cert

  2. Stop the CMS 6.1 (SP 4) Administration Server instance. 

    cd /usr/netscape/servers

./stop-admin

  3. Stop the OCSP, DRM, and CA internal database instances. 

    cd /usr/netscape/servers/slapd-ocsp-db

./stop-slapd

cd /usr/netscape/servers/slapd-drm-db

./stop-slapd

cd /usr/netscape/servers/slapd-ca-db

./stop-slapd

  4. Stop the Configuration Directory Server instance. 

    cd /usr/netscape/servers/slapd-ds

./stop-slapd

After stopping the server, back up the entire CMS 6.1 (SP 4) system using the external backup tool.

15.1.2. Step 2: Creating a New Certificate System Installation

  1. Install a new Certificate System 7.2 system on the Red Hat Enterprise Linux 4 (AS) machine, server.example.com.

    1. Download the Certificate System packages from the Red Hat Network or through the up2date command.

    2. To install the subsystems, run the install utility; this is not necessary if the subsystems were installed through up2date.

      rhpki-install -pki-subsystem=ca 
 -pki_package_path=/media/cdrom/RedHat/RPMS -force

  2. Configure the CA instance. It is possible to change the names of migrated Certificate System subsystem instances, but greater care must be taken when extracting and renaming certain portions of the data. Because port numbers are stored in the server.xml file, which is unaffected by subsystem migration, port numbers can be changed between instances without difficulty.

    Go through the HTML configuration wizard. When the installation process is completed, the server returns a URL pointing to the configuration wizard. For example:

    http://server.example.com:9080/ca/admin/console/config/
 login?pin=Yc6EuvuY2OeezKeX7REk

    For more information on the panels in the configuration wizard, see chapter 2, "Installation and Configuration," in the Certificate System Administration Guide.

15.1.3. Step 3: Stopping All New Certificate System Instances

  1. Stop the Certificate System 7.2 CA instance.

    /etc/init.d/rhpki-ca stop

  2. Stop the Directory Server instance.

    cd /opt/redhat-ds/slapd-DS-instance

./stop-slapd

15.1.4. Step 4: Migrating Security Databases

Do the following to migrate the Certificate Management System 6.1 CA subsystem security databases to the Certificate System 7.2 HSM:

NOTE

For more detailed information on migrating the 6.1 CA subsystem, refer to Section 7.5.1.2, “Case II: Security Databases to HSM Migration”.

  1. Remove the 7.2 CA security databases which will receive migrated data.

    rm /var/lib/rhpki-ca/alias/cert8.db

rm /var/lib/rhpki-ca/alias/key3.db

  2. Copy the certificate and key security databases from the old server to the new server.

    cp /usr/netscape/servers/alias/cert-ca-alpha-cert8.db
 /var/lib/rhpki-ca/alias/cert8.db

cp /usr/netscape/servers/alias/cert-ca-alpha-key3.db
 /var/lib/rhpki-ca/alias/key3.db

  3. Log into the new server hosting server.example.com as the Certificate System user, and open the Certificate System alias/ directory.

    cd /var/lib/rhpki-ca/alias

  4. Log in as root, and set the file user and group to the new server Certificate System user and group.

    su

chown pkiuser:pkiuser cert8.db

chown pkiuser:pkiuser key3.db

  5. Log out as root. As the Certificate System user, change the permissions on the files.

    chmod 00600 cert8.db

chmod 00600 key3.db

  6. List the certificates stored in the old security databases by using the certutil command. In this example, -L lists the certificates.

    certutil -L -d .

Server-Cert cert-ca cu,cu,cu
caSigningCert cert-ca cu,cu,cu
ocspSigningCert cert-ca CTu,Cu,Cu

  7. Export the public/private key pairs of each entry in the Certificate System databases using the pk12util tool; -o exports the key pairs to a PKCS #12 file, and -n gives the name of the certificate and the old database prefix.

    pk12util -o ServerCert.p12 -n "Server-Cert cert-ca" -d .

Enter Password or Pin for "NSS Certificate DB":********
Enter password for PKCS12 file: ********
Re-enter password: ********
pk12util: PKCS12 EXPORT SUCCESSFUL

pk12util -o caSigningCert.p12 -n "caSigningCert cert-ca" -d .

Enter Password or Pin for "NSS Certificate DB":********
Enter password for PKCS12 file: ********
Re-enter password: ********
pk12util: PKCS12 EXPORT SUCCESSFUL

pk12util -o ocspSigningCert.p12 -n "ocspSigningCert cert-ca" -d .

Enter Password or Pin for "NSS Certificate DB":********
Enter password for PKCS12 file: ********
Re-enter password: ********
pk12util: PKCS12 EXPORT SUCCESSFUL

    NOTE

    For this example, the old security databases did not contain any additional public/private key pairs.

  8. Delete the old security databases. 

    rm cert8.db

rm key3.db

  9. Register the new HSM in the new token database. 

    modutil -nocertdb -dbdir . -add "epsilon" -libfile /usr/lib/libepsilon.so

  10. Identify the new HSM slot name. 

    modutil -dbdir . -nocertdb -list

    This reveals slots called rho, tau, and phi. The slot called rho is used for the CA.

  11. Create new security databases. 

    certutil -N -d .

  12. Import the public/private key pairs of each entry from the PKCS #12 files into the new HSM. 

    pk12util -i ServerCert.p12 -d . -h rho

Enter Password or Pin for "rho":********
Enter password for PKCS12 file: ********
pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i caSigningCert.p12 -d . -h rho

Enter Password or Pin for "rho":********
Enter password for PKCS12 file: ********
pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i ocspSigningCert.p12 -d . -h rho

Enter Password or Pin for "rho":********
Enter password for PKCS12 file: ********
pk12util: PKCS12 IMPORT SUCCESSFUL

  13. Optionally, delete the PKCS #12 files. 

    rm ServerCert.p12

rm caSigningCert.p12

rm ocspSigningCert.p12

  14. Set the trust bits on the public/private key pairs that were imported into the new HSM. 

    certutil -M -n "rho:Server-Cert cert-ca" -t "cu,cu,cu" -d . -h epsilon

certutil -M -n "rho:caSigningCert cert-ca" -t "CTu,CTu,CTu" -d . -h epsilon

certutil -M -n "rho:ocspSigningCert cert-ca" -t "CTu,Cu,Cu" -d . -h epsilon

  15. Open the CS.cfg configuration file. 

    cd /var/lib/rhpki-ca/conf/

vi CS.cfg

  16. Edit the ca.signing.cacertnickname and ca.ocsp_signing.cacertnickname attributes to reflect the new CA information. 

    ca.signing.cacertnickname=rho:caSigningCert cert-ca

ca.ocsp_signing.cacertnickname=rho:ocspSigningCert cert-ca

  17. Since there is CA-DRM connectivity, also modify the ca.connector.KRA.nickname attribute.

    ca.connector.KRA.nickname=rho:caSigningCert cert-ca

  18. In the same directory, edit the serverCertNick.conf file to contain the old certificate nickname. For example: 

    vi serverCertNick.conf

rho:Server-Cert cert-ca

15.1.5. Step 5: Migrating Password Cache Data

To migrate the CA password cache data from the 6.1 pwdcache.db and password.conf files to the 7.2 password.conf file, do the following:

NOTE

For more detailed instructions on migrating the password files, refer to Section 8.3, “Migrating 6.0, 6.1, 6.2, 7.0, and 7.1 Password Cache Data”.

  1. Log into the old server hosting alpha.example.com as the Certificate System user.

  2. Use the PasswordCache tool on the old Certificate System to extract the password information from the CA database. 

    cd /usr/netscape/servers/cert-ca/config/

/usr/netscape/servers/bin/cert/tools/PasswordCache password 
-d /usr/netscape/servers/alias -P cert-ca-alpha-

list
cert/key prefix = cert-ca-alpha-
path = /usr/netscape/servers/alias
about to read password cache
----- Password Cache Content -----
internal : diamond
Internal LDAP Database : diamond

    The passwords are displayed in clear text; write down this information.

  3. This example server also uses the password.conf file to start the old CA instance automatically on alpha.example.com. Copy the password.conf file to server.example.com, overwriting the default password.conf file. 

    cp /usr/netscape/servers/cert-ca/config/password.conf 
/var/lib/rhpki-ca/conf/password.conf

  4. Log into the new server hosting server.example.com as the Certificate System user, and open the CA subsystem conf/ directory. 

    cd /var/lib/rhpki-ca/conf/

  5. Log in as root, and set the file user and group to the new server Certificate System user and group. 

    su

chown pkiuser:pkiuser password.conf

  6. Log out as root. As the Certificate System user, change the permissions on the file. 

    chmod 00600 password.conf

  7. Copy the passwords extracted from the old server pwdcache.db into the password.conf file.

15.1.6. Step 6: Migrating Internal Databases

NOTE

For more detailed information on migrating internal databases, see Section 9.8, “Migrating Internal Databases for 6.1”.

To migrate the 6.1 (SP4) internal databases to the new Certificate System 7.2 server, do the following:

  1. Log into the new CA server hosting server.example.com as the Certificate System user, and export the new internal database content to LDIF using the db2ldif tool.

    cd /opt/redhat-ds/slapd-DS-instance/db/server.example.com-rhpki-ca-db

db2ldif -n server.example.com-rhpki-ca

    The LDIF file location is given when the export from the database is finished.

    ldif file: /opt/redhat-ds/slapd-DS-instance/ldif/2005_06_07_874021.ldif

  2. Open the given LDIF location, and rename the LDIF file new.ldif.

    cd /opt/redhat-ds/slapd-DS-instance/ldif

mv 2005_06_07_874021.ldif new.ldif

  3. Copy the latest version of the migration utility from the new Certificate System to the old server.

    Since the Certificate System migration utility is platform independent, always use the latest version of the migration utility on both server installations. The latest migration tools are available in the /usr/share/rhpki/migrate directory of the new server instance.

    1. Open the migration tools directory. 

      cd /usr/share/rhpki

    2. Package the latest version of the migration utility using zip or tar. 

      tar -cvf migrate.tar migrate

      NOTE

      Regardless of the packaging tool used, the corresponding tool must be present on the old server machine. If the platforms are identical and the zip utility is used, copy the unzip utility to the /usr/netscape/servers/bin/cert/ directory so that the zip and unzip versions match.

    3. Copy the package from the new server to the old server, then remove the package from the new server. 

      cp /usr/share/rhpki/migrate.tar /usr/netscape/servers/bin/cert

rm /usr/share/rhpki/migrate.tar

    4. Log into the old server hosting alpha.example.com as the Certificate System user, and open the Certificate System bin/cert/ directory. 

      cd /usr/netscape/servers/bin/cert

    5. Log into alpha.example.com as root, and set the file user and group to the old Certificate Management System user and group. 

      su
chown cmsuser:cmsgroup migrate.tar

    6. Log out as root. As the Certificate System user, change the permissions on the file. 

      chmod 00600 migrate.tar

    7. Since the old Certificate Management System migration utility will not be used, remove the old upgrade/ directory. 

      rm -rf /usr/netscape/servers/bin/cert/upgrade

    8. Unpackage the latest version of the migration utility using unzip or tar. 

      tar -xvf migrate.tar

    9. Remove the migration utility package and any additional utilities, such as the unzip utility, that were copied to the old Certificate System server. 

      rm migrate.tar

  4. Run the db2ldif command to export the database contents to LDIF.

    cd /usr/netscape/servers/slapd-ca-db

db2ldif -n userRoot

    The LDIF file location is shown when the export from the database is complete.

    ldif file: 
/usr/netscape/servers/slapd-ca-db/ldif/2005_06_07_439837.ldif

  5. Open the given LDIF location, and rename the LDIF file old.ldif. 

    cd /usr/netscape/servers/slapd-ca-db/ldif

mv 2005_06_07_439837.ldif old.ldif

  6. Adjust the LDIF content of old.ldif.

    NOTE

    In this example, the LDIF file is relatively small, so any text editor works. For large files, use an appropriate program.

    1. Open the 6.1 CA database directory. 

      cd /usr/netscape/servers/slapd-ca-db/ldif

    2. Replace the following entry with the one in new.ldif. 

      cn=aclResources,o=CertificateServer

    3. Add new groups for the the security domains. 

      cn=Security Domain Administrators,ou=groups,basedn
cn=Enterprise CA Administrators,ou=groups, basedn
cn=Enterprise KRA Administrators,ou=groups, basedn
cn=Enterprise OCSP Administrators,ou=groups, basedn
cn=Enterprise TKS Administrators,ou=groups, basedn
cn=Enterprise TPS Administrators,ou=groups, basedn

  7. Convert the old.ldif file to a text file.

    1. Open the version-to-text directory in the 6.1 server's migrate/ directory. 

      cd /usr/netscape/servers/bin/cert/migrate/61ToTxt

    2. Edit the run.sh script by uncommenting and setting the values for the following lines:

      • SERVER_ROOT=/usr/netscape/servers

      • export SERVER_ROOT

      • INSTANCE=ca

      • export INSTANCE

    3. Run the run.sh to use the old.ldif file to create a text file. 

      run.sh /usr/netscape/servers/slapd-ca-db/ldif/old.ldif >
 /usr/netscape/servers/slapd-ca-db/ldif/old.txt

  8. Open the old CA LDIF directory, and copy the old.txt file to the new CA server instance's internal database LDIF directory. 

    cd /usr/netscape/servers/slapd-ca-db/ldif

cp /usr/netscape/servers/slapd-ca-db/ldif/old.txt 
/opt/redhat-ds/slapd-DS-instance/ldif

  9. Log into the new CA server hosting server.example.com as the Certificate System user, and open the Certificate System ldif/ directory. 

    cd /opt/redhat-ds/slapd-DS-instance/ldif

  10. Log in as root, and set the file user and group to the Certificate System user and group. 

    su

chown pkiuser:pkiuser old.txt

  11. Log out as root. As the Certificate System user, change the permissions on the file. 

    chmod 00600 old.txt

  12. Convert the old.txtfile to LDIF.

    1. Open the text-to-version directory in the Red Hat Certificate System migration directory. 

      cd /usr/share/rhpki/migrate/TxtTo72

    2. Edit the run.sh tool by uncommenting and setting the values for the following lines:

      • SERVER_ROOT=/var/lib

      • export SERVER_ROOT

      • INSTANCE=rhpki-ca

      • export INSTANCE

    3. Run run.sh to use old.txt to create an LDIF file. 

      run.sh /opt/redhat-ds/slapd-DS-instance/ldif/old.txt > 
/opt/redhat-ds/slapd-DS-instance/ldif/old.ldif

  13. Import the old.ldif LDIF file into this new CA server instance's internal database.

    1. Open the 7.2 CA database directory. 

      cd /opt/redhat-ds/slapd-DS-instance/db

    2. Import the 6.1 LDIF file into the 7.2 database. 

      ldif2db -n server.example.com-rhpki-ca
 -i /opt/redhat-ds/slapd-DS-instance/ldif/old.ldif

    3. Force the virtual list views (VLV) indexes to be re-indexed. 

      db2index

15.1.7. Step 7: Customizing User Data (Non-Console)

This example contains no user customizations.

15.1.8. Step 8: Starting All New Certificate System Instances

  1. Start the associated Directory Server instance.

    cd /opt/redhat-ds/slapd-DS-instance

./start-slapd

  2. Start the 7.2 CA instance. 

    /etc/init.d/rhpki-ca start

15.1.9. Step 9: Generating New Certificate System Server Certificates

Renew the CA SSL server certificate by doing the following:

NOTE

For more detailed information on renewing the CA SSL server certificate, see Section 12.1, “Renewing a CA SSL Server Certificate by Signing It with the CA Signing Certificate”.

  1. Start the CA Console.

    pkiconsole https://server.example.com:9443/ca

  2. Select the 7.2 CA instance with the migrated data, and open the Console for that instance.

  3. In the Console, select the Configuration tab.

  4. Select the System Keys and Certificates option from the menu on the left.

  5. Select the Local Certificates tab on the right.

  6. Press the Add/Renew button to launch the Certificate Setup Wizard.

  7. Go through the certificate wizard panels and fill in the information as directed.

    1. In the Type of Operation panel, select the Request a certificate option (the default).

    2. In the Certificate Selection panel, select SSL Server Certificate from the pull-down menu, and use the default option, Sign this SSL Certificate with my CA Signing Certificate. The SSL server certificate is automatically generated.

    3. In the Key-Pair Information for the SSL Server Certificate panel, select Create new key pair since the renewed SSL server certificate requires changing the CN component of its DN. Fill in information in the other fields on this panel or use the defaults.

    4. Select the desired hashing algorithm or use the default, SHA-1, in the Message Digest Algorithm panel.

    5. The next panel is Subject Name for the SSL Certificate. For the CN component, enter server.example.com. Fill in information in the other fields on this panel; it is strongly recommended that the O and C components also be filled in.

    6. Click through the remaining panels in the Certificate Setup Wizard; fill in settings as desired or accept the defaults.

    7. The CA's SSL server certificate is automatically renewed with the updated data.

  8. Close the Console windows.

  9. Restart the CA instance.

    /etc/init.d/rhpki-ca restart

15.1.10. Step 10: Customizing User Data (Console)

This example contains no user customizations.

15.1.11. Step 11: After Migration

After migrating the Certificate Management System 6.1 (SP 4) CA instance to the corresponding Certificate System 7.2 CA instance, access the end-entity services and the agent services interfaces of the Certificate System 7.2 CA instance to ensure that everything is working properly.

http://server.example.com:9080/ca
https://server.example.com:9443/ca

Then log into the Certificate System Console to verify that the new instance can be managed through the Console. 

pkiconsole https://server.example.com:9443/ca

The port numbers for all CA interfaces can be found in the server.xml in the CA instance conf/ directory.