Summary of Contents for Netscape NETSCAPE MANAGEMENT SYSTEM 6.2 - COMMAND-LINE
Page 1
Command-Line Tools Guide Netscape Certificate Management System Version 6.2 June 2003...
Page 2
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.
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’s in This Guide SSL cipher suites The purpose of and major steps in the SSL handshake • 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...
Conventions Used in This Guide Chapter 5 “PIN Generator Describes how to use the tool for generating Tool” unique PINs for your users and for populating their directory entries with PINs. Chapter 6 “Extension Joiner Describes how to use the tool for joining Tool”...
Page 10
Conventions Used in This Guide Example: Rotation frequency. From the drop-down list, select the interval at which the server should rotate the active error log file. The available choices are Hourly, Daily, Weekly, Monthly, and Yearly. The default selection is Monthly.
Documentation Documentation All documentation is installed with the product and can be accessed from the help system. Further, the documentation can also be accessed from the installed product in the following directory: <server_root>/manual/en/ The documentation set for CMS includes the following: Managing Servers with Netscape Console Provides background information on basic cryptography concepts and the role of Netscape Console.
Page 12
Documentation Netscape Certificate Management System Command-Line Tools Guide • June 2003...
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.
Page 14
Table 1-1 Summary of command-line utilities (Continued) Utility/Tool Function ExtJoiner (Extension Joiner Tool) A command line utility utilized to join a sequence of extensions together so that the final output can be used in the configuration wizard for specifying extra extensions in default certificates (i. e. - CA certificate, SSL certificate).
Page 15
Table 1-1 Summary of command-line utilities (Continued) Utility/Tool Function A command line utility utilized to send either a KEYGEN or bulkissuance CRMF enrollment request to the bulk issuance interface for the (Bulk Issuance Tool) automatic creation of certificates. View and manipulate the certificate database (cert8.db) and key certutil (Certificate and Key Database Tool) database (key3.db) contents.
Page 16
Table 1-1 Summary of command-line utilities (Continued) Utility/Tool Function Upgrade Utility Upgrades from a CMS 4.2, CMS 4.2 (SP 2), 4.5, 6.0, 6.01, or 6.1 (SP (Upgrade an old CMS version to CMS 1) instance to a CMS 6.2 instance. For details, see Chapter 2, “CMS 6.2) Upgrade Utility.”...
Page 17
Table 1-1 Summary of command-line utilities (Continued) Utility/Tool Function Dumps the contents of binary base-64-encoded data. Note that the dumpasn1 tool is freeware that is packaged with Certificate Management (Display the contents of System for your convenience. For more information about this binary base-64 encoded data) tool, check this site: http://www.cs.auckland.ac.nz/~pgut001/...
Page 18
• 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.
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.2. The utility enables you to upgrade from the following releases of Certificate Management System (CMS) to the CMS 6.2 release: •...
Before Upgrading Before Upgrading Before upgrading from a CMS 4.2, 4.2 (SP 1), 4.2 (SP 1a), 4.2 (SP 2), 4.5, 6.0, or 6.1 (SP 1) instance to a CMS 6.2 instance, you must complete the following tasks: • Backing Up Your Previous CMS Instance Backing Up Your Previous CMS Instance You must backup your existing CMS 4.2, 4.2 (SP 1), 4.2 (SP 1a), 4.2 (SP 2), 4.5, 6.0, 6.01, or 6.1 (SP 1) instance before you can upgrade to CMS 6.2.
Page 21
Upgrading What you do next depends on which version you are converting. Follow the steps below that apply to the version you are converting: For migrating from CMS 4.2/CMS 4.2 (SP 1) or CMS 4.2 (SP 1a): Remove the following file from the new server: <62_server_root>/alias/cert-<instance>-<hostname>-cert8.d Copy the following filefrom the old server: <old_server_root>/cert-<instance>/config/cert7.db...
Page 22
Upgrading Copy the following file from the older server: <old_server_root>/admin-serv/config/secmod.db to the following location in the new server: (overwrite this file) <62_server_root>/alias/secmod.db For migrating from CMS 6.0 or CMS 6.01 or CMS 6.1 (SP 1): Remove the following file from the new server: <62_server_root>/alias/cert-<instance>-<hostname>-cert8.d Copy the following file from the older server: <old_server_root>/alias/cert-<instance>-<hostname>-cert7.
Page 23
Upgrading ----- Password Cache ----- Internal LDAP Database : <password> Internal Key Storage Token : <password> Migrating from CMS 6.0 / CMS 6.01/ CMS 6.1 (SP 1): Go to the following directory: <old_server_root>/cert-<instance>/config Execute the following command: <old_server_root>/bin/cert/tools/PasswordCache <password> -d <alias directory>...
Page 24
Upgrading Generate protection key. To do this, execute the following command: <62_server_root>/bin/cert/tools/PasswordCache <password> -d <alias directory> -P <prefix> -c <file> rekey For example: <62_server_root>/bin/cert/tools/PasswordCache <password> -d <62_server_root>/alias -P cert-<instance>-<hostname>- -c pwcache.db rekey The following will be output to the screen when the command is run: cert/key prefix = cert-<instance>-<hostname>- cert/key db path = <62_server_root>/alias password cache file = pwcache.db...
Page 25
Upgrading Add password tags and their associated passwords (from step 4.) back to the cache (You may need to do this mutiple times). Do this by executing the following command: <62_server_root>/bin/cert/tools/PasswordCache <password> -d <alias directory> -P <prefix> -c <file> -k <key file> add <tag>...
Page 26
Upgrading password cache file = pwcache.db token name = internal PWsdrCache: mToken = internal adding Internal Key Storage Token:<associated_tag_password> PWsdrCache: in addEntry about to read password cache PWsdrCache: after readPWcache() adding new tag: Internal Key Storage Token operation completed for pwcache.db Confirm everything is OK.
Page 27
Upgrading What you do next depends on which version you are converting. Follow the steps below that apply to the version you are converting: Migrating from CMS 4.2 / CMS 4.2 (SP 1) / CMS 4.2 (SP 1a) NOTE: Replace the ca.ocsp_signing.cacertnickname with the ca.signing.cacertnickname (in CMS.cfg) since one does not exist in CMS 4.2 / CMS 4.2 (SP 1) / CMS 4.2 (SP 1a) For example:...
Page 28
Upgrading Go to the following directory: <62_server_root>/slapd-<instance>-db Execute the following db2ldif command to export the internal directory content: db2ldif -n userRoot The LDIF file will be created in the following directory: <62_server_root>/slapd-<instance>-db/ldif Go to the following directory: <62_server_root>/slapd-<instance>-db/ldif Rename the ldif file new.ldif Adjust the LDIF content.
Page 29
Upgrading What you do next depends on which version you are converting. Follow the steps below that apply to the version you are converting: Migrating from CMS 4.2 / CMS 4.2 (SP 1) / CMS 4.2 (SP 1a) Go to the following directory: <62_server_root>/bin/cert/upgrade/42ToTxt Execute the following command: run.sh...
Page 30
Upgrading Go to the following directory: <old_server_root>/slapd-<instance>-db/ldif Move into <old_server_root>/slapd-<instance>-db/ldif/old.txt <62_server_root>/slapd-<instance>-db/ldif Convert into (6.2 format) by running: old.txt old.ldif Unset environment variable ( JAVA_HOME= Set environment variable ( SERVER_ROOT=<62_server_root>, OS_NAME=<platform> Export environment variable ( export SERVER_ROOT, OS_NAME Go to the following directory: <62_server_root>/bin/cert/upgrade/TxtTo61 Execute the following command: run.sh <62_server_root>/slapd-<instance>-db/ldif/old.txt >...
After Upgrading After Upgrading After upgrading to CMS 6.2, access the End-Entity Services and the Agent Services interfaces of the new CMS 6.2 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.
Page 32
After Upgrading Netscape Certificate Management System Command-Line Tools Guide • June 2003...
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 directory (must be run from this <server_root>/cert-<instance_id>/config directory unless the "-c" option is used): PasswordCache <sso_password> -d <certificate/key db directory> [-h <token name>] -P <certificate/key db prefix> [-c <pwcache db directory>] [-k <file containing base-64 encoded key ID>] <command>...
Usage the names known by Certificate Management System: for example, the internal cryptographic module is known as internal, the internal LDAP bind password is known as Internal LDAP Database, and the LDAP publishing bind password for the Certificate Manager is known as CA LDAP Publishing.
Usage PasswordCache <sso_password> -d <certificate/key db directory> -P <certificate/key db prefix> list For example, assume your single sign-on password is , the CMS mySsoPwd instance name is , and the host name is . The command would demoCA cmshost look like this: PasswordCache mySsoPwd -d /usr/netscape/servers/alias -P cert-demoCA-cmshost- list Generating a new Protection Key for the...
Usage Save the value portion of the key id into a local file such as key.txt Save the value portion of the key id into the CMS.cfg file under the variable "pwcKeyid" Adding a New Entry to the Password Cache To add a new entry to the cache: Open a command window.
Usage PasswordCache <sso_password> -d <certificate/key db directory> -P <certificate/key db prefix> -k keyID.txt change <password_name> <password> For example, assume your single sign-on password is , the CMS mySsoPwd instance name is , the host name is , the string describing the demoCA cmshost password usage is...
Chapter 4 AuditVerify About the AuditVerify Tool The AuditVerify tool is used to verify that signed audit logs were signed with the signed audit private signing key, and that the signed audit log has not been compromised. Auditors can verify the authenticity of signed audit logs using the AuditVerify tool.
Audit Verify Tool Syntax As an auditor, create the security database directory in your file system. For example: mkdir dbdir Use the tool to create an empty set of certificate databases in the certutil directory you just created. For example: certutil -d <dbdir>...
Return Values A text file you create containing a comma log_list_file separated list (in chronological order) of the signed audit logs you are verifying (e.g., the content of the log_list_file would look like the following: /user/server/cmsRoot/cert-ca/logs /signedAudit/ca_cert-ca_audit,/us er/server/cmsRoot/cert-ca/logs/si gnedAudit/ca_cert-ca_audit.200302 27102711,/user/server/cmsRoot/cer t-ca/logs/signedAudit/ca_cert-ca_ audit.20030226094015) The prefix to prepend to the certificate and...
Page 42
Using the Audit Verify Tool Create a text file containing a comma-separated list of the files you want to verify. The name of this file will be used in the AuditVerify command to identify this file. In this example this file is called logListFile For example, this file might contain the following contents: auditlog.1213, auditlog.1214, auditlog.1215...
Chapter 5 PIN Generator Tool For Netscape Certificate Management System (CMS) to use the authentication plug-in module named your authentication directory must UidPwdPinDirAuth 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.
The setpin Command The setpin Command You run the PIN Generator by entering the command and its arguments in setpin a command shell and monitoring the output in the shell window. This section gives the syntax for the command and its arguments. For instructions on setpin generating PINs and storing them in your authentication directory, see section “Setting Up Pin Based Enrollment”...
Page 45
The setpin Command Table 5-1 output Redirect stdout to a file write Turn on writing to directory (otherwise, pins will not get written) clobber Overwrite old pins in the directory testpingen Test pin generation mode. testpingen=count debug Turn on debugging, or use debug=attrs for even more optfile Read in options (one per line) from specified file setup...
Page 46
The setpin Command specifies the base DN to be utilized by the LDAP search <LDAP_base_DN> filter. If this argument is not specified, the filter will begin searching from the root. • [length=<PIN_length> | minlength=<minimum_PIN_length> maxlength=<maximum_PIN_length>] Use this argument to specify the exact number or a range of characters that a PIN must contain.
Page 47
The setpin Command 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 want to store PINs as SHA-1 or MD5 hashed values in the directory, be sure to specify an output file for storing PINs in plain text.
Page 48
The setpin Command • [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.
How the Tool Works Example The following command generates PINs for all entries that have the attribute (in their distinguished name) defined in an LDAP directory named that is laiking listening at port . The PIN Generator binds to the directory as user 19000 and starts searching the directory from the node DirectoryManager...
Page 50
How the Tool Works Figure 5-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.com pin:G69uV7 status:notwritten Netscape Certificate Management System Command-Line Tools Guide •...
How the Tool Works Because the PIN Generator makes a lot of changes to your directory, it is important that you specify the correct filter; otherwise, you may change the wrong entries. As a safeguard, a option is provided that you use to enable writing to the write directory after you verify the output;...
Page 52
How the Tool Works The purpose of the input file is multi fold. 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.
How the Tool Works dn:cn=user3, o=example.com pin:3knAg60 <blank line> You cannot provide hashed PINs to the tool. NOTE Output File The PIN Generator can capture the output to a text file specified by the argument. output=<file_name> The captured output will contain a sequence of records and will be in the following format: dn: <user_dn>1 pin: <generated_pin>1...
How the Tool Works • On Unix: • On Windows NT: \r\n How PINs Are Stored in the Directory Each PIN is concatenated with the corresponding user's LDAP attribute named in argument. If this argument is not specified, the DN of the user saltattribute is used.
Page 55
How the Tool Works Table 5-3 Exit codes returned by the PIN Generator (Continued) Exit code Description Indicates that the tool could not bind to the directory as the user specified by the binddn parameter (over SSL). Indicates that the tool could not open the output file specified by the output parameter.
Page 56
How the Tool Works Netscape Certificate Management System Command-Line Tools Guide • June 2003...
Chapter 6 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: <server_root>/bin/cert/tools Syntax To run the tool, type the following command: ExtJoiner java ExtJoiner <ext_file0> <ext_file1> ... <ext_fileN> where specifies the path, including the filename, to files that contain <ext_file>...
Page 59
Usage 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 utility and then verify the binary data by AtoB dumping the contents of the base-64 encoded blob using the utility.
Page 60
Usage Netscape Certificate Management System Command-Line Tools Guide • June 2003...
Chapter 7 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: •...
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.
Backing Up Data What the Backup Tool Does There is a script or batch file installed in the instance directory of every CMS instance. This file calls the Perl script (using a Perl 5.005 interpreter <server_root>/bin/cert/tools/CMSBackup.pl bundled with Certificate Management System). does the following: CMSBackup.pl •...
Page 64
Backing Up Data • , the Configuration files for the server and its associated LDAP data *.conf The backup tool will use the Netscape Directory Server tool to create a db2bak backup of the CMS server instance internal database directory and the configuration directory (if it is running locally).
Backing Up Data 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 (a copy of is installed in ).
Backing Up Data • You are logged in as a user with permission to run , to run cmsbackup db2bak 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.
Signing Backup Data Using cmsutil 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.
Page 68
Signing Backup Data Using cmsutil Invoke a command-line interface such as a telnet session. From the command line, assuming a Bourne Shell ("sh") on a Solaris system, set and export the LD_LIBRARY_PATH environment variable: LD_LIBRARY_PATH=<server_root>/bin/cert/lib:$LD_LIBRARY_PATH export LD_LIBRARY_PATH From the command line, assuming a Bourne Shell ("sh") on a Solaris system, set and export the PATH environment variable: PATH=<server_root>/bin/cert/tools:$PATH export PATH...
Verifying Signed Backup Data using cmsutil Sign the CMS backup data file by executing the following command: cmsutil -S -N <nickname of EMAIL Signing user certificate> -T -i /var/tmp/<CMS backup data file> -o /var/tmp/<CMS backup data file signature file> -d <server_root>/alias -p <password>...
Restoring Data Import the EMAIL Signing user certificate and corresponding key from the PKCS #12 file specified in “Signing Backup Data Using cmsutil,” on page 67 into this respectfully by executing the following cert8.db key3.db command: pk12util -i <PKCS #12 file> -d . Execute the following command: cd /var/tmp Execute the following command:...
Restoring Data Before You Restore Data Before you can restore from a backup archive, the archive you want to use has 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 originally created it ( on Windows NT or...
Restoring Data • 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.
Page 73
Restoring Data Execute the restore script: either on UNIX or cmsrestore cmsrestore.bat Windows NT systems. You can either provide the as an argument or use the <archive_path> argument (to read the archive path from automatic logs/latest_backup # ./cmsrestore <archive_path> | automatic For example, # ./cmsrestore \ /var/tmp/CMS_cmsdemo_BACKUP-19991115093827.zip...
Page 74
Restoring Data Non-CMS shared data is data in the <server_root>/shared/config directory. CMS certificate and key databases are the databases in the directory. <server_root>/alias After you answer the questions, the Administration Server is 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.
Page 75
Restoring Data 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 again. You cmsrestore may need to change permissions on some files or manually start some servers before running again.
Page 76
Restoring Data Netscape Certificate Management System Command-Line Tools Guide • June 2003...
Chapter 8 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,” on page 77 • “Syntax,” on page 77 •...
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 and writes the binary equivalent of the data to the file named data.in data.out Netscape Certificate Management System Command-Line Tools Guide • June 2003...
Chapter 9 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,” on page 79 • “Syntax,” on page 79 •...
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 and writes the ASCII equivalent of the data to the file named data.in data.out Netscape Certificate Management System Command-Line Tools Guide • June 2003...
Chapter 10 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,” on page 81 •...
Examples specifies the path to the file to write the certificate. This <output_file> argument is optional; if you don’t specify an output file, the certificate information is written to the standard output. Examples PrettyPrintCert.bat C:\test\cert.in C:\test\cert.out The above command takes the ASCII base-64 encoded certificate in the file cert.in and writes the certificate in the pretty-print form to the output file named...
Chapter 11 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,” on page 85 •...
Example Example PrettyPrintCrl.bat C:\test\crl.in C:\test\crl.out The above command takes the ASCII base-64 encoded CRL in the file and crl.in writes the CRL in the pretty-print form to the output file named crl.out The base-64 encoded CRL (content of the file) would look similar to this: crl.in -----BEGIN CRL----- MIIBkjCBAIBATANBgkqhkiG9w0BAQQFADAsMREwDwYDVQQKEwhOZXRzY2FwZTEXMBUG...
Page 87
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...
Page 88
Example Netscape Certificate Management System Command-Line Tools Guide • June 2003...
Need help?
Do you have a question about the NETSCAPE MANAGEMENT SYSTEM 6.2 - COMMAND-LINE and is the answer not in the manual?
Questions and answers