Red Hat CERTIFICATE SYSTEM 6.0 - MIGRATION GUIDE User manual

Red Hat Certificate System
Migration Guide: 6.x to 7.3
6.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 6.0, 6.1, and 6.2 to
Red Hat Certificate System 7.3.
Red Hat Certificate System

Red Hat Certificate System: Migration Guide: 6.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 6.x 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 ...................................19
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 ...................................26
2.3. Option 3: HSM to Security Databases Migration ...................................30
2.4. Option 4: HSM to HSM Migration .........................................................33
3. Online Certificate Status Protocol Manager (OCSP) Migration .........................37
3.1. Option 1: Security Databases to Security Databases Migration ..............37
3.2. Option 2: Security Databases to HSM Migration ...................................39
3.3. Option 3: HSM to Security Databases Migration ...................................43
3.4. Option 4: HSM to HSM Migration .........................................................46
6. Step 5: Migrating Password Cache Data .................................................................51
7. Step 6: Migrating Internal Databases ......................................................................53
8. Step 7: Customizing User Data (Non-Console) ........................................................59
9. Step 8: Starting All Certificate System 7.3 Instances ................................................61
10. Step 9: Generate New Certificate System Server Certificates .................................63
1. Self-Signing an SSL Server Certificate for a CA ..............................................63
2. Requesting a New SSL Server Certificate from a Third-Party CA .....................64
3. Generating a New DRM, OCSP, or TKS SSL Server Certificate .......................65
11. Step 10: Customizing User Data (Console) ...........................................................67
12. Step 11: Verifying Migration .................................................................................69
v

vi

Introduction to Red Hat Certificate
System Migration
Netscape Certificate Management System (CMS) versions 6.0x, 6.1, and 6.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 Certificate
Management System 6.2 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 6.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 6.x to the
Certificate System 7.3 password file.
4. Migrate the Certificate Management System 6.x internal databases, which contain user and
group entries, to the Certificate System 7.3 server.
5. Migrate customized server configuration data from the 6.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 6.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.) For
example, migrating from Certificate Management System 6.01 uses the 60ToTxt
program to export data.
Certificate System migration export utilities are files named versionToTxt. For migrating 6.0x,
6.1, and 6.2 servers to Certificate System 7.3, there are three files which are used, depending
on your 6.x version: 60ToTxt,61ToTxt, and 62ToTxt. 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.
Chapter 1. Introduction to Red Hat Certificate System Migration
2

Certificate System migration import utilities are files named TxtToversion. To migrate the
Certificate Management System 6.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 6.0 CA
DRM
OCSP
RA
Solaris 8
Windows 2000 (SP 2)
Certificate System Subsystems
3

Product (including service
packs and hot-fixes) Subsystems Platforms
Netscape Certificate
Management System 6.01 aCA DRM
OCSP
RA
Red Hat Linux 7.2
Red Hat Enterprise Linux AS
2.1
Solaris 8
Netscape Certificate
Management System 6.1 CA
DRM
OCSP
RA
Solaris 8
Netscape Certificate
Management System 6.2 CA
DRM
OCSP
RA
Red Hat Enterprise Linux AS
2.1
Solaris 8
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)
aAlthough Certificate Management System 6.01 was considered a service pack of version 6.0, Certificate Management
System 6.01 is listed separately in this table because it is supported on different platforms.
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
Chapter 1. Introduction to Red Hat Certificate System Migration
4

migration is complete before starting the migration of the next subsystem.
Setting File Permissions.
• 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.
• 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 6.x versions.
There is no way to migrate from the old key-splitting scheme to the new scheme. Therefore,
DRM instances in Certificate Management System 6.x versions cannot be successfully
migrated to version 7.3.
• The RA subsystem was deprecated in Certificate Management System 7.0 and redesigned in
Red Hat Certificate System 7.3, so it is not possible to migrate RA subsystems into Certificate
System version 7.3. All RA request queues should be processed by the 6.x-version servers
into their existing CAs before beginning any CA migrations.
Considerations before Migration
5

6

Step 1: Preparing the 6.x Server
Instance for Migration
Before migrating a Certificate System instance, back up the Certificate System instance. When
the backup process is complete, then stop the old Certificate System, Directory Server, and
Administration Server instances.
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 backup facility (either the included Certificate Management System utility or a
commercial utility) to back up all data associated with the Certificate Management System
6.0x, 6.1, or 6.2 installation. For example, using the Certificate Management System utility:
cd /usr/netscape/servers/cert-instance
./cmsbackup
For more information on using the 6.x backup utility, see chapter 8, "Backing Up and
Restoring Data," in the Netscape Certificate Management System 6.x Command-Line Tools
Guide.
Additionally, RA subsystems in Certificate Management System 6.x cannot be migrated to
Certificate System 7.3. The RA subsystem was deprecated in Certificate Management System
7.0 and redesigned in Red Hat Certificate System 7.3 and is not compatible with 6.x versions of
the RA subsystem. 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.
7

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 Administration 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 (cert7.db or cert8.db) and key (key3.db) security databases for the Netscape
Certificate Management System 6.x 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.
There are three subsystems which can be migrated from Certificate Management System 6.x to
Red Hat Certificate System 7.3 — the CA, DRM, and OCSP — 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”
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

NOTE
On Certificate Management System 6.0x, the certificate database is cert7.db,
not cert8.db.
2. Copy the certificate and key security databases from the 6.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 in 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 log back into the system as the Certificate System user.
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
Chapter 5. Step 4: Migrating Security Databases
14