Netscape Certificate Management System Installation and Deployment Guide:

Complete Contents
About This Guide
PART 1: Overview and Demo Installation
Chapter 1 Introduction to Certificate Management System 4.0
Chapter 2 Default Demo Installation
PART 2: Planning and Installation
Chapter 3 Planning Your Deployment
Chapter 4 Installation Worksheet
Chapter 5 Installation and Configuration
Appendix A Migrating from Certificate Server 1.x
Appendix B Certificate Extensions
Appendix C Certificate Download Specification
Appendix D Using SSL with Enterprise Server 3.x
Appendix E Export Control Information
Glossary

Contents

Index

Bookshelf

Appendix A Migrating from Certificate Server 1.x

This appendix explains how to use the Migration Tool that comes with Netscape Certificate Management System. This executable command-line script extracts database contents (as stored in the Informix database) and certificate/key data (as stored in flat-file DBM databases) from Certificate Server 1.x and places the data in three platform-independent files that can be transferred by diskette, tape, or FTP to a Certificate Management System 4.0 installation area for import into the new system.

This appendix has the following sections:

Using the Migration Tool

Importing the Data to New Databases

Hardware, Operating System, and Version Support

Using the Migration Tool

To begin the migration process, you enter the migrate command and its arguments in a command shell, provide database information and passwords, and monitor the output in the shell window.

Before running the Migration Tool, make sure that the following conditions have been met:

You have processed all pending database requests.

The global variable INFORMIXSQLHOSTS is undefined.

The directory in which you will write the exported files has read and write permissions.

To terminate the execution of the tool at any time, type Control-C on Unix or Control-Break on Windows NT.

Command-Line Syntax

Use the following command in a Unix or DOS command shell:

migrate certsrvroot=<directory> outputdir=<directory>

	dbrootdir=<directory> servername=<name> help

Arguments

The migrate command takes the following arguments:


certsrvroot	The server root/server identifier, as defined in the Certificate Server 1.x installation documentation. This directory must point to the root of the server instance that will be migrated.
outputdir	A directory that does not currently exist but that will be created and populated with the results of the migrate command.
dbrootdir	The directory in which the Informix database resides--by default, /usr/informix on Unix platforms and c:\informix on Windows NT.
servername	The name of the Informix database server to which to connect. By default, the database server name is ifmx_online.
help	Optional. Prints a usage string for the command to the command shell.

The Migration Process

There are two stages to the migration process. The Migration Tool first connects to the Informix database, extracts database records, and writes them out to an LDIF file in the specified output directory. It then connects to the flat files containing the key and certificate information, and transfers that information to ASCII files in the output directory.

When you issue the migrate command, the tool prompts you to enter login information and passwords for the Certificate Server 1.x Informix database, and performs the first phase of the migration. After migrating the database records, the tool prompts for the key and certificate database passwords, and migrates the flat file information.

Entering Informix Database Login Information

The tool prompts for the Informix database name and login:

database Name [cmsdb]: <data base name>  

database login name [cmsdbusr]: <data base administrative user name> 

database password: *********

The database name is the name of the Informix database in which the Certificate Server tables t_cert_record, t_seq_num_gen, and t_iss_auth_prop reside.

The default database name and user name are those used for a standard installation of Certificate Server 1.x. Unless you changed the names during the installation, you can accept the defaults by pressing Enter at the prompt.

When you have entered the login information, the Migration Tool connects to the database, extracts records, and writes the extracted records to files in the directory specified by the outputdir argument. Text such as the following appears:

Starting Database migration... 

Connected to database! 

migrating certificate records... 

extracted 3293 cert record(s) 

migrating last serial number... 

migrating Certificate Revocation List... 

Data Base migration completed, LDIF files generated.

If the migration of data from the Informix database fails, the tool shows the Informix error and asks whether to continue or exit. If you choose to continue, certificate and key migration proceeds. See Informix manuals to find the source of the problem, fix it, then run the tool again to extract the Informix data.

For example, if you run the Migration Tool on the wrong computer, and it cannot find the Informix database, you might see the following message referring to the Informix error 461 (file not found):

Starting Database migration... 

CMS -- UNLOGGABLE FAILURE: [VENDORLIB] Vendor Library Error: 

Cannot open file `sql.iem'; Cannot open file `os.iem' (-461)(4)

migrate: error: Could not connect to database!

