Command-Line Tools Guide Netscape Certificate Management System Version 6.
Netscape Communications Corporation ("Netscape") and its licensors retain all ownership rights to the software programs 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.
Contents About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 What You Should Already Know . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 What’s in This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Conventions Used in This Guide . . . . . . . . .
Starting Up the CMS 6.01 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 After Upgrading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 4 Chapter 3 Password Cache Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Chapter 7 ASCII to Binary Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 Example . . . . . . . . . . . . . . . .
Netscape 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.
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.
Conventions Used in This Guide • 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.
Where to Go for Related Information • [ ]—Square brackets enclose commands that are optional. Example: PrettyPrintCert [] specifies the path to the file that contains the base-64 encoded certificate. 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.
Where to Go for Related Information • 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: /manual/en/admin/ag/contents.
Where to Go for Related Information • End-Entity Help 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: /cert-/web-apps/ee/manual/ee_guide/con tents.htm For a complete list of CMS documentation, open the /manual/index.html file.
Chapter 1 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-1 Summary of command-line utilities Utility/Tool Function Batch/Shell Scripts located under /bin/cert/upgrade/: Upgrade Utility Updrades from a CMS 4.2, 4.
Table 1-1 Summary of command-line utilities (Continued) Utility/Tool Function certutil (Certificate and Key Database Tool) View and manipulate the certificate database (cert7.db) and key database (key3.db) contents. For details, check the http://www.mozilla.org/projects/security/pki/nss /tools/. site. setpin (PIN Generator tool) Generates PINs for end users for directory- and PIN-based authentication. For details, see Chapter 4, “PIN Generator Tool.
Table 1-1 Summary of command-line utilities (Continued) Utility/Tool Function bin/base/jre/bin/jre Java runtime executable for Netscape Console. bin/cert/jre/bin/jre 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. bin/cert/tools/unzip Decompression utility executable.
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 security tool, as this site is updated often.
Chapter 2 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.
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 CMS Command-Line Tools Guide that was provided with the product; open the /manual/en/cert/tools_guide/backup.htm file. You can also find the CMS 4.5 documentation at this site: http://enterprise.netscape.com/docs/cms/index.html • For instructions to back up a CMS 6.
Before Upgrading Creating Your Previous Internal Database File in LDIF Format After locating your previous CMS internal database file, you need to create it in LDAP Interchange Format (LDIF) format. • Creating an LDIF File for CMS 4.2 or 4.5 Internal Database • Creating an LDIF File for CMS 6.0 Internal Database Creating an LDIF File for CMS 4.2 or 4.5 Internal Database To create a CMS 4.2 or 4.
Before Upgrading The default file name is time stamped and is of the form __.ldif. For example: /usr/netscape/server60/slapd-firefly-db/ldif/2002_04_08_123356.l dif Normalizing Your Previous Internal Database 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.) For example, delete: dn: dc=,dc=netscape,dc=com ...
Upgrading cd /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 /45ToTxt export SERVER_ROOT=<45_server_root> run.sh <45_ldif> > <45_txt> 2. Execute the TxtTo601 command: cd /TxtTo601 export SERVER_ROOT=<601_server_root> run.sh <45_txt> > <601_ldif> Converting the CMS 6.
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 the CMS Installation and Setup Guide for instructions on how to install Certificate Management System. NOTE Later on you will overwrite the CMS 6.01 configuration information, such as keys and subject names, with your previous CMS 4.2, 4.
Upgrading Installing CMS 4.2 or 4.5 Security Databases Install your previous CMS 4.2 or 4.5 security databases by copying them to your new CMS 6.01 installation using the following commands: cp <4x_cert7> \ <601_server_root>/alias/cert---cert7.db cp <4x_key3> \ <601_server_root>/alias/cert---key3.db cp <4x_secmod> <601_server_root>/alias/secmod.db For example: cd /usr/netscape/server42/cert-firefly/config cp cert7.
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--db ldif2db -n userRoot -i <601_ldif> Updating the CMS 6.
After Upgrading ./start-slapd cd <601_server_root>/cert- ./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: /config/server.
After Upgrading 26 Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter 3 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.
Syntax Syntax To run the utility, execute the following command from the /cert- directory: PasswordCache -d -P specifies the current single sign-on password. specifies the path to the certificate database (cert7.db) and key database (key3.db) files. The default path is /alias.
Usage • 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. NOTE You must run the utility from the /cert- directory. The server queries the password cache only during start up, and hence recongnizes the changes you’ve made to the cache only if you restart the server from the command line.
Usage 3. At the prompt, enter the command below, substituting the variables with appropriate values: PasswordCache -d -P add For example, assume your single sign-on password is mySsoPwd, the CMS instance name is demoCA, the host name is cmshost, the string describing the password usage is Bind Password for LDAP Publishing Directory, and the password is myLdapPubPwd.
Usage Deleting an Entry From the Password Cache To delete an entry from the cache: 1. Open a command window. 2. Go to this directory: /cert- 3.
Usage 32 Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter 4 PIN Generator Tool For Netscape Certificate Management System (CMS) to use the authentication plug-in module named UidPwdPinDirAuth your authentication directory must 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-line tool called the PIN Generator. This tool allows you to generate unique PINs for entries in an LDAP-compliant user directory.
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 setpin command and its arguments. For instructions on generating PINs and storing them in your authentication directory, see section “Configuring Authentication for End-User Enrollment” in Chapter 15, “Setting Up End-User Authentication” of CMS Installation and Setup Guide.
The setpin Command • ["binddn=" bindpw=] specifies the user ID that has read and write permission to the LDAP directory; the PIN Generator binds to the directory as this user. 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.
The setpin Command • [gen=RNG-alpha | RNG-alphanum | RNG-printableascii] Use this argument to specify the type of characters for PINs. The characters in the password can be constructed out of alphabetic characters (RNG-alpha), alphanumeric characters (RNG-alphanum), or any printable ASCII characters (printableascii). • [case=upperonly] 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.
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.
How the Tool Works How the Tool Works The Pin Generator allows you to generate PINs for user entries in an LDAP-compliant directory and update the directory with these PINs.
How the Tool Works Figure 4-1 Using an input and output file for the PIN-generation process Examples of output follow: Processing: cn=QA Managers,ou=employees,o=example.com Adding new pin/password dn:cn=QA Managers,ou=employees,o=example.com pin:lDWynV status:notwritten Processing: cn=PD Managers,ou=employees,o=example.com Adding new pin/password dn:cn=PD Managers,ou=employees,o=example.
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-1 PIN Generator status Exit code Description notwritten Specifies that the PINs were not written to the directory, because the write option was not specified on the command line. writefailed Specifies that the tool made an attempt to modify the directory, but the write operation was unsuccessful.
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 directory 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.
How the Tool Works NOTE You cannot provide hashed PINs to the tool. Output File The PIN Generator can capture the output to a text file specified by the output= argument. The captured output will contain a sequence of records and will be in the following format: dn: 1 pin: 1 status: 1 dn: 2 pin: 2 status: 2 ...
How the Tool Works How PINs Are Stored in the Directory Each PIN is concatenated with the corresponding user's LDAP attribute named in the saltattribute argument. If this argument is not specified, the DN of the user is used. Then, this string is hashed with the hash routine specified in the hash argument (the default selection is SHA-1). Then, one byte is prepended to indicate the hash type used.
How the Tool Works Table 4-2 Exit codes returned by the PIN Generator (Continued) Exit code Description 7 Indicates an error parsing command-line arguments. 8 Indicates that the tool could not open the input file specified by the input parameter. 9 Indicates that the tool encountered an internal error. 10 Indicates that the tool found a duplicate entry in the input file specified by the input parameter.
Chapter 5 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.
Location Location The ExtJoiner program is located with the rest of the command-line tools in this directory: /bin/cert/tools Syntax To run the ExtJoiner tool, type the following command: java ExtJoiner ... where specifies the path, including the filename, to files that contain the base-64 encoded DER encoding of an X.509 extension.
Usage 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 AtoB utility and then verify the binary data by dumping the contents of the base-64 encoded blob using the dumpasn1 utility. For information on the AtoB utility see, Chapter 7, “ASCII to Binary Tool” and for the dumpasn1 utility see, Table 1-1 on page 13. Here’s how you would do this verification: a.
Usage 48 Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter 6 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.
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 /cert-/ directory of every CMS instance: • cmsbackup[.
Backing Up Data • Copies non-CMS certificate and key databases and shared files • Copies files required to configure the Netscape Console and Administration Server • Backs up the configuration Directory Server using that server’s db2bak backup utility (if the server is running locally) • Backs up the CMS internal database (Directory Server) using that server’s db2bak backup utility • Copies CMS global and local class files • Copies CMS user interface files and templates • Copies CMS instance c
Backing Up Data These CMS global and local class files are Java classes for custom plug-ins used by CMS servers.
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.
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 cmsbackup: 1.
Restoring Data 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 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 should be running on the same network ports as they were when the backup archive was created.
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 /usr/netscape/servers and the instance ID of the server you want to restore is cmsinstance: # cd /usr/netscape/servers/cert-cmsinstance 3. Execute the restore script: either cmsrestore on UNIX or cmsrestore.bat on Windows NT systems.
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 /shared/config directory. c. CMS certificate and key databases are the databases in the /alias directory.
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.
Restoring Data 60 Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter 7 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 The tool is located with the rest of the command-line tools in this directory: /bin/cert/tools Syntax To run the ASCII to Binary tool, type the following command: AtoB[.bat] .
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.in and writes the binary equivalent of the data to the file named data.out.
Chapter 8 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 The tool is located with the rest of the command-line tools in this directory: /bin/cert/tools Syntax To run the Binary to ASCII tool, type the following command: BtoA[.bat] .
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.in and writes the ASCII equivalent of the data to the file named data.out.
Chapter 9 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 The tool is located with the rest of the command-line tools in this directory: /bin/cert/tools Syntax To run the Pretty Print Certificate tool, type the following command: PrettyPrintCert[.
Example Example PrettyPrintCert.bat C:\test\cert.in C:\test\cert.out 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 cert.
Example 31:F2:CA:C9:16:87:B9:AD:B8:39:69:18:CE:29:81:5F: F3:4D:97:B9:DF:B7:60:B3:00:03:16:8E:C1:F8:17:6E: 7A:D2:00:0F:7D:9B:A2:69:35:18:70:1C:7C:AE:12:2F: 0B:0F:EC:69:CD:57:6F:85:F3:3E:9D:43:64:EF:0D:5F: EF:40:FF:A6:68:FD:DD:02:03:01:00:01: Extensions: Identifier: 2.16.840.1.113730.1.1 Critical: no Value: 03:02:00:A0: Identifier: Authority Key Identifier - 2.5.29.35 Critical: no Key Identifier: EB:B5:11:8F:00:9A:1A:A6:6E:52:94:A9:74:BC:65:CF: 07:89:2A:23: Signature: Algorithm: OID.1.2.840.113549.1.1.5 - 1.
Example 68 Netscape Certificate Management System Command-Line Tools Guide • May 2002
Chapter 10 Pretty Print CRL Tool You can use the Pretty Print CRL tool to print the contents of a CRL stored as ASCII base-64-encoded data in a human-readable form. The chapter has the following sections: • Location (page 69) • Syntax (page 69) • Example (page 70) Location The tool is located with the rest of the command-line tools in this directory: /bin/cert/tools Syntax To run the Pretty Print CRL tool, type the following command: PrettyPrintCrl[.bat] [] .
Example Example PrettyPrintCrl.bat C:\test\crl.in C:\test\crl.out The above command takes the ASCII base-64 encoded CRL in the crl.in file and writes the CRL in the pretty-print form to the output file named crl.out. The base-64 encoded CRL (content of the crl.
Example Serial Number: 0x11 Revocation Date: Wednesday, December 16, 1998 4:51:54 AM Extensions: Identifier: Revocation Reason - 2.5.29.21 Critical: no Reason: Key_Compromise Serial Number: 0x10 Revocation Date: Thursday, December 17, 1998 2:37:24 AM Extensions: Identifier: Revocation Reason - 2.5.29.21 Critical: no Reason: Affiliation_Changed Serial Number: 0xA Revocation Date: Wednesday, November 25, 1998 5:11:18 AM Extensions: Identifier: Revocation Reason - 2.5.29.
Example 72 Netscape Certificate Management System Command-Line Tools Guide • May 2002
Index A adding new entries to the password cache 29 ASCII to Binary tool 61 example 62 location 61 syntax 61 for adding extensions to CMS certificates 45 location 13 Password Cache tool 27 PasswordCache tool 13 PIN Generator 33 Pretty Print Certificate 65 Pretty Print CRL 69 some guidelines 15 summary table 13 conventions used in this book 9 B Binary to ASCII tool 63 example 64 location 63 syntax 63 D deleting entries from the password cache 31 documentation conventions followed 9 dumpasn1 tool 14 C ch
ExtJoiner tool example 46 location 46 syntax 46 fonts used in this book 9 syntax 34 where to find 33 Pretty Print Certificate tool 65 example 66 location 65 syntax 65 Pretty Print CRL tool 69 example 70 location 69 syntax 69 L S listing contents of password cache 29 location of command-line utilities 13 PIN Generator tool 33 setpin command 34 F terms used in this book 9 type styles used in this book 9 typestyles used in this book 9 P password cache tool for managing 27 Password Cache utility 27 add
