Red Hat SYSTEM 8.0, Certificate System 8.0 User Manual

Download

Page 1

Red Hat Certificate

System 8.0

Migration Guide

7.x to 8.0

Matthew Harmsen

Publication date: July 22, 2009, updated on March 22, 2010

Page 2

Migration Guide

Red Hat Certificate System 8.0 Migration Guide

7.x to 8.0 Edition 8.0.7

The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.

Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, JBoss, MetaMatrix, Fedora, the Infinity Logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.

Linux® is the registered trademark of Linus Torvalds in the United States and other countries.

All other trademarks are the property of their respective owners.

1801 Varsity Drive Raleigh, NC 27606-2072 USA Phone: +1 919 754 3700 Phone: 888 733 4281 Fax: +1 919 754 3701 PO Box 13588 Research Triangle Park, NC 27709 USA

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

Page 3

iii

About This Guide vii

1. Recommended Knowledge ............................................................................................. vii

2. Examples and Formatting .............................................................................................. vii

2.1. Formatting for Examples and Commands ............................................................. vii

2.2. Tool Locations .................................................................................................... viii

2.3. Guide Formatting ............................................................................................... viii

3. Additional Reading ........................................................................................................ viii

4. Giving Feedback ............................................................................................................ ix

5. Document History ............................................................................................................ x

1. Introduction to Red Hat Certificate System Migration 1

1.1. Certificate System Migration Overview ........................................................................... 1

1.1.1. Migration Scripts ................................................................................................ 1

1.1.2. Certificate System Subsystems .......................................................................... 2

1.2. Considerations Before Migration .................................................................................... 3

2. Setting up Certificate System 8.0 Subsystems 7

2.1. Installing New Certificate System Subsystem Instances .................................................. 7

2.2. Default File and Directory Locations for Certificate System Subsystems ......................... 11

2.2.1. Default CA Instance Information ....................................................................... 11

2.2.2. Default RA Instance Information ....................................................................... 12

2.2.3. Default DRM Instance Information .................................................................... 12

2.2.4. Default OCSP Instance Information .................................................................. 13

2.2.5. Default TKS Instance Information ..................................................................... 14

2.2.6. Default TPS Instance Information ..................................................................... 14

2.2.7. Shared Certificate System Subsystem File Locations ......................................... 16

3. Migrating a CA Instance to Certificate System 8.0 17

3.1. Flush the Request Queue ........................................................................................... 17

3.2. Migrating the Security Databases ................................................................................ 17

3.2.1. Option 1: Security Databases to Security Databases Migration ............................ 17

3.2.2. Option 2: Security Databases to HSM Migration ................................................ 19

3.2.3. Option 3: HSM to Security Databases Migration ................................................ 22

3.2.4. Option 4: HSM to HSM Migration ..................................................................... 24

3.3. Migrating Subsystem Password Stores ........................................................................ 27

3.3.1. Migrating Passwords from 7.1 .......................................................................... 27

3.3.2. Migrating Passwords from 7.2 and 7.3 .............................................................. 28

3.4. Migrating the LDAP Database ..................................................................................... 29

3.5. Migrating Custom CS.cfg Settings and Other Data ....................................................... 35

3.6. Restarting the CA Instance ......................................................................................... 36

3.7. Setting Custom Configuration in the Console ............................................................... 37

3.8. Verifying the CA Migration .......................................................................................... 37

4. Migrating an RA to 8.0 39

4.1. Dumping the 7.3 Databases ........................................................................................ 39

4.2. Preparing 7.3 Security Databases ............................................................................... 39

4.3. Importing the 7.3 SQL Database Information into the 8.0 SQL Database ........................ 40

4.4. Migrating the 7.3 Security Databases to the 8.0 RA ...................................................... 41

4.5. Migrating Passwords .................................................................................................. 42

4.6. Migrating Custom Configuration .................................................................................. 42

4.7. Restarting the RA Instance ......................................................................................... 42

4.8. Verifying the RA Migration .......................................................................................... 42

5. Migrating a DRM Instance to Certificate System 8.0 43

Page 4

Migration Guide

5.1. Migrating the Security Databases ................................................................................ 43

5.1.1. Option 1: Security Databases to Security Databases Migration ............................ 43

5.1.2. Option 2: Security Databases to HSM Migration ................................................ 45

5.1.3. Option 3: HSM to Security Databases Migration ................................................ 48

5.1.4. Option 4: HSM to HSM Migration ..................................................................... 51

5.2. Migrating Subsystem Password Stores ........................................................................ 54

5.2.1. Migrating Passwords from 7.1 .......................................................................... 54

5.2.2. Migrating Passwords from 7.2 and 7.3 .............................................................. 55

5.3. Migrating the LDAP Database ..................................................................................... 56

5.4. Migrating Custom CS.cfg and Other Data Settings ....................................................... 60

5.5. Restarting the DRM Instance ...................................................................................... 61

5.6. Setting Custom Configuration in the Console ............................................................... 61

5.7. Verifying the DRM Migration ....................................................................................... 61

6. Migrating a OCSP Instance to Certificate System 8.0 63

6.1. Migrating the Security Databases ................................................................................ 63

6.1.1. Option 1: Security Databases to Security Databases Migration ............................ 63

6.1.2. Option 2: Security Databases to HSM Migration ................................................ 65

6.1.3. Option 3: HSM to Security Databases Migration ................................................ 68

6.1.4. Option 4: HSM to HSM Migration ..................................................................... 70

6.2. Migrating Subsystem Password Stores ........................................................................ 73

6.2.1. Migrating Passwords from 7.1 .......................................................................... 73

6.2.2. Migrating Passwords from 7.2 and 7.3 .............................................................. 74

6.3. Migrating the LDAP Database ..................................................................................... 75

6.4. Migrating Custom Data and Settings ........................................................................... 79

6.5. Restarting the OCSP Instance .................................................................................... 79

6.6. Setting Custom Configuration in the Console ............................................................... 79

6.7. Verifying the OCSP Migration ...................................................................................... 80

7. Migrating a TKS Instance to Certificate System 8.0 81

7.1. Migrating the Security Databases ................................................................................ 81

7.1.1. Option 1: Security Databases to Security Databases Migration ............................ 81

7.1.2. Option 2: Security Databases to HSM Migration ................................................ 83

7.1.3. Option 3: HSM to Security Databases Migration ................................................ 87

7.1.4. Option 4: HSM to HSM Migration ..................................................................... 91

7.2. Migrating Subsystem Password Stores ........................................................................ 95

7.2.1. Migrating Passwords from 7.1 .......................................................................... 95

7.2.2. Migrating Passwords from 7.2 and 7.3 .............................................................. 96

7.3. Migrating the LDAP Database ..................................................................................... 96

7.4. Migrating Custom CS.cfg Settings and Other Data ...................................................... 101

7.5. Restarting the TKS Instance ..................................................................................... 101

7.6. Setting Custom Configuration in the Console ............................................................. 101

8. Migrating a TPS Instance to 8.0 103

8.1. Migrating the LDAP Database ................................................................................... 103

8.2. Migrating the Security Databases .............................................................................. 105

8.2.1. Option 1: Security Databases to Security Databases Migration .......................... 105

8.2.2. Option 2: Security Databases to HSM Migration ............................................... 107

8.2.3. Option 3: HSM to Security Databases Migration ............................................... 109

8.2.4. Option 4: HSM to HSM Migration .................................................................... 111

8.3. Migrating the TPS Configuration ................................................................................ 113

8.4. Migrating Passwords ................................................................................................. 113

8.5. Restarting the TPS Instance ..................................................................................... 114

Page 5

8.6. Verifying the TPS Migration ....................................................................................... 114

Page 6

Page 7

vii

About This Guide

This guide explains how to migrate a Red Hat Certificate System 7.1, 7.2, and 7.3 deployment to a Red Hat Certificate System 8.0. Installation and administration topics are covered in the Red Hat Certificate System Administrator's Guide, while processing certificate requests and other aspects of managing the certificate lifecycle is covered in Certificate System Agent's Guide and using smart cards is covered in the Managing Smart Cards with the Enterprise Security Client. For more information on the tools used in this migration guide, see the Certificate System Command-Line Tools Guide.

1. Recommended Knowledge

Before reading this guide, be familiar with the following concepts:

• Intranet, extranet, and Internet security and the role of digital certificates in a secure enterprise, including the following topics:

• Encryption and decryption

• Public keys, private keys, and symmetric keys

• Significance of key lengths

• Digital signatures

• Digital certificates, including different types of digital certificates

• The role of digital certificates in a public-key infrastructure (PKI)

• Certificate hierarchies

• LDAP and Red Hat Directory Server

• Public-key cryptography and the Secure Sockets Layer (SSL) protocol, including the following:

• SSL cipher suites

• The purpose of and major steps in the SSL handshake

2. Examples and Formatting

2.1. Formatting for Examples and Commands

All of the examples for Red Hat Certificate System commands, file locations, and other usage are given for Red Hat Enterprise Linux 5 (32-bit) systems. Be certain to use the appropriate commands and files for your platform.

To start the Red Hat Certificate System:

service pki-ca start

Example 1. Example Command

Page 8

About This Guide

viii

2.2. Tool Locations

All of the tools for Red Hat Certificate System are located in the /usr/bin directory. These tools can be run from any location without specifying the tool location.

2.3. Guide Formatting

Certain words are represented in different fonts, styles, and weights. Different character formatting is used to indicate the function or purpose of the phrase being highlighted.

Formatting Style Purpose

Monospace font Monospace is used for commands, package names, files and

Monospace with a background

Italicized text Any text which is italicized is a variable, such as

Bolded text Most phrases which are in bold are application names, such as

Other formatting styles draw attention to important text.

NOTE

A note provides additional information that can help illustrate the behavior of the system or provide more detail for a specific issue.

IMPORTANT

Important information is necessary, but possibly unexpected, such as a configuration change that will not persist after a reboot.

WARNING

A warning indicates potential data loss, as may happen when tuning hardware for maximum performance.

3. Additional Reading

The documentation for Certificate System includes the following guides:

• Certificate System Deployment Guide1 describes basic PKI concepts and gives an overview of the planning process for setting up Certificate System.

This manual is intended for Certificate System administrators.

Page 9

Giving Feedback

• Certificate System Installation Guide2 covers the installation process for all Certificate System subsystems.

This manual is intended for Certificate System administrators.

• Certificate System Administrator's Guide3 explains all administrative functions for the Certificate System. Administrators maintain the subsystems themselves, so this manual details backend configuration for certificate profiles, publishing, and issuing certificates and CRLs. It also covers managing subsystem settings like port numbers, users, and subsystem certificates.

This manual is intended for Certificate System administrators.

• Certificate System Agent's Guide4 describes how agents — users responsible for processing certificate requests and managing other aspects of certificate management — can use the Certificate System subsystems web services pages to process certificate requests, key recovery, OCSP requests and CRLs, and other functions.

This manual is intended for Certificate System agents.

• Managing Smart Cards with the Enterprise Security Client5 explains how to install, configure, and use the Enterprise Security Client, the user client application for managing smart cards, user certificates, and user keys.

This manual is intended for Certificate System administrators, agents, privileged users (such as security officers), and regular end users.

• Using End User Services6 is a quick overview of the end-user services in Certificate System, a simple way for users to learn how to access Certificate System services.

This manual is intended for regular end users.

• Certificate System Command-Line Tools Guide7 covers the command-line scripts supplied with Red Hat Certificate System.

This manual is intended for Certificate System administrators.

• Certificate System Migration Guide8 covers version-specific procedures for migrating from older versions of Certificate System to Red Hat Certificate System 8.0.

This manual is intended for Certificate System administrators.

• Release Notes9 contains important information on new features, fixed bugs, known issues and workarounds, and other important deployment information for Red Hat Certificate System 8.0.

All of the latest information about Red Hat Certificate System and both current and archived documentation is available at http://www.redhat.com/docs/manuals/cert-system/.

4. Giving Feedback

If there is any error in this Migration Guide: 7.x to 8.0 or there is any way to improve the documentation, please let us know. Bugs can be filed against the documentation for Red Hat Certificate System through Bugzilla, http://bugzilla.redhat.com/bugzilla. Make the bug report as specific as possible, so we can be more effective in correcting any issues:

• Select the Red Hat Certificate System product.

Page 10

About This Guide

• Set the component to Doc - migration-guide.

• Set the version number to 8.0.

• For errors, give the page number (for the PDF) or URL (for the HTML), and give a succinct description of the problem, such as incorrect procedure or typo.

For enhancements, put in what information needs to be added and why.

• Give a clear title for the bug. For example, "Incorrect command example for setup script options" is better than "Bad example".

We appreciate receiving any feedback — requests for new sections, corrections, improvements, enhancements, even new ways of delivering the documentation or new styles of docs. You are welcome to contact Red Hat Content Services directly at docs@redhat.com.

5. Document History

Revision 8.0.7 March 22, 2010

Removed last reference to changing subsystem names at migration (which is not supported).

Revision 8.0.6 March 18, 2010

Made a lot of minor text edits and clarifications request by SEG, including Bugzilla #561558, Bugzilla #561556, Bugzilla #561559, Bugzilla #561561, Bugzilla #559790, Bugzilla #559778, Bugzilla #559792, and Bugzilla #561555.

Revision 8.0.5 October 13, 2009

Minor edits to the TPS migration section, from input by Ade Lee in Bugzilla #519038.

Revision 8.0.4 September 18, 2009

Tech edits to chapter 1 (introduction) and chapter 2 (installing new instances), per review bugs Bugzilla #510574 and Bugzilla #519032, respectively.

Revision 8.0.3 September 9, 2009

Revising the TPS security databases migration section to include scenarios for migrating to and from HSMs, Bugzilla #519038.

Revision 8.0.2 September 4, 2009

Minor corrections to command line examples for the tech review in OCSP migration, Bugzilla #519036.

Revision 8.0.1 August 1, 2009

Adding an extra step to the installation procedure to unset the DONT_RUN_PKICREATE environment variable before running pkicreate.

Revision 8.0.0 July 22, 2009

Initial draft.

Page 11

Chapter 1.

Introduction to Red Hat Certificate System Migration

Red Hat Certificate System 7.1, 7.2, and 7.3 can be migrated to Red Hat Certificate System version

8.0 using the Red Hat Certificate System migration utility. These migration scripts can extract data from the installation of a previous version and migrate this data to 8.0. 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 8.0 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 8.0 installation, even if the 8.0 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.

Release Date Product Name

May 27, 2005 Red Hat Certificate System 7.1

November 6, 2006 Red Hat Certificate System 7.2

May 2007 Red Hat Certificate System 7.3

July 22, 2009 Red Hat Certificate System 8.0

Table 1.1. Summary of Certificate System Releases

1.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 8.0 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 8.0 instances.

3. Migrate the password database information for Certificate Management System 7.x to the

Certificate System 8.0 password file.

4. Migrate the Certificate Management System 7.x internal databases, which contain user and group

entries, to the Certificate System 8.0 server.

5. Migrate customized server configuration data from the 7.x server to Certificate System 8.0.

6. Renew all migrated certificates.

1.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

Page 12

Chapter 1. Introduction to Red Hat Certificate System Migration

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.1, 7.2, and

7.3 servers to Certificate System 8.0, there are three migration scripts available, depending on the 7.x version:

• 71ToTxt

• 72ToTxt

• 73ToTxt

Each export tool directory (71ToTxt/, 72ToTxt/, and 73ToTxt/) contains the following files:

• Two precompiled Java™ classes

• A tool shell script

• A tool batch script

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 Certificate Management System 7.x servers to Certificate System 8.0, use the TxtTo80 script. The import tool directory (TxtTo80/) contains the following files:

• Two precompiled Java™ classes

• A tool shell script

Each compilation batch and shell script is dependent upon a specific version of the Java™ software development kit as defined in the comments.

1.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)

Page 13

Considerations Before Migration

• Online Certificate Status Protocol (OCSP) Manager

• Registration Authority (RA)

• Token Key Service (TKS)

• Token Processing System (TPS)

Table 1.2, “Certificate System Subsystem Types and Platforms” defines the platforms and subsystems

supported by different versions of Certificate System:

Product (including service packs and hot-fixes) Subsystems Platforms

Red Hat Certificate System 7.1 CA

Red Hat Certificate System 7.2 CA

Red Hat Certificate System 7.3 CA

Red Hat Certificate System 8.0 CA

Table 1.2. Certificate System Subsystem Types and Platforms

1.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.

Page 14

Chapter 1. Introduction to Red Hat Certificate System Migration

Directory Names, Directory Locations, and FHS

In Certificate System 7.2, the Certificate System instance directories were changed from a single server root to follow Filesystem Hierarchy Standards. The configuration files were then stored, for example, in /var/lib while the log files were moved to /var/log, and the tools are located in / usr/bin. Therefore, the server directories and file locations are very different in Certificate System

8.0 than Certificate System 7.1, if you migrate from that version.

Additionally, the directory names are different in Certificate System 8.0 than in Certificate System

7.2 or 7.3. In those earlier versions, the directories were prefaced with rhpki, such as /var/lib/

rhpki-ca/conf. In Certificate System 8.0, the directories are named with pki, such as /var/ lib/new_CA_instance/conf.

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.

IMPORTANT

For migration to work on a LunaSA HSM, then the following line must be added to the / etc/Chrystoki.conf configuration file:

Misc { NetscapeCustomize=1023; }

Additionally, these two lines must be removed:

AppIdMajor=2; AppIdMinor=4;

Updating Port Numbers

The default subsystems are installed and configured with a separate TCP/IP port for each service, called port separation. Each Certificate System subsystem uses up to five ports:

• A standard port

• An SSL port for end users services

• An SSL port for agent services

Page 15

Considerations Before Migration

• An SSL port for the administrative console or admin services

• A web server port (Tomcat for CA, DRM, OCSP, and TKS subsystems, Apache for the TPS and RA subsystems)

However, Certificate System versions older than 8.0 used only three ports, a web server port, an unsecure port, and a single SSL port. This means that special care needs to be taken when migrating to Certificate System 8.0 from any Certificate System 7.x server. Either the port configuration must be updated in the 7.x server configuration, or the Certificate System 8.0 subsystem has to be installed using pkicreate to specify a single SSL port. Using pkicreate is described in the Installation Guide, and reconfiguring ports is described in the Administrator's Guide.

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 a 7.3 instance is being migrated, so default directory paths and file names correspond to the 7.3 subsystem versions. Make sure that the information in your migration steps correspond to your appropriate version and platform.

All examples assume that the new passwords are the same as the old passwords.

Backing up Existing Data

Before migrating any Certificate System instance, back up the information for the Certificate System instance, including the security databases in the alias/ directory and all data stored in the internal LDAP database. When the backup process is complete, then stop the old Certificate System, Directory Server, and Administration Server instances.

Page 16

Page 17

Chapter 2.

Setting up Certificate System 8.0 Subsystems

For every Certificate System 7.x subsystem which will be migrated, there must be a new Certificate System 8.0 subsystem installed and properly configured.

2.1. Installing New Certificate System Subsystem Instances

The configuration of the new Certificate System 8.0 instances is extremely important. As mentioned in Section 1.2, “Considerations Before Migration”, the instance names, directory locations, and port numbers in Certificate System 8.0 are different than those in the Certificate System 7.x versions. Since port numbers are easily updated in instances, the separated SSL ports in Certificate System

8.0 can be easily used since they enhance security. However, having different instance names makes

migration much more difficult because it changes the certificate names, directory paths, and database names used by the instance. Therefore, the new Certificate System 8.0 instances must be specially installed to reuse the original instance names.

The standard installation process described in the Certificate System Installation Guide will not work for a typical migration scenario because it automatically uses version 8.0 instance settings. To install a migration instance, use this procedure.

NOTE

There is an environment variable, DONT_RUN_PKICREATE, which stops the pkicreate script from running automatically after the subsystems are installed. This allows the default instances to be installed in user-defined installation directories, instead of the default locations in /var/lib. To use custom directory locations, install the subsystems through the ISO image with this environment variable set to block the pkicreate script.

1. Certificate System requires OpenJDK 1.6.0. On Red Hat Enterprise Linux systems, this JDK must

be installed separately.

The OpenJDK can be installed by using yum or by downloading the packages directly from http://

openjdk.java.net/install/. For example:

yum install java-1.6.0-openjdk

After installing the JDK, run /usr/sbin/alternatives as root to insure that the proper JDK is available:

/usr/sbin/alternatives --config java

There are 3 programs which provide 'java'.

Selection Command

---------------------------------------------- 1 /usr/lib/jvm/jre-1.4.2-gcj/bin/java 2 /usr/lib/jvm/jre-1.6.0-openjdk/bin/java *+ 3 /usr/lib/jvm/jre-1.6.0-sun.x86_64/bin/java

2. Install Red Hat Directory Server 8.1, if a directory service is not already available. For example:

Page 18

Chapter 2. Setting up Certificate System 8.0 Subsystems

yum install redhat-ds

3. Install Apache if it is not already available. For example:

yum install httpd

4. Install mod_nss.

yum install mod_nss

5. Before installing any Red Hat Certificate System 8.0 packages, set an environment variable which prevents the installation program from automatically creating the default instances. These instances must be created manually so that they have the same settings as the 7.x instances.

export DONT_RUN_PKICREATE=1

6. Install the subsystem, management, and migration packages for the subsystem:

yum install pki-type pki-console pki-migrate

Each subsystem has its own package, and it is possible to install any or all subsystems on the same machine. For example:

yum install pki-ca pki-kra pki-ra pki-ocsp pki-tks pki-tps pki-console pki-migrate

IMPORTANT

If you are installing Certificate System on multiple hosts, make sure that you always set the DONT_RUN_PKICREATE before installing any packages, and then unset the environment variable to run the pkicreate command manually with user-defined settings.

7. Unset the DONT_RUN_PKICREATE environment variable, so that pkicreate can be run manually.

export DONT_RUN_PKICREATE=0

8. Manually run the pkicreate command to create a new 8.0 subsystem instance for each and every Certificate System 7.x instance that will be migrated. It is strongly recommended that the new instance name is the same for the new version as for the original one.

The port settings are slightly different for the CA, DRM, OCSP, and TKS compared to the RA and TPS because of the different kinds of administrative interfaces and web services that they use. For example, to install a CA with the 7.2 and 7.3 instance name of rhpki-ca:

pkicreate -pki_instance_root=/var/lib -pki_instance_name=rhpki-ca -subsystem_type=ca agent_secure_port=9443 -ee_secure_port=9444 -admin_secure_port=9445 -unsecure_port=9180 tomcat_server_port=9701 -redirect conf=/etc/rhpki-ca -redirect logs=/var/log/rhpki-ca

Page 19

Installing New Certificate System Subsystem Instances

Installing the DRM, OCSP, and TKS subsystems are similar to installing the CA, except for the subsystem type and instance-specific settings, like the name and port numbers.

To install an RA with the 7.2 and 7.3 instance name of rhpki-ra:

pkicreate -pki_instance_root=/var/lib -pki_instance_name=rhpki-ra -subsystem_type=ra secure_port=12889 -non_clientauth_secure_port=12890 -unsecure_port=12888 -redirect conf=/ etc/rhpki-ra -redirect logs=/var/log/rhpki-ra

Installing the TPS subsystem is similar to installing the RA because it has a similar port setup. The differences, obviously, include the subsystem type and instance-specific settings like the name and port numbers.

NOTE

The default name for instances in 8.0 is pki-type, like pki-ca. In versions 7.2 and

7.3, the default naming scheme was rhpki-type. The examples for creating a new instance use the 7.x naming convention, because it is easier to migrate between instances of the same name.

The pkicreate command is described in more detail in the Certificate System Command-Line Tools Guide.

9. When the installation process is complete, a URL to access this instance is printed to the screen which gives the subsystem instances hostname, port, and a login PIN to access the configuration wizard. For example:

PKI instance creation Utility ...

PKI instance creation completed ...

Starting pki-ca: [ OK ]

pki-ca (pid 17990) is running ...

'pki-ca' must still be CONFIGURED! (see /var/log/pki-ca-install.log)

Before proceeding with the configuration, make sure the firewall settings of this machine permit proper access to this subsystem.

Please start the configuration by accessing:

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

After configuration, the server can be operated by the command:

/sbin/service pki-ca start | stop | restart

10. Go through the configuration wizard to set up the CA; this is described in detail in the Certificate System Installation Guide.

11. Restart the new instance; this is required as part of the installation. For example:

Page 20

Chapter 2. Setting up Certificate System 8.0 Subsystems

service new_CA_instance restart

12. Run pkicreate, configure, and restart every new instance which will be migrated on the server.

13. Once every instance has been created and configured, stop all of the new instances. The new instance cannot be running when the migration process is started. For example:

service new_CA_instance stop service new_DRM_instance stop service new_RA_instance stop service new_OCSP_instance stop service new_TKS_instance stop service new_TPS_instance stop

14. Last, stop the Red Hat Directory Server 8.1 and Administration Server instances used by the Certificate System 8.0 instances.

service instance_name stop service dirsrv-admin stop

15. Certificate System 8.0 automatically configures signed audit logging for every subsystem (except the RA). However, Certificate System 7.x servers did not configure signed audit logging the same way. The new instances, then, must be reconfigured to accommodate the migrated certificate information.

The simplest option is to disable the signed audit logs in the Certificate System 8.0 instances. Reset the signed audit log parameter to false:

log.instance.SignedAudit.enable=false

The other option is to re-enroll for new signed audit certificate for the migrated instance. Requesting and retrieving certificates through the end users services for the CA is described in the Using End User Services guide; the basic process is:

a. Generate a signing certificate request. For example:

certutil -R -k ec -g 256 -s "CN=CA auditSigningCert,O=Example Domain" -n "auditSigningCert cert-new_CA_instance" -o request.cert -v 12 -d /var/ lib/new_CA_instance/alias -1 -7 -8

b. Submit the certificate to the Audit Signing Certificate Enrollment form or the Manual Log

Signing Certificate Enrollment form.

c. Retrieve the certificate from the end-entities pages, and install it in the migrated certificate

database.

certutil -A -n "auditSigningCert cert-new_CA_instance" -d /var/lib/new_CA_instance/ alias

Page 21

Default File and Directory Locations for Certificate System Subsystems

2.2. Default File and Directory Locations for Certificate System Subsystems

Certificate System servers consist of subsystems (which are types of servers) and instances.

Server subsystems are servers for a specific type of PKI function and are installed by the Certificate System RPMs. This general subsystem information is contained in non-relocatable, RPM-defined shared libraries, Java archive files, binaries, and templates. These are stored in a fixed location.

Server instances are somewhat relocatable and have user-specific default and customized forms and data. Subsystem instances can be stored anywhere on a system.

When the Certificate System is first installed, one instance for each subsystem type is also installed. The default information such as the port numbers, instance name, and configuration file location for each subsystem (after being installed and going through the setup process) is listed in the following sections.

2.2.1. Default CA Instance Information

The default CA configuration is listed in Table 2.1, “Default CA Instance Information”. Most of these values are unique to the default instance; the default certificates and some other settings are true for every CA instance.

Setting Value

Standard Port

9180

Agents Port

9443

Secure End Users Port

9444

Admin Port

9445

Tomcat Port

9701

Instance Name pki-ca

Main Directory /var/lib/new_CA_instance

Configuration Directory /etc/new_CA_instance

Configuration File /etc/new_CA_instance/CS.cfg

/etc/new_CA_instance/password.conf

Subsystem Certificates CA signing certificate