Continue migration [y|n]: y

In this example, the user chooses to continue with the second phase of the migration, then go back and run the tool on the right machine to perform the Informix database migration.

Entering Key and Certificate Database Passwords

After it has migrated the records from the Informix database, the tool prompts for the passwords used to open the flat key and certificate database files, as well as a transport password that is used to encrypt data for the migration of certificates and keys.

Enter the passwords used to protect server key data:  

Server key password : *******  

Signing key password :  *******

If either password is incorrect, an error message appears and the tool exits. See Exit Codes and Error Messages.

Next, the tool prompts you to provide and confirm a transport password:

Select a Transport password to protect the private key material: 

Transport password: **********  

Verify Transport password: **********

The transport password is used to encrypt keys as they are extracted from the key database, before they are written out to the keyscerts.dat file. If the transport password and the verify transport password entries are not the same, the following message appears, and the tool exits:

Transport and verify transport passwords are not the same

If the transport password does not conform to the two minimum quality rules, one of the following messages appears, and the password prompt reappears:

The transport password must be a minimum of 8 characters

The transport password must contain both alphabetic and numeric 
characters

When you have entered the passwords, the Migration Tool opens and extracts information from the flat certificate and key database files, writing it out to an ASCII file in the directory specified by the outputdir argument. Text such as the following appears:

Starting Certs and Keys migration... 

Successfully Dumped Server Certificate Chain 

Successfully Dumped Signing Cert 

Successfully dumped ServerKey 

Successfully dumped Signing Key 

Certs and Keys migration completed, keyscerts.dat file generated

Exit Codes and Error Messages

If the data migration process is successful, the Migration Tool returns the code 0 and prints the success message. If an error occurs, the tool returns one of the error codes and prints an explanatory message in the command shell window. Table A.1 describes the success and error exit codes and conditions.

Table A.1 Exit codes and conditions


Exit codes	Exit message	Reason
0	Successfully created outputdir with Certificate Server 1.x data and the three output files	Indicates successful export of both the key material and database contents.
1	Invalid password; unable to export	One of the three passwords required to access the signing key, server key, and database was incorrect.
2	Could not connect to database!	A problem occurred opening a connection to the DBMS. Check to make sure the DBMS is running. Use onmonitor or another Informix command to start the DBMS. In most cases this error occurs if a user name or password is incorrect.
3	Could not create outputdir	The tool could not create the output directory. The cause could be that the parent directory does not exist or that there are not enough inodes or disk space
4	Transport and verify transport passwords are not the same	The two strings entered for the password and its verification were not the same.
5	Could not create outputdir/keyscerts.dat	The tool failed to create a file in the output directory. Possible permissions problem.
6	Could not open [outputdir/database_add.ldif \| outputdir/database_mod.ldif] for write	The tool failed to create ldif files in the output directory. Possible permissions problem.
7	failure_location: Out of memory	The tool was unable to allocate more memory at the indicated location.
8	Base 64 Encoding of data failed: Unable to encode	Possible corrupt binary data was found. The tool could not proceed with base-64 encoding of binaries obtained from the database or from the flat database files.
9	"magnus.conf" not found	The configuration file needed to find the locations of Certificate Server 1.x flat database files does not exist, cannot be read, or cannot be found.
10	Error writing in the output file	The tool could not write to the keyscerts.dat file.
11	Failed to open the Key Database: <path>/ServerKey.db NOTE: The user of this executable must have both read and write privileges for this file.	The tool could not open the key database file, possibly because the user does not have both read and write permission for that file.
12	usage: migrate certsrvroot=<directory> outputdir=<directory> dbrootdir=<directory> servername=<name>	The help argument was used to display the usage message.
13	Lost connection to database while migrating Certificate revocation list	The connection to the database was lost while the tool was copying the revocation list.
14	database table "t_iss_auth_prop" was not found, CRL migration skipped	This table is optional. If it is not in the database, this code is signaled, and the migration continues.
15	database table "t_cent_record" was not found, certificate records migration aborted	This table is required. If it is not in the database, this code is signaled, and the migration halts.
16	database table "t_seq_num_gen" was not found, CRL migration aborted	This table is required. If it is not in the database, this code is signaled, and the migration halts.
17	No binary found in "t_iss_auth_prop", CRL migration skipped	This table is optional. If it is not in the database, this code is signaled, and the migration continues.