Red Hat CERTIFICATE SYSTEM 7.0 - MIGRATION GUIDE User manual

Red Hat Certificate System
Migration Guide: 7.x to 7.3
7.0
Matthew Harmsen
ISBN: N/A
Publication date: March 12, 2008

This migration guide provides in-depth procedures to migrate subsystems, user information, and
certificate and key materials from Netscape Certificate Management System 7.0 and Red Hat
Certificate System 7.1 and 7.2 to Red Hat Certificate System 7.3.
Red Hat Certificate System

Red Hat Certificate System: Migration Guide: 7.x to 7.3
Author Matthew Harmsen <[email protected]>
Editor Ella Deon Lackey <[email protected]>
Copyright ©2008 Red Hat, Inc.
Copyright ©2008 Red Hat. This material may only be distributed subject to the terms and conditions set forth in the
Open Publication License, V1.0 or later with the restrictions noted below (the latest version of the OPL is presently
available at http://www.opencontent.org/openpub/).
Distribution of substantively modified versions of this document is prohibited without the explicit permission of the
copyright holder.
Distribution of the work or derivative of the work in any standard (paper) book form for commercial purposes is
prohibited unless prior permission is obtained from the copyright holder.
Red Hat and the Red Hat "Shadow Man" logo are registered trademarks of Red Hat, Inc. in the United States and other
countries.
All other trademarks referenced herein are the property of their respective owners.
The GPG fingerprint of the [email protected] key is:
CA 20 86 86 2B D6 9D FC 65 F6 EC C4 21 91 80 CD DB 42 A6 0E
1801 Varsity Drive
Raleigh, NC 27606-2072
USA
Phone: [phone]
Phone: [phone]
Fax: [phone]
PO Box 13588
Research Triangle Park, NC 27709
USA

Red Hat Certificate System

1. Introduction to Red Hat Certificate System Migration ................................................ 1
1. Certificate System Migration Overview ............................................................ 1
1.1. Migration Scripts ................................................................................. 2
1.2. Certificate System Subsystems ............................................................ 3
2. Considerations before Migration ...................................................................... 4
2. Step 1: Preparing the Older Server Instance for Migration ......................................... 7
3. Step 2: Installing the New Certificate System ........................................................... 9
4. Step 3: Stopping the New Certificate System Servers ..............................................11
5. Step 4: Migrating Security Databases .....................................................................13
1. Certificate Authority (CA) Migration ................................................................13
1.1. Option 1: Security Databases to Security Databases Migration ..............13
1.2. Option 2: Security Databases to HSM Migration ...................................15
1.3. Option 3: HSM to Security Databases Migration ...................................18
1.4. Option 4: HSM to HSM Migration .........................................................21
2. Data Recovery Manager (DRM) Migration ......................................................23
2.1. Option 1: Security Databases to Security Databases Migration ..............24
2.2. Option 2: Security Databases to HSM Migration ...................................25
2.3. Option 3: HSM to Security Databases Migration ...................................29
2.4. Option 4: HSM to HSM Migration .........................................................33
3. Online Certificate Status Protocol Manager (OCSP) Migration .........................36
3.1. Option 1: Security Databases to Security Databases Migration ..............36
3.2. Option 2: Security Databases to HSM Migration ...................................38
3.3. Option 3: HSM to Security Databases Migration ...................................41
3.4. Option 4: HSM to HSM Migration .........................................................44
4. Token Key Service (TKS) Migration ................................................................47
4.1. Option 1: Security Databases to Security Databases Migration ..............47
4.2. Option 2: Security Databases to HSM Migration ...................................49
4.3. Option 3: HSM to Security Databases Migration ...................................54
4.4. Option 4: HSM to HSM Migration .........................................................58
6. Step 5: Migrating Password Cache Data .................................................................63
7. Step 6: Migrating Internal Databases ......................................................................65
8. Step 7: Customizing User Data (Non-Console) ........................................................71
9. Step 8: Starting All Certificate System 7.3 Instances ................................................73
10. Step 9: Generate New Certificate System Server Certificates .................................75
1. Self-Signing an SSL Server Certificate for a CA ..............................................75
2. Requesting a New SSL Server Certificate from a Third-Party CA .....................76
3. Generating a New DRM, OCSP, or TKS SSL Server Certificate .......................77
11. Step 10: Customizing User Data (Console) ...........................................................79
12. Step 11: Verifying Migration .................................................................................81
v

vi

Introduction to Red Hat Certificate
System Migration
Netscape Certificate Management System (CMS) versions 7.0, 7.1, and 7.2 can be migrated to
Red Hat Certificate System version 7.3 using the Red Hat Certificate System migration utility.
Certificate System has the ability to extract data from the installation of a previous version and
migrate this data to 7.3. Each Certificate System subsystem is migrated independently.
• Product downgrade, extracting information from a newer version to import into an older
version, is not supported by the migration utility in any version of the Certificate System.
• Certificate System 7.3 does not support in-place upgrades. This is true even when the
installations are on the same machine, running the same platform. For example, a Red Hat
Certificate System 7.1 installation on a machine named delta.example.com running Red Hat
Enterprise Linux has to be migrated to Certificate System 7.3 installation, even if the 7.3
installation is on the same machine named delta.example.com running Red Hat Enterprise
Linux. This is accomplished simply by supplying a different installation directory for each
instance.
NOTE
Throughout this manual, all system instances are referred to as Certificate
System, unless the specific version or product name is required.
1. Certificate System Migration Overview
The migration process is staged to migrate the different subsets of Certificate System
information separately. The general process is as follows:
1. Install the Certificate System 7.3 subsystem instances.
2. Migrate the Certificate Management System 7.x security databases, which contains the key
and certificate materials for the server, to the Certificate System 7.3 instances.
3. Migrate the password database information for Certificate Management System 7.x to the
Certificate System 7.3 password file.
4. Migrate the Certificate Management System 7.x internal databases, which contain user and
group entries, to the Certificate System 7.3 server.
5. Migrate customized server configuration data from the 7.x server to Certificate System 7.3.
Chapter 1.
1

6. Renew all migrated certificates.
1.1. Migration Scripts
The Certificate System migration utility contains several separate platform-independent tools,
but only two are required for migrating a Certificate System installation: one program to convert
all of the data in an LDIF that was exported from the 7.x installation into a normalized LDIF text
file, and another program to convert the normalized LDIF text file into an LDIF data file that can
be imported into the newer Certificate System.
NOTE
The major version number of the migration export/import package is applied to all
service packs for that version. (This also applies to installations which contain
hot-fixes, individual bug fixes made after a service pack is released.)
Certificate System migration export utilities are files named versionToTxt. For migrating 7.0,
7.1, and 7.2 servers to Certificate System 7.3, there are three files which are used, depending
on your 7.x version: 70ToTxt,71ToTxt, and 72ToTxt. Each export tool contains the following
files:
• Two precompiled Java™classes
• An tool shell script
• An tool batch script
• The Java™source file that produced the precompiled Java™classes
• A sample shell script that can compile the source file
• A sample batch script that can compile the source file
The export file to use is determined by the older version of the Certificate System being
migrated.
NOTE
Each compilation batch and shell script is dependent on a specific version of the
Java software development kit defined in its comments.
Certificate System migration import utilities are files named TxtToversion. To migrate the
Chapter 1. Introduction to Red Hat Certificate System Migration
2

Certificate Management System 7.x servers to Certificate System 7.3, use the TxtTo73 script.
The import tool contains the following files:
• Three precompiled Java™classes
• An tool shell script
• An tool batch script
• The Java™source file that produced the precompiled Java™classes
• A sample shell script that can compile the source file
• A sample batch script that can compile the source file
Each compilation batch and shell script is dependent upon a specific version of the Java™
software development kit as defined in the comments.
1.2. Certificate System Subsystems
Certificate System installations may exist on different platforms. Additionally, each Certificate
System installation may contain more than one type of subsystem or more than one instance of
a type of subsystem. The following subsystems may be present in a Certificate System
installation:
• Certificate Authority (CA)
• Data Recovery Manager (DRM)
• Online Certificate Status Protocol (OCSP) Manager
• Registration Authority (RA)
• Token Key Service (TKS)
• Token Processing System (TPS)
The following table defines the platforms and subsystems supported by different versions of
Certificate System:
Product (including service
packs and hot-fixes) Subsystems Platforms
Netscape Certificate
Management System 7.0 CA
DRM
OCSP
TKS
TPS
Red Hat Enterprise Linux AS
2.1
Solaris 8
Certificate System Subsystems
3

Product (including service
packs and hot-fixes) Subsystems Platforms
Red Hat Certificate System
7.1 CA
DRM
OCSP
TKS
TPS
Red Hat Enterprise Linux
AS/ES 3
Red Hat Enterprise Linux
AS/ES 4
Solaris 9
Red Hat Certificate System
7.2 CA
DRM
OCSP
TKS
TPS
Red Hat Enterprise Linux
AS/ES 4 (i386)
Red Hat Enterprise Linux
AS/ES 4 (AMD64, Intel
EM64T)
Solaris 9 (64-bit)
Red Hat Certificate System
7.3 CA
DRM
OCSP
RA
TKS
TPS
Red Hat Enterprise Linux
AS/ES 4 (i386)
Red Hat Enterprise Linux
AS/ES 4 (for AMD64 and Intel
EM64T)
Solaris 9 (64-bit)
Table 1.1. Certificate System Subsystem Types and Platforms
2. Considerations before Migration
Since all migrations are unique to a deployment, it is strongly recommended that the entire
migration process be planned in advance. Here are some common issues related to migration.
The Migration Procedure.
• Not all steps in the migration processes apply to every deployment. Follow only the steps
which apply to the deployment being migrated.
• Perform all steps in the migration procedure for every instance of each subsystem being
migrated. Always follow the steps for migration in the order which they are presented in the
manual, even if not every step needs to be performed.
• Perform each subsystem migration as a separate migration. Wait until one subsystem
migration is complete before starting the migration of the next subsystem.
Setting File Permissions.
Chapter 1. Introduction to Red Hat Certificate System Migration
4

• On Linux and UNIX systems, make sure that the file owner (user and group) and the file
permissions are correct when the file is copied between two instances. Also make sure that
the target machine allows the file transfer.
• The chmod command used in the examples have the permissions 00600 (octal, no sticky bit
permissions, user read/write permissions, no group permissions, no other permissions).
These are the recommended permissions, but are not required.
Extracting Data from a Hardware Security Module.
While the migration procedure refers to extracting data from a hardware security module (HSM),
no Certificate System tool can extract public/private key pairs from an HSM because of Federal
Information Processing Standard (FIPS) 140-1, which protects the private key portion of an
entry. Contact the HSM vendor for information on how to extract data from an old HSM.
Extracted keys should not have any dependencies, such as nickname prefixes, on the old HSM.
Changing Subsystem Names and Port Numbers.
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.
About Usage Examples.
All examples assume that the new passwords are the same as the old passwords.
Subsystem and Version Related Considerations.
• It is not possible to migrate TPS data from Netscape Certificate Management System 7.0 to
Red Hat Certificate System 7.3.
• The default key-splitting scheme used by the DRM subsystem in Certificate System 7.1 and
later is not the scheme required by the DRM subsystem key recovery feature in Netscape
Certificate Management System 7.0. There is no way to migrate from the old key-splitting
scheme to the new scheme. Therefore, DRM instances in Certificate Management System
7.0 cannot be successfully migrated to version 7.3.
Considerations before Migration
5

6

Step 1: Preparing the Older Server
Instance for Migration
Before migrating a Certificate System instance, back up the Certificate System instance. When
the backup process is complete, then make sure that the old Certificate System, Directory
Server, and Administration Server instances have been stopped.
For commercial backup programs, do the following:
1. Stop all server instances running in the Certificate System, including all Certificate System
subsystems; the Directory Server, including all internal databases; and the Administration
Server instances on the local machine.
2. Run the commercial backup facility to back up all data associated with the old Certificate
System installation.
For the Certificate System backup facilities, do the following:
NOTE
Back up utilities are not included on Certificate System versions 7.2 and later, but
are available on previous versions of Certificate System.
1. Run the Certificate System backup facility to back up all data associated with this old
installation based upon the version information below.
• Certificate Management System 4.1, 4.2, 4.2 (SP 2), or 4.5
For instructions to back up a Certificate Management System 4.1, 4.2, 4.2 (SP 2), or 4.5
instance, see the Certificate Management System 4.x Certificate Management System
Command-Line Tools Guide. This information is located in the
server_root/manual/en/cert/tools/backup.htm file.
• iPlanet Certificate Management System 4.7
For instructions to back up an iPlanet Certificate Management System 4.7 instance, refer
to the documentation provided with the product.
• Netscape Certificate Management System 6.0, 6.1, 6.2, or 7.0 and Red Hat Certificate
System 7.1
For instructions to back up a versions 6.0, 6.1, 6.2, 7.0, or 7.1, see chapter 8, "Backing Up
and Restoring Data," in the Certificate Management System 6.x Certificate Management
Chapter 2.
7

System Command-Line Tools Guide.
2. Stop all server instances running in the Certificate System, including all Certificate System
subsystems; the Directory Server, including all internal databases; and the Administration
Server instances on the local machine.
Additionally, RA subsystems in older versions of Certificate System cannot be migrated to
Certificate System Red Hat Certificate System 7.3. 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
Chapter 2. Step 1: Preparing the Older Server Instance for Migration
8

Step 2: Installing the New Certificate
System
Install a new Certificate System 7.3 instance. All subsystem instances are installed separately;
make sure that every subsystem type which will be migrated has a corresponding new
subsystem instance.
1. Obtain the appropriate packages either through the up2date command or by downloading
the ISO image from the Certificate System 7.3 Red Hat Network channel.
2. If installing from an ISO image, run the installation utility to install the packages. This is done
automatically when using up2date.
rhpki-install -pki_subsystem=subsystem_type -pki_package_path=/path/to/ISO
image -force
3. Go through the HTML configuration wizard for each subsystem.
When the installation process is completed, the server returns a URL pointing to the
configuration wizard. Click that link to open the configuration wizard. For example:
http://server.example.com:9080/ca/admin/console/config/login?pin=Yc6EuvuY2OeezKeX7REk
The configuration wizard will fully configure the new subsystem instance and will generate all
required certificates. Make sure to have all necessary information when going through this
wizard. All subsystems require information to an external Red Hat Directory Server, including
bind information. DRM, OCSP, TKS, and subordinate CAs require information for the CA
which will generate their subsystem certificates.
NOTE
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.
For more information on the panels in the configuration wizard, see chapter 2, "Installation
and Configuration," in the Certificate System Administrator's Guide.
Chapter 3.
9

10

Step 3: Stopping the New Certificate
System Servers
1. First, stop all new Certificate System instances.
/etc/init.d/instance_ID stop
2. Then stop the Directory Server instance used by the Certificate System 7.3 servers.
cd /opt/redhat-ds/slapd-DS-instance
./stop-slapd
Chapter 4.
11

12

Step 4: Migrating Security Databases
For every Red Hat Certificate System subsystem instance migration, the data from the
certificate (cert8.db) and key (key3.db) security databases for the Netscape Certificate
Management System 7.0 or Red Hat Certificate System 7.1 or 7.2 instances must be extracted
and copied into the Red Hat Certificate System 7.3 subsystem's /alias directory. Follow the
migration procedure corresponding to the subsystem being migrated.
Four subsystems can be migrated from Certificate Management System 7.0 and Certificate
System 7.1 and 7.2 to Certificate System 7.3 — the Certificate Authority (CA), the Data
Recovery Manager (DRM), the Online Certificate Status Protocol Manager (OCSP), and the
Token Key Service (TKS) — each with a different migration procedure.
•Section 1, “Certificate Authority (CA) Migration”
•Section 2, “Data Recovery Manager (DRM) Migration”
•Section 3, “Online Certificate Status Protocol Manager (OCSP) Migration”
•Section 4, “Token Key Service (TKS) Migration”
1. Certificate Authority (CA) Migration
Determine if the migration to be performed involves software security databases, an HSM, or
both, and follow the appropriate process for the deployment scenario being migrated.
•Section 1.1, “Option 1: Security Databases to Security Databases Migration”
•Section 1.2, “Option 2: Security Databases to HSM Migration”
•Section 1.3, “Option 3: HSM to Security Databases Migration”
•Section 1.4, “Option 4: HSM to HSM Migration”
1.1. Option 1: Security Databases to Security Databases
Migration
1. Remove all the security databases in the Certificate System 7.3 server which will receive
migrated data.
rm /var/lib/instance_ID/alias/cert8.db
rm /var/lib/instance_ID/alias/key3.db
Chapter 5.
13

2. Copy the certificate and key security databases from the 7.x server to the 7.3 server.
cp old_server_root/alias/cert-old_CA_instance-cert8.db
/var/lib/instance_ID/alias/cert8.db
cp old_server_root/alias/cert-old_CA_instance-key3.db
/var/lib/instance_ID/alias/key3.db
3. Open the Certificate System /alias directory.
cd /var/lib/instance_ID/alias/
4. Log into the 7.3 server as root.
5. Set the file user and group to the Certificate System user and group.
# chown user:group cert8.db
# chown user:group key3.db
6. Log out as root and change to the Certificate System user login.
7. Set the file permissions.
chmod 00600 cert8.db
chmod 00600 key3.db
8. List the contents of the certificate database using the certutil tool. In this example, -L lists
the certificates in the database.
certutil -L -d .
Server-Cert cert-old_CA_instance cu,cu,cu
caSigningCert cert-old_CA_instance cu,cu,cu
ocspSigningCert cert-old_CA_instance CTu,Cu,Cu
subsystemCert cert-old_CA_instance cu,cu,cu
9. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.
10.Edit the ca.signing.cacertnickname and ca.ocsp_signing.cacertnickaname attributes
to reflect the 7.3 CA instance.
ca.signing.cacertnickname=caSigningCert cert-old_CA_instance
ca.ocsp_signing.cacertnickname=ocspSigningCert cert-old_CA_instance
Chapter 5. Step 4: Migrating Security Databases
14