OCSP signing certificate (for the CA's internal OCSP service) SSL server certificate Audit log signing certificate Subsystem certificate

Security Databases /var/lib/new_CA_instance/alias

Log Files /var/log/new_CA_instance

Install Logs /var/log/new_CA_instance-install.log

Process File /var/run/pki-ca.pid

Profile Files /var/lib/new_CA_instance/profiles/ca

Email Notification Templates /var/lib/new_CA_instance/emails

Web Services Files /var/lib/new_CA_instance/webapps

Running service instance_name status lists all of the configured ports and URLs (interfaces) for the subsystem instance.

Page 22

Chapter 2. Setting up Certificate System 8.0 Subsystems

The subsystem certificate is always issued by the security domain so that domain-level operations that require client authentication are based on this subsystem certificate.

Table 2.1. Default CA Instance Information

2.2.2. Default RA Instance Information

The default RA configuration is listed in Table 2.2, “Default RA Instance Information”. Most of these values are unique to the default instance; the default certificates and some other settings are true for every RA instance.

Setting Value

Standard Port (for End Users)

12888

SSL Port (for end users)

12889

SSL Port (for agents and administrators)

12890

Instance Name pki-ra

Main Directory /var/lib/new_RA_instance

Configuration Directory /etc/new_RA_instance

Configuration File /etc/new_RA_instance/CS.cfg

/etc/new_RA_instance/nss.conf /etc/new_RA_instance/password.conf

Subsystem Certificates SSL server certificate

Subsystem certificate

Security Databases /var/lib/new_RA_instance/alias

Log Files /var/log/new_RA_instance

Install Logs /var/log/new_RA_instance-install.log

Web Services Files /var/lib/new_RA_instance/docroot

/var/lib/new_RA_instance/lib

Running service instance_name status lists all of the configured ports and URLs (interfaces) for the subsystem instance.

The subsystem certificate is always issued by the security domain so that domain-level operations that require client authentication are based on this subsystem certificate.

Table 2.2. Default RA Instance Information

2.2.3. Default DRM Instance Information

The default DRM configuration is listed in Table 2.3, “Default KRA Instance Information”. Most of these values are unique to the default instance; the default certificates and some other settings are true for every DRM instance.

Setting Value

Standard Port

10180

Secure End Users Port

10444

Agents Port

10443

Admin Port

10445

Tomcat Port

10701

Instance Name pki-kra

Page 23

Default OCSP Instance Information

Setting Value

Main Directory /var/lib/new_DRM_instance

Configuration Directory /etc/new_DRM_instance

Configuration File /etc/new_DRM_instance/CS.cfg

/etc/new_DRM_instance/password.conf

Subsystem Certificates Transport certificate

Storage certificate SSL server certificate Audit log signing certificate Subsystem certificate

Security Databases /var/lib/new_DRM_instance/alias

Log Files /var/log/new_DRM_instance

Install Logs /var/log/new_DRM_instance-install.log

Process File /var/run/pki-kra.pid

Web Services Files /var/lib/new_DRM_instance/webapps

Running service instance_name status lists all of the configured ports and URLs (interfaces) for the subsystem instance.

The subsystem certificate is always issued by the security domain so that domain-level operations that require client authentication are based on this subsystem certificate.

Table 2.3. Default KRA Instance Information

2.2.4. Default OCSP Instance Information

The default OCSP configuration is listed in Table 2.4, “Default OCSP Instance Information”. Most of these values are unique to the default instance; the default certificates and some other settings are true for every OCSP instance.

Setting Value

Standard Port

11180

Secure End Users Port

11444

Agents Port

11443

Admin Port

11445

Tomcat Port

11701

Instance Name pki-ocsp

Main Directory /var/lib/new_OCSP_instance

Configuration Directory /etc/new_OCSP_instance

Configuration File /etc/new_OCSP_instance/CS.cfg

/etc/new_OCSP_instance/password.conf

Subsystem Certificates OCSP signing certificate

SSL server certificate Audit log signing certificate Subsystem certificate

Security Databases /var/lib/new_OCSP_instance/alias

Log Files /var/log/new_OCSP_instance

Page 24

Chapter 2. Setting up Certificate System 8.0 Subsystems

Setting Value

Install Logs /var/log/new_OCSP_instance-install.log

Process File /var/run/pki-ocspocsp.pid

Web Services Files /var/lib/new_OCSP_instance/webapps

Running service instance_name status lists all of the configured ports and URLs (interfaces) for the subsystem instance.

The subsystem certificate is always issued by the security domain so that domain-level operations that require client authentication are based on this subsystem certificate.

Table 2.4. Default OCSP Instance Information

2.2.5. Default TKS Instance Information

The default TKS configuration is listed in Table 2.5, “Default TKS Instance Information”. Most of these values are unique to the default instance; the default certificates and some other settings are true for every TKS instance.

Setting Value

Standard Port

13180

Secure End Users Port

13444

Agents Port

13443

Admin Port

13445

Tomcat Port

13701

Instance Name pki-tks

Main Directory /var/lib/new_TKS_instance

Configuration Directory /etc/new_TKS_instance

Configuration File /etc/new_TKS_instance/CS.cfg

/etc/new_TKS_instance/password.conf

Subsystem Certificates SSL server certificate

Audit log signing certificate Subsystem certificate

Security Databases /var/lib/new_TKS_instance/alias

Log Files /var/log/new_TKS_instance

Install Logs /var/log/new_TKS_instance-install.log

Process File /var/run/pki-tks.pid

Running service instance_name status lists all of the configured ports and URLs (interfaces) for the subsystem instance.

The subsystem certificate is always issued by the security domain so that domain-level operations that require client authentication are based on this subsystem certificate.

Table 2.5. Default TKS Instance Information

2.2.6. Default TPS Instance Information

The default TPS configuration is listed in Table 2.6, “Default TPS Instance Information”. Most of these values are unique to the default instance; the default certificates and some other settings are true for every TPS instance.

Page 25

Default TPS Instance Information

Setting Value

Standard Port (for End Users)

7888

SSL Port (for agents and administrators)

7889

Instance Name pki-tps

Main Directory /var/lib/new_TPS_instance

Configuration Directory /etc/new_TPS_instance

Configuration File /etc/new_TPS_instance/CS.cfg

/etc/new_TPS_instance/nss.conf /etc/new_TPS_instance/password.conf

Subsystem Certificates SSL server certificate

Subsystem certificate

Security Databases /var/lib/new_TPS_instance/alias

Log Files /var/log/new_TPS_instance

Install Logs /var/log/new_TPS_instance-install.log

Web Services Files /var/lib/pki-tps/docroot

/var/lib/pki-tps/cgi-bin /var/lib/pki-tps/lib

Running service instance_name status lists all of the configured ports and URLs (interfaces) for the subsystem instance.

Table 2.6. Default TPS Instance Information

The TPS ports (7888, 7889, and 7890) are most commonly accessed by the Enterprise Security Client, not by users directly. This access is done using different URLs to access different docroot directories for the TPS, depending on the Enterprise Security Client UI that is being used.

By default, the Enterprise Security Client has two URLs to access the regular token enrollment UI:

• One over a standard port, http://server.example.com:7888/cgi-bin/home/index.cgi

• One over a secure (SSL) port, https://server.example.com:7890/cgi-bin/home/index.cgi

There are two ports for enrolling security officers and the one URL to access the security officer workstation UI:

• One enrollment UI over a standard port, http://server.example.com:7888/cgi-bin/so/

enroll.cgi

• One enrollment UI over a secure (SSL) port, http://server.example.com:7889/cgi-bin/so/ enroll.cgi

• One workstation UI, which is always over a secure (SSL) port, http://server.example.com:7888/ cgi-bin/sow/welcome.cgi

Then there is one last URL which is accessed by operators, agents, and administrators over HTTPS, http://server.example.com:7888/tps/services. This URL is used to manage the TPS subsystem, such as configuring audit logging and adding users, and it also has minimal token management operations, such as manually adding tokens to the TPS's token database.

As with the other subsystems, running service pki-tps status will show all of the ports and interface URLs for the instance.

Page 26

Chapter 2. Setting up Certificate System 8.0 Subsystems

The Phone Home URL configured in the Enterprise Security Client's esc-prefs.js configuration file determines which URL to access. Setting the Phone Home URL is described in the Managing Smart Cards with the Enterprise Security Client guide.

2.2.7. Shared Certificate System Subsystem File Locations

There are some directories used by all Certificate System subsystems for general server operations, listed in Table 2.7, “Subsystem File Locations”.

Directory Location Contents

/var/lib/subsystem_name /var/lib64/subsystem_name

Contains user-specific default and customized configuration files, profiles, certificate databases, web files, and other files for the subsystem instance.

/usr/share/java/pki Contains Java archive files shared by the Certificate System subsystems. Along with shared files for all subsystems, there are subsystem-specific

files in subfolders: pki/ca/ (CA) pki/kra/ (DRM) pki/ocsp/ (OCSP) pki/tks/ (TKS)

Not used by the RA or TPS subsystems.

/usr/share/pki Contains common files and templates used to create Certificate System instances. Along with shared files for all subsystems, there are subsystem-

specific files in subfolders: pki/ca/ (CA) pki/kra/ (DRM) pki/ocsp/ (OCSP) pki/ra/ (RA) pki/tks/ (TKS) pki/tps (TPS)

/usr/bin Contains the pkicreate and pkiremove instance configuration scripts and tools (Java, native, and security) shared by the Certificate System

subsystems.

/var/lib/tomcat5/common/lib Contains Java archive files shared by local Tomcat web applications and shared by the Certificate System subsystems. Not used by the TPS and RA

subsystems.

/var/lib/tomcat5/server/lib Contains Java archive files used by the local Tomcat web server and shared by the Certificate System subsystems. Not used by the TPS and RA

subsystems.

/usr/lib/httpd/modules /usr/lib64/httpd/modules

Contains Apache modules shared by TPS and RA subsystems. Not used by the CA, DRM, OCSP, or TKS subsystems.

/usr/lib/mozilla /usr/lib64/mozilla

Mozilla LDAP SDK tools shared by TPS and RA subsystems. Not used by the CA, DRM, OCSP, or TKS subsystems.

Table 2.7. Subsystem File Locations

Page 27

Chapter 3.

Migrating a CA Instance to Certificate System 8.0

Migrating a 7.x version of the Certificate Manager to the 8.0 requires migrating individual areas of data — the certificate and key databases for the subsystem, its internal LDAP database, its subsystem password stores — into the new subsystem and then reconfiguring the new subsystem.

Version-specific scripts are available to properly migrate and process data from the internal database so that it is formatted to work in the 8.0 database.

IMPORTANT

Every new Red Hat Certificate System 8.0 instance which will be installed on the host must be installed and fully configured, as described in Chapter 2, Setting up Certificate

System 8.0 Subsystems, before beginning a single subsystem migration.

3.1. Flush the Request Queue

Before migrating a CA, make sure that all requests submitted to the CA have been processed. Certificates stored in the CA databases are migrated to the later version, but certificate requests are not. Any outstanding requests must then be processed before migration, and the 7.x CA must be taken offline to prevent any further requests from coming in.

3.2. Migrating the Security Databases

The data from the certificate (cert8.db) and key (key3.db) security databases for the Red Hat Certificate System 7.1, 7.2, or 7.3 instances must be extracted and copied into the Red Hat Certificate System 8.0 subsystem's alias/ directory.

IMPORTANT

Make sure the new 8.0 instance and its LDAP database are stopped before beginning migration.

• Section 3.2.1, “Option 1: Security Databases to Security Databases Migration”

• Section 3.2.2, “Option 2: Security Databases to HSM Migration”

• Section 3.2.3, “Option 3: HSM to Security Databases Migration”

• Section 3.2.4, “Option 4: HSM to HSM Migration”

3.2.1. Option 1: Security Databases to Security Databases Migration

1. Remove all the security databases in the Certificate System 8.0 server which will receive migrated

data.

rm /var/lib/new_CA_instance/alias/cert8.db

Page 28

Chapter 3. Migrating a CA Instance to Certificate System 8.0

rm /var/lib/new_CA_instance/alias/key3.db

2. Copy the certificate and key security databases from the 7.x server to the 8.0 server.

cp old_server_root/alias/cert-old_instance-cert8.db /var/lib/new_CA_instance/alias/ cert8.db

cp old_server_root/alias/cert-old_instance-key3.db /var/lib/new_CA_instance/alias/key3.db

WARNING

Changing either the instance name or the fully-qualified domain name is not supported for migration. The fully-qualified domain name of the host machine for the new instance must be the same as the fully-qualified domain name of the original instance. Likewise, the new instance name must also be the same as the original instance name.

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

3. Open the Certificate System /alias directory.

cd /var/lib/new_CA_instance/alias/

4. Log into the 8.0 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.

Page 29

Option 2: Security Databases to HSM Migration

10. Edit the ca.signing.cacertnickname and ca.ocsp_signing.cacertnickaname

attributes to reflect the 8.0 CA instance.

ca.signing.cacertnickname=caSigningCert cert-old_CA_instance ca.ocsp_signing.cacertnickname=ocspSigningCert cert-old_CA_instance

11. If there is CA-DRM connectivity, then also modify the ca.connector.KRA.nickname attribute.

ca.connector.KRA.nickname=caSigningCert cert-old_CA_instance

12. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

Server-Cert cert-old_CA_instance

3.2.2. Option 2: Security Databases to HSM Migration

1. Remove all the security databases in the Certificate System 8.0 which will receive migrated data.

rm /var/lib/new_CA_instance/alias/cert8.db

rm /var/lib/new_CA_instance/alias/key3.db

2. Copy the certificate and key security databases from the 7.x server to the 8.0 server.

cp old_server_root/alias/cert-old_instance-cert8.db /var/lib/new_CA_instance/alias/ cert8.db

cp old_server_root/alias/cert-old_instance-key3.db /var/lib/new_CA_instance/alias/key3.db

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

3. Open the Certificate System /alias directory.

cd /var/lib/new_CA_instance/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

Page 30

Chapter 3. Migrating a CA Instance to Certificate System 8.0

# chown user:group key3.db

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

chmod 00600 cert8.db

chmod 00600 key3.db

7. List the certificates stored in the 7.x security databases by using the certutil command; -L lists

the certificates.

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

8. Export the public/private key pairs of each entry in the Certificate System databases using the

pk12util tool; -o exports the key pairs to file, and -n sets the name of the certificate and the old database prefix.

pk12util -o ServerCert.p12 -n "Server-Cert cert-old_CA_instance" -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-old_CA_instance" -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-old_CA_instance" -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** Re-enter password: ******** pk12util: PKCS12 EXPORT SUCCESSFUL

pk12util -o subsystemCert.p12 -n "subsystemCert cert-old_CA_instance" -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** Re-enter password: ******** pk12util: PKCS12 EXPORT SUCCESSFUL

NOTE

The 7.x security databases may contain additional public/private key pairs; these can also be extracted using pk12util.

9. Delete the 7.x security databases.

rm cert8.db

Page 31

Option 2: Security Databases to HSM Migration

rm key3.db

10. Register the new HSM in the 8.0 token database.

modutil -nocertdb -dbdir . -add new_HSM_token_name -libfile new_HSM_library_path/ new_HSM_library

11. Identify the new HSM slot name.

modutil -dbdir . -nocertdb -list

12. Create new security databases.

certutil -N -d .

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

pk12util -i ServerCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

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

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

pk12util -i ocspSigningCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i subsystemCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

14. Optionally, delete the PKCS #12 files.

rm ServerCert.p12

rm caSigningCert.p12

rm ocspSigningCert.p12

rm subsystemCert.p12

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

certutil -M -n "new_HSM_slot_name:Server-Cert cert-old_CA_instance" -t "cu,cu,cu" -d . h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:caSigningCert cert-old_CA_instance" -t "CTu,CTu,CTu" d . -h new_HSM_token_name

Page 32

Chapter 3. Migrating a CA Instance to Certificate System 8.0

certutil -M -n "new_HSM_slot_name:ocspSigningCert cert-old_CA_instance" -t "CTu,Cu,Cu" d . -h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:subsystemCert cert-old_CA_instance" -t "cu,cu,cu" -d . h new_HSM_token_name

16. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

17. Edit the ca.signing.cacertnickaname and ca.ocsp_signing.cacertnickname

attributes to reflect the 8.0 CA instance.

ca.signing.cacertnickname=new_HSM_slot_name:caSigningCert cert-old_CA_instance ca.ocsp_signing.cacertnickname=new_HSM_slot_name:ocspSigningCert cert-old_CA_instance

18. If there is CA-DRM connectivity, then also modify the ca.connector.KRA.nickname attribute.

ca.connector.KRA.nickname=new_HSM_slot_name:caSigningCert cert-old_CA_instance

19. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

new_HSM_slot_name:Server-Cert cert-old_CA_instance

3.2.3. Option 3: HSM to Security Databases Migration

1. Extract the public/private key pairs from the HSM. The format for the extracted key pairs should be portable, such as a PKCS #12 file.

The pk12util tool provided by Certificate System cannot extract public/private key pairs from an HSM because of requirements in the FIPS 140-1 standard which protect the private key. To extract this information, contact the HSM vendor. The extracted keys should not have any dependencies, such as nickname prefixes, on the HSM.

2. Copy the extracted key pairs from the 7.x server to the 8.0 server.

cp old_server_root/alias/ServerCert.p12 /var/lib/new_CA_instance/alias/ServerCert.p12

cp old_server_root/alias/caSigningCert.p12 /var/lib/new_CA_instance/alias/ caSigningCert.p12

cp old_server_root/alias/ocspSigningCert.p12 /var/lib/new_CA_instance/alias/ ocspSigningCert.p12

cp old_server_root/alias/subsystemCert.p12 /var/lib/new_CA_instance/alias/ subsystemCert.p12

WARNING

Page 33

Option 3: HSM to Security Databases Migration

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

3. Open the Certificate System /alias directory.

cd /var/lib/new_CA_instance/alias/

4. Log in as root.

5. Set the file user and group to the Certificate System user and group.

# chown user:group ServerCert.p12

# chown user:group caSigningCert.p12

# chown user:group ocspSigningCert.p12

# chown user:group subsystemCert.p12

6. Log out as root, and log back into the system as the Certificate System user.

7. Set the file permissions.

chmod 00600 ServerCert.p12

chmod 00600 caSigningCert.p12

chmod 00600 ocspSigningCert.p12

chmod 00600 subsystemCert.p12

8. Import the public/private key pairs of each entry from the PKCS #12 files into the 8.0 security databases.

pk12util -i ServerCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i caSigningCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i ocspSigningCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i subsystemCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

Page 34

Chapter 3. Migrating a CA Instance to Certificate System 8.0

9. Optionally, delete the PKCS #12 files.

rm ServerCert.p12

rm caSigningCert.p12

rm ocspSigningCert.p12

rm subsystemCert.p12

10. Set the trust bits on the public/private key pairs that were imported into the 8.0 security databases.

certutil -M -n "Server-Cert cert-old_CA_instance" -t "cu,cu,cu" -d .

certutil -M -n "caSigningCert cert-old_CA_instance" -t "CTu,CTu,CTu" -d .

certutil -M -n "ocspSigningCert cert-old_CA_instance" -t "CTu,Cu,Cu" -d .

certutil -M -n "subsystemCert cert-old_CA_instance" -t "cu,cu,cu" -d .

11. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

12. Edit the ca.signing.cacertnickname and ca.ocsp_signing.cacertnickname attributes

to reflect the 8.0 CA instance.

ca.signing.cacertnickname=caSigningCert cert-old_CA_instance ca.ocsp_signing.cacertnickname=ocspSigningCert cert-old_CA_instance

13. If there is CA-DRM connectivity, then also modify the ca.connector.KRA.nickname attribute.

ca.connector.KRA.nickname=caSigningCert cert-old_CA_instance

14. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

Server-Cert cert-old_CA_instance

3.2.4. Option 4: HSM to HSM Migration

1. Extract the public/private key pairs from the HSM. The format for the extracted key pairs should be portable, such as a PKCS #12 file.

2. Copy the extracted key pairs from the 7.x server to the 8.0 server.

cp old_server_root/alias/ServerCert.p12 /var/lib/new_CA_instance/alias/ServerCert.p12

cp old_server_root/alias/caSigningCert.p12 /var/lib/new_CA_instance/alias/ caSigningCert.p12

Page 35

Option 4: HSM to HSM Migration

cp old_server_root/alias/ocspSigningCert.p12 /var/lib/new_CA_instance/alias/ ocspSigningCert.p12

cp old_server_root/alias/subsystemCert.p12 /var/lib/new_CA_instance/alias/ subsystemCert.p12

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

3. Open the Certificate System /alias directory.

cd /var/lib/new_CA_instance/alias/

4. Log in as root.

5. Set the file user and group to the Certificate System user and group.

# chown user:group ServerCert.p12

# chown user:group caSigningCert.p12

# chown user:group ocspSigningCert.p12

6. Log out as root, and log back into the system as the Certificate System user.

7. Set the file permissions.

chmod 00600 ServerCert.p12

chmod 00600 caSigningCert.p12

chmod 00600 ocspSigningCert.p12

chmod 00600 subsystemCert.p12

8. Register the new HSM in the 8.0 token database.

modutil -nocertdb -dbdir . -add new_HSM_token_name -libfile new_HSM_library_path/new_HSM_library

9. Identify the new HSM slot name.

modutil -dbdir . -nocertdb -list

Page 36

Chapter 3. Migrating a CA Instance to Certificate System 8.0

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

pk12util -i ServerCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i caSigningCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i ocspSigningCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i subsystemCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

11. Optionally, delete the PKCS #12 files.

rm ServerCert.p12

rm caSigningCert.p12

rm ocspSigningCert.p12

rm subsystemCert.p12

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

certutil -M -n "new_HSM_slot_name:Server-Cert cert-old_CA_instance" -t "cu,cu,cu" -d . h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:caSigningCert cert-old_CA_instance" -t "CTu,CTu,CTu" d . -h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:ocspSigningCert cert-old_CA_instance" -t "CTu,Cu,Cu" d . -h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:subsystemCert cert-old_CA_instance" -t "cu,cu,cu" -d . h new_HSM_token_name

13. Open the CS.cfg configuration file in the /var/lib/new_CA_instance/conf directory.

14. Edit the ca.signing.cacertnickname and ca.ocsp_cacertnickname attributes to reflect the 8.0 CA instance.

ca.signing.cacertnickname=new_HSM_slot_name:caSigningCert cert-old_CA_instance ca.ocsp_signing.cacertnickname=new_HSM_slot_name:ocspSigningCert cert-old_CA_instance

15. If there is CA-DRM connectivity, then also modify the ca.connector.KRA.nickname attribute.

ca.connector.KRA.nickname=new_HSM_slot_name:caSigningCert cert-old_CA_instance

Page 37

Migrating Subsystem Password Stores

16. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

new_HSM_slot_name:Server-Cert cert-old_CA_instance

3.3. Migrating Subsystem Password Stores

The password information for the Certificate System subsystems are saved in a special password file. In Certificate System 7.1, these were kept in the pwcache.db file. The contents of the password file must be decrypted and listed using the PasswordCache tool in the 7.x subsystem instance. Then, this information must be used to build the contents of the 8.0 password.conf file.

In Certificate System 7.2 and 7.3, passwords were kept in the password.conf file in the /var/ lib/instance_ID/conf/ directory, the same file that is used in Certificate System 8.0. This file contains the passwords for both internal database and the password for the key3.db file. The 7.2 or

7.3 password.conf file just needs to be copied over to the 8.0 conf directory.

3.3.1. Migrating Passwords from 7.1

1. Log into the 7.x server as the Certificate System user for that machine, and open the config/

directory.

cd old_server_root/cert-old_instance/config/

2. Run the PasswordCache tool from the tools directory to retrieve the passwords from the

database.

old_server_root/bin/cert/tools/PasswordCache old_passwordcache_password d old_server_root/alias -P cert-old_instance-old_hostname- -c pwcache.db list

This lists the information stored in the password cache.

cert/key prefix = cert-old_instance-old_hostnamepath = old_server_root/alias about to read password cache

----- Password Cache Content ----internal : password Internal LDAP Database : passwordldap

3. Use the listed tags and passwords to create the password.conf file. For example:

internal=password Internal LDAP Database=passwordldap

4. If the 7.x server instance used the password.conf file to start the server instance automatically,

then this file must also be migrated to the 8.0 server instance.

cp old_server_root/cert-old_instance/config/password.conf /var/lib/new_CA_instance/conf/ password.conf

5. Log into the 8.0 server as the Certificate System user, and open the Certificate System conf/

directory.

Page 38

Chapter 3. Migrating a CA Instance to Certificate System 8.0

cd /var/lib/new_CA_instance/conf/

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

chown user:group password.conf

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

chmod 00600 password.conf

8. Copy the tags and passwords that were listed from the 7.x pwdcache.db file into the password.conf file.

The password cache dump from the pwdcache.db file looks like the following:

CA LDAP Publishing : password internal : password Internal LDAP Database : password

The password.conf file has the following format:

internal=310062130979 internaldb=password replicationdb=-2057636068

internaldb in 8.0 is the same as Internal LDAP Database in 7.x, and replicationdb in

8.0 is the same as CA LDAP Publishing.

3.3.2. Migrating Passwords from 7.2 and 7.3

Versions 7.2, 7.3, and 8.0 all store passwords in a text file, password.conf, in the conf/ directory.

To migrate the passwords, simply copy the password.conf file to the 8.0 instance directory.

NOTE

Make sure that the permissions and ownership for the password.conf file are set properly so that it can be accessed by the migrated instance.

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

group.

# chown user:group password.conf

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

chmod 00600 password.conf

Page 39

Migrating the LDAP Database

3.4. Migrating the LDAP Database

Every 7.x CA subsystem contains LDIF data in an associated internal database which must be migrated to the corresponding Red Hat Certificate System 8.0 subsystem internal database. The only difference between Certificate System 7.x versions is which import and export utility to use; these are version specific.

1. Log into the Directory Server 8.1 for the Certificate System 8.0 instance, and export the internal database content to LDIF. The internal database name for the Certificate System instance is in the internaldb.database parameter in the CS.cfg file. Name the output file new-new_CA_instance.ldif.

For example:

/usr/lib/dirsrv/slapd-example/db2ldif -U -n server.example.com-new_CA_instance -a /var/ lib/dirsrv/slapd-example/ldif/new-new_CA_instance.ldif

2. If they are not already installed, download and install the Certificate System migration utilities. For example:

yum install pki-migrate

3. If you are migrating to a different platform or machine, then copy the newest version of the migration utility from the Certificate System 8.0 server to the Certificate System 7.x server.

4. Open the Certificate System instance directory. The migration utilities are in the migrate directory.

cd /usr/share/pki

5. Package the latest version of the Certificate System 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 7.x server machine. If the platforms are identical and the zip utility is used, copy the zip tool from the 8.0 server to the 7.x server so that the zip and unzip versions match.

6. Copy the package from the 8.0 server to the 7.x server, and then remove the package from the 8.0 server. (You can use any copy tool, such as sftp, scp, and mv.)

cp /usr/share/pki/migrate.tar old_server_root/bin/cert

rm /usr/share/pki/migrate.tar

7. Log into the 7.x server as the Certificate System user for that machine, and open the Certificate System tools directory.

Page 40

Chapter 3. Migrating a CA Instance to Certificate System 8.0

cd old_server_root/bin/cert

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

# chown user:group migrate.tar

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

chmod 00600 migrate.tar

10. Since the Certificate System 7.x migration utility will not be used, remove the Certificate System

7.x's upgrade/ directory. This ensures that only the newest migration scripts, in the copied migrate directory, are available.

rm -rf old_server_root/bin/cert/upgrade

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

tar -xvf migrate.tar

12. Remove the migration utility package and any additional utilities, such as the unzip utility, that

were copied to the Certificate System 7.x server.

rm migrate.tar

13. Log into the 7.x Certificate System instance, and export the database contents to LDIF. Name the

output file old-old_CA_instance.ldif.

For example:

/opt/redhat-ds/slapd-DS-instance/db/db2ldif -U -n server.example.com-old_CA_instance -a / opt/redhat-ds/slapd-DS-instance/ldif/old-old_CA_instance.ldif

14. Convert the old-old_CA_instance.ldif file to a text file.

a. Open the version-to-text directory in the migration directory copied to the Certificate System

7.x server. Each 7.x major version has its own migration directory. For example, for migrating from version 7.3, then use 73ToTxt. For example:

cd old_server_root/bin/cert

b. Edit the run.sh script to set the proper server and JRE information.

• For 7.1 migrations, uncomment and set the values for the following lines:

SERVER_ROOT=old_server_root export SERVER_ROOT INSTANCE=old_instance export INSTANCE

Page 41

Migrating the LDAP Database

• For versions 7.2 and 7.3, make sure that the appropriate JRE root is given for the JRE version on the server. The default, for example, on Red Hat Enterprise Linux 4 is:

JRE_ROOT=/usr/lib/jvm/jre-1.5.0-ibm export JRE_ROOT

c. Run the run.sh to use the old-old_CA_instance.ldif file to create a text file.

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

15. Open the Certificate System 7.x LDIF directory, and copy the old-old_CA_instance.txt file

into the Certificate System 8.0 server instance's internal database LDIF directory.

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

cp /opt/redhat-ds/slapd-DS-instance/ldif/old-old_CA_instance.txt /var/lib/dirsrv/slapdexample/ldif

16. Open the Certificate System ldif/ directory.

cd /var/lib/dirsrv/slapd-example/ldif

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

# chown user:group old-old_CA_instance.txt

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

chmod 00600 old-old_CA_instance.txt

19. Convert the old-old_CA_instance.txt file to LDIF, and name the file rhcs80-new_CA_instance.ldif.

a. Open the 8.0 text-conversion migration directory in the Certificate System 8.0 server.

cd /usr/share/pki/migrate/TxtTo80

b. Run run.sh to use old-old_CA_instance.txt to create the

rhcs80-new_CA_instance.ldif file.

run.sh /var/lib/dirsrv/slapd-example/ldif/old-old_CA_instance.txt > /var/lib/dirsrv/ slapd-example/ldif/rhcs80-new_CA_instance.ldif

20. Modify the content of rhcs80-new_CA_instance.ldif so that the LDIF files contain the required ACLs and other settings that were created with the new 8.0 instances.

Page 42

Chapter 3. Migrating a CA Instance to Certificate System 8.0

NOTE

When using a text editor to perform the substitution instead of a script, use an editor that supports file sizes greater than 4 gigabytes, such as vim, because the LDIF files may be larger than 2 gigabytes and even 4 gigabytes in some deployments.

a. Open the Certificate System 8.0 LDIF directory.

cd /var/lib/dirsrv/slapd-example/ldif

b. Open the new-new_CA_instance.ldif file, in read-only mode.

view new-new_CA_instance.ldif

c. Open the rhcs80-new_CA_instance.ldif file.

vi rhcs80-new_CA_instance.ldif

d. Delete the entries for o=hostname-db,o=netscapeCertificateServer and

o=netscapeCertificateServer.

e. Add a new entry for the base DN used in the 8.0 database (something like

dc=server.example.com-new_CA_instance). For example:

dn: dc=server.example.com-new_CA_instance objectClass: top objectClass: domain dc: server.example.com-new_CA_instance

f. Change the base DN in every entry in the original file (o=hostname-

db,o=netscapeCertificateServer) to the one used for entries in the new-new_CA_instance.ldif file (dc=server.example.com-new_CA_instance).

There could be thousands of entries affected.

g. Replace cn=aclResources entry in the rhcs80-new_CA_instance.ldif file with the

cn=aclResources entry from the new-new_CA_instance.ldif file. For example:

dn: cn=aclResources,dc=server.example.com-new_CA_instance resourceACLS: certServer.usrgrp.administration:read,modify:allow (read) group= "Administrators" || group="Auditors" || group="Certificate Manager Agents" || group="Registration Manager Agents" || group="Data Recovery Manager Agents" || group="Online Certificate Status Manager Agents"; allow (modify) group="Administrators":Administrators, auditors, and agents are allowed to read user and group configuration but only administrators are allowed to modify

... list of ACLs ... objectClass: top objectClass: CertACLS cn: aclResources

Page 43

Migrating the LDAP Database

h. Add new groups for the the security domains to the rhcs80-new_CA_instance.ldif file.

Security domains were not a feature in 7.1 versions of Certificate System, so it is necessary to add all of the group entries; for 7.2, it is only necessary to add the RA group entry; for 7.3, it is not necessary to add any groups at all.

dn: cn=Security Domain Administrators,ou=groups,dc=server.example.com-new_CA_instance description: People who are the Security Domain administrators objectClass: top objectClass: groupOfUniqueNames cn: Security Domain Administrators uniqueMember: uid=admin,ou=People,dc=server.example.com-new_CA_instance

dn: cn=Enterprise CA Administrators,ou=groups,dc=server.example.com-new_CA_instance description: People who are the administrators for the security domain for CA objectClass: top objectClass: groupOfUniqueNames cn: Enterprise CA Administrators uniqueMember: uid=admin,ou=People,dc=server.example.com-new_CA_instance

dn: cn=Enterprise KRA Administrators,ou=groups,dc=server.example.com-new_CA_instance description: People who are the administrators for the security domain for KRA objectClass: top objectClass: groupOfUniqueNames cn: Enterprise KRA Administrators uniqueMember: uid=admin,ou=People,dc=server.example.com-new_CA_instance

dn: cn=Enterprise OCSP Administrators,ou=groups,dc=server.example.com-new_CA_instance description: People who are the administrators for the security domain for OCSP objectClass: top objectClass: groupOfUniqueNames cn: Enterprise OCSP Administrators uniqueMember: uid=admin,ou=People,dc=server.example.com-new_CA_instance

dn: cn=Enterprise TKS Administrators,ou=groups,dc=server.example.com-new_CA_instance description: People who are the administrators for the security domain for TKS objectClass: top objectClass: groupOfUniqueNames cn: Enterprise TKS Administrators uniqueMember: uid=admin,ou=People,dc=server.example.com-new_CA_instance

dn: cn=Enterprise RA Administrators,ou=groups,dc=server.example.com-new_CA_instance description: People who are the administrators for the security domain for RA objectClass: top objectClass: groupOfUniqueNames cn: Enterprise RA Administrators uniqueMember: uid=admin,ou=People,dc=server.example.com-new_CA_instance

dn: cn=Enterprise TPS Administrators,ou=groups,dc=server.example.com-new_CA_instance description: People who are the administrators for the security domain for TPS objectClass: top objectClass: groupOfUniqueNames cn: Enterprise TPS Administrators uniqueMember: uid=admin,ou=People,dc=basedn

i. Create a group entry for the security domain configuration in the

rhcs80-new_CA_instance.ldif file.

i. Look up the name of the old security domain in the old CS.cfg file.

Page 44

Chapter 3. Migrating a CA Instance to Certificate System 8.0

securitydomain.name=ms2cs8264ca1from71on20100128

ii. Create the security domain container entry in the rhcs80-new_CA_instance.ldif file,

with the name attribute set to the value of the old securitydomain.name parameter.

dn: ou=Security Domain,dc=server.example.com-new_CA_instance objectClass: top objectClass: pkiSecurityDomain ou: Security Domain name: securitydomain.name=ms2cs8264ca1from71on20100128

j. Add the PKI subsystem lists for the the security domains to the

rhcs80-new_CA_instance.ldif file. Each security domain contains a subsystemspecific list containing each instance of that type configured in the domain. In 7.2 and 7.3, this information was stored separately in the domain.xml file, while it did not exist at all in 7.1 servers.

dn: cn=CAList,ou=Security Domain,dc=server.example.com-new_CA_instance objectClass: top objectClass: pkiSecurityGroup cn: CAList

dn: cn=OCSPList,ou=Security Domain,dc=server.example.com-new_CA_instance objectClass: top objectClass: pkiSecurityGroup cn: OCSPList

dn: cn=KRAList,ou=Security Domain,dc=server.example.com-new_CA_instance objectClass: top objectClass: pkiSecurityGroup cn: KRAList

dn: cn=RAList,ou=Security Domain,dc=server.example.com-new_CA_instance objectClass: top objectClass: pkiSecurityGroup cn: RAList

dn: cn=TKSList,ou=Security Domain,dc=server.example.com-new_CA_instance objectClass: top objectClass: pkiSecurityGroup cn: TKSList

dn: cn=TPSList,ou=Security Domain,dc=server.example.com-new_CA_instance objectClass: top objectClass: pkiSecurityGroup cn: TPSList

k. Copy every PKI domain record into the rhcs80-new_CA_instance.ldif file. Every

instance configured in the security domain has a domain record; the domain entry is added when the instance is first configured. For example, this is a CA domain record:

dn: cn=server.example.com:9445,cn=CAList,ou=Security Domain,dc=server.example.com-new_CA_instance objectClass: top objectClass: pkiSubsystem host: server.example.com SecurePort: 9444

Page 45

Migrating Custom CS.cfg Settings and Other Data

SecureAgentPort: 9443 SecureAdminPort: 9445 UnSecurePort: 9180 Clone: false SubsystemName: Certificate Authority cn: server.example.com:9445 DomainManager: true

Each domain record will have the pkiSubsystem object class. Make sure that every domain record is copied into the rhcs80-new_CA_instance.ldif file.

l. If the subsystem instance is a cloned instance, add a group entry to maintain a list of users

who can create clones.

dn: cn=ClonedSubsystems,ou=groups,dc=server.example.com-new_CA_instance description: People who can clone the master subsystem objectClass: top objectClass: groupOfUniqueNames cn: ClonedSubsystems

21. Set the file permissions and ownership for the rhcs80-new_CA_instance.ldif file.

chown nobody:nobody rhcs80-new_CA_instance.ldif chmod 00644 rhcs80-new_CA_instance.ldif

22. Import the rhcs80-new_CA_instance.ldif LDIF file into the Certificate System 8.0 server instance's internal database using the Directory Server ldif2db tool.

The internal database name for the Certificate System instance is in the internaldb.database parameter in the CS.cfg file. For example:

/var/lib/dirsrv/slapd-example/db/ldif2db -n server.example.com-new_CA_instance -i /var/ lib/dirsrv/slapd-example/ldif/rhcs80-new_CA_instance.ldif

3.5. Migrating Custom CS.cfg Settings and Other Data

Copy all customized plug-ins, profiles, and forms to the Certificate System 8.0 server, and apply any hand-edited changes to the Certificate System 8.0 CS.cfg file.

NOTE

As other subsystems are migrated, then it may be necessary to update the corresponding subsystem in the CA's CS.cfg file. For example, when a DRM is migrated, then the ca.connector.KRA.transportCert parameter in the CA CS.cfg file must be updated with the migrated transport certificate.

For example, the profile configuration in the old_CA_instance has been changed to enable S/MIME support. To migrate the configuration, make the same changes to the new_CA_instance. In Certificate Management System 7.x, S/MIME support is enabled by editing the caTokenUserEncryptionKeyEnrollment profile. Duplicate these changes over to the corresponding new_CA_instance profile.

Page 46

Chapter 3. Migrating a CA Instance to Certificate System 8.0

1. Log into the 7.x server as the Certificate Management System user for that machine, and open the

Certificate Management System profiles/ca/ directory.

2. Copy the p1 policy set in the caTokenUserEncryptionKeyEnrollment.cfg file, as shown:

policyset.set1.p1.constraint.class_id=noConstraintImpl policyset.set1.p1.constraint.name=No Constraint policyset.set1.p1.default.class_id=nsTokenUserKeySubjectNameDefaultImpl policyset.set1.p1.default.name=nsTokenUserKeySubjectNameDefault policyset.set1.p1.default.params.dnpattern=UID=$request.uid$,OU=Engineering,O=Example policyset.set1.p1.default.params.ldap.enable=true policyset.set1.p1.default.params.ldap.searchName=uid policyset.set1.p1.default.params.ldapStringAttributes=uid,mail policyset.set1.p1.default.params.ldap.basedn=dc=example,dc=com policyset.set1.p1.default.params.ldap.maxConns=4 policyset.set1.p1.default.params.ldap.minConns=1 policyset.set1.p1.default.params.ldap.ldapconn.Version=2 policyset.set1.p1.default.params.ldap.ldapconn.host=ldaphostA.example.com policyset.set1.p1.default.params.ldap.ldapconn.port=389 policyset.set1.p1.default.params.ldap.ldapconn.secureConn=false

This configuration enables S/MIME support for services that use this profile to obtain certificates, such as token management systems.

3. Log into the new server as the Certificate System user, and open the Certificate System

profiles/ca/ directory.

4. Manually change the configuration in the new_CA_instance configuration to mimic the old_CA_instance configuration by editing the p1 policy set in the caTokenUserEncryptionKeyEnrollment.cfg file, as shown:

policyset.set1.p1.constraint.class_id=noConstraintImpl policyset.set1.p1.constraint.name=No Constraint policyset.set1.p1.default.class_id=nsTokenUserKeySubjectNameDefaultImpl policyset.set1.p1.default.name=nsTokenUserKeySubjectNameDefault policyset.set1.p1.default.params.dnpattern=UID=$request.uid$, OU=Engineering,O=Example policyset.set1.p1.default.params.ldap.enable=true policyset.set1.p1.default.params.ldap.searchName=uid policyset.set1.p1.default.params.ldapStringAttributes=uid,mail policyset.set1.p1.default.params.ldap.basedn=dc=example,dc=com policyset.set1.p1.default.params.ldap.maxConns=4 policyset.set1.p1.default.params.ldap.minConns=1 policyset.set1.p1.default.params.ldap.ldapconn.Version=2 policyset.set1.p1.default.params.ldap.ldapconn.host=ldaphostA.example.com policyset.set1.p1.default.params.ldap.ldapconn.port=389 policyset.set1.p1.default.params.ldap.ldapconn.secureConn=false

The altered profile serves certificate requests with S/MIME support enabled.

3.6. Restarting the CA Instance

1. Restart the Directory Server and Administration Server for the Certificate System 8.0 instance.

service dirsrv start service dirsrv-admin start

2. Start the Certificate Manager instances.

Page 47

Setting Custom Configuration in the Console

service new_CA_instance start

3.7. Setting Custom Configuration in the Console

Use the Console to configure any custom behavior of the different subsystems, such as customized plug-ins, logging, and auditing. A subsystem may have to be restarted once all configuration changes have been applied.

3.8. Verifying the CA Migration

After migrating the 7.x CA instance, open the CA end-entities services page and agent services page for the 8.0 instance to ensure that everything is working properly. For example:

https://server.example.com:9444/ca/ee/ca/ https://server.example.com:9443/ca/agent/ca

Then log into the Certificate System Console and verify that the new server can be managed through the Console.

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

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

Page 48

Page 49

Chapter 4.

Migrating an RA to 8.0

Although the original Certificate System RA subsystem was deprecated and removed in Red Hat Certificate System 7.1, it was reintroduced in Red Hat Certificate System 7.3. This 7.3 RA subsystem can be migrated to Certificate System 8.0.

The migration process for the RA differs from that of the other subsystems in several important ways:

• There are no migration scripts required for this migration. All steps are done using existing system or application tools.

• The RA uses a SQLite database for its internal database, rather than an LDAP database, as the other subsystems do. The migration process for this requires (as with the LDAP database) dumping the database information from the old version and then importing it into the new version, using the native SQLite tools.

As with migration the other subsystems, migrating the RA involves moving two important sets of information — the security databases and the database information — from the 7.3 version to the 8.0 of the subsystem.

IMPORTANT

Every new Red Hat Certificate System 8.0 instance which will be installed on the host must be installed and fully configured, as described in Chapter 2, Setting up Certificate

System 8.0 Subsystems, before beginning a single subsystem migration.

4.1. Dumping the 7.3 Databases

1. Shut down the 7.3 RA instance to be migrated.

2. Find the location of the 7.3 RA instance's SQLite database by checking the database.dbfile

parameter in the RA's CS.cfg file. For example:

database.dbfile=/var/lib/rhpki-ra/conf/dbfile

3. Open the SQLite database file location.

cd /var/lib/rhpki-ra/conf/

4. Dump the contents of the 7.3 SQLite database so that it can be imported into the 8.0 RA's SQLite

database:

sqlite dbfile .dump > old_dbfile.sql

4.2. Preparing 7.3 Security Databases

The Red Hat Certificate System 7.3 security databases are, by default, stored in the alias/ directory for the instance. For example:

/var/lib/rhpki-ra/alias/

Page 50

Chapter 4. Migrating an RA to 8.0

There are three databases in this directory:

• cert8.db

• key3.db

• secmod.db

To migrate these databases to the new 8.0 RA, zip the alias/ directory and copy it to the 8.0 RA's alias/ directory or to the 8.0 host machine.

zip -r old_alias.zip /var/lib/rhpki-ra/alias/

4.3. Importing the 7.3 SQL Database Information into the

8.0 SQL Database

1. Find the location of the 8.0 RA instance's SQLite database by checking the database.dbfile parameter in the RA's CS.cfg file. For example:

database.dbfile=/var/lib/new_RA_instance/conf/dbfile

2. Open the SQLite database file location.

cd /var/lib/new_RA_instance/conf/

3. Copy the dump file of the 7.3 RA SQLite database, old_dbfile.sql, into the 8.0 RA's SQLite database directory. For example:

cp /var/lib/rhpki-ra/conf/old_dbfile.sql /var/lib/new_RA_instance/conf/

4. Save a backup copy of the 8.0 RA SQLite database:

mv dbfile dbfile.orig

5. Make certain that this restored dbfile has the same file ownership and permissions configured that the default database file, dbfile has. The default owner and group should be pkiuser, and the default permissions should be 0644.

stat old_dbfile.sql File: `old_dbfile.sql' Size: 23001 Blocks: 56 IO Block: 4096 regular file Device: fd00h/64768d Inode: 11273634 Links: 1 Access: (0644/-rw-r--r--) Uid: ( 0/ root) Gid: ( 0/ root)

If necessary, reset the owner or permissions. For example:

chown pkiuser:pkiuser old_dbfile.sql

6. Restore the data in the old_dbfile.sql into the 8.0 RA's database, dbfile. For example:

Page 51

Migrating the 7.3 Security Databases to the 8.0 RA

sqlite dbfile < old_dbfile.sql

4.4. Migrating the 7.3 Security Databases to the 8.0 RA

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

1. Open the main configuration directory for the Certificate System 8.0 RA. For example:

cd /var/lib/new_RA_instance

2. Copy the zipped 7.3 alias/ directory, old_alias.zip, into this 8.0 RA's main directory.

cp /var/lib/rhpki-ra/old_alias.zip

3. Save a backup copy of the default 8.0 RA security databases.

mv alias alias.orig

4. Replace the default 8.0 alias/ directory with the 7.3 alias/ directory.

unzip old_alias.zip

5. The new alias/ directory and the three databases within it must have the identical owners and permissions as the default security databases, in alias.orig/. The files and directory should be belong to pkiuser and the permissions should be 0775 for the directory and 0600 for each of the databases within the directory.

stat alias/ File: `alias/' Size: 4096 Blocks: 16 IO Block: 4096 directory Device: fd00h/64768d Inode: 5668917 Links: 2 Access: (0775/drwxrwxr-x) Uid: ( 500/ pkiuser) Gid: ( 500/ pkiuser)

stat alias/cert8.db File: `alias/cert8.db' Size: 65536 Blocks: 144 IO Block: 4096 regular file Device: fd00h/64768d Inode: 5669533 Links: 1 Access: (0600/-rw-------) Uid: ( 500/ pkiuser) Gid: ( 500/ pkiuser)

If necessary, reset the file permissions using chmod or reset the user and group using chown.

Page 52

Chapter 4. Migrating an RA to 8.0

4.5. Migrating Passwords

Versions 7.3 and 8.0 of the RA both store passwords in a text file, password.conf, in the conf/ directory.

To migrate the passwords, simply copy the password.conf file to the 8.0 instance directory.

NOTE

Make sure that the permissions and ownership for the password.conf file are set properly so that it can be accessed by the migrated instance.

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

group.

# chown user:group password.conf

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

chmod 00600 password.conf

4.6. Migrating Custom Configuration

The RA has two important configuration files:

• CS.cfg, which configures the subsystem itself, such as request profiles

• nss.conf, which configures the Apache services for the RA

Any custom configuration needs to be copied from those two files in the 7.3 conf/ directory to the corresponding 8.0 configuration files.

4.7. Restarting the RA Instance

Start the new 8.0 RA instance.

service new_RA_instance start

4.8. Verifying the RA Migration

Open the RA end-entities services page and agent services page for the 8.0 instance to ensure that everything is working properly. For example:

https://server.example.com:12889/ee/index.cgi https://server.example.com:12889/services

The port numbers for all the agent services interfaces can be found in the nss.conf in the conf/ directory for the Certificate System 8.0 subsystem.

Page 53

Chapter 5.

Migrating a DRM Instance to Certificate System 8.0

Migrating a 7.x version of the Data Recovery Manager to the 8.0 requires migrating individual areas of data — the certificate and key databases for the subsystem, its internal LDAP database, its subsystem password stores — into the new subsystem and then reconfiguring the new subsystem.

Version-specific scripts are available to properly migrate and process data from the internal database so that it is formatted to work in the 8.0 database.

IMPORTANT

Every new Red Hat Certificate System 8.0 instance which will be installed on the host must be installed and fully configured, as described in Chapter 2, Setting up Certificate

System 8.0 Subsystems, before beginning a single subsystem migration.

5.1. Migrating the Security Databases

The data from the certificate (cert8.db) and key (key3.db) security databases for the Certificate System 7.1, 7.2, or 7.3 instances must be extracted and copied into the Red Hat Certificate System

8.0 subsystem's /alias directory.

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 5.1.1, “Option 1: Security Databases to Security Databases Migration”

• Section 5.1.2, “Option 2: Security Databases to HSM Migration”

• Section 5.1.3, “Option 3: HSM to Security Databases Migration”

• Section 5.1.4, “Option 4: HSM to HSM Migration”

5.1.1. Option 1: Security Databases to Security Databases Migration

1. Remove all the security databases in the Certificate System 8.0 server which will receive migrated data.

rm /var/lib/instance_ID/alias/cert8.db

rm /var/lib/instance_ID/alias/key3.db

2. Copy the certificate and key security databases from the 7.x server to the 8.0 server.

cp old_server_root/alias/cert-old_DRM_instance-cert8.db /var/lib/instance_ID/alias/ cert8.db

cp old_server_root/alias/cert-old_DRM_instance-key3.db /var/lib/instance_ID/alias/key3.db

Page 54

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

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 certificates in the 7.x security databases by using the certutil tool; -L lists the

certificates.

certutil -L -d .

Server-Cert cert-old_DRM_instance cu,cu,cu caSigningCert cert-old_DRM_instance CT,c, kraStorageCert cert-old_DRM_instance u,u,u kraTransportCert cert-old_DRM_instance u,u,u

9. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

10. Edit the kra.storageUnit.nickname and kra.transportUnit.nickname attribute to

reflect the 8.0 DRM instance.

kra.storageUnit.nickname=kraStorageCert cert-old_DRM_instance kra.transportUnit.nickname=kraTransportCert cert-old_DRM_instance

Page 55

Option 2: Security Databases to HSM Migration

NOTE

The caSigningCert is not referenced in the CS.cfg file.

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

Server-Cert cert-old_DRM_instance

5.1.2. Option 2: Security Databases to HSM Migration

1. Remove all the security databases in the Certificate System 8.0 which will receive migrated data.

rm /var/lib/instance_ID/alias/cert8.db

rm /var/lib/instance_ID/alias/key3.db

2. Copy the certificate and key security databases from the 7.x server to the 8.0 server.

cp old_server_root/alias/cert-old_DRM_instance-cert8.db /var/lib/instance_ID/alias/ cert8.db

cp old_server_root/alias/cert-old_DRM_instance-key3.db /var/lib/instance_ID/alias/key3.db

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

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.

Page 56

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

7. Set the file permissions.

chmod 00600 cert8.db

chmod 00600 key3.db

8. List the certificates stored in the 7.x security databases by using the certutil command; -L lists

the certificates.

certutil -L -d .

Server-Cert cert-old_DRM_instance cu,cu,cu caSigningCert cert-old_DRM_instance cT,c, kraStorageCert cert-old_DRM_instance u,u,u kraTransportCert cert-old_DRM_instance u,u,u

9. 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 sets the name of the certificate and the old database prefix.

pk12util -o ServerCert.p12 -n "Server-Cert cert-old_DRM_instance" -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** Re-enter password: ******** pk12util: PKCS12 EXPORT SUCCESSFUL

pk12util -o kraStorageCert.p12 -n "kraStorageCert cert-old_DRM_instance" -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** Re-enter password: ******** pk12util: PKCS12 EXPORT SUCCESSFUL

pk12util -o kraTransportCert.p12 -n "kraTransportCert cert-old_DRM_instance" -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** Re-enter password: ******** pk12util: PKCS12 EXPORT SUCCESSFUL

NOTE

The 7.x security databases may contain additional public/private key pairs; these can also be extracted using pk12util.

10. Export the public key using the certutil tool; -L lists the named certificate, -n sets the name of the file and the old prefix, and -a outputs the information to a base-64 file.

certutil -L -n "caSigningCert cert-old_DRM_instance" -d . -a > caSigningCert.b64

NOTE

The 7.x security databases may contain additional public keys; these can also be extracted using certutil.

Page 57

Option 2: Security Databases to HSM Migration

11. Delete the 7.x security databases.

rm cert8.db

rm key3.db

12. Register the new HSM in the 8.0 token database.

modutil -nocertdb -dbdir . -add new_HSM_token_name -libfile new_HSM_library_path/ new_HSM_library

13. Identify the new HSM slot name.

modutil -dbdir . -nocertdb -list

14. Create new security databases.

certutil -N -d .

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

pk12util -i ServerCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i kraStorageCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i kraTransportCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

16. Optionally, delete the PKCS #12 files.

rm ServerCert.p12

rm kraStorageCert.p12

rm kraTransportCert.p12

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

certutil -M -n "new_HSM_slot_name:Server-Cert cert-old_DRM_instance" -t "cu,cu,cu" -d . h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:kraStorageCert cert-old_DRM_instance" -t "u,u,u" -d . h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:kraTransportCert cert-old_DRM_instance" -t "u,u,u" -d .

-h new_HSM_token_name

Page 58

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

18. Import the public key from the base-64 file into the new HSM, and set the trust bits.

certutil -A -n "new_HSM_slot_name:caSigningCert cert-old_DRM_instance"

-t "CT,c," -d . -h new_HSM_token_name -i caSigningCert.b64

19. Optionally, delete the base-64 file.

rm caSigningCert.b64

20. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

21. Edit the kra.storageUnit.nickname and kra.transportUnit.nickname attributes to reflect the 8.0 DRM information.

kra.storageUnit.nickname=new_HSM_slot_name:kraStorageCert cert-old_DRM_instance kra.transportUnit.nickname=new_HSM_slot_name:kraTransportCert cert-old_DRM_instance

NOTE

The caSigningCert is not referenced in the CS.cfg file.

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

new_HSM_slot_name:Server-Cert cert-old_DRM_instance

5.1.3. Option 3: HSM to Security Databases Migration

1. Extract the public/private key pairs from the HSM. The format for the extracted key pairs should be portable, such as a PKCS #12 file.

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

2. Copy the extracted key pairs from the 7.x server to the 8.0 server.

Page 59

Option 3: HSM to Security Databases Migration

cp old_server_root/alias/ServerCert.p12 /var/lib/instance_ID/alias/ServerCert.p12

cp old_server_root/alias/kraStorageCert.p12 /var/lib/instance_ID/alias/kraStorageCert.p12

cp old_server_root/alias/kraTransportCert.p12 /var/lib/instance_ID/alias/ kraTransportCert.p12

3. Extract the public key of the CA signing certificate from the 7.x security databases and save the

base-64 encoded output to a file called caSigningCert.b64. a. Open the Certificate Management System 7.x /alias directory.

cd old_server_root/alias

b. Set the LD_LIBRARY_PATH environment variable to search the Certificate System libraries.

LD_LIBRARY_PATH=old_server_root/bin/cert/lib

export LD_LIBRARY_PATH

c. Use the Certificate Management System 7.x certutil tool to identify the old HSM slot name.

old_server_root/bin/cert/tools/certutil -U -d .

d. Use the Certificate Management System 7.x certutil tool to extract the public key from the

security databases and save the base-64 output to a file.

old_server_root/bin/cert/tools/certutil -L

-n "old_HSM_slot_name:caSigningCert cert-old_DRM_instance"

-d . -h old_HSM_token_name -a > caSigningCert.b64

e. Copy the key information from the 7.x server to the 8.0 server.

cp old_server_root/alias/caSigningCert.b64 /var/lib/instance_ID/alias/ caSigningCert.b64

4. Open the Certificate System /alias directory.

cd /var/lib/instance_ID/alias/

5. Log in as root.

6. Set the file user and group to the Certificate System user and group.

# chown user:group ServerCert.p12

# chown user:group kraStorageCert.p12

# chown user:group kraTransportCert.p12

# chown user:group caSigningCert.b64

7. Log out as root, and log back into the system as the Certificate System user.

Page 60

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

8. Set the file permissions.

chmod 00600 ServerCert.p12

chmod 00600 kraStorageCert.p12

chmod 00600 kraTransportCert.p12

chmod 00600 caSigningCert.b64

9. Import the public/private key pairs of each entry from the PKCS #12 files into the 8.0 security databases.

pk12util -i ServerCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i kraStorageCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i kraTransportCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

10. Optionally, delete the PKCS #12 files.

rm ServerCert.p12

rm kraStorageCert.p12

rm kraTransportCert.p12

11. Set the trust bits on the public/private key pairs that were imported into the 8.0 security databases.

certutil -M -n "Server-Cert cert-old_DRM_instance" -t "cu,cu,cu" -d .

certutil -M -n "kraStorageCert cert-old_DRM_instance" -t "u,u,u" -d .

certutil -M -n "kraTransportCert cert-old_DRM_instance" -t "u,u,u" -d .

12. Import the public key from the base-64 file, and set the trust bits.

certutil -A -n "caSigningCert cert-old_DRM_instance" -t "CT,c," -d . -i caSigningCert.b64

13. Optionally, delete the base-64 file.

rm caSigningCert.b64

14. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

15. Edit the kra.storageUnit.nickname and kra.transportUnit.nickname attributes to reflect the 8.0 DRM instance.

Page 61

Option 4: HSM to HSM Migration

kra.storageUnit.nickname=kraStorageCert cert-old_DRM_instance kra.transportUnit.nickname=kraTransportCert cert-old_DRM_instance

NOTE

The caSigningCert is not referenced in the CS.cfg file.

16. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

Server-Cert cert-old_DRM_instance

5.1.4. Option 4: HSM to HSM Migration

1. Extract the public/private key pairs from the HSM. The format for the extracted key pairs should be portable, such as a PKCS #12 file.

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

2. Copy the extracted key pairs from the 7.x server to the 8.0 server.

cp old_server_root/alias/ServerCert.p12 /var/lib/instance_ID/alias/ServerCert.p12

cp old_server_root/alias/kraStorageCert.p12 /var/lib/instance_ID/alias/kraStorageCert.p12

cp old_server_root/alias/kraTransportCert.p12 /var/lib/instance_ID/alias/ kraTransportCert.p12

3. Extract the public key of the CA signing certificate from the 7.x security databases and save the base-64 encoded output to a file called caSigningCert.b64. a. Open the Certificate Management System 7.x /alias directory.

Page 62

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

cd old_server_root/alias

b. Set the LD_LIBRARY_PATH environment variable to search the Certificate System libraries.

LD_LIBRARY_PATH=old_server_root/bin/cert/lib

export LD_LIBRARY_PATH

c. Use the Certificate Management System 7.x certutil tool to identify the old HSM slot name.

old_server_root/bin/cert/tools/certutil -U -d .

d. Use the Certificate Management System 7.x certutil tool to extract the public key from the

security databases and save the base-64 output to a file.

old_server_root/bin/cert/tools/certutil -L

-n "old_HSM_slot_name:caSigningCert cert-old_DRM_instance"

-d . -h old_HSM_token_name -a > caSigningCert.b64

e. Copy the key information from the 7.x server to the 8.0 server.

cp old_server_root/alias/caSigningCert.b64 /var/lib/instance_ID/alias/ caSigningCert.b64

4. Open the Certificate System /alias directory.

cd /var/lib/instance_ID/alias/

5. Log in as root.

6. Set the file user and group to the Certificate System user and group.

# chown user:group ServerCert.p12

# chown user:group kraStorageCert.p12

# chown user:group kraTransportCert.p12

# chown user:group caSigningCert.b64

7. Log out as root, and log back into the system as the Certificate System user.

8. Set the file permissions.

chmod 00600 ServerCert.p12

chmod 00600 kraStorageCert.p12

chmod 00600 kraTransportCert.p12

chmod 00600 caSigningCert.b64

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

Page 63

Option 4: HSM to HSM Migration

modutil -nocertdb -dbdir . -add new_HSM_token_name -libfile new_HSM_library_path/ new_HSM_library

10. Identify the new HSM slot name.

modutil -dbdir . -nocertdb -list

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

pk12util -i ServerCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i kraStorageCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i kraTransportCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

12. Optionally, delete the PKCS #12 files.

rm ServerCert.p12

rm kraStorageCert.p12

rm kraTransportCert.p12

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

certutil -M -n "new_HSM_slot_name:Server-Cert cert-old_DRM_instance" -t "cu,cu,cu" -d . h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:kraStorageCert cert-old_DRM_instance" -t "u,u,u" -d . h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:kraTransportCert cert-old_DRM_instance" -t "u,u,u" -d .

-h new_HSM_token_name

14. Import the public key from the base-64 file into the new HSM, and set the trust bits.

certutil -A -n "new_HSM_slot_name:caSigningCert cert-old_DRM_instance"

-t "CT,c," -d . -h new_HSM_token_name -i caSigningCert.b64

15. Optionally, delete the base-64 file.

rm caSigningCert.b64

16. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

Page 64

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

17. Edit the kra.storageUnit.nickname and kra.transportUnit.nickname attributes to

reflect the 8.0 DRM information.

kra.storageUnit.nickname=new_HSM_slot_name:kraStorageCert cert-old_DRM_instance kra.transportUnit.nickname=new_HSM_slot_name:kraTransportCert cert-old_DRM_instance

NOTE

The caSigningCert is not referenced in the CS.cfg file.

18. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

new_HSM_slot_name:Server-Cert cert-old_DRM_instance

5.2. Migrating Subsystem Password Stores

In Certificate System 7.2, passwords were kept in the password.conf file in the / etc/subsystem_name directory, the same file that is used in Certificate System 8.0. This file contains the passwords for both internal database and the password for the key3.db file. The 7.2 or

7.3 password.conf file just needs to be copied over to the 8.0 conf directory.

5.2.1. Migrating Passwords from 7.1

1. Log into the 7.x server as the Certificate System user for that machine, and open the config/

directory.

cd old_server_root/cert-old_instance/config/

2. Run the PasswordCache tool from the tools directory to retrieve the passwords from the

database.

old_server_root/bin/cert/tools/PasswordCache old_passwordcache_password d old_server_root/alias -P cert-old_instance-old_hostname- -c pwcache.db list

This lists the information stored in the password cache.

cert/key prefix = cert-old_instance-old_hostnamepath = old_server_root/alias about to read password cache

----- Password Cache Content ----internal : password Internal LDAP Database : passwordldap

3. Use the listed tags and passwords to create the password.conf file. For example:

Page 65

Migrating Passwords from 7.2 and 7.3

internal=password Internal LDAP Database=passwordldap

4. If the 7.x server instance used the password.conf file to start the server instance automatically, then this file must also be migrated to the 8.0 server instance.

cp old_server_root/cert-old_instance/config/password.conf /var/lib/new_DRM_instance/conf/ password.conf

5. Log into the 8.0 server as the Certificate System user, and open the Certificate System conf/ directory.

cd /var/lib/new_DRM_instance/conf/

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

chown user:group password.conf

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

chmod 00600 password.conf

8. Copy the tags and passwords that were listed from the 7.x pwdcache.db file into the password.conf file.

The password cache dump from the pwdcache.db file looks like the following:

internal : password Internal LDAP Database : password

The password.conf file has the following format:

internal=310062130979 internaldb=password

internaldb in 8.0 is the same as Internal LDAP Database in 7.x.

5.2.2. Migrating Passwords from 7.2 and 7.3

Versions 7.2, 7.3, and 8.0 all store passwords in a text file, password.conf, in the conf/ directory.

To migrate the passwords, simply copy the password.conf file to the 8.0 instance directory.

NOTE

Make sure that the permissions and ownership for the password.conf file are set properly so that it can be accessed by the migrated instance.

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

group.

Page 66

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

# chown user:group password.conf

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

chmod 00600 password.conf

5.3. Migrating the LDAP Database

Every Red Hat Certificate System 7.x subsystem contains LDIF data in an associated internal database which must be migrated to the corresponding Red Hat Certificate System 8.0 subsystem internal database. The procedure is the same for each subsystem type. The only difference between Certificate System 7.x versions is which import and export utility to use; these are version specific.

For example:

/usr/lib/dirsrv/slapd-example/db2ldif -U -n server.example.com-new_DRM_instance -a /var/ lib/dirsrv/slapd-example/ldif/new-new_DRM_instance.ldif

2. If they are not already installed, download and install the Certificate System migration utilities. For example:

yum install pki-migrate

3. If you are migrating to a different platform or machine, then copy the newest version of the migration utility from the Certificate System 8.0 server to the Certificate System 7.x server.

4. Open the Certificate System instance directory. The migration utilities are in the migrate directory.

cd /usr/share/pki

5. Package the latest version of the Certificate System migration utility using zip or tar.

tar -cvf migrate.tar migrate/

NOTE

Page 67

Migrating the LDAP Database

6. Copy the package from the 8.0 server to the 7.x server, and then remove the package from the 8.0

server. (You can use any copy tool, such as sftp, scp, and mv.)

cp /usr/share/pki/migrate.tar old_server_root/bin/cert

rm /usr/share/pki/migrate.tar

7. Log into the 7.x server as the Certificate System user for that machine, and open the Certificate System tools directory.

cd old_server_root/bin/cert

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

# chown user:group migrate.tar

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

chmod 00600 migrate.tar

10. Since the Certificate System 7.x migration utility will not be used, remove the Certificate System

7.x's upgrade/ directory. This ensures that only the newest migration scripts, in the copied migrate directory, are available.

rm -rf old_server_root/bin/cert/upgrade

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

tar -xvf migrate.tar

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

rm migrate.tar

13. Log into the 7.x Certificate System instance, and export the database contents to LDIF. Name the output file old-old_DRM_instance.ldif.

For example:

/opt/redhat-ds/slapd-DS-instance/db/db2ldif -U -n server.example.com-old_DRM_instance -a / opt/redhat-ds/slapd-DS-instance/ldif/old-old_DRM_instance.ldif

14. Convert the old-old_DRM_instance.ldif file to a text file. a. Open the version-to-text directory in the migration directory copied to the Certificate System

7.x server. Each 7.x major version has its own migration directory. For example, for migrating from version 7.3, then use 73ToTxt. For example:

cd old_server_root/bin/cert

b. Edit the run.sh script to set the proper server and JRE information.

Page 68

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

• For 7.1 migrations, uncomment and set the values for the following lines:

SERVER_ROOT=old_server_root export SERVER_ROOT INSTANCE=old_instance export INSTANCE

• For versions 7.2 and 7.3, make sure that the appropriate JRE root is given for the JRE version on the server. The default, for example, on Red Hat Enterprise Linux 4 is:

JRE_ROOT=/usr/lib/jvm/jre-1.5.0-ibm export JRE_ROOT

c. Run the run.sh to use the old-old_DRM_instance.ldif file to create a text file.

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

15. Open the Certificate System 7.x LDIF directory, and copy the old-old_DRM_instance.txt file

into the Certificate System 8.0 server instance's internal database LDIF directory.

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

cp /opt/redhat-ds/slapd-DS-instance/ldif/old-old_DRM_instance.txt /var/lib/dirsrv/slapdexample/ldif

16. Open the Certificate System ldif/ directory.

cd /var/lib/dirsrv/slapd-example/ldif

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

# chown user:group old-old_DRM_instance.txt

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

chmod 00600 old-old_DRM_instance.txt

19. Convert the old-old_DRM_instance.txt file to LDIF, and name the file rhcs80-new_DRM_instance.ldif.

a. Open the 8.0 text-conversion migration directory in the Certificate System 8.0 server.

cd /usr/share/pki/migrate/TxtTo80

b. Run run.sh to use old-old_DRM_instance.txt to create the

rhcs80-new_DRM_instance.ldif file.

run.sh /var/lib/dirsrv/slapd-example/ldif/old-old_DRM_instance.txt > /var/lib/dirsrv/ slapd-example/ldif/rhcs80-new_DRM_instance.ldif

Page 69

Migrating the LDAP Database

20. Modify the content of rhcs80-new_DRM_instance.ldif so that the LDIF files contain the

required ACLs and other settings that were created with the new 8.0 instances.

NOTE

a. Open the Certificate System 8.0 LDIF directory.

cd /var/lib/dirsrv/slapd-example/ldif

b. Open the new-new_DRM_instance.ldif file, in read-only mode.

view new-new_DRM_instance.ldif

c. Open the rhcs80-new_DRM_instance.ldif file.

vi rhcs80-new_DRM_instance.ldif

d. Delete the entries for o=hostname-db,o=netscapeCertificateServer and

o=netscapeCertificateServer.

e. Add a new entry for the base DN used in the 8.0 database (something like

dc=server.example.com-new_DRM_instance). For example:

dn: dc=server.example.com-new_DRM_instance objectClass: top objectClass: domain dc: server.example.com-new_DRM_instance

f. Change the base DN in every entry in the original file (o=hostname-

db,o=netscapeCertificateServer) to the one used for entries in the new-new_DRM_instance.ldif file (dc=server.example.com-new_DRM_instance).

There could be thousands of entries affected.

g. Replace cn=aclResources entry in the rhcs80-new_DRM_instance.ldif file with the

cn=aclResources entry from the new-new_DRM_instance.ldif file. For example:

dn: cn=aclResources,dc=server.example.com-new_DRM_instance resourceACLS: certServer.usrgrp.administration:read,modify:allow (read) group= "Administrators" || group="Auditors" || group="Certificate Manager Agents" | | group="Registration Manager Agents" || group="Data Recovery Manager Agents " || group="Online Certificate Status Manager Agents";allow (modify) group=" Administrators":Administrators, auditors, and agents are allowed to read user and group configuration but only administrators are allowed to modify ... list of ACLs ... objectClass: top objectClass: CertACLS cn: aclResources

Page 70

Chapter 5. Migrating a DRM Instance to Certificate System 8.0

h. If the subsystem instance is a cloned instance, add a group entry to maintain a list of users

who can create clones.

dn: cn=ClonedSubsystems,ou=groups,dc=server.example.com-new_CA_instance description: People who can clone the master subsystem objectClass: top objectClass: groupOfUniqueNames cn: ClonedSubsystems

21. Set the file permissions and ownership for the rhcs80-new_DRM_instance.ldif file.

chown nobody:nobody rhcs80-new_DRM_instance.ldif chmod 00644 rhcs80-new_DRM_instance.ldif

22. Import the rhcs80-new_DRM_instance.ldif LDIF file into the Certificate System 8.0 server instance's internal database using the Directory Server ldif2db tool.

The internal database name for the Certificate System instance is in the internaldb.database parameter in the CS.cfg file. For example:

/var/lib/dirsrv/slapd-example/db/ldif2db -n server.example.com-new_DRM_instance -i /var/ lib/dirsrv/slapd-example/ldif/rhcs80-new_DRM_instance.ldif

5.4. Migrating Custom CS.cfg and Other Data Settings

The DRM can have custom settings for subsystem settings, such as logging or access control. Apply any hand-edited changes to the new DRM's CS.cfg file in the /var/lib/new_DRM_instance/ conf directory.

Once the DRM is migrated, make sure that the configuration for any other subsystem instance which accesses the DRM is also updated. The DRM is always used by at least one CA and can optionally be accessed by the TKS and TPS. The newly-migrated DRM 8.0 information must be updated in the CA and TKS:

• Edit any CA's CS.cfg file to update the value in the ca.connector.KRA.transportCert

parameter with the newly-migrated DRM transport certificate. For example:

ca.connector.KRA.transportCert=MIIDdDCCAlygAwIBAgIBBzANBgkqhkiG9w0BAQUFADA6MRgwFgYDVQQKEw9qdWx5IGZvdXJ0ZWVudGgxHjAcBgNVBAMTFUNlcnRpZmljYXRlIEF1dGhvc....

• Verify that the DRM certificate cited in the TKS's tks.drm_transport_cert_nickname matches

the certificate in the TKS's and DRM's certificate databases.

tks.drm_transport_cert_nickname=DRM Transport Certificate - Example Domain

List the certificates in the TKS and DRM certificate databases to make sure that the same nickname exists in both databases with a trust setting of c,c,c.

certutil -L -d /var/lib/new_TKS_instance/alias

... DRM Transport Certificate - Example Domain c,c,c

Page 71

Restarting the DRM Instance

5.5. Restarting the DRM Instance

1. Restart the Directory Server and Administration Server for the Certificate System 8.0 instance.

service dirsrv start service dirsrv-admin start

2. Start the DRM instance.

service new_DRM_instance start

5.6. Setting Custom Configuration in the Console

5.7. Verifying the DRM Migration

After migrating the 8.0 DRM instance, open the DRM agent services pages for the 8.0 instance to ensure that everything is working properly. For example:

https://server.example.com:10443/kra/agent/kra

Then log into the DRM Console and verify that the new server can be managed through the Console.

pkiconsole https://server.example.com:10445/kra

The port numbers for the agent services interfaces can be found in the server.xml in the conf/ directory for the 8.0 DRM.

Page 72

Page 73

Chapter 6.

Migrating a OCSP Instance to Certificate System 8.0

Migrating a 7.x version of the OCSP Manager to the 8.0 requires migrating individual areas of data — the certificate and key databases for the subsystem, its internal LDAP database, its subsystem password stores — into the new subsystem and then reconfiguring the new subsystem.

Version-specific scripts are available to properly migrate and process data from the internal database so that it is formatted to work in the 8.0 database.

IMPORTANT

Every new Red Hat Certificate System 8.0 instance which will be installed on the host must be installed and fully configured, as described in Chapter 2, Setting up Certificate

System 8.0 Subsystems, before beginning a single subsystem migration.

6.1. Migrating the 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 Certificate System 7.1, 7.2, or 7.3 instances must be extracted and copied into the Red Hat Certificate System 8.0 subsystem's /alias directory.

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 6.1.1, “Option 1: Security Databases to Security Databases Migration”

• Section 6.1.2, “Option 2: Security Databases to HSM Migration”

• Section 6.1.3, “Option 3: HSM to Security Databases Migration”

• Section 6.1.4, “Option 4: HSM to HSM Migration”

6.1.1. Option 1: Security Databases to Security Databases Migration

1. Remove all the security databases in the Certificate System 8.0 server which will receive migrated data.

rm /var/lib/new_OCSP_instance/alias/cert8.db

rm /var/lib/new_OCSP_instance/alias/key3.db

2. Copy the certificate and key security databases from the 7.x server to the 8.0 server.

cp old_server_root/alias/cert-old_OCSP_instance-cert8.db /var/lib/new_OCSP_instance/alias/ cert8.db

cp old_server_root/alias/cert-old_OCSP_instance-key3.db /var/lib/new_OCSP_instance/alias/ key3.db

Page 74

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

3. Open the Certificate System /alias directory.

cd /var/lib/new_OCSP_instance/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. As the Certificate System user, set the file permissions.

chmod 00600 cert8.db

chmod 00600 key3.db

7. List the certificates in the security databases using the certutil command; -L lists the

certificates.

certutil -L -d .

Server-Cert cert-old_OCSP_instance cu,cu,cu caSigningCert cert-old_OCSP_instance CT,c, ocspSigningCert cert-old_OCSP_instance cu,cu,cu

8. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

9. Edit the ocsp.signing.certnickname attribute to reflect the 8.0 OCSP instance.

ocsp.signing.certnickname=ocspSigningCert cert-old_OCSP_instance

NOTE

The caSigningCert is not referenced in the CS.cfg file.

Page 75

Option 2: Security Databases to HSM Migration

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

Server-Cert cert-old_OCSP_instance

6.1.2. Option 2: Security Databases to HSM Migration

1. Remove all the security databases in the Certificate System 8.0 server which will receive migrated data.

rm /var/lib/new_OCSP_instance/alias/cert8.db

rm /var/lib/new_OCSP_instance/alias/key3.db

2. Copy the certificate and key security databases from the 7.x server to the 8.0 server.

cp old_server_root/alias/cert-old_OCSP_instance-cert8.db /var/lib/new_OCSP_instance/alias/ cert8.db

cp old_server_root/alias/cert-old_OCSP_instance-key3.db /var/lib/new_OCSP_instance/alias/ key3.db

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

3. Open the Certificate System /alias directory.

cd /var/lib/new_OCSP_instance/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. As the Certificate System user, set the file permissions.

chmod 00600 cert8.db

chmod 00600 key3.db

Page 76

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

7. List the certificates in the 7.x security databases using the certutil command; -L lists the

certificates.

certutil -L -d .

Server-Cert cert-old_OCSP_instance cu,cu,cu caSigningCert cert-old_OCSP_instance CT,c, ocspSigningCert cert-old_OCSP_instance cu,cu,cu

8. 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 sets the name of the certificate and the old database prefix.

pk12util -o ServerCert.p12 -n "Server-Cert cert-old_OCSP_instance" -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-old_OCSP_instance" -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** Re-enter password: ******** pk12util: PKCS12 EXPORT SUCCESSFUL

NOTE

The 7.x security databases may contain additional public/private key pairs; these can also be extracted using pk12util.

9. Export the public key using the certutil tool; -L lists the named certificate, -n sets the name of the file and the old prefix, and -a outputs the information to a base-64 file.

certutil -L -n "caSigningCert cert-old_OCSP_instance" -d . -a > caSigningCert.b64

NOTE

The 7.x security databases may contain additional public keys; these can also be exported using the certutil tool.

10. Delete the 7.x security databases.

rm cert8.db

rm key3.db

11. Register the new HSM in the 8.0 token database.

modutil -nocertdb -dbdir . -add new_HSM_token_name -libfile new_HSM_library_path/ new_HSM_library

12. Identify the new HSM slot name.

Page 77

Option 2: Security Databases to HSM Migration

modutil -dbdir . -nocertdb -list

13. Create new security databases.

certutil -N -d .

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

pk12util -i ServerCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i ocspSigningCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

15. Optionally, delete the PKCS #12 files.

rm ServerCert.p12

rm ocspSigningCert.p12

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

certutil -M -n "new_HSM_slot_name:Server-Cert cert-old_OCSP_instance" -t "cu,cu,cu" -d . h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:ocspSigningCert cert-old_OCSP_instance" -t "cu,cu,cu" d . -h new_HSM_token_name

17. Import the public key from the base-64 file into the new HSM, and set the trust bits.

certutil -A -n "new_HSM_slot_name:caSigningCert cert-old_OCSP_instance"

-t "CT,c," -d . -h new_HSM_token_name -i caSigningCert.b64

18. Optionally, delete the base-64 file.

rm caSigningCert.b64

19. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

20. Edit the ocsp.signing.certnickname attribute to reflect the 8.0 OCSP instance.

ocsp.signing.certnickname=new_HSM_slot_name:ocspSigningCert cert-old_OCSP_instance

Page 78

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

NOTE

The caSigningCert is not referenced in the CS.cfg file.

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

new_HSM_slot_name:Server-Cert cert-old_OCSP_instance

6.1.3. Option 3: HSM to Security Databases Migration

1. Extract the public/private key pairs from the HSM. The format for the extracted key pairs should be portable, such as a PKCS #12 file.

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

2. Copy the extracted key pairs from the 7.x server to the 8.0 server.

cp old_server_root/alias/ServerCert.p12 /var/lib/new_OCSP_instance/alias/ServerCert.p12

cp old_server_root/alias/ocspSigningCert.p12 /var/lib/new_OCSP_instance/alias/ ocspSigningCert.p12

cd old_server_root/alias

b. Set the LD_LIBRARY_PATH environment variable to search the Certificate System libraries.

LD_LIBRARY_PATH=old_server_root/bin/cert/lib

Page 79

Option 3: HSM to Security Databases Migration

export LD_LIBRARY_PATH

c. Use the Certificate Management System 7.x certutil tool to identify the old HSM slot name.

old_server_root/bin/cert/tools/certutil -U -d .

d. Use the Certificate Management System 7.x certutil tool to extract the public key from the

security databases and save the base-64 output to a file.

old_server_root/bin/cert/tools/certutil -L -n "old_HSM_slot_name:caSigningCert cert-old_OCSP_instance" -d . -h old_HSM_token_name -a > caSigningCert.b64

e. Copy the key information from the 7.x server to the 8.0 server.

cp old_server_root/alias/caSigningCert.b64 /var/lib/new_OCSP_instance/alias/ caSigningCert.b64

4. Open the Certificate System /alias directory.

cd /var/lib/new_OCSP_instance/alias/

5. Log in as root.

6. Set the file user and group to the Certificate System user and group.

# chown user:group ServerCert.p12

# chown user:group ocspSigningCert.p12

# chown user:group caSigningCert.b64

7. Log out as root. As the Certificate System user, set the file permissions.

chmod 00600 ServerCert.p12

chmod 00600 ocspSigningCert.p12

chmod 00600 caSigningCert.b64

8. Import the public/private key pairs of each entry from the PKCS #12 files into the 8.0 security databases.

pk12util -i ServerCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i ocspSigningCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

9. Optionally, delete the PKCS #12 files.

Page 80

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

rm ServerCert.p12

rm ocspSigningCert.p12

10. Set the trust bits on the public/private key pairs that were imported into the 8.0 security databases.

certutil -M -n "Server-Cert cert-old_OCSP_instance" -t "cu,cu,cu" -d .

certutil -M -n "ocspSigningCert cert-old_OCSP_instance" -t "cu,cu,cu" -d .

11. Import the public key from the base-64 file, and set the trust bits.

certutil -A -n "caSigningCert cert-old_OCSP_instance" -t "CT,c," -d . -i caSigningCert.b64

12. Optionally, delete the base-64 file.

rm caSigningCert.b64

13. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

14. Edit the ocsp.signing.certnickname attribute to reflect the 8.0 OCSP instance.

ocsp.signing.certnickname=ocspSigningCert cert-old_OCSP_instance

NOTE

The caSigningCert is not referenced in the CS.cfg file.

15. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

Server-Cert cert-old_OCSP_instance

6.1.4. Option 4: HSM to HSM Migration

1. Extract the public/private key pairs from the HSM. The format for the extracted key pairs should be portable, such as a PKCS #12 file.

WARNING

Page 81

Option 4: HSM to HSM Migration

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

2. Copy the extracted key pairs from the 7.x server to the 8.0 server.

cp old_server_root/alias/ServerCert.p12 /var/lib/new_OCSP_instance/alias/ServerCert.p12

cp old_server_root/alias/ocspSigningCert.p12 /var/lib/new_OCSP_instance/alias/ ocspSigningCert.p12

3. Extract the public key of the CA signing certificate from the 7.x security databases and save the

base-64 encoded output to a file called caSigningCert.b64. a. Open the Certificate Management System 7.x /alias directory.

cd old_server_root/alias

b. Set the LD_LIBRARY_PATH environment variable to search the Certificate System libraries.

LD_LIBRARY_PATH=old_server_root/bin/cert/lib

export LD_LIBRARY_PATH

c. Use the Certificate Management System 7.x certutil tool to identify the old HSM slot name.

old_server_root/bin/cert/tools/certutil -U -d .

d. Use the Certificate Management System 7.x certutil tool to extract the public key from the

security databases and save the base-64 output to a file.

old_server_root/bin/cert/tools/certutil -L -n "old_HSM_slot_name:caSigningCert cert-old_OCSP_instance" -d . -h old_HSM_token_name -a > caSigningCert.b64

e. Copy the key information from the 7.x server to the 8.0 server.

cp old_server_root/alias/caSigningCert.b64 /var/lib/new_OCSP_instance/alias/ caSigningCert.b64

4. Open the Certificate System /alias directory.

cd /var/lib/new_OCSP_instance/alias/

5. Log in as root.

Page 82

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

6. Set the file user and group to the Certificate System user and group.

# chown user:group ServerCert.p12

# chown user:group ocspSigningCert.p12

# chown user:group caSigningCert.b64

7. Log out as root. As the Certificate System user, set the file permissions.

chmod 00600 ServerCert.p12

chmod 00600 ocspSigningCert.p12

chmod 00600 caSigningCert.b64

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

modutil -nocertdb -dbdir . -add new_HSM_token_name -libfile new_HSM_library_path/ new_HSM_library

9. Identify the new HSM slot name.

modutil -dbdir . -nocertdb -list

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

pk12util -i ServerCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

pk12util -i ocspSigningCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

11. Optionally, delete the PKCS #12 files.

rm ServerCert.p12

rm ocspSigningCert.p12

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

certutil -M -n "new_HSM_slot_name:Server-Cert cert-old_OCSP_instance -t "cu,cu,cu" -d . h new_HSM_token_name

certutil -M -n "new_HSM_slot_name:ocspSigningCert cert-old_OCSP_instance" -t "cu,cu,cu" d . -h new_HSM_token_name

13. Import the public key from the base-64 file into the new HSM, and set the trust bits.

certutil -A -n "new_HSM_slot_name:caSigningCert cert-old_OCSP_instance"

-t "CT,c," -d . -h new_HSM_token_name -i caSigningCert.b64

Page 83

Migrating Subsystem Password Stores

14. Optionally, delete the base-64 file.

rm caSigningCert.b64

15. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/ directory.

16. Edit the ocsp.signing.certnickname attribute to reflect the 8.0 subsystem information.

ocsp.signing.certnickname=new_HSM_slot_name:ocspSigningCert cert-old_OCSP_instance

NOTE

The caSigningCert is not referenced in the CS.cfg file.

17. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

new_HSM_slot_name:Server-Cert cert-old_OCSP_instance

6.2. Migrating Subsystem Password Stores

7.3 password.conf file just needs to be copied over to the 8.0 conf directory.

6.2.1. Migrating Passwords from 7.1

1. Log into the 7.x server as the Certificate System user for that machine, and open the config/

directory.

cd old_server_root/cert-old_instance/config/

2. Run the PasswordCache tool from the tools directory to retrieve the passwords from the

database.

old_server_root/bin/cert/tools/PasswordCache old_passwordcache_password d old_server_root/alias -P cert-old_instance-old_hostname- -c pwcache.db list

This lists the information stored in the password cache.

cert/key prefix = cert-old_instance-old_hostnamepath = old_server_root/alias about to read password cache

----- Password Cache Content -----

Page 84

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

internal : password Internal LDAP Database : passwordldap

3. Use the listed tags and passwords to create the password.conf file. For example:

internal=password Internal LDAP Database=passwordldap

4. If the 7.x server instance used the password.conf file to start the server instance automatically, then this file must also be migrated to the 8.0 server instance.

cp old_server_root/cert-old_instance/config/password.conf /var/lib/new_OCSP_instance/conf/ password.conf

5. Log into the 8.0 server as the Certificate System user, and open the Certificate System conf/ directory.

cd /var/lib/new_OCSP_instance/conf/

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

chown user:group password.conf

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

chmod 00600 password.conf

8. Copy the tags and passwords that were listed from the 7.x pwdcache.db file into the password.conf file.

The password cache dump from the pwdcache.db file looks like the following:

internal : password Internal LDAP Database : password

The password.conf file has the following format:

internal=310062130979 internaldb=password

internaldb in 8.0 is the same as Internal LDAP Database in 7.x.

6.2.2. Migrating Passwords from 7.2 and 7.3

Versions 7.2, 7.3, and 8.0 all store passwords in a text file, password.conf, in the conf/ directory.

To migrate the passwords, simply copy the password.conf file to the 8.0 instance directory.

NOTE

Make sure that the permissions and ownership for the password.conf file are set properly so that it can be accessed by the migrated instance.

Page 85

Migrating the LDAP Database

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

group.

# chown user:group password.conf

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

chmod 00600 password.conf

6.3. Migrating the LDAP Database

For example:

/usr/lib/dirsrv/slapd-example/db2ldif -U -n server.example.com-new_OCSP_instance -a /var/ lib/dirsrv/slapd-example/ldif/new-new_OCSP_instance.ldif

2. If they are not already installed, download and install the Certificate System migration utilities. For example:

yum install pki-migrate

3. If you are migrating to a different platform or machine, then copy the newest version of the migration utility from the Certificate System 8.0 server to the Certificate System 7.x server.

4. Open the Certificate System instance directory. The migration utilities are in the migrate directory.

cd /usr/share/pki

5. Package the latest version of the Certificate System 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 7.x server machine. If the platforms are identical and the zip utility is used, copy

Page 86

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

the zip tool from the 8.0 server to the 7.x server so that the zip and unzip versions match.

6. Copy the package from the 8.0 server to the 7.x server, and then remove the package from the 8.0

server. (You can use any copy tool, such as sftp, scp, and mv.)

cp /usr/share/pki/migrate.tar old_server_root/bin/cert

rm /usr/share/pki/migrate.tar

7. Log into the 7.x server as the Certificate System user for that machine, and open the Certificate System tools directory.

cd old_server_root/bin/cert

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

# chown user:group migrate.tar

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

chmod 00600 migrate.tar

10. Since the Certificate System 7.x migration utility will not be used, remove the Certificate System

7.x's upgrade/ directory. This ensures that only the newest migration scripts, in the copied migrate directory, are available.

rm -rf old_server_root/bin/cert/upgrade

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

tar -xvf migrate.tar

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

rm migrate.tar

13. Log into the 7.x Certificate System instance, and export the database contents to LDIF. Name the output file old-old_OCSP_instance.ldif.

For example:

/opt/redhat-ds/slapd-DS-instance/db/db2ldif -U -n server.example.com-old_OCSP_instance a /opt/redhat-ds/slapd-DS-instance/ldif/old-old_OCSP_instance.ldif

14. Convert the old-old_OCSP_instance.ldif file to a text file. a. Open the version-to-text directory in the migration directory copied to the Certificate System

7.x server. Each 7.x major version has its own migration directory. For example, for migrating from version 7.3, then use 73ToTxt. For example:

Page 87

Migrating the LDAP Database

cd old_server_root/bin/cert

b. Edit the run.sh script to set the proper server and JRE information.

• For 7.1 migrations, uncomment and set the values for the following lines:

SERVER_ROOT=old_server_root export SERVER_ROOT INSTANCE=old_instance export INSTANCE

• For versions 7.2 and 7.3, make sure that the appropriate JRE root is given for the JRE version on the server. The default, for example, on Red Hat Enterprise Linux 4 is:

JRE_ROOT=/usr/lib/jvm/jre-1.5.0-ibm export JRE_ROOT

c. Run the run.sh to use the old-old_OCSP_instance.ldif file to create a text file.

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

15. Open the Certificate System 7.x LDIF directory, and copy the old-old_OCSP_instance.txt

file into the Certificate System 8.0 server instance's internal database LDIF directory.

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

cp /opt/redhat-ds/slapd-DS-instance/ldif/old-old_OCSP_instance.txt /var/lib/dirsrv/slapdexample/ldif

16. Open the Certificate System ldif/ directory.

cd /var/lib/dirsrv/slapd-example/ldif

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

# chown user:group old-old_OCSP_instance.txt

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

chmod 00600 old-old_OCSP_instance.txt

19. Convert the old-old_OCSP_instance.txt file to LDIF, and name the file rhcs80-new_OCSP_instance.ldif.

a. Open the 8.0 text-conversion migration directory in the Certificate System 8.0 server.

cd /usr/share/pki/migrate/TxtTo80

b. Run run.sh to use old-old_OCSP_instance.txt to create the

rhcs80-new_OCSP_instance.ldif file.

Page 88

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

run.sh /var/lib/dirsrv/slapd-example/ldif/old-old_OCSP_instance.txt > /var/lib/dirsrv/ slapd-example/ldif/rhcs80-new_OCSP_instance.ldif

20. Modify the content of rhcs80-new_OCSP_instance.ldif so that the LDIF files contain the

required ACLs and other settings that were created with the new 8.0 instances.

NOTE

a. Open the Certificate System 8.0 LDIF directory.

cd /var/lib/dirsrv/slapd-example/ldif

b. Open the new-new_OCSP_instance.ldif file, in read-only mode.

view new-new_OCSP_instance.ldif

c. Open the rhcs80-new_OCSP_instance.ldif file.

vi rhcs80-new_OCSP_instance.ldif

d. Delete the entries for o=hostname-db,o=netscapeCertificateServer and

o=netscapeCertificateServer.

e. Add a new entry for the base DN used in the 8.0 database (something like

dc=server.example.com-new_OCSP_instance). For example:

dn: dc=server.example.com-new_OCSP_instance objectClass: top objectClass: domain dc: server.example.com-new_OCSP_instance

f. Change the base DN in every entry in the original file (o=hostname-

db,o=netscapeCertificateServer) to the one used

for entries in the new-new_OCSP_instance.ldif file (dc=server.example.com-new_OCSP_instance). There could be thousands of entries affected.

g. Replace cn=aclResources entry in the rhcs80-new_OCSP_instance.ldif file with the

cn=aclResources entry from the new-new_OCSP_instance.ldif file. For example:

dn: cn=aclResources,dc=server.example.com-new_OCSP_instance resourceACLS: certServer.usrgrp.administration:read,modify:allow (read) group= "Administrators" || group="Auditors" || group="Certificate Manager Agents" | | group="Registration Manager Agents" || group="Data Recovery Manager Agents " || group="Online Certificate Status Manager Agents";allow (modify) group=" Administrators":Administrators, auditors, and agents are allowed to read user and group configuration but only administrators are allowed to modify

Page 89

Migrating Custom Data and Settings

... list of ACLs ... objectClass: top objectClass: CertACLS cn: aclResources

h. If the subsystem instance is a cloned instance, add a group entry to maintain a list of users

who can create clones.

dn: cn=ClonedSubsystems,ou=groups,dc=server.example.com-new_CA_instance description: People who can clone the master subsystem objectClass: top objectClass: groupOfUniqueNames cn: ClonedSubsystems

21. Set the file permissions and ownership for the rhcs80-new_OCSP_instance.ldif file.

chown nobody:nobody rhcs80-new_OCSP_instance.ldif chmod 00644 rhcs80-new_OCSP_instance.ldif

22. Import the rhcs80-new_OCSP_instance.ldif LDIF file into the Certificate System 8.0 server instance's internal database using the Directory Server ldif2db tool.

The internal database name for the Certificate System instance is in the internaldb.database parameter in the CS.cfg file. For example:

/var/lib/dirsrv/slapd-example/db/ldif2db -n server.example.com-new_OCSP_instance -i /var/ lib/dirsrv/slapd-example/ldif/rhcs80-new_OCSP_instance.ldif

6.4. Migrating Custom Data and Settings

Copy all customized plug-ins, profiles, and forms to the Certificate System 8.0 server, and apply any hand-edited changes to the OCSP's CS.cfg file in the /var/lib/new_OCSP_instance/conf.

6.5. Restarting the OCSP Instance

1. Restart the Directory Server and Administration Server for the Certificate System 8.0 instance.

service dirsrv start service dirsrv-admin start

2. Start the OCSP Manager instances.

service new_OCSP_instance start

6.6. Setting Custom Configuration in the Console

Page 90

Chapter 6. Migrating a OCSP Instance to Certificate System 8.0

6.7. Verifying the OCSP Migration

After migrating the 7.x OCSP instance, open the OCSP agent services pages for the 8.0 instance to ensure that everything is working properly. For example:

https://server.example.com:11443/ocsp/agent/ocsp

Then log into the Certificate System Console and verify that the new server can be managed through the Console.

pkiconsole https://server.example.com:11445/ocsp

The port numbers for the agent services interfaces can be found in the server.xml in the conf/ directory for the 8.0 OCSP.

Page 91

Chapter 7.

Migrating a TKS Instance to Certificate System 8.0

Migrating a 7.x version of the TKS to the 8.0 requires migrating individual areas of data — the certificate and key databases for the subsystem, its internal LDAP database, its subsystem password stores — into the new subsystem and then reconfiguring the new subsystem.

Version-specific scripts are available to properly migrate and process data from the internal database so that it is formatted to work in the 8.0 database.

IMPORTANT

Every new Red Hat Certificate System 8.0 instance which will be installed on the host must be installed and fully configured, as described in Chapter 2, Setting up Certificate

System 8.0 Subsystems, before beginning a single subsystem migration.

7.1. Migrating the Security Databases

Determine if the migration to be performed involves software security databases, an HSM, or both; follow the appropriate process for the deployment scenario being migrated.

• Section 7.1.1, “Option 1: Security Databases to Security Databases Migration”

• Section 7.1.2, “Option 2: Security Databases to HSM Migration”

• Section 7.1.3, “Option 3: HSM to Security Databases Migration”

• Section 7.1.4, “Option 4: HSM to HSM Migration”

7.1.1. Option 1: Security Databases to Security Databases Migration

1. Remove all the security databases in the new Certificate System which will receive migrated data.

rm /var/lib/new_TKS_instance/alias/cert8.db

rm /var/lib/new_TKS_instance/alias/key3.db

2. Log into the 7.x server as the Certificate System user for that machine.

3. Migrate the master key from the 7.x TKS instance. (Depending on your installation, there may not be any master key information stored in the 7.x TKS instance.)

a. Open the 7.x configuration file.

• If the migration is from Certificate System 7.1, open the CS.cfg file in the Certificate System config/ directory.

• If the migration is from Certificate System 7.2 or 7.3, open the CS.cfg file in the Certificate System /etc/subsystem_name directory.

b. Write down the exact value for the tks.mk_mappings. line.

Page 92

Chapter 7. Migrating a TKS Instance to Certificate System 8.0

tks.mk_mappings.#tks_master_key_version_number#01=internal:tks_master_key_version_name

A tks.mk_mappings value looks like the following:

tks.mk_mappings.#02#01=internal:tks_master_key_v2

In this example, 02 is the tks_master_key_version_ number, and tks_master_key_v2 is the tks_master_key_version_name.

4. Copy the certificate and key security databases from the 7.x server to the 8.0 server.

cp old_server_root/alias/cert-old_instance-cert8.db /var/lib/new_TKS_instance/alias/ cert8.db

cp old_server_root/alias/cert-old_instance-key3.db /var/lib/new_TKS_instance/alias/key3.db

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

5. Open the Certificate System alias/ directory.

cd /var/lib/new_TKS_instance/alias/

6. Log in as root.

7. Set the file user and group to the Certificate System user and group.

# chown user:group cert8.db

# chown user:group key3.db

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

chmod 00600 cert8.db

chmod 00600 key3.db

9. List the certificates in the security databases using the certutil command. In this example, -L

lists the certificates.

certutil -L -d .

Page 93

Option 2: Security Databases to HSM Migration

Server-Cert cert-old_TKS_instance cu,cu,cu caSigningCert cert-old_TKS_instance CT,c, tksTransportCert cert-old_TKS_instance CT,C,

10. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/.

11. If server-side keygen has been enabled, edit the tks.drm_transport_cert_nickname

attribute to reflect the new TKS instance.

tks.drm_transport_cert_nickname=tksTransportCert cert-old_TKS_instance

12. If a master key was migrated from an 7.x TKS instance,

edit the Certificate System 8.0 CS.cfg, and insert the "tks.mk_mappings.#tks_master_key_version_number#01=internal:tks_master_key_version_name" value from the Certificate System 7.x CS.cfg file. Be sure to use the proper tks_master_key_version_number and tks_master_key_version_name values.

NOTE

The caSigningCert is not referenced in the CS.cfg file.

13. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

Server-Cert cert-old_TKS_instance

7.1.2. Option 2: Security Databases to HSM Migration

1. Remove all the security databases in the new Certificate System which will receive migrated data.

rm /var/lib/new_TKS_instance/alias/cert8.db

rm /var/lib/new_TKS_instance/alias/key3.db

2. Log into the 7.x server as the Certificate System user for that machine.

3. Migrate the master key from the 7.x TKS instance. (Depending on your installation, there may not be any master key information stored in the 7.x TKS instance.)

a. Open the configuration file for the 7.x server instance being migrated.

• If the migration is from Certificate System 7.1, open the CS.cfg file in the Certificate System config directory.

• If the migration is from Certificate System 7.2 or 7.3, open the CS.cfg file in the Certificate System /etc/subsystem_name directory.

b. Write down the exact value for the tks.mk_mappings. line.

tks.mk_mappings.#tks_master_key_version_number#01=internal:tks_master_key_version_name

Page 94

Chapter 7. Migrating a TKS Instance to Certificate System 8.0

A tks.mk_mappings value looks like the following example:

tks.mk_mappings.#02#01=internal:tks_master_key_v2

In this example, 02 is the tks_master_key_version_ number, and tks_master_key_v2 is the tks_master_key_version_name.

4. Migrate symmetric keys from a 7.x TKS instance. Two things are necessary:

• A written copy of the original three session key shares to reproduce the symmetric transport key on the 7.x TKS instance.

• Copies of all files (there is at least one) containing the wrapped master keys for the 7.x security database; for example, tks_master_key_v2.txt.

NOTE

These files are created whenever the user generates a new master key using the tkstool -W option.

5. Copy the certificate and key security databases from the 7.x server to the 8.0 server.

cp old_server_root/alias/cert-old_instance-cert8.db /var/lib/new_TKS_instance/alias/ cert8.db

cp old_server_root/alias/cert-old_instance-key3.db /var/lib/new_TKS_instance/alias/key3.db

6. Log into the new server as the Certificate System user, and open the Certificate System alias/

directory.

cd /var/lib/new_TKS_instance/alias/

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

7. Log in as root.

8. Set the file user and group to the Certificate System user and group.

# chown user:group cert8.db

Page 95

Option 2: Security Databases to HSM Migration

# chown user:group key3.db

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

chmod 00600 cert8.db

chmod 00600 key3.db

10. List the certificates stored in the 7.x security databases by using the certutil command. In this example, -L lists the certificates.

certutil -L -d .

Server-Cert cert-old_TKS_instance cu,cu,cu caSigningCert cert-old_TKS_instance CT,c, tksTransportCert cert-old_TKS_instance CT,C,C

11. 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 sets the name of the certificate and the old database prefix.

pk12util -o ServerCert.p12 -n "Server-Cert cert-old_TKS_instance" -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** Re-enter password: ******** pk12util: PKCS12 EXPORT SUCCESSFUL

12. Export the public key using the certutil tool; -L lists the named certificate, -n sets the name of the file and the old prefix, and -a outputs the information to a base-64 file.

certutil -L -n "caSigningCert cert-old_TKS_instance" -d . -a > caSigningCert.b64

certutil -L -n "tksTransportCert cert-old_TKS_instance" -d . -a > tksTransportCert.b64

13. Delete the 7.x security databases.

rm cert8.db

rm key3.db

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

modutil -nocertdb -dbdir . -add new_HSM_token_name -libfile new_HSM_library_path/new_HSM_library

15. Identify the new HSM slot name.

modutil -dbdir . -nocertdb -list

16. Create new security databases.

certutil -N -d .

Page 96

Chapter 7. Migrating a TKS Instance to Certificate System 8.0

17. Import the public/private key pair from the PKCS #12 file into the new HSM.

pk12util -i ServerCert.p12 -d . -h new_HSM_slot_name Enter Password or Pin for "new_HSM_slot_name":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

18. Optionally, delete the PKCS #12 file:

rm ServerCert.p12

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

certutil -M -n "new_HSM_slot_name:Server-Cert cert-old_TKS_instance" -t "cu,cu,cu" -d . -h <new_HSM_token_name

20. Import the public keys from the base-64 files into the new HSM, and set the trust bits.

certutil -A -n "new_HSM_slot_name:caSigningCert cert-old_TKS_instance" t "CT,c," -d . h new_HSM_token_name -i caSigningCert.b64

certutil -A -n "new_HSM_slot_name:tksTransportCert cert-old_TKS_instance" -t "CT,C,C" -d .

-h new_HSM_token_name -i tksTransportCert.b64

21. Optionally, delete the base-64 files.

rm caSigningCert.b64

rm tksTransportCert.b64

22. Import the original symmetric transport key into the new HSM.

tkstool -I -d . new_HSM_token_name -n tks_transport_key_name

23. Type in the original three key session key shares (as prompted) to recreate the original transport key on the new HSM.

24. Log in as root.

25. Set the file user and group to the Certificate System user and group for each wrapped_tks_master_key_file file.

26. Unwrap and store all the original master keys in the new HSM.

tkstool -U -d . -h new_HSM_token_name -t tks_transport_key_name n tks_master_key_version_name -i wrapped_tks_master_key_file

Do this for every file containing a wrapped TKS master key.

27. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/.

28. If server-side keygen has been enabled, edit the tks.drm_transport_cert_nickname to reflect the new TKS information.

Page 97

Option 3: HSM to Security Databases Migration

tks.drm_transport_cert_nickname=new_HSM_slot_name:tksTransportCert Cert cert-old_TKS_instance

29. If a master key was migrated from the 7.x TKS instance, then also insert

the tks.mk_mappings.# tks_master_key_version_number #01=< new_HSM_slot_name:tks_master_key_version_name line at the end of the CS.cfg. Be certain that the proper values for tks_master_key_version_number, new_HSM_slot_name, and tks_master_key_version_name are set.

NOTE

The caSigningCert is not referenced in the CS.cfg file.

30. In the same directory, edit the serverCertNick.conf file to contain the old certificate

nickname. For example:

new_HSM_slot_name:Server-Cert cert-old_TKS_instance

7.1.3. Option 3: HSM to Security Databases Migration

1. Extract the public/private key pairs from the HSM. The format for the extracted key pairs should be portable, such as a PKCS #12 file.

WARNING

The instance and domain information has to be the same for both instances because the certificate and key material — among other instance and database information — has to be the same.

2. Log into the 7.x server as the Certificate System user for that machine.

3. Migrate the master key from the 7.x TKS instance. (Depending on your installation, there may not be any master key information stored in the 7.x TKS instance.)

a. Open the Certificate System 7.x configuration file.

• If the migration is from Certificate System 7.1, open the CS.cfg file in the Certificate System config directory.

Page 98

Chapter 7. Migrating a TKS Instance to Certificate System 8.0

• If the migration is from Certificate System 7.2 or 7.3, open the CS.cfg file in the Certificate System /etc/subsystem_name directory.

b. Write down the exact name-value pair for the tks.mk_mappings.#

tks_master_key_version_number #01= old_HSM_slot_name:tks_master_key_version_name line. A tks.mk_mappings value looks like the following:

tks.mk_mappings.#02#01=mu:tks_master_key_v2

In this example, 02 is the tks_master_key_version_ number, mu is the old_HSM_slot_name, and tks_master_key_v2 is the tks_master_key_version_name.

4. Migrate symmetric keys from the 7.x TKS instance. Two things are required:

• A written copy of the original three session key shares to reproduce the symmetric transport key on the 7.x TKS instance.

• Copies of all files (there is at least one) containing the wrapped master keys on the old HSM; for example, tks_master_key_v2.txt.

NOTE

These files are created whenever the user generates a new master key using the tkstool -W option.

5. Copy the extracted public/private key pairs from the 7.x server to the 8.0 server.

cp old_server_root/alias/ServerCert.p12 /var/lib/new_TKS_instance/alias/ServerCert.p12

6. Extract the public key of the "old_HSM_slot_name:caSigningCert cert-old_TKS_instance" and "old_HSM_slot_name:tksTransportCert" cert-old_TKS_instance" from the 7.x security databases and save the base-64 encoded output to files called caSigningCert.b64 and tksTransportCert.b64, respectively. a. Open the Certificate System 7.x alias/ directory. cd old_server_root/alias

b. Set the LD_LIBRARY_PATH environment variable to search the Certificate System libraries.

LD_LIBRARY_PATH=old_server_root/bin/cert/lib

export LD_LIBRARY_PATH

c. Use the Certificate System 7.x certutil tool to identify the old HSM slot name.

old_server_root/bin/cert/tools/certutil -U -d .

d. Use the Certificate System 7.x certutil tool to extract the public key of the following entries

from the security databases and save each base-64 output to a separate file.

old_server_root/bin/cert/tools/certutil -L

-n "old_HSM_slot_name:caSigningCert cert-old_TKS_instance"

Page 99

Option 3: HSM to Security Databases Migration

-d . -h old_HSM_token_name -a > caSigningCert.b64

old_server_root/bin/cert/tools/certutil -L

-n "old_HSM_slot_name:tksTransportCert cert-old_TKS_instance"

-d . -h old_HSM_token_name -a > tksTransportCert.b64

e. Copy the key data from the 7.x server to the 8.0 server.

cp old_server_root/alias/caSigningCert.b64 /var/lib/new_TKS_instance/alias/ caSigningCert.b64

cp old_server_root/alias/tksTransportCert.b64 /var/lib/new_TKS_instance/alias/ tksTransportCert.b64

7. Log into the new server as the Certificate System user, and open the Certificate System alias/

directory.

cd /var/lib/new_TKS_instance/alias/

8. Log in as root.

9. Set the file user and group to the Certificate System user and group.

# chown user:group ServerCert.p12

# chown user:group caSigningCert.b64

# chown user:group tksTransportCert.b64

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

chmod 00600 ServerCert.p12

chmod 00600 caSigningCert.b64

chmod 00600 tksTransportCert.b64

11. Import the public/private key pair from the PKCS #12 file into the new security databases.

pk12util -i ServerCert.p12 -d . Enter Password or Pin for "NSS Certificate DB":******** Enter password for PKCS12 file: ******** pk12util: PKCS12 IMPORT SUCCESSFUL

12. Optionally, delete the PKCS #12 file:

rm ServerCert.p12

13. Set the trust bits on the public/private key pairs that were imported into the new security databases.

certutil -M -n "Server-Cert cert-old_TKS_instance" -t "cu,cu,cu" -d .

14. Import the public keys from the base-64 files, and set the trust bits.

Page 100

Chapter 7. Migrating a TKS Instance to Certificate System 8.0

certutil -A -n "caSigningCert cert-old_TKS_instance"

-t "CT,c," -d . -i caSigningCert.b64

certutil -A -n "tksTransportCert cert-old_TKS_instance"

-t "CT,C,C" -d . -i tksTransportCert.b64

15. Optionally, delete the base-64 files.

rm caSigningCert.b64

rm tksTransportCert.b64

16. Import the original symmetric transport key into the new security databases.

tkstool -I -d . -n tks_transport_key_name

17. Type in the original three key session keyshares (as prompted) to recreate the original transport key in the new security databases.

18. Log in as root.

19. Set the file user and group to the Certificate System user and group for each wrapped_tks_master_key_file file.

20. Unwrap and store all the original master keys into the new security databases.

tkstool -U -d . -t tks_transport_key_name -n tks_master_key_version_name i wrapped_tks_master_key_file

Perform this step for each and every file containing a wrapped TKS master key.

21. Open the CS.cfg configuration file in the /var/lib/instance_ID/conf/.

22. If server-side keygen has been enabled, edit the tks.drm_transport_cert_nickname to reflect new TKS information.

tks.drm_transport_cert_nickname=tksTransportCert cert-old_TKS_instance

23. If a master key has been migrated from the 7.x TKS instance, insert the "tks.mk_mappings.# tks_master_key_version_number #01=internal: tks_master_key_version_name" line at the end of the CS.cfg. Be certain to use the proper values for tks_master_key_version_number, and tks_master_key_version_name.

NOTE

The caSigningCert is not referenced in the CS.cfg file.

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

Red Hat SYSTEM 8.0, Certificate System 8.0 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual