Netscape Communications Corporation("Netscape") and its licensorsretain all ownership rights to the softwareprograms offered by
Netscape (referred to herein as "Software") and related documentation. Use of the Software and related documentation is governed by the
license agreement for the Software and applicable copyright law.
Your right to copy this documentation is limited by copyright law. Making unauthorized copies, adaptations or compilation works is
prohibited and constitutes a punishable violation of the law. Netscape may revise this documentation from time to time without notice.
THIS DOCUMENTATION IS PROVIDED "AS IS" WITHOUT WARRANTYOF ANY KIND. IN NO EVENT SHALL NETSCAPEBE LIABLE
FOR INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY KIND ARISING FROM ANY ERROR IN THIS
DOCUMENTATION, INCLUDING W ITHOUT LIMITATION ANY LOSS OR INTERRUPTION OF BUSINESS, PROFITS, USE, OR DATA.
Netscape and the Netscape N logo are registered trademarks of Netscape Communications Corporation in the United States and other
countries. Other Netscape logos, product names, and service names are also trademarksof NetscapeCommunications Corporation, which
may be registered in some countries. Other product and brand names are the exclusive property of their respective owners.
The downloading, exporting, or reexporting of Netscape software or any underlying information or technology must be in full compliance
with all United States and other applicable laws and regulations. Any provision of Netscape software or documentation to the U.S.
government is with restricted rights as described in the license agreement for that Software.
Index ........................................................................ 73
5
6Netscape Certificate Management System Command-Line Tools Guide • May 2002
About This Guide
The Command-Line Tools Guide describes various command-line tools or utilities
that are bundled with Netscape Certificate Management System (CMS). It provides
the information such as the command syntax, platform support, examples, and so
on, required to use these tools.
This preface has the following sections:
•What You Should Already Know (page 7)
•What’s in This Guide (page 8)
•Conventions Used in This Guide (page 9)
•Where to Go for Related Information (page 10)
What You Should Already Know
This guide is intended for experienced system administrators who are planning to
deploy Certificate Management System. CMS agents should refer to CMS Ag ent’sGuide for information on how to perform agent tasks, such as handling certificate
requests and revoking certificates.
This guide assumes that you
•Are familiar with the basic concepts of public-key cryptography and the Secure
Sockets Layer (SSL) protocol.
❍SSL cipher suites
❍The purpose of and major steps in the SSL handshake
7
What’s in This Guide
•Understand the concepts of intranet, extranet, and the Internet security and the
role of digital certificates in a secure enterprise. These include the following
topics:
❍Encryption and decryption
❍Public keys, private keys, and symmetric keys
❍Significance of key lengths
❍Digital signatures
❍Digital certificates, incl uding various types of digital certificates
❍The role of digital certificates in a public-key infrastructure (PKI)
❍Certificate hierarchies
If you are new to these concepts, we recommend that you read the
security-related appendixes of the accompanying manual, Manag ing Server swith Netscape Cons ole.
•Are familiar with the role of Netscape Console in managing Netscape version
6.x servers. Otherwise, see the accompanying manual, Managing Servers withNetscape Console.
•Are reading this guide in conjunction with the documentation listed in “Where
to Go for Related Information” on page 10.
What’s in This Guide
This guide covers the following topics:
•Chapter 1, “Command-Line Tools” Provides an overview of the command-line
tools provided with Certificate Management System, including the ones that
are not covered in this documentation.
•Chapter 2, “CMS Upgrade Utility” Describes how to use the utility to upgrade
from a previous release of Certificate Management System.
•Chapter 3, “Password Cache Utility” Describes how to use the tool for
managing the single sign-on password cache.
•Chapter 4, “PIN Generator Tool” Describes how to use the tool for generating
unique PINs for your users and f or populating their directory entries with
PINs.
8Netscape Certificate Management System Command-Line Tools Guide • May 2002
•Chapter 5, “Extension Joiner Tool” Describes how to use the tool for joining
MIME-64 encoded formats of certificate extensions to create a single blob.
•Chapter 7, “ASCII to Binary Tool” Describes how to use the tool for converting
ASCII data to its binary equivalent.
•Chapter 8, “Binary to ASCII Tool” Describes how to use the tool for converting
binary data to its ASCII equivalent.
•Chapter 9, “Pretty Print Certificate Tool” Describes how to use the tool for
printing or viewing the contents of a certificate stored as ASCII base-64 encoded data in
a human-readable form.
•Chapter 10, “Pretty Print CRL Tool” Describes how to use the tool for printing
or viewing the contents of a CRL stored as ASCII base-64 encoded data in a
human-readable form.
Conventions Used in This Guide
This guide uses the following conventions:
The following conventions are used in this guide:
•
computer screen or text that you should type. It’s also used for filenames,
functions, and examples.
Example:
Server Root is the directory where the CMS binaries are kept.
•Italic—Italic type is used for emphasis, book titles, and glossary terms.
Example: This control depends on the access permissions the superadministrator
has set up for you.
•Text within “quotation marks”—Indicates cross-references to other topics
within this guide.
Example: For more information, see “Issuing a Certificate to a New User” on
page 154.
About This Guide9
WheretoGoforRelatedInformation
•[]—Square brackets enclose commands that are optional.
Example:
PrettyPrintCert <input_file> [<output_file>]
<input_file>
specifies the path to the file that contains the base-64
encoded certificate.
<output_file> specifies the path to the file to write the certificate. This
argument is optional; if you don’t specify an output file, the certificate
information is written to the standard output.
<>—Angle brackets enclose variables or placeholders. When following
•
examples, replace the angle brackets and their text with text that applies to
your situation. For example, when path names appear in angle brackets,
substitute the path names used on your computer.
Example: Using Netscape Communicator 4.7x or later, enter the URL for the
Administration Server:
http://<hostname>:<port_number>
•/—A forward slash is used to separate directories in a path. If you use the
Windows NT operating system, you should replace / with \ in paths.
Example: Except for the Security Module Database Tool, you can find all the
other command-line utilities at this location:
<server_root>/bin/cert/tools
•Sidebar text—Sidebar text marks important information. Make sure you read
the information before continuing with a task.
Examples:
NOTEYou can use Netscape Console only when Administration Server is
up and running.
CAUTIONA caution note documents a potential risk of losing data, damaging
software or hardware, or otherwise disrupting system performance.
Where to Go for Related Information
This section summarizes the documentation that ships with Certificate
Management System, using these conventions:
<server_root> is the directory where the CMS binaries are kept (specified
•
during installation).
10Netscape Certificate Management System Command-Line Tools Guide • May 2002
Where to Go for Related Information
•<instance_id> is the ID for this instance of Certificate Management System
(specified during installation).
The documentation set for Certificate Management System includes the following:
•Managing Servers with Netscape Console
Provides background information on basic cryptography concepts and the role
of Netscape Console. For the HTML version, open this file:
<server_root>/manual/en/admin/ag/contents.htm
•CMS Installation and Setup Guide
Describes how to plan for, install, and administer Certificate Management
System. To access the installation and configuration information from within
the CMS Installation Wizard or from the CMS window (within Netscape
Console), click any help button. To view the HTML version of this guide, open
this file:
Provides detailed reference information on CMS agent interfaces. To access
this information from the Agent Services pages, click any help button. To view
the HTML version of this guide, open this file:
<server_root>/cert-<instance_id>/web-apps/agent/manual/agent_gui
de
/contents.htm
About This Guide11
WheretoGoforRelatedInformation
•End-EntityHelp
Provides detailed reference information on CMS end-entity interfaces. To
access this information from the end-entity pages, click any help button. To
view the HTML version of this guide, open this file:
12Netscape Certificate Management System Command-Line Tools Guide • May 2002
Command-Line Tools
Netscape Certificate Management System (CMS) is bundled with various
command-line utilities. This chapter summarizes these utilities and provides
pointers to chapters that further explain them.
Table 1-1 summarizes the command-line utilities that are bundled with Certificate
Management System.
Table 1-1Summary of command-line utilities
Utility/ToolFunction
Batch/Shell Scripts located under <server_root>/bin/cert/upgrade/:
Chapter1
Upgrade UtilityUpdrades from a CMS 4.2, 4.5, or 6.0 instance to a CMS 6.01
instance. For or details, see Chapter 2, “CMS Upgrade Utility.”
Batch/Shell Scripts located under <server_root>/bin/cert/tools/ (require jre):
PasswordCache
(Password Cache Utility)
AtoB
(ASCII to BinaryTool)
BtoA
(Binary to ASCII Tool)
PrettyPrintCert
(Pretty Print Certificate Tool)
PrettyPrintCrl
(Pretty Print CRL Tool)
Executable tools located under <server_root>/bin/cert/tools:
Manipulates the contents of the single sign-on password cache.
For details, see Chapter 3, “Password Cache Utility.”
Converts ASCII base-64 encoded data to binary base-64 encoded
data. For details, see Chapter 7, “ASCII to Binary Tool.”
Converts binary base-64 encoded data to ASCII base-64 encoded
data. For details, see Chapter 8, “Binary to ASCII Tool.”
PrintsthecontentsofacertificatestoredasASCIIbase-64encoded
data in a human-readable form. For details, see Chapter 9, “Pretty
Print Certificate Tool.”
Prints the contents of a CRL stored as ASCII base-64 encoded data
in a human-readable form. For details, see Chapter 10, “Pretty
Print CRL Tool.”
13
Table 1-1Summary of command-line utilities (Continued)
Utility/ToolFunction
certutil
(Certificate and Key Database Tool)
View and manipulate the certificate database (cert7.db)andkey
database (key3.db) contents. For details, check the
Perl Scripts located under <server_root>/bin/cert/tools (require _perl):
cmsbackupCopies all of the pertinent data and configuration files for a CMS
instance, the local Administration Server, and local Netscape
DirectoryServers that the instance uses into a compressed archive.
For details, see Chapter 6, “Backing Up and Restoring Data.”
cmsrestoreOpens a named archive, extracts the data, and uses it to restorethe
configuration of a CMS instance. For details, see Chapter 6,
“Backing Up and Restoring Data.”
Executable tools located under <server_root>/shared/bin:
modutil
(Security Module Database Tool)
Used for managing the PKCS #11 module information within
secmod.db files or within hardware tokens. For details,check the
http://www.mozilla.org/projects/security/pki/nss
/tools/.site.
Third-party executable tools located under <server_root>/bin/cert/tools:
dumpasn1Dumps the contents of binary base-64-encodeddata.Note that the
tool is freeware that is packaged with Certificate Management
System for your convenience. For more information about this
tool, check this site: http://www.cs.auckland.ac.nz/~pgut001/
Third-party support tools located under <server_root>:
14Netscape Certificate Management System Command-Line Tools Guide • May 2002
Table 1-1Summary of command-line utilities (Continued)
Utility/ToolFunction
bin/base/jre/bin/jre
bin/cert/jre/bin/jre
bin/cert/tools/unzipDecompression utility executable.
bin/cert/tools/zipCompression utility executable.
install/perlperl scripting language executable.
Java runtime executable for Netscape Console.
Java runtime executable for Certificate Management System.
Note that the CMS jre is invoked as cms_daemon during CMS
installation and configuration, as cms_watchdog to monitor the
status of the CMS server, and as cms_server to actually run the
CMS server.
ssltap), and Security Database Tool (modutil)areapartof
Network Security Services (NSS) tools. The remaining tools are CMS-specific tools.
•The
AtoB, BtoA, PrettyPrintCert, PrettyPrintCrl,anddumpasn1 tools are
useful for converting back and forth between various encodings and formats
you may encounter when dealing with keys and certificates.
•The Password Cache Utility can be used to manipulate the contents of an
existing single sign-on password cache and to create a new cache.
•The PIN Generator tool is used to create PINs for directory authentication.
•The Certificate and Key Database Tool and Security Module Database Tool are
useful for a variety of administrative tasks that involve manipulating certificate
and key databases.
•The Netscape Signing Tool can be used to associate a digital signature with any
file, including CMS log files.
•The SSL Debugging Tool is useful for testing and debugging purposes.
If you find any problems with NSS tools, you may obtain the source code and build
instructions for the very latest version of these tools (and/or potentially a binary
image for the newer tool) at the following URL:
If you’re familar with older versions of NSS tools, notice that all Key Database Tool
functions have now been incorporated into the single tool, Certificate Database
Tool, and that several of the command-line options for many of the tools may have
changed. Be sure to check back often to obtain the very latest version of the desired
securitytool,asthissiteisupdatedoften.
16Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter2
CMS Upgrade Utility
If you have a previous installation of Netscape Certificate Management System
(Certificate Management System), you can use the CMS Upgrade utility for
upgrading to Certificate Management System, version 6.01. The utility enables you
to upgrade from Certificate Management System version 4.2, 4.5, or 6.0 to CMS
6.01.
There are three phases to upgrading from a previous CMS instance. This chapter
explains these phases in the following sections:
•Before Upgrading (page 17)
•Upgrading (page 21)
•After Upgrading (page 25)
Before Upgrading
Before upgrading from a CMS 4.2, 4.5, or 6.0 instance to a CMS 6.01 instance, you
must complete the following tasks:
•Backing Up Your Previous CMS Instance
•Locating Your Previous Security Databases
•Creating Your Previous Internal Database File in LDIF Format
•Normalizing Your Previous Internal Database File
17
Before Upgrading
Backing Up Your Previous CMS Instance
You must backup your existing CMS 4.2, 4.5, or 6.0 instance before you can
upgrade to CMS 6.01.
•For instructions to back up a CMS 4.2 or 4.5 instance, check the CMSCommand-Line Tools Guide that was provided with the product; open the
<server_root>/manual/en/cert/tools_guide/backup.htm file. You can
•For instructions to back up a CMS 6.0 instance,see Chapter 6, “Backing Up and
Restoring Data.”
Locating Your Previous Security Databases
Each instance of Certificate Management System uses a set of key pairs and
certificates, which can be maintained in an internal/software token or a hardware
token, or a combination of both. These tokens contain public keys, private keys,
and relevant PKCS #11 compatible drivers. For more information about tokens,
check CMS In stallation and Setup Guide.
As a part of the upgrade process, you will be required later to import your existing
key pairs and certificates to the new CMS instance. If you used hardware tokens,
keep those tokens and the corresponding passwords handy. If you used software
tokens, make a note of the following for your CMS instance, where
<4x_server_root> is the location of your CMS 4.2 or 4.5 instance and
<60_server_root> is the location of your CMS 6.0 instance:
•Public keys and the corresponding certificates are stored in the certificate
database, this file:
To import a CMS 4.2 or 4.5 LDIF file into a CMS 6.01 instance, you need to adjust
the LDIF file by deleting the first two LDIF entries. (You don’t need to delete the
first two entries in the CMS 6.0 LDIF file.)
Next, you need to convert the adjusted LDIF files to a text format:
•Converting the CMS 4.2 LDIF File to a Text Format
•Converting the CMS 4.5 LDIF File to a Text Format
•Converting the CMS 6.0 LDIF File to a Text Format
NOTEIn the sections that follow, replace
<server_root>/bin/cert/upgrade.
Converting the CMS 4.2 LDIF File to a Text Format
If you are upgrading from a CMS 4.2 instance to a CMS 6.01 instance:
1.Execute the 42ToTxt command:
cd <upgrade_tool>/42ToTxt
export SERVER_ROOT=<42_server_root>
run.sh <42_ldif> > <42_txt>
2.
Execute the TxtTo601 comm and:
20Netscape Certificate Management System Command-Line Tools Guide • May 2002
<upgrade_tool> with
cd <upgrade_tool>/TxtTo601
export SERVER_ROOT=<601_server_root>
run.sh <42_txt> > <601_ldif>
Converting the CMS 4.5 LDIF File to a Text Format
If you are upgrading from a CMS 4.5 instance to a CMS 6.01 instance:
1.Execute the 45ToTxt command:
cd <upgrade_tool>/45ToTxt
export SERVER_ROOT=<45_server_root>
run.sh <45_ldif> > <45_txt>
2.
Execute the TxtTo601 command:
cd <upgrade_tool>/TxtTo601
export SERVER_ROOT=<601_server_root>
run.sh <45_txt> > <601_ldif>
Converting the CMS 6.0 LDIF File to a Text Format
If you are upgrading from a CMS 6.0 instance to a CMS 6.01 instance:
Upgrading
1.Execute the 60ToTxt command:
2.
Upgrading
The following procedures describe how to upgrade from a CMS 4.2, 4.5, or 6.0
instance to a CMS 6.01 instance.
•Installing and Configuring CMS 6.01
cd <upgrade_tool>/60ToTxt
export SERVER_ROOT=<60_server_root>
run.sh <60_ldif> > <60_txt>
Execute the TxtTo601 command:
cd <upgrade_tool>/TxtTo601
export SERVER_ROOT=<601_server_root>
run.sh <60_txt> > <601_ldif>
Chapter 2CMS Upgrade Utility21
Upgrading
•Shutting Down the CMS 6.01 Server
•Installing the Old Security Databases
•Installing the Old Internal Database
•Starting Up the CMS 6.01 Server
Installing and Configuring CMS 6.01
Install a CMS 6.01 instance into a separate server root. Refer to theCMS Installation
and Setup Guide for instructions on how to install Certificate Management System.
NOTELater on you will overwrite the CMS 6.01 configuration information,
such as keys and subject names, with your previous CMS 4.2, 4.5, or
6.0 internal security databases.
Shutting Down the CMS 6.01 Server
After configuring CMS 6.01, shut down your CMS 6.01 instance and the
corresponding internal database, where
CMS 6.01 instance:
cd <601_server_root>/cert-<instance_id>
./stop-cert
cd <601_server_root>/slapd-<instance_id>-db
./stop-slapd
<601_server_root> is the location of your
Installing the Old Security D atabases
You need to install your old CMS 4.2, 4.5, or 6.0 security database into your new
CMS 6.01 installation.
•Installing CMS 4.2 or 4.5 Security Databases
•Installing CMS 6.0 Security Databases
22Netscape Certificate Management System Command-Line Tools Guide • May 2002
Upgrading
Installing CMS 4.2 or 4.5 Security Databases
InstallyourpreviousCMS4.2or4.5securitydatabasesbycopyingthemtoyour
new CMS 6.01 installation using the following commands:
/usr/netscape/server601/alias/cert-firefly-firefly-key3.db
cd /usr/netscape/server60/alias
cp secmod.db /usr/netscape/server601/alias/secmod.db
Chapter 2CMS Upgrade Utility23
Upgrading
Installing the Old Internal Database
To install your old internal database, import your old LDIF into the CMS 6.01
internal database. (See “Normalizing Your Previous Internal Database File,” on
page 20 for instructions on how to adjust your old LDIF file.)
Import your adjusted CMS 4.2, 4.5, or 6.0 LDIF file into the CMS 6.01 internal
database using the following commands:
cd <601_server_root>/slapd-<instance_id>-db
ldif2db -n userRoot -i <601_ldif>
Updating the CMS 6.01 Password Cache
Recreate the CMS 6.01 password cache so that it will work with your old security
databases:
cd <601_server_root>/cert-<instance_id>/config
mv pwcache.db pwcache.db.org
touch pwcache.db
../../bin/cert/tools/PasswordCache <key3_password> \
24Netscape Certificate Management System Command-Line Tools Guide • May 2002
./start-slapd
cd <601_server_root>/cert-<instance_id>
./start-cert
After Upgrading
After upgrading to CMS 6.01, access the End-Entity Services and the Agent
Services interfaces of the new CMS 6.01 instance to ensure that everything is
working properly.
You must also log in to the CMS Console and verify that you can manage the server
via the console.
The port numbers for all these interfaces can be found in this file:
<server_root>/config/server.xml
After Upgrading
Chapter 2CMS Upgrade Utility25
After Upgrading
26Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter3
Password Cache Utility
During the installation of Netscape Certificate Management System (CMS), the
installation daemon stores all the passwords required by the server for starting
up—such as the bind passwords used by Certificate Management System to access
and update the internal LDAP database and the LDAP directory used for
authentication or publishing—in a password cache. The cache is maintained in a
file encrypted using a symmetric key generated by the cryptographic module
wherein the key resides, and encrypted by the single sign-on password (internal
cryptographic module password) you specify during installation.
Location
The command-line utility named
contents of the password cache. You will be required to manipulate the password
cache for various reasons. For example, assume you’ve configured the Certificate
Manager to publish certificates and CRLs to an LDAP directory and have
configured it to bind to the directory with Directory Manager’s DN and password.
If the directory administrator changes the Directory Manager’s password, the
Certificate Manager will fail to bind to the directory during startup. You can
resolve this problem by modifying the corresponding bind password in the cache
using the
This chapter has the following sections:
•Location (page 27)
•Syntax (page 28)
•Usage (page 28)
The PasswordCache utility is located with the rest of the command-line tools in
this directory:
PasswordCache utility.
<server_root>/bin/cert/tools
PasswordCache enables you to manipulate the
27
Syntax
Syntax
To run the utility, execute the following command from the
<server_root>/cert-<instance_id> directory:
PasswordCache <sso_password> -d <certificate/key db directory>
-P <certificate/key db prefix> <command>
<sso_password>
<certificate/key db directory> specifies the path to the certificate
database (
<server_root>/alias.
<certificate/key db prefix> specifies the prefix for the certificate database
cert7.db) and key database (key3.db) files. The default prefix is in the
(
cert-<instance_id>-<hostname>- format.
<command> can be any of the following:
cert7.db) and key database (key3.db) files. The default path is
list
add <password_name> <password>
change <password_name> <password>
delete <password_name>
<password_name>
specifies the current single sign-on password.
specifies the string (describing the password usage) you
want to add to, or modify or delete from the cache; it is equivalent to the
value assigned to the
configuration file. It is essential that the
bindPWPrompt or tokenname parameter in the CMS
<password_name> coincide with
the names known by Certificate Management System: for example, the
internal cryptographic module is known as internal,theinternalLDAP
bind password is known as Internal LDAP Database,andtheLDAP
publishing bind password for the Certificate Manager is known as CALDAP Publishing.
<password> specifies the new password.
Usage
You can use the PasswordCache utility for the following:
•Listing or viewing the contents of the password cache
•Adding a new entry to the cache
28Netscape Certificate Management System Command-Line Tools Guide • May 2002
•Changing the password associated with an entry
•Deleting an entry in the cache
The sections that follow explain how you can accomplish the above mentioned
tasks.
NOTEYou must run the utility from the
<server_root>/cert-<instance_id> directory.
The server queries the password cache only during start up, and
hencerecongnizesthechangesyou’vemadeto the cache only if you
restart the server from the command line. If you left any of the
passwords blank, the server will prompt you to enter that during
startup and from then on stores it in the password cache.
Listing the Contents of the Password C ache
To list or view the contents of the password cache:
Usage
1.Open a command window.
2.Go to this directory: <server_root>/cert-<instance_id>
At the prompt, enter the command below, substituting the variables with
3.
appropriate values:
PasswordCache <sso_password> -d <certificate/key db directory> -P
<certificate/key db prefix> list
For example, assume your single sign-on password is mySsoPwd,theCMS
instance name is
Ifthepasswordnamestringincludesspaces,besuretoenclosethestringin
double quotes as indicated in the above example.
demoCA, the host name is cmshost, the string describing the
Bind Password for LDAP Publishing Directory.The
“CA LDAP Publishing”
Usage
Chapter 3Password Cache Utility31
Usage
32Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter4
PIN Generator Tool
For Netscape Certificate Management System (CMS) to use the authentication
plug-in module named
contain unique PINs for each end entity to whom you intend to issue a certificate.
To aid you in generating PINs for end-entity entries in a directory, Certificate
Management System provides a command-linetool called the PIN Generator.This
tool allows you to generate unique PINs for entries in an LDAP-compliant user
directory. The tool stores these PINs (as hashed values) in the same directory
against the corresponding user entries, and it copies the PINs to a text file, from
which you can deliver the PINs to end entities by an a ppropriate, secure means.
UidPwdPinDirAuth your authentication directory must
This chapter explains how to use the PIN Generator. The chapter has the following
sections:
•Locating the PIN Generator Tool (page 33)
•The setpin Command (page 34)
•How the Tool Works (page 38)
Locating the PIN Generator Tool
You can find the PIN Generator at this location:
<server_root>/bin/cert/tools/setpin.exe
33
The setpin Command
The setpin Command
You run the PIN Generator by entering the setpin command and its arguments in
a command shell and monitoring the output in the shell window. This section gives
the syntax for the
generating PINs and storing them in your authentication directory, see section
“Configuring Authenticationfor End-User Enrollment”in Chapter 15, “Setting Up
End-User Authentication” of CMS Installation and Setup Guide.
Command-Line Syntax
Use the following command in a Unix or DOS command shell:
<host_name> specifies the LDAP directory to connect to.
<port_number> specifies the TCP/IP port to bind to; the default port number
is the default LDAP port, 389.
34Netscape Certificate Management System Command-Line Tools Guide • May 2002
The setpin Command
•["binddn=<user_id>"bindpw=<bind_password>]
<user_id> specifies the user ID that has read and write permission to the
LDAP directory; the PIN Generator binds to the directory as this user.
<bind_password> specifies the password for the user ID that has read and
write access to the LDAP directory. If the bind password is not given at the
command line, the tool prompts for it.
•[objectclass=<objectclass_to_add>]
Use this argument to specify the object class, if any, the tool should add to the
authentication directory. By default it is
•[attribute=<attribute_name_for_pins>]
pinPerson.
Use this argument to specify the authentication directory attribute to which
PINs should be published. If you don’t specify an attribute, it defaults to
the new attribute added to the authentication-directory schema.
•["filter=<LDAP_search_filter>"]
Use this argument to filter those DNs in the directory for which the tool should
generate PINs. For information on how to specify filters, see the information
available at this URL:
dirsdk/capi/search.htm
http://developer.netscape.com/docs/manuals/
pin,
•[input=<file_name>]
Use this argument to specify the name of the file that contains the list of DNs to
process. Using this argument is optional. If you do, the tool compares the
filtered DNs to the ones specified by the input file and generates PINs for only
those DNs that are also in the file.
Use this argument to specify the exact number or a range of characters that a
PIN must contain. The PINs can be either a fixed length or generated to be
between two values (x,y) inclusive (x,y>0).
<PIN_length> specifies the exact length for the PINs. For example, if you want
PIN length to be eight characters, enter
8. PIN length must be an integer
greater than zero.
<minimum_PIN_length> specifies the minimum length for the PINs. For
example, if you want PIN length to be at least six characters, enter
<maximum_PIN_length> specifies the maximum length for the PINs. For
6.
example, if you want PIN length to be nine characters at the most, enter
Use this argument to specify t he type of characters for PINs. The characters in
the password can be constructed out of alphabetic characters (
alphanumeric characters (
printableascii).
(
•[case=upperonly]
RNG-alphanum), or any printable ASCII characters
RNG-alpha),
Use this argument with the gen parameter. If you do, the case for all alphabetic
characters is fixed to uppercase only; otherwise, the case is mixed. Restricting
alphabetic characters to uppercase reduces the overall combinations for the
password space significantly.
•[hash=sha1 | md5 | none]
Use this argument to specify the message digest algorithm the tool should use
to hash the PINs before storing them in the authentication directory. If you
wanttostorePINsasSHA-1orMD5hashedvaluesinthedirectory,besureto
specify an output file for storing PINs in plain text. You will need the PINs in
plain text for delivering them to end entities.
sha1 produces a 160-bit message digest. This option is used by default.
md5 produces a 128-bit message digest.
none does not hash the PINs.
•[output=<file_name>]
Use this argument to specify the absolute path to the file to which the tool
should write the PINs as it generates them; this is the file to which the tool will
capture the output.
If you don’t specify a filename, the tool will write the output to the standard
output. In any case, all the error messages will be directed to the standard
error.
•[clobber]
Use this argument to specify whether the tool should overwrite preexisting
PINs, if any, associated with a DN (user). If specified, the tool overwrites the
existing PINs with the one it generates. Otherwise, it leaves the existing PINs
as they are.
•[write]
Use this argument to specify whether the tool should write PINs to the
directory. If specified, the tool writes PIN s (as it generates) to the directory.
Otherwise, the tool does not make any changes to the directory.
36Netscape Certificate Management System Command-Line Tools Guide • May 2002
The setpin Command
For example, if you want to check PINs—that the PINs are being given to the
correct users and that they are conforming to the length and character-set
restrictions—before updating the directory, do not specify this option. You can
check the PINs before updating the directory by looking at the output file; for
details, see “Output File” on page 42.
Use this argument to specify the LDAP attribute the tool should use for salt
creation. If you specify an attribute, the tool integrates the corresponding value
of the attribute with each PIN, and hashes the resulting string with the hash
routine specified in the hash argument.
If you don’t specify this argument, the DN of the user is used. For details, see
“How PINs Are Stored in the Directory” on page 43.
•[debug]
Use this argument to specify whether the tool should write debugging
information (to the standard error). If
debug=attrs is specified, the tool writes
much more information about each entry in the directory.
•[testpingen=<count>]
Use this argument to test the pin-generation mode.
<count> specifies the total number (in decimal) of PINs to be generated for
testing purposes.
•[optfile]
Use this argument to specify that the tool should read in options (one per line)
from specified file; this option enables you to put all the arguments in a file,
instead of typing them on the command line.
Example
The following command generates PINs for all entries that have the CN attribute (in
their distinguished name) defined in an LDAP directory named
listening at port
DirectoryManager and starts searching the directory from the node
dn=o=example.com in the directory tree. ThetooloverwritestheexistingPINs,if
19000. The PIN Generator binds to the directory as user
This command, if run, will query the directory for all the entries that match the
filter criteria, which in this case is all users belonging to an organizational unit (
employees. For each entry matching the filter, information is printed out to
called
ou)
standard error. Additionally, to the standard output or the file named in output;
see “Output File” on page 42.
You can also provide the tool with an input argument using the
input option. The
argument must be in the form of an ASCII file of pre-prepared DNs a nd PINs (see
Figure 4-1). Note that the input file is not a substitute for the LDAP directory
entries; the filter attribute must still be provided. If an input file is provided, the
tool updates only those filtered attributes that match the ones in the input file. For
more information about the input file, see “Input File” on page 40.
38Netscape Certificate Management System Command-Line Tools Guide • May 2002
Figure 4-1Using an input and output file for the PIN-generation process
Because the PIN Generator makes a lot of changes to your directory, it is important
that you specify the correct filter; otherwise, you m ay change the wrong entries. As
a safeguard, a
write option is provided that you use to enable writing to the
directory after you verify the output; the tool doesn’t make any changes to the
directory until you specify the
write option on the command line.
Chapter 4PINGenerator Tool39
How the Tool Works
The output also contains the status of each entry in the directory. It can be one of
the values specified in Table 4-1.
Table 4-1PIN Generator status
Exit codeDescription
notwrittenSpecifies that the PINs were not written to the directory, because the write
option was not specified on the command line.
writefailedSpecifies that the tool made an attempt to modify the directory, but the write
operation was unsuccessful.
addedSpecifies that the tool added the new PIN to directory successfully.
replacedSpecifies that the tool replaced an old PIN with a new one (the clobber option
was specified).
notreplacedSpecifies that the tool did not replace the old PIN with a new one (the clobber
option was not specified).
If a PIN already exists for a user, it will by default not be changed if you run the
setpin command a second time. This is so that you can generate PINs for new
users without overwriting PINs for users who have previously been notified of
their PINs. If you want to overwrite a PIN, you should use the
clobber option.
Once you are sure that the filter is matching the right users, you should run the
setpin command again with the write option, and with output set to the name of
the file to capture the unhashed PINs. This output file is in the same format as the
input file. For details about the output file, see “Output File” on page 42.
Input File
The P IN Generator can receive a list of DNs to modify in a text file specified by the
input=<file_name> argument. If you specify an input file, the tool compares the
DNs it filtered from the LDAP directory with the ones in the input file, and updates
only those DNs that matched the ones in the input file.
The purpose of the input file is multifold. It enables you to provide the Pin
Generator with an exact list of DNs to modify. Via the input file, you can also
provide the PIN Generator with PINs (in plain text format) for all DNs or for
specific DNs.
The following examples explain why you might want to use the input file:
40Netscape Certificate Management System Command-Line Tools Guide • May 2002
How the Tool Works
•Assume that you have set PINs for all entries in the user directory. Two new
users joined your organization and you updated the d irectory with new users’
information. For the new users to get certificates, the directory must contain
PINs. And you want to set PINs for just those user entries without making
changes to any of the other user entries. Instead of constructing a complex
LDAP filter to filter out just these two entries, you can construct a general filter,
put the two users’ DNs in the input file, and run the PIN Generator.
•Assume that you want your users to use their social security numbers as PINs.
You can enter users’ social security numbers as PINs in the input file, and the
PIN Generator will store them as hashed values in the directory.
The format of the input file is the same as that of the output file (see “Output File”
on page 42), with the omission of the status line. In the input file, you can choose to
specify PINs for all the DNs in the file, for specific DNs, or for none of the DNs. If
the PIN attribute is missing for a DN, the tool automatically generates a random
PIN.
For example, you can set up your input file to look like this:
dn:cn=user1, o=example.com
<blank line>
dn:cn=user2, o=example.com
<blank line>
...
dn:cn=user3, o=example.com
You can also provide PINs, in plain-text format, for the DNs in the input file, which
is then hashed according to the command-line arguments. For example, you can set
up your input file to look like this:
<user_dn> is a distinguished name that matched the specified DN pattern
(specified by the DN filter) or that was in the input file (the DN file). By default, the
delimiter is "
<generated_pin> is a string of characters with either fixed or variable length,
;" or the character defined on the command line.
dependent on parameters passed into the command.
<status> is one of the values specified in Table 4-1 on page 40.
The first line in each record will always be the distinguished name. The subsequent
lines, for
pin and status, are optional. The record ends with a blank line. The end
of line (EOL) sequence is as follows:
•OnUnix:
\n
•On Windows NT: \r\n
42Netscape Certificate Management System Command-Line Tools Guide • May 2002
How the Tool Works
How PINs Are Stored in the Directory
Each PIN is concatenated with the corresponding user's LDAP attribute named in
saltattribute argument. If this argument is not specified, the DN of the user
the
is used. Then, this string is hashed with the hash routinespecifiedin the hash
argument (the default selection is SHA-1).
Then, o ne byte is prepended to indicate the hash type used. Here’s how the PIN
gets stored:
byte[0] = X
The value of X depends on the hash algorithm chosen during the PIN generation
process:
X=0 if the hash algorithm chosen is SHA-1.
X=1 if the hash algorithm chosen is MD5.
X=45 if the hash algorithm chosen is none.
byte[1...] = hash("DN"+"pin")
The PIN is stored in the directory as a binary value, not as a base-64 encoded value.
Exit Codes
The PIN Generator returns exit codes to the shell window; for a list of codes, see
Table 4-2. If you plan on automating the PIN-generation process, exit codes are
useful in programming shell scripts.
Table 4-2Exit codes returned by the P IN Generator
Exit codeDescription
0Indicates that PIN generation was successful; that is, PINs are set for all the DNs in the
specified directory.
2Indicates that the tool could not open the certificate database specified by the certdb
parameter.
3Indicates that the tool could not locate the certificate specified by the nickname
parameter in the specified certificate database.
4Indicates that the tool could not bind to the directory as the user specified by the
binddn parameter (over SSL).
5Indicates that the tool could not open the output file specified by the output
parameter.
Chapter 4PINGenerator Tool43
How the Tool Works
Table 4-2Exit codes returned by the P IN Generator (Continued)
Exit codeDescription
7Indicates an error parsing command-line arguments.
8Indicates that the tool could not open the input file specified by the input parameter.
9Indicates that the tool encountered an internal error.
10Indicates that the tool found a duplicate entry in the input file specified by the input
parameter.
11Indicates that the tool didn’t find the salt attribute, specified by the saltattribute
parameter, in the directory.
44Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter5
Extension Joiner Tool
Netscape Certificate Management System (CMS) provides many policy plug-in
modules that enable you to add standard and custom X.509 certificate extensions
to end-entity certificates the server issues. Similarly, the wizard that helps you
generate the certificates required by the Certificate Manager, Registration
Manager, Data Recovery Manager, and Online Certificate Status Manager enables
you to select extensions that you want to include in the certificates. Additionally,
thewizardinterfaceandtherequest-approvalpageoftheAgentinterfacecontains
a text area, enabling you to paste any extension i n its MIME-64 encoded format.
Certificate Management System also provides tools that generate MIME-64
encoded blobs for many standard extensions. You can use these tools for
generating MIME-64 encoded blobs for any extensions that you may want to
include in CA and other certificate requests. The tools are located with the rest of
the command-line utilities in this directory:
<server_root>/bin/cert/tools
The text field provided for pasting the extension in general accepts a single
extension blob. If you want to add multiple extensions, you should first join them
to form a single extension blob and then paste the blob into the text field.
The ExtJoiner is a program that joins a sequence of extensions together so that the
final output can be used in the wizard text field or in the request-approval page of
the Agent interface for specifying multiple extensions.
This chapter has the following sections:
•Location (page 46)
•Syntax (page 46)
•Usage (page 46)
45
Location
Location
Syntax
Usage
The ExtJoiner program is located with the rest of the command-line tools in this
directory:
To run the ExtJoiner tool, type the following command:
where <ext_file> specifies the path, including the filename, to files that contain
the base-64 encoded DER encoding of an X.509 extension.
As discussed in the introduction of this chapter, the ExtJoiner program doesn’t
generate an extension in its MIME-64 encoded format, it only joins the extensions
that are in MIME-64 encoded format. The steps below outli ne how you can use the
ExtJoiner to join multiple custom extensions and add the extensions to a
certificate request.
<server_root>/bin/cert/tools
1.Write the appropriate Java programs for the extensions.
2.Join the extensions using ExtJoiner. To do this:
a.Note the file paths to the files that contain the programs for extensions.
b.Open a command window.
c.Run the ExtJoiner, substituting the appropriate file paths. For example, if
you have two extension files named
them to the same directory as the ExtJoiner, the command would look like
java ExtJoiner myExt1 myExt2
this:
You should see a base-64 encoded blob, similar to the one below, of the
Copy the encoded blob, without any modifications, to a file.
46Netscape Certificate Management System Command-Line Tools Guide • May 2002
myExt1 and myExt2 and have copied
3.Verify that the extensions are joined correctly before adding them to a
certificate request. To do this, first you’ll need to convert the binary data to
ASCII format using the
dumping the contents of the base-64 encoded blob using the
For information on the
for the
dumpasn1 utility see, Table 1-1 on page 13.
AtoB utility and then verify the binary data by
dumpasn1 utility.
AtoB utility see, Chapter 7, “ASCII to Binary Tool” and
Here’s how you would do this verification:
a.Go to this directory: <server_root>/bin/cert/tools
b.Enter this command: AtoB <input_file> <output_file>, substituting
<input_file> with the path to the file that contains the base-64 encoded
data in ASCII format (from Step 2) and
<output_file> with the path to
the file to write the base-64 encoded data in binary format.
c.Next, enter this command: dumpasn1 <ouput_file>, substituting
<output_file> with the path to the file to that contains the base-64
encoded data in binary format. Your output should look similar to this:
d.If the output doesn’t appear right, repeat steps 1 through 3 to get the
correct output.
4.Copy the base-64 encoded blob in step 2 (the output generated by the
ExtJoiner) to the CMS wizard screen and generate the certificate or the
certificate signing request (CSR), if submitting the request to another CA.
Chapter 5Extension Joiner Tool47
Usage
48Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter6
Backing Up and Restoring Data
This chapter explains how to back up the Netscape Certificate Management System
(CMS) data and configuration information and how to use the backups to restore
data if there is a need.
The chapter has the following sections:
•Backup and Restore Tools (page 49)
•Backing Up Data (page 50)
•Restoring Data (page 55)
Backup and Restore Tools
Certificate Management System provides tools to backup and restore the data and
configuration for a CMS instance. These tools can be used, for example, to back up
just your CMS data before you upgrade hardware or software on a machine. You
might also use these tools as part of your overall system backup plan, perhaps to
provide more frequent checkpoints of the CMS data than a nightly disk backup
would record.
Since only CMS configuration and data are backed up, you will need to take other
measures to back up data for external PKCS#11 cryptographic or key storage
devices (such as smart card readers). If you rely on an external device for key
storage (for example, to store the CA signing key), make sure that its data is backed
up whenever you back up CMS data. When you restore the CMS data, it will rely
on the external keys still being available. Refer to the PKCS#11 module vendor’s
instructions for how to back up the data.
49
Backing Up Data
The backup and restore tools are simple Perl scripts; most Perl programmers
should find no difficulty in customizing or extending them. Read this chapter to
familiarize yourself with how the scripts work as well as their capabilities and
limitations.
The Perl scripts that perform the backup or restore are called from shell scripts
installed in the
instance:
cmsbackup[.bat] copies all of the pertinent data and configuration files for a
•
CMS instance, the local Administration Server, and local Netscape Directory
Servers that the instance uses into an compressed archive (a zip file). See
“Backing Up Data” on page 50 for instructions on how to use this tool.
cmsrestore[.bat] opens a named archive, extracts the data, and uses it to
•
restore the configuration of a CMS instance. You have the option to restore
everything or to select a subset of the archived data. See “Res toring Data” on
page 55 for instructions on how to use this tool.
Be aware that the backup archivescontain sensitive information (for example, your
CMS key database). Protect the backup archives as carefully as you protect the
server itself. The backups are stored on a local disk by default. To avoid losing both
the current data and the backup because of a disk failure, move the backup
archives to another medium as soon as they are created. If possible, encrypt the
archives or store them on removable media in a secured location.
<server_root>/cert-<instance_id>/ directory of every CMS
BackingUpData
Backing up your data is actually a very simple process. You run the script, and it
creates an archive that you store securely. This section explains what the backup
You should review the log file after each backup to make sure that all phases of the
backup completed successfully. If all or part of the backup fails it is usually due to
a directory that is missing or not readable by the u ser running the backup.
The default temporary backup directory is
/var/tmp (Unix) or C:\Temp (Windows
NT). Ensure that access to this directory is restricted so that no one can intercept
backup files while the archive is being built. You can change the working backup
directory by changing the value of
$backup_path_prefix in CMSBackup.pl.
The non-CMS databases and shared files that are backed up are:
•<server_root>/alias/*
•<server_root>/shared/config/*.conf
The Administration Server files that are backed up are the following files from
<server_root>/admin-serv/config/:
admpw, the Administration Server password cache
•
*.conf, the Configuration files for the server and its associated LDAP data
•
*.db, the certificate and key databases for the Administration Server and
•
secmod.db (database of PKCS#11 modules available to all server instances)
The backup tool will use the Netscape Directory Server
db2bak tool to create a
backup of the CMS server instance internal database directory and the
configuration directory (if it is running locally). Check the Netscape Directory
Server documentation for full details on what this tool does. The data backed up
includes all schema and object class definitions and, of course, all entries in the
directory.
Chapter 6BackingUp and Restoring Data51
Backing Up Data
These CMS global and local class files are Java classes for custom plug-ins used by
CMS servers. To back up this data, all files and subdirectories in the following
directories are backed up:
<server_root>/bin/cert/classes
•
•<server_root>/cert-<instance_id>/classes
The following CMS global configuration files, which are used for access control
and the certificate mapping, are also backed up:
<server_root>/adminacl
•
•<server_root>/httpacl
•<server_root>/userdb
The CMS user interface files and templates are the files used to create the forms end
entities and agents use to interact with CMS servers. All of these files for the
instance you are backing up are in
<server_root>/cert-<instance_id>/web-apps
•
•<server_root>/cert-<instance_id>/emails
The CMS configuration files that get backed up are in
<server_root>/cert-<instance_id>/config. The specific files and their
purposes are:
CMS.cfg, the current master configuration file for the instance.
•
CMS.cfg.*, previous configuration files, available for reverting to an earlier
•
configuration.
*.db, the server instance key and certificate databases.
•
*.ldif, ldif-format files that describe objects in the configuration database.
•
pwcache.db, the server instance password cache.
•
All of the data to be backed up is copied to the temporary backup directory. After
all of the data has been copied, the script archives the entire backup directory into a
compressed archive using
<server_root>/bin/cert/tools/zip). The script deletes the backup directory
zip (a copy of zip is installed in
once the zip archive is created.
52Netscape Certificate Management System Command-Line Tools Guide • May 2002
Backing Up Data
What the Backup Tool Does Not Do
The cmsbackup script backs up only configuration and data related to a single CMS
server instance. You may need to back up other files to recover from a failure
completely, depending on the nature of the failure. For example, if some entries in
your configuration Directory Server become corrupted then the data backed up by
cmsbackup is sufficient to restore the directory to a previous state. If, however, you
suffer a catastrophic disk failure, you will probably have to reinstall or restore
Certificate Management System, Netscape Console, and Netscape Directory Server
binaries and related tools before you use
configuration.
The following is a list of items which may be part of your overall CMS deployment,
but which are not backed up by
•Other instances of CMS servers i n the same server root
Each instance has a copy of the cmsbackup script that backs up only data
related to that instance.
•External PKCS#11 module data
If you use an external PKCS#11 device for key storage, make sure you follow
the vendor’s instructions for backing up its data whenever you back up your
CMS server. It may be possible to extend the
CMSRestore.pl Perl scripts to include this data in the archives used by the
CMS backup tools.
cmsbackup:
cmsrestore to recover your previous
CMSBackup.pl and
•Server binaries, libraries, and tools
These f iles do not change after installation, and a re not backed up. To restore
these files, you can install the software again from the original media. You can
also use a more generic disk backup tool to archive the contents of all
directories beneath the server root.
Running the Backup Tool
Before you run cmsbackup,makesurethat
•You are logged in as a user with permission to run
for the LDAP servers, and to write to the output directory; you may need to
become superuser on a UNIX system or Administrator on a Windows NT
system.
Chapter 6BackingUp and Restoring Data53
cmsbackup,torundb2bak
Backing Up Data
•There is plenty of disk space in the output directory; the size of the backup
archive will vary with the amount of data in your system, so you will learn
from experience how much space you require.
The configuration that you back up, of course, will use all of your current
passwords. You will need to remember the current passwords if you restore this
data after you change some passwords.
To run
1.Log in to the machine where your CMS instance is running and open a
cmsbackup:
command shell.
2.Change to the CMS server instance directory in the server root. For example, if
your server root is
youwanttobackupis
# cd /usr/netscape/servers/cert-cmsinstance
3.Execute the backup script: either cmsbackup on UNIX or cmsbackup.bat on
/usr/netscape/servers and the instance ID of the server
cmsinstance:
Windows NT systems. For example,
# ./cmsbackup
The script will run. Control returns to the command prompt when the script has
finished.
After You Finish a Backup
Immediately after running the backup tool, you should check the log file to make
sure that all systems were archived successfully. The log file is
<server_root>/cert-<instance>/logs/cmsbackup.log
If the any part of the backup was not successful, there will be a message labeled
WARNING or ERROR that tells you why. Most of the time, the problems are the result
of directories or files that are missing or inaccessible to the user running
cmsbackup. If necessary, change the permissions on the required files, delete the
zip archive in the output directory, and run
cmsbackup again.
Once you have a successful zip archive, you should secure it. The output directory
is probably accessible to any user on the system, and it may be on the same
physical disk as the server instance itself. You want to make sure the archive is not
accessible to unauthorized users and that you can use the archive if there is a
system hardware failure. Remember, the archive contains a database of private
keys. Although it is not easy to extract a key from the database without the correct
passwords, you do not want anyone to have the opportunity to try.
54Netscape Certificate Management System Command-Line Tools Guide • May 2002
Move the zip archive to another machine or removable medium. If possible,
encrypt the archive (do not use the private keys stored in your CMS server’s
database, since they may not be available when you need to restore the data). If you
copy the archive to removable media such as tape or CD, make sure the copy is
kept in a limited-access, locked area.
Restoring Data
The purpose of creating back up archives, of course, is to allow you to restore a
previous state of the CMS server instance after a hardware or software failure
corrupts your current state. The restore tool allows you to recover all or part of the
configuration that was backed up. For example, you can use the tool to restore just
the internal database of a CMS server instance.
A special case, automatic restore, allows you to completely restore the
configuration from the latest backup archive quickly and without interaction.
Before You Restore Data
Restoring Data
Before you can restore from a backuparchive,the archive you wantto use h as to be
available on a disk accessible from the server instance directory. If you want to use
the automatic restore feature, you should put the archive in the output directory
where
UNIX).
Note the full path name to the backup archive; in the instructions later it will be
referred to as
<archive_path> might be
You can use the word
thebackuparchive.Ifyouuse
logs/latest_backup to find the path name of the archive. This file is created by
cmsbackup and contains the name of the last archive created. Note that automatic
always causes all data to be restored: you will not be able to select only a subset of
the data.
If you moved the zip archive to another machine or removable medium, copy it
back to the local file system. If you encrypted the archive, decrypt it before you try
to restore the data.
cmsbackup originally created it (C:\Temp on Windows NT or /var/tmp on
<archive_path>. For example, on a UNIX system, the
/var/tmp/CMS_cmsdemo_BACKUP-19991115093827.zip.
automatic instead of a path name to indicate the location of
automatic, the restore tool will read the file
Chapter 6BackingUp and Restoring Data55
Restoring Data
You cannot restore data to a CMS instance that has not been configured. If you
re-installed CMS prior to attempting to restore data, you must configure the new
CMS instance. When you configure the new installation, keep the following points
in mind:
•All services s hould be running on the same network ports as they were when
the backup archive was created. For example, the administration console port
isarandomnumberbydefault;besuretochangethedefaulttothesameport
that your original installation used.
•During configuration, you still need to create new keys and certificates for any
servers that use the internal token. You only need to create these keys to
complete the configuration process. Your signing, SSL, or DRM transport
certificates will be restored (replacing whatever you create during the new
configuration) when you run the restore script.
The user running the restore tool will probably need superuser (UNIX) or
Administrator (Windows NT) privileges. The user running the tool will need
privileges to do the following:
•Read the backup zip archive
•Create a temporary working directory in t he directory where the archive is
located
•Create directories and files in the server root and server instance directories
(for example, if the
•Runthe
bak2db tool for any Netscape Directory Servers that are being res tored
CMS.cfg file needs to be restored)
•(UNIX) Change file ownership of the LDAP database backup files to the
Directory Server user. The Directory Server user is defined by the
parameter in slapd.conf. If the Directory Server user is different from the user
running
cmsrestore, the user running the tool must be able to run chown to
change the owner of the files to the LDAP server user (typically only the
superuser has this privilege).
The process of restoring data will require that some servers be stopped and
restarted. If any of your servers require passwords to start (for example, if they
need to unlock the key database in order to listen for SSL requests), you will be
prompted for the password. If any passwords have changed since you created the
backup archive, make sure you know the password that was valid at the time the
archive was created.
56Netscape Certificate Management System Command-Line Tools Guide • May 2002
localuser
Restoring Data
Running the Restore Tool
To run cmsrestore:
1.Log in to the machine where the CMS instance you want to restore is installed
and open a command shell.
2.Change to the CMS server instance directory in the server root. For example, if
your server root is
youwanttorestoreis
# cd /usr/netscape/servers/cert-cmsinstance
3.
Execute the restore script: either cmsrestore on UNIX or cmsrestore.bat on
Windows NT systems.
/usr/netscape/servers and the inst ance ID of the server
cmsinstance:
You can either provide the
argument
# ./cmsrestore <archive_path> | automatic
automatic (to read the archive path from logs/latest_backup):
If you use automatic as the argument, the restore proceeds automatically; go
to Step 9 when
4.The script asks if you would like to perform a complete or prompted restore.
cmsrestore completes.
Enter
❍c (complete) to completely restore the contents of the archive without
further prompts. Proceed with Step 9 when the restore is complete.
❍p (prompted) to have the script ask you whether you want to restore
specific parts of the archive.
5.If the configuration Directory Server is located in the same server root, the first
prompt asks if you want to restore it. The configuration Directory Server is the
directory used by the Administration Server to store information about
servers, users, and groups.
If you answer
yes, the restore tool stops the Directory Server, restores the data,
then restarts the server. You may be asked to enter a password if one is
required to start the server.
6.Next you are asked if you want to restore selected Administration Server data.
Chapter 6BackingUp and Restoring Data57
Restoring Data
If you answer no, no Administration Server data will be restored; proceed with
the next step.
If you answer
yes, you will be asked three more questions about specific
Administration Server data you want to restore:
a.Main admin data is data in the Administration Server’s configuration
directory.
b.Non-CMS shared data is data in the <server_root>/shared/config
directory.
c.CMS certificate and key databases are the databases in the
<server_root>/alias directory.
After you answer the questions, the Administration Server i s stopped, the data
restored from the archive, and the server is started again. If necessary, you will
be prompted to enter a password to start the Administration Server.
7.Next you are asked if you want to restore the CMS internal database Directory
Server. This is the Directory Server this CMS instance uses as its internal
database.
If you answer
yes, the restore tool stops the Directory Server, restores the data,
then restarts the server. You may be asked to enter a password if one is
required to start the server.
8.Next you are asked if you want to restore selected data for this CMS server
instance.
If you answer
yes, you will be asked four more questions about the following
CMS server instance data that you can restore:
a.Global CMS classes are Java classes that are shared by all CMS servers in
thesameserverroot.
b.Critical CMS data includes the configuration files, certificate and key
databases, and password cache in the
instance.
c.LocalCMSclassesareJavaclassesusedonlybythisserverinstance.
d.Custom CMS UI data includes all HTML files and templates in the
web-apps and emails directory of this CMS instance.
58Netscape Certificate Management System Command-Line Tools Guide • May 2002
config directory for this CMS
Restoring Data
After you answer these questions, the tool stops the CMS server, restores the
data, then restarts the server. You will be asked to enter the single sign-on
password that unlocks the password cache when the server restarts (see
section “Password Cache” in Chapter 8, “Starting and Stopping CMS
Instances” of CMS Installation and Setup Guide .)
9.After the tool finishes restoring data, view the cmsrestore.log file in the
server instance
logs directory.
Review each step to make sure there were no errors in restoring the data. If
there were errors or warnings, you may want to run
cmsrestore again. You
may need to change permissions on some files or manually start some servers
before running
cmsrestore again.
The restore tool deletes the working directory where it unpacked the archive, but it
does not delete the archive itself. You probably will not want to keep the backup
archive on disk. Remember that the backup archive contains sensitive information.
Delete or secure the archive when you are done using it to restore data.
Chapter 6BackingUp and Restoring Data59
Restoring Data
60Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter7
ASCII to Binary Tool
You can use the ASCII to Binary tool to convert ASCII base-64 encoded data to
binary base-64 encoded data.
This chapter has the following sections:
•Location (page 61)
•Syntax (page 61)
•Example (page 62)
Location
Syntax
The tool is located with the rest of the command-line tools in this directory:
<server_root>/bin/cert/tools
To run the ASCII to Binary tool, type the following command:
AtoB[.bat] <input_file> <output_file>
.bat specifies the file extension; this is required only when running the utility
on a Windows NT system.
<input_file> specifies the path to the file that contains the base-64 encoded
data in ASCII format.
<output_file> specifies the path to the file to write the base-64 encoded data
in binary format.
61
Example
Example
AtoB.bat C:\test\data.in C:\test\data.out
The above command takes the base-64 encoded data (in ASCII format) in the file
named
data.out.
data.in and writes the binary equivalent of the data to the file named
62Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter8
Binary to ASCII Tool
You can use the Binary to ASCII tool to convert binary base-64 encoded data to
ASCII base-64 encoded data.
The chapter has the following sections:
•Location (page 63)
•Syntax (page 63)
•Example (page 64)
Location
Syntax
The tool is located with the rest of the command-line tools in this directory:
<server_root>/bin/cert/tools
To run the Binary to ASCII tool, type the following command:
BtoA[.bat] <input-file> <output_file>
.bat specifies the file extension; this is required only when running the utility
on a Windows NT system.
<input_file> specifies the path to the file that contains the base-64 encoded
data in binary format.
<output_file> specifies the path to the file to write the base-64 encoded data
in ASCII format.
63
Example
Example
BtoA.bat C:\test\data.in C:\test\data.out
The above command takes the base-64 encoded data (in binary format) in the file
named
data.out.
data.in and writes the ASCII equivalent of the data to the file named
64Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter9
Pretty Print Certificate Tool
You can use the Pretty Print Certificate tool to print the contents of a certificate
stored as ASCII base-64 encoded data in a human-readable form.
The chapter has the following sections:
•Location (page 65)
•Syntax (page 65)
•Example (page 66)
Location
Syntax
The tool is located with the rest of the command-line tools in this directory:
<server_root>/bin/cert/tools
To run the Pretty Print Certificate tool, type the following command:
The above command takes the ASCII base-64 encoded certificate in the cert.in file
and writes the certificate in the pretty-print form to the output file named
cert.out.
The base-64 encoded certificate (content of the
this: