|
|
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".
***************************************************************************
LEGAL NOTICES
The information in this document is subject to change without notice.
WARRANTY DISCLAIMER
HEWLETT-PACKARD MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS
INFORMATION, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Hewlett-Packard
shall not be liable for errors contained herein or for direct, indirect,
special, incidental or consequential damages in connection with the
furnishing, performance or use of this material.
RESTRICTED RIGHTS LEGEND
Use, duplication or disclosure by the U.S. Government is subject to
restrictions as set forth in subparagraph (c) (1) (ii) of the Rights in
Technical Data and Computer Software clause at DFARS 252.227-7013 for DOD
agencies. Rights for non-DOD U.S. Government Department and Agencies are
as set forth in FAR 52.227-19 (c)(1,2).
COPYRIGHT NOTICES
Copyright 2001-2006 Hewlett-Packard Development Company, L.P.
This document contains information which is protected by copyright.
All Rights Reserved. Reproduction, adaptation, or translation without
prior written permission is prohibited, except as allowed under the
copyright laws.
TRADEMARK NOTICES
UNIX is a registered trademark in the United States and other countries,
licensed exclusively through X/Open Company Limited.
Java and all Java-based trademarks and logos are trademarks or
registered trademarks of Sun Microsystems, Inc. in the U.S. and
other countries.
Netscape is a U.S. trademark of Netscape Communications Corporation.
ACKNOWLEDGEMENTS
This product includes software developed by the Apache Software Foundation
This documentation is based on information from the Apache Software Foundation
(http://www.apache.org).
This product includes software developed by the OpenSSL Project for use
in the OpenSSL Toolkit (http://www.openssl.org).
This product includes cryptographic software written by Eric Young
([email protected]).
|
