welcome hpws docs hp-ux webservers home contact hp support
hp logo - invent  hp-ux web server suite

User Guide for Certmig : A Netscape certificate migration tool

TABLE OF CONTENTS

Overview Getting ready to perform migration Migration of Certificates Usage - Help - Listing of Certificates in the database - Extract Certificates - Exporting Certificates in PKCS#12 format Legal Notices

OVERVIEW

- /opt/hpws/apache/bin/certmig is the PKCS executable. - Certmig can be used to migrate iPlanet 4.x certificates over to HP-UX Apache-based Web Server. It will not work with Netscape 3.x certificates. Certmig is an extension of the PK12UTIL utility provided by the Mozilla community. - Certmig uses the Network Security Services (NSS) libraries. We are not delivering all components of NSS, but only the required components for converting iPlanet certificates, key translations and certificate chains to that of HP-UX Apache-based Web Server. The FAQ for NSS can be found under: http://www.mozilla.org/projects/security/pki/nss/faq.html#Q1.1 - Public-Key Cryptography Standard #12 : The PKCS standard developed by RSA Laboratories that governs the format used to store or transport private keys, certificates, and other secret material. - /opt/hpws/apache/util/test_certmig.sh : This is a wrapper around certmig. It can be used to import / extract / list the certificates in an iPlanet 4.1.x Certificate database. For usage information, please type "/opt/hpws/apache/util/test_certmig.sh -h".

GETTING READY TO PERFORM MIGRATION

- Before any trust (Keys) databases are created and Certificate Databases are installed, the iPlanet 'alias' directory is EMPTY. Once a trust database is created, and a certificate installed, let's say for the server instance http-X on the server Y, the following files are created in the 'alias' directory: http-X-Y-cert7.db, http-X-Y-key3.db, secmod.db To use the certmig utility, first rename these files : cp https-X-Y-cert7.db cert7.db cp https-X-Y-key3.db key3.db If you do not rename these files, and you execute the following command: /opt/apache/bin/certmig -L -d /opt/iplanet/alias all you get back is: "Opened Cert DB successfully", but no certificates are displayed. If you now look in the /opt/iplanet/alias directory, you will notice that two new files, cert7.db and key3.db are generated.

MIGRATION OF CERTIFICATES

Suppose Certificate files related to iPlanet (that you want to migrate over to HP-UX Apache-based Web Server) are available under the /opt/iplanet/alias directory. You should do the following: STEP 1: Determine the nick names of the server and/or personal certificates as shown in USAGE1 below. STEP 2: Extract the certificates and the corresponding keys in PKCS#12 format as shown in USAGE3 below. STEP 3: The output of STEP 2 is a single file that contains a certificate as well as the corresponding key. This file has to be manually split into *.crt and *.key files. These are ready to be used with HP-UX Apache-based Web Server. If you have set ClientVerify to be ON, then perform the following steps: STEP 1: Extract all the CA certificates as shown in USAGE2 below. STEP 2: Determine the nick names of the server and/or personal certificates as shown in USAGE1 below. STEP 3: Extract the certificates and the corresponding keys in PKCS#12 format as shown in USAGE3 below. STEP 4: The output of STEP 2 will result in *.crt and *.key files, ready to be used with HP-UX Apache-based Web Server. Now configure your /opt/hpws/apache/conf/ssl.conf with SSLCertificateFile and SSLCertificateKeyFile to point to the above certificate and key files.

USAGE

USAGE0. Help : "--h" option or "-help" option -------------------------------------------------------------- Usage : certmig -help : certmig --h This option lists the various options that can be passed to the certmig utility - for listing, importing and extracting certificates from the Netscape database. USAGE1. Listing of Certificates in the database : "-L" option -------------------------------------------------------------- Usage : certmig -L -d CertDirectory Example : certmig -L -d /opt/iplanet/alias This option lists the NickNames of the all the certificates available in the database specified. The NickName can be used by the export feature ("-o" option) of the certmig utility to export the certificate in PKCS#12 format. NOTE : Only the certificates which have a valid key in the keys database can be exported in the PKCS#12 format i.e., only the certificates that were installed locally into the Netscape certificate database can be extracted. USAGE2. Extract Certificates : "-E" option ----------------------------------------------------------------- Usage : certmig -E -d CertDirectory [-n "NickName"] Example : 1. certmig -E -d ~/.netscape 2. certmig -E -d /opt/iplanet/alias -n "Valicert Class 1 VA" This option extracts the Certificate (ONLY) from the specified database. It DOES NOT extract the corresponding key from the keys database. The certificates extracted are in the X.509 format and the contents of the certificate can be displayed using the openssl utility by typing : openssl x509 -text -in <file.crt> The NickName can be known by using the "-L" option of the certmig utility. If the NickName is not given on the command line, the utility displays all the certificates available in the database specified, and prompts for the certificate to be extracted. USAGE3. Exporting Certificates in PKCS#12 format : "-o" option : ----------------------------------------------------------------- Usage : certmig -o exportfile -n nickname [-d crtdir] [-k slotpwfile | -K slotpw] [-w p12filepwfile | -W p12filepw] where, exportfile = File where certificates are migrated in PKCS#12 format. nickname = Name you used to create the iPlanet certificates. crtdir = Directory where the iPlanet certificate database is present. slotpwfile = File which contains the password to the keys database. slotpw = Password to the keys database. p12filepwfile = File containing the encryption password for the PKCS#12 file. p12filepw = Encryption Password for PKCS#12 file. Example : certmig -o server.p12 -n "My Personal Certificate" -d ~/.netscape This option exports the certificate identified by nickname from the database to the PKCS#12 format in the exportfile specified. The exportfile contains both the certificate and the corresponding key in the same file in the DER format (binary format). The DER format file can be converted into the PEM format by using the openssl utility: openssl pkcs12 -in exportfile.der -out exportfile.pem You will be asked to enter the PEM pass phrase. The resulting file, exportfile.pem, contains both the key and the certificates in the same file. You should manually split this file into <choose-a-name>.crt, with certificate in it and <choose-the-same-name>.key with key in it. Note : This option can be used only for those certificates which have a valid key in the keys database. If the certificate doesn't have a corresponding key in the database, the utility will fail with the error "certmig: find cert by nickname failed". ***************************************************************************