Netscape MANAGEMENT SYSTEM 6.0 - COMMAND-LINE Manual

Command-line tools guide
Table of Contents

Advertisement

Quick Links

Command-Line Tools Guide
Netscape Certificate Management System
Version 6.0
March 2002

Advertisement

Table of Contents
loading
Need help?

Need help?

Do you have a question about the NETSCAPE MANAGEMENT SYSTEM 6.0 - COMMAND-LINE and is the answer not in the manual?

Questions and answers

Summary of Contents for Netscape NETSCAPE MANAGEMENT SYSTEM 6.0 - COMMAND-LINE

  • Page 1 Command-Line Tools Guide Netscape Certificate Management System Version 6.0 March 2002...
  • 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.
  • Page 3: Table Of Contents

    Contents About This Guide ............. . . 9 What You Should Already Know .
  • Page 4 Arguments ............... 28 Example .
  • Page 5 Syntax ................63 Example .
  • Page 6 Command Syntax ..............97 Command Options .
  • Page 7 Export Policy and Step-up ............131 Examples .
  • Page 8 Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 9: About This Guide

    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: •...
  • Page 10: What's In This Guide

    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, including various types of digital certificates...
  • Page 11: Conventions Used In This Guide

    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.
  • Page 12 Conventions Used in This Guide • 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.
  • Page 13: Where To Go For Related Information

    Where to Go for Related Information Where to Go for Related Information This section summarizes the documentation that ships with Certificate Management System, using these conventions: • is the directory where the CMS binaries are kept (specified <server_root> during installation). •...
  • Page 14 Where to Go for Related Information • CMS Agent’s Guide 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 contents.htm •...
  • Page 15: Chapter 1 Command-Line Tools

    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 16 Summary of command-line utilities (Continued) Table 1-1 Utility/Tool Function Kills or terminates system processes in Windows NT. For details, killproc see Chapter 3, “Kill Process Tool.” (Kill Process Tool) Generates PINs for end users for directory- and PIN-based setpin authentication. For details, see Chapter 4, “PIN Generator Tool.” (PIN Generator tool) Digitally signs any file, including log files.
  • Page 17 Summary of command-line utilities (Continued) Table 1-1 Utility/Tool Function Decompression utility executable. bin/cert/tools/unzip Compression utility executable. bin/cert/tools/zip perl scripting language executable. install/perl , and tools are AtoB BtoA PrettyPrintCert PrettyPrintCrl dumpasn1 useful for converting back and forth between various encodings and formats you may encounter when dealing with keys and certificates.
  • Page 18 Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 19: Chapter 2 Password Cache Utility

    Chapter 2 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.
  • Page 20: Syntax

    Syntax Syntax To run the utility, execute the following command from the directory: <server_root>/cert-<instance_id> PasswordCache <sso_password> -d <certificate/key db directory> -P <certificate/key db prefix> <command> specifies the current single sign-on password. <sso_password> specifies the path to the certificate <certificate/key db directory> database ( ) and key database ( ) files.
  • Page 21: Listing The Contents Of The Password Cache

    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. You must run the utility from the NOTE directory. <server_root>/cert-<instance_id> 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.
  • Page 22: Changing The Password Of An Entry In The Password Cache

    Usage At the prompt, enter the command below, substituting the variables with appropriate values: PasswordCache <sso_password> -d <certificate/key db directory> -P <certificate/key db prefix> add <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...
  • Page 23: Deleting An Entry From The Password Cache

    Usage Deleting an Entry From the Password Cache To delete an entry from the cache: Open a command window. Go to this directory: <server_root>/cert-<instance_id> At the prompt, enter the command below, substituting the variables with appropriate values: PasswordCache <sso_password> -d <certificate/key db directory> -P <certificate/key db prefix>...
  • Page 24 Usage Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 25: Chapter 3 Kill Process Tool

    Chapter 3 Kill Process Tool When running Netscape Certificate Management System (CMS) on a Windows machine, if an error causes the server to become unresponsive and all attempts to stop it from Netscape Console fail, it may be necessary to kill the server process manually.
  • Page 26: Usage

    Usage Usage On a Windows NT system, the CMS server process will have file extension .exe and will be listed in the Windows NT Task Manager. However, because it is a system process, you cannot terminate it from the Task Manager. Instead, you should terminate it using the command-line tool.
  • Page 27: Chapter 4 Pin Generator Tool

    Chapter 4 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.
  • Page 28: The Setpin Command

    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 “Configuring Authentication for End-User Enrollment”...
  • Page 29 The setpin Command • ["binddn=<user_id>" bindpw=<bind_password>] specifies the user ID that has read and write permission to the <user_id> LDAP directory; the PIN Generator binds to the directory as this user. specifies the password for the user ID that has read and <bind_password>...
  • Page 30 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 ( ), or any printable ASCII characters RNG-alphanum printableascii •...
  • Page 31: Example

    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;...
  • Page 32: How The Tool Works

    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. To run the command, you need at a minimum to specify the following: setpin •...
  • Page 33 How the Tool Works Using an input and output file for the PIN-generation process Figure 4-1 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 Because the PIN Generator makes a lot of changes to your directory, it is important that you specify the correct filter;...
  • Page 34: Input File

    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. PIN Generator status Table 4-1 Exit code Description Specifies that the PINs were not written to the directory, because the write notwritten option was not specified on the command line.
  • Page 35 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.
  • Page 36: Output File

    How the Tool Works 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...
  • Page 37: How Pins Are Stored In The Directory

    How the Tool Works 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. Then, this string is hashed with the hash routine specified in the hash argument (the default selection is SHA-1).
  • Page 38 How the Tool Works Exit codes returned by the PIN Generator (Continued) Table 4-2 Exit code Description Indicates an error parsing command-line arguments. Indicates that the tool could not open the input file specified by the input parameter. Indicates that the tool encountered an internal error. Indicates that the tool found a duplicate entry in the input file specified by the input parameter.
  • Page 39: Chapter 5 Extension Joiner Tool

    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.
  • Page 40: Location

    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 41 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 42 Usage Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 43: Chapter 6 Backing Up And Restoring Data

    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: •...
  • Page 44: Backing Up Data

    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.
  • Page 45 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 backup db2bak utility (if the server is running locally) •...
  • Page 46 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: •...
  • Page 47: What The Backup Tool Does Not Do

    Backing Up Data What the Backup Tool Does Not Do script backs up only configuration and data related to a single CMS cmsbackup 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 is sufficient to restore the directory to a previous state.
  • Page 48: After You Finish A Backup

    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.
  • Page 49: Restoring Data

    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.
  • Page 50 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: •...
  • Page 51: Running The Restore Tool

    Restoring Data Running the Restore Tool To run cmsrestore Log in to the machine where the CMS instance you want to restore is installed and open a command shell. Change to the CMS server instance directory in the server root. For example, if your server root is and the instance ID of the server /usr/netscape/servers...
  • Page 52 Restoring Data If you answer , no Administration Server data will be restored; proceed with the next step. If you answer , you will be asked three more questions about specific Administration Server data you want to restore: Main admin data is data in the Administration Server’s configuration directory.
  • Page 53 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”...
  • Page 54 Restoring Data Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 55: Chapter 7 Ascii To Binary Tool

    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 55) • Syntax (page 55) • Example (page 56) Location The tool is located with the rest of the command-line tools in this directory:...
  • Page 56: Example

    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 • March 2002...
  • Page 57: Chapter 8 Binary To Ascii Tool

    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 57) • Syntax (page 57) • Example (page 58) Location The tool is located with the rest of the command-line tools in this directory:...
  • Page 58: Example

    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 • March 2002...
  • Page 59: Chapter 9 Pretty Print Certificate Tool

    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 59) •...
  • Page 60: Example

    Example Example 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 cert.out The base-64 encoded certificate (content of the file) would look similar to cert.in this: -----BEGIN CERTIFICATE-----...
  • Page 61 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.2.840.113549.1.1.5 Signature: 3E:8A:A9:9B:D1:71:EE:37:0D:1F:A0:C1:00:17:53:26: 6F:EE:28:15:20:74:F6:C5:4F:B4:E7:95:3C:A2:6A:74: 92:3C:07:A8:39:12:1B:7E:C4:C7:AE:79:C8:D8:FF:1F: D5:48:D8:2E:DD:87:88:69:D5:3A:06:CA:CA:9C:9A:55: DA:A9:E8:BF:36:BC:68:6D:1F:2B:1C:26:62:7C:75:27: E2:8D:24:4A:14:9C:92:C6:F0:7A:05:A1:52:D7:CC:7D: E0:9D:6C:D8:97:3A:9C:12:8C:25:48:7F:51:59:BE:3C: 2B:30:BF:EB:0A:45:7D:A6:49:FB:E7:BE:04:05:D6:8F: Chapter 9 Pretty Print Certificate Tool...
  • Page 62 Example Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 63: Chapter 10 Pretty Print Crl Tool

    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 63) •...
  • Page 64: Example

    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 65 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 66 Example Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 67: Chapter 11 Certificate Database Tool

    Chapter 11 Certificate Database Tool Certificate Database Tool is a command-line utility that can create the certificate database file ( for Netscape Certificate Management System (CMS). The cert7.db) utility can also list, generate, modify, or delete certificates within the file. Certificate database management tasks are part of a process that typically also involves managing key databases ( files).
  • Page 68: Syntax

    Syntax Syntax To run Certificate Database Tool, type the following command: option [arguments] certutil where options and arguments are combinations of the options and arguments listed in the following section. Each command takes one option. Each option may take zero or more arguments. To see a usage string, issue the command without options, or with the option.
  • Page 69 Syntax Table 11-1 Command options and their arguments (Continued) Display a list of the options and arguments used by Certificate Database Tool. Argument Use ASCII format or allow the use of ASCII format for input or output. This formatting follows RFC #1113. For certificate requests, ASCII output defaults to standard output unless redirected.
  • Page 70 Syntax Table 11-1 Command options and their arguments (Continued) Display detailed information when validating a certificate with the -V option. serial-number Assign a unique serial number to a certificate being created. This operation should be performed by a CA. The default serial number is 0 (zero). Serial numbers are limited to integers.
  • Page 71 Syntax Table 11-1 Command options and their arguments (Continued) certusage Specify a usage context to apply when validating a certificate with the -V option. The contexts are the following: C (as an SSL client) V (as an SSL server) S (as an email signer) R (as an email recipient) valid-months Set the number of months a new certificate will be valid.
  • Page 72: Usage

    Usage Table 11-1 Command options and their arguments (Continued) Add an authority key ID extension to a certificate that is being created or added to a database. This extension supports the identification of a particular certificate, from among multiple certificates associated with one subject name, as the correct issuer of a certificate.
  • Page 73: Examples

    Examples • Adding a certificate to an existing database: certname trustargs tokenname certdir -A -n ] [-d ] [-a] cert-request-file • Listing all certificates or a named certificate: certname certdir -L [-n ] [-d ] [-r] [-a] • Validating a certificate: certname validity-time certusage...
  • Page 74: Listing Certificates In A Database

    Examples Listing Certificates in a Database This example lists all the certificates in the file in the specified directory: cert7.db certdir certutil -L -d Certificate Database Tool displays output similar to the following: Certificate Name Trust Attributes Uptime Group Plc. Class 1 CA C,C, VeriSign Class 1 Primary CA VeriSign Class 2 Primary CA...
  • Page 75: Creating A Certificate

    Examples certutil -R -s "CN=John Smith, O=Example Corporation, L=Mountain View, ST=California, C=US" -p "650-555-8888" -k e95c -o e95c.req -d certdir Before it creates the request file, Certificate Database Tool prompts you for a password: Enter Password or Pin for "Communicator Certificate DB": Creating a Certificate A valid certificate must be issued by a trusted CA.
  • Page 76: Validating A Certificate

    Examples Validity: Not Before: Thu Mar 12 00:10:40 1998 Not After: Sat Sep 12 00:10:40 1998 Subject: CN=John Smith, O=Example Corporation, L=Mountain View, ST=California, C=US Subject Public Key Info: Public Key Algorithm: PKCS #1 RSA Encryption RSA Public Key: Modulus: 00:da:53:23:58:00:91:6a:d1:a2:39:26:2f:06:3a: 38:eb:d4:c1:54:a3:62:00:b9:f0:7f:d6:00:76:aa: 18:da:6b:79:71:5b:d9:8a:82:24:07:ed:49:5b:33:...
  • Page 77 Examples certutil -V -n jsmith@example.com -b 9803201212Z -u SR -e -l certdir Certificate Database Tool shows results similar to Certificate:’jsmith@example.com’ is valid. UID=jsmith, E=jsmith@example.com, CN=John Smith, O=Example Corporation, C=US : Expired certificate UID=jsmith, E=jsmith@example.com, CN=John Smith, O=Example Corporation, C=US : Certificate not approved for this operation Chapter 11 Certificate Database Tool...
  • Page 78 Examples Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 79: Chapter 12 Key Database Tool

    Chapter 12 Key Database Tool Key Database Tool is a command-line utility that can modify the key database file ) of Netscape Certificate Management System (CMS). You can use the key3.db utility to create or change the database password, generate new public and private key pairs, display the contents of the database, or delete key pairs from the database.
  • Page 80: Syntax

    Syntax Syntax To run Key Database Tool, type the command option [arguments] keyutil where option and arguments are combinations of the options and arguments listed in the following section. Each command takes one option. Each option may take zero or more arguments. To see a usage string, issue the command without options, or with the option.
  • Page 81 Syntax Table 12-1 Description of options and arguments (Continued) Delete a private key from a key database. Specify the key to delete with the -k argument. Specify the database from which to delete the key with the -d argument. Use the -t argument to specify explicitly whether to delete a DSA or an RSA key.
  • Page 82: Usage

    Usage Table 12-1 Description of options and arguments (Continued) List DSA as well as RSA keys when listing keys in the key database. pqgfile Read an alternate PQG value from the specified file when generating DSA key pairs. If this argument is not used, Key Database Tool generates its own PQG value.
  • Page 83: Examples

    Examples • Displaying public key information from the database: shortkeyID tokenname -P -k [-t rsa|dsa] [-h keydir password-file ] [-w • Deleting private keys from a key database file: shortkeyID tokenname -D -k [-t rsa|dsa] [-h keydir password-file ] [-w •...
  • Page 84: Generating A New Key

    Examples Generating a New Key This example generates a new key in a key database: keydir keyutil -G -d Key Database Tool then displays the following: ---------------------------------------------------- Netscape Communications Corporation Key Generation -------------------------------------------------------- Welcome to the key generator. With this program, you can generate the public and private keys that you use for secure communications.
  • Page 85: Displaying Public Key Information

    Examples Displaying Public Key Information This example prints the public key’s information: keydir keyutil -P -k e95c -d The public key information appears after you give the correct password: Password: It’s the first key found. RSA Public-Key: modulus: 00:e9:5c:4a:73:74:39:22:6d:c6:da:4e:b3:1f:01:26:9d:be: d1:74:ae:cd:c7:7d:65:f9:1d:31:1f:71:fb:60:d0:45:46:5f: 5a:19:e7:61:1e:e7:ce:9f:4a:13:4e:d6:e9:06:90:2a:ba:bd: 0b:5f:7b:a3:28:21:1e:0f:1c:f4:3a:ba:3a:8f:0b:e1:99:91: cc:e8:fd:17:d2:1c:66:13:6b:95:27:b1:eb:bc:9c:e6:7b:f0:...
  • Page 86: Deleting A Private Key

    Examples Deleting a Private Key This example deletes a private key from the key database: keydir keyutil -D -k e95c -d When you delete keys, be sure to remove any certificates associated with those keys from the certificate database by using the Certificate Database Tool. Netscape Certificate Management System Command-Line Tools Guide •...
  • Page 87: Chapter 13 Netscape Signing Tool

    Chapter 13 Netscape Signing Tool This chapter describes how to use version 1.3 of Netscape Signing Tool ( signtool on the command line) to digitally sign software, including binary files intended for distribution via SmartUpdate, Java class files, and JavaScript scripts. Version 1.3 includes all the capabilities of, and is fully compatible with, previous versions of Netscape Signing Tool (.50, .60, 1.0, 1.1, and 1.2).
  • Page 88: What Is Netscape Signing Tool

    Introduction to Netscape Signing Tool • Object-Signing Certificates For a complete introduction to object signing technology, see Netscape Object Signing: Establishing Trust for Downloaded Software at this URL: http://developer.netscape.com/docs/manuals/signedobj/trust/index.ht What Is Netscape Signing Tool? Netscape Signing Tool is a stand-alone command-line tool that creates digital signatures and uses the Java Archive (JAR) format to associate them with files in a directory.
  • Page 89: Jar Format And Jar Archives

    Introduction to Netscape Signing Tool JAR Format and JAR Archives The Java Archive (JAR) format is a set of conventions for associating digital signatures, installer scripts, and other information with files in a directory. Signing tools such as Netscape Signing Tool allow you to sign files using the JAR format and package them as a single JAR file.
  • Page 90: What Signing A File Means

    Introduction to Netscape Signing Tool What Signing a File Means If you have a signing certificate, you can use Netscape Signing Tool to digitally sign files and package them as a JAR file. An object-signing certificate is a special kind of certificate that allows you to associate your digital signature with one or more files.
  • Page 91: Using Netscape Signing Tool

    Using Netscape Signing Tool • CA server software running on your corporate intranet or extranet. Netscape Certificate Management System provides a complete management solution for creating, deploying, and managing certificates, including CAs that issue object-signing certificates. You must also have a certificate for the CA that issues your signing certificate before you can sign files.
  • Page 92: Getting Ready To Use Netscape Signing Tool

    Using Netscape Signing Tool Getting Ready to Use Netscape Signing Tool Before using Netscape Signing Tool, you must have the executable in signtool your path environment variable. You must also have an object-signing certificate. Netscape Signing Tool includes an option that allows you to generate an object-signing certificate for testing purposes.
  • Page 93: Listing Available Certificates

    Using Netscape Signing Tool If you are using Windows 95 or NT, the executable doesn't know where signtool your certificates are, so either put the files in the current key3.db cert7.db directory and use “ ” or use to point to the directory in which they are located.
  • Page 94: Signing A File

    Using Netscape Signing Tool Verisign Object Signing Cert Issued by: VeriSign, Inc. - Verisign, Inc. Expires: Tue May 19, 1998 test object signing cert Issued by: test object signing cert (Signtool 1.0 Testing Certificate (960187691)) Expires: Sun May 17, 1998 --------------------------------------- For a list including CAs, use "signtool -L"...
  • Page 95: Using Netscape Signing Tool With A Zip Utility

    Using Netscape Signing Tool Test the archive you just created. % signtool -v testjar.jar using certificate directory: /u/jsmith/.netscape archive "testjar.jar" has passed crypto verification. status path ------------ ------------------- verified test.f You can also use Netscape Signing Tool from within a script to automate some aspects of signing.
  • Page 96 Using Netscape Signing Tool • If you are signing metadata only and not files, you still need to create a blank directory for Netscape Signing Tool to sign. • When using the Windows NT version of Netscape Signing Tool, always use a relative path.
  • Page 97: Signtool Syntax And Options

    SignTool Syntax and Options SignTool Syntax and Options This section summarizes the syntax and options for Netscape Signing Tool 1.3. • Command Syntax • Command Options • Command File Syntax • Command File Keywords and Example Command Syntax To run Netscape Signing Tool, type signtool options where options can be any sequence of the options listed in this chapter.
  • Page 98 SignTool Syntax and Options Table 13-1 Description of options Specifies the compression level for the -J or -Z option. The symbol # represents a number from 0 to 9, where 0 means no compression and 9 means maximum compression. The higher the level of compression, the smaller the output but the longer the operation takes.
  • Page 99 SignTool Syntax and Options Table 13-1 Description of options -k key ... directory Specifies the nickname (key) of the certificate you want to sign with and signs the files in the specified directory. The directory to sign is always specified as the last command-line argument.
  • Page 100 SignTool Syntax and Options Table 13-1 Description of options Signs a directory of HTML files containing JavaScript and creates as many archive files as are specified in the HTML tags. Even if signtool creates more than one archive file, you need to supply the key database password only once. The -J option is available only in Netscape Signing Tool 1.0 and later versions.
  • Page 101 SignTool Syntax and Options Table 13-1 Description of options Lists the PKCS #11 modules available to signtool, including smart cards. The -M option is available in Netscape Signing Tool 1.0 and later versions only. For information on using Netscape Signing Tool with smart cards, see “Using Netscape Signing Tool with Smart Cards”...
  • Page 102: Command File Syntax

    SignTool Syntax and Options Table 13-1 Description of options Tells signtool not to store the signing time in the digital signature. This option is useful if you want the expiration date of the signature checked against the current date and time rather than the time the files were signed. -Z jarfile Creates a JAR file with the specified name.
  • Page 103 SignTool Syntax and Options Keyword Value Same as -j option. javascriptdir Same as -J option. htmldir Nickname of certificate, as with -k and -l -k options. certname The directory to be signed, as with -k option. signdir Same as -l option. Value is ignored, but = sign must be list present.
  • Page 104: Generating Test Object-Signing Certificates

    Generating Test Object-Signing Certificates where somefile contains the following lines: certdir=c:\netscape\users\james certname=mycert jarfile=myjar.jar signdir=signdir outfile=output.txt Generating Test Object-Signing Certificates Netscape Signing Tool allows you to create object-signing certificates for testing purposes. This section describes how to create and use such test certificates. Unlike certificates normally used to sign finished code to be distributed over a network, the test certificates created with Netscape Signing Tool are not signed by a recognized certificate authority.
  • Page 105 Generating Test Object-Signing Certificates Warning If you intend to install the new key pair and certificate in the Communicator databases, you must exit Communicator before using Netscape Signing Tool to generate the object-signing certificate. Otherwise, you risk corrupting your certificate and key databases. Certificates contain standard information about the entity they identify, such as the common name and organization name.
  • Page 106: Using Netscape Signing Tool With Smart Cards

    Using Netscape Signing Tool with Smart Cards Using Netscape Signing Tool with Smart Cards This section describes how to use smart cards from within Netscape Signing Tool to digitally sign files. • What Is a Smart Card? • Setting Up a Smart Card •...
  • Page 107 Using Netscape Signing Tool with Smart Cards Click Cryptographic Modules in the left frame. Click the Add button. Type an appropriate name for the module you want to add in the box labeled Security Module Name. Type the name of the driver that was supplied with your smart card in the box labeled Security Module File.
  • Page 108: Using The -M Option To List Smart Cards

    Using Netscape Signing Tool with Smart Cards Using the -M Option to List Smart Cards You can use the option to list the PKCS #11 modules, including smart cards, that are available to signtool % signtool -d "c:\netscape\users\jsmith" -M using certificate directory: c:\netscape\users\<username> Listing of PKCS11 modules ----------------------------------------------- 1.
  • Page 109: Netscape Signing Tool And Fips-140-1

    Netscape Signing Tool and FIPS-140-1 To see fully qualified certificate names when you run Communicator, click the Security button in Navigator, then click Yours under Certificates in the left frame. Fully qualified names are of the format smart card:certificate, for example "...
  • Page 110: Verifying Fips Mode

    Netscape Signing Tool and FIPS-140-1 After switching the Navigator cryptographic module to FIPS mode, you have two choices: • Use the same security module database from Netscape Signing Tool (by option). specifying the same directory with the • Make a copy of Communicator's security module database and place it in Netscape Signing Tool's database directory.
  • Page 111: Answers To Common Questions

    Answers to Common Questions Answers to Common Questions This section answers the most common technical questions regarding Netscape Signing Tool. Netscape Signing Tool, or Communicator, fails to report the presence of a particular certificate in the database, even though that certificate should be there.
  • Page 112 Answers to Common Questions Click Import a Certificate and give the database password. Select a certificate file to open and give the certificate’s password. Repeat steps 9 and 10 for each certificate to be re-imported. The certificate needed to sign an object is in the certificate database, but Netscape Signing Tool’s options report “Unable to find issuer certificate”...
  • Page 113 Answers to Common Questions Click the Security Info button on Communicator’s toolbar. Click Yours under Certificates and select a certificate to rename. Click Export and save a PKCS #12 copy of the certificate to a safe location (if no copy already exists). This copy is needed if replacement fails. Click Delete and remove the certificate from the certificate database.
  • Page 114 Answers to Common Questions Although certificates expire, valid signatures do not. Signature validation is based on the date of the signature rather than the time verification occurs. If a certificate chain was valid at signing, Communicator will continue to recognize that signature even after certificates in that chain expire.
  • Page 115: Chapter 14 Ssl Debugging Tool

    Chapter 14 SSL Debugging Tool SSL Debugging Tool is an SSL-aware command-line proxy. It watches TCP connections and displays the data going by. If a connection is SSL, the data display includes interpreted SSL records and handshaking information. This chapter has the following sections: •...
  • Page 116: Syntax

    Syntax The tool cannot and does not decrypt any encrypted message data. You use the tool to look at the plain text and binary data that are part of the handshake procedure, before the secure connection is established. Syntax To run SSL Debugging Tool, type this command in a command shell: port] hostname:port ssltap -vhfsxl...
  • Page 117: Examples

    Examples Table 14-1 Description of command options (Continued) Turn on looping; that is, continue to accept connections rather than stopping after the first connection is complete. Change the default rendezvous port (1924) to another port. The following are well-known port -p port numbers: HTTP 80...
  • Page 118: Example 1

    Examples The raw data stream is sent to standard output and is not interpreted in any way. This can result in peculiar effects, such as sounds, flashes, and even crashes of the command shell window. To output a basic, printable interpretation of the data, use option, or, if you are looking at an SSL connection, the option.
  • Page 119 Examples (0x000006) SSL3/RSA/RC2CBC40/MD5 session-id = { } challenge = { 0xec5d 0x8edb 0x37c9 0xb5c9 0x7b70 0x8fe9 0xd1d3 0x2592 } <-- [ SSLRecord { 0: 16 03 00 03 |..type = 22 (handshake) version = { 3,0 } length = 997 (0x3e5) handshake { 0: 02 00 00 46 |...F...
  • Page 120 Examples type = 12 (server_key_exchange) length = 202 (0x0000ca) 0: 0e 00 00 00 |..type = 14 (server_hello_done) length = 0 (0x000000) --> [ SSLRecord { 0: 16 03 00 00 |..D type = 22 (handshake) version = { 3,0 } length = 68 (0x44) handshake {...
  • Page 121 Examples <-- [ SSLRecord { 0: 16 03 00 00 |..8 type = 22 (handshake) version = { 3,0 } length = 56 (0x38) < encrypted > --> [ SSLRecord { 0: 17 03 00 01 |..type = 23 (application_data) version = { 3,0 } length = 287 (0x11f)
  • Page 122: Example 2

    Examples Example 2 option turns on SSL parsing. Because the option is not used in this example, undecoded values are output as raw data. The output is routed to a text file. Command ssltap.exe -s -p 444 interzone.mcom.com:443 > s.txt Output Connected to interzone.mcom.com:443 -->...
  • Page 123 Examples server_version = {3, 0} random = {...} session ID = { length = 32 contents = {..} cipher_suite = (0x0003) SSL3/RSA/RC4-40/MD5 type = 11 (certificate) length = 709 (0x0002c5) CertificateChain { chainlength = 706 (0x02c2) Certificate { size = 703 (0x02bf) data = { saved in file ’cert.001’...
  • Page 124 Examples length = 56 (0x38) < encrypted > <-- [ SSLRecord { type = 20 (change_cipher_spec) version = { 3,0 } length = 1 (0x1) <-- [ SSLRecord { type = 22 (handshake) version = { 3,0 } length = 56 (0x38) <...
  • Page 125: Example 3

    Examples < encrypted > Server socket closed. Example 3 In this example, the option turns hex/ASCII format. There is no SSL parsing or decoding. The output is routed to a text file. Command ssltap.exe -h -p 444 interzone.mcom.com:443 > h.txt Output Connected to interzone.mcom.com:443 -->...
  • Page 126: Example 4

    Examples Example 4 In this example, the option turns on SSL parsing, and the options turns on hex/ASCII format. Both formats are shown for each record. The output is routed to a text file. Command ssltap.exe -hs -p 444 interzone.mcom.com:443 > hs.txt Output Connected to interzone.mcom.com:443 -->...
  • Page 127: Usage Tips

    Usage Tips Usage Tips • When SSL restarts a previous session, it makes use of cached information to do a partial handshake. If you wish to capture a full SSL handshake, restart the browser to clear the session id cache. •...
  • Page 128 Usage Tips Netscape Certificate Management System Command-Line Tools Guide • March 2002...
  • Page 129: Chapter 15 Ssl Strength Tool

    Chapter 15 SSL Strength Tool SSL Strength Tool is a command-line tool that connects to an SSL server and reports back the encryption cipher and strength used for the connection. This chapter has the following sections: • Location (page 129) •...
  • Page 130: Options And Arguments

    Usage This form of the command returns a list of the possible ciphers. A letter in the first column of the output is the code used by the option. Pass any number of ciphers= cipher codes to the argument to identify the cipher preferences. ciphers= Options and Arguments The SSL Strength Tool command options and their arguments are defined as...
  • Page 131: Restricting Ciphers

    Usage When you issue the command, the tool first prints the list of ciphers sslstrength enabled on the client. It then connects to an SSL server and reports back the following information: • The bulk encryption algorithm selected • The key size selected •...
  • Page 132: Examples

    Examples A connection that steps up starts out with 40-bit encryption, then, upon encountering a handshake, changes to 128-bit encryption. To change-cipher-spec check whether a client has stepped up correctly upon encountering a step-up certificate, check that it is using export policy, and that the secret key size is 128 bits.
  • Page 133: Example 2

    Examples Data Security, Inc.", C=US Subject: CN=myhost.example.com, OU=E-Store Merchant Server, O=Example Corporation, L=Mountain View, ST=California, C=US Valid: from Fri Oct 02, 1998 to Sat Oct 02, 1999 Example 2 This example shows output from a command that limits the client to three ciphers. sslstrength myhost.example.com ciphers=jkl Using domestic policy...
  • Page 134 Examples SSL_RSA_WITH_RC4_128_MD5 (ssl3) Yes Step-up only SSL_RSA_WITH_3DES_EDE_CBC_SHA (ssl3) Yes Step-up only SSL_RSA_EXPORT_WITH_RC4_40_MD5 (ssl3) SSL_RSA_EXPORT_WITH_RC2_CBC_40_MD5 (ssl3) SSL_RSA_WITH_NULL_MD5 (ssl3) SSL Connection Status Cipher: RC4-40 Key Size: Secret Key Size: 40 Issuer: OU=Secure Server Certification Authority, O="RSA Data Security, Inc.", C=US Subject: CN=myhost.example.com, OU=E-Store Merchant Server, O=Example Corporation, L=Mountain View, ST=California, C=US Valid: from Fri Oct 02, 1998 to Sat Oct 02, 1999...
  • Page 135: Chapter 16 Security Module Database Tool

    Chapter 16 Security Module Database Tool The Security Module Database Tool is a command-line utility for managing PKCS#11 module information within files or within hardware tokens. secmod.db You can use the tool to add and delete PKCS #11 modules, change passwords, set defaults, list module contents, enable or disable slots, enable or disable FIPS-140-1 compliance, and assign default providers for cryptographic operations.
  • Page 136: Syntax

    Syntax Syntax To run the Security Module Database Tool, type the command modutil option [arguments] where and [ arguments] are combinations of the options and arguments option listed in the following section. Each command takes one option. Each option may take zero or more arguments.
  • Page 137 Syntax Table 16-1 Options and Arguments for modutil (Continued) Change the password on the named token. If the token has not been initialized, -changepw tokenname this option initializes the password. Use this option with the -pwfile and -newpwfile arguments. In this context, the term “password” is equivalent to a personal identification number (PIN).
  • Page 138 Syntax Table 16-1 Options and Arguments for modutil (Continued) Specify the security mechanisms for which a particular module will be flagged -mechanisms as a default provider. The mechanism-list is a colon-delimited list of mechanism mechanism-list names. Enclose this list in quotation marks if it contains spaces. The module becomes a default provider for the listed mechanisms when those mechanisms are enabled.
  • Page 139: Usage

    Usage Usage The Security Module Database Tool’s capabilities are grouped as follows, using these combinations of options and arguments. The options and arguments in square brackets are optional, those without square brackets are required. • Creating a set of security management database files ( , and key3.db cert7.db...
  • Page 140: Jar Installation File

    JAR Installation File -disable modulename [-slot slotname] • Enabling or disabling FIPS-140-1 compliance within the Netscape Communicator internal module: -fips [true | false] • Disabling interactive prompts for the Security Module Database Tool, to support scripted operation: -force JAR Installation File When a JAR file is run by a server, by the Security Module Database Tool, or by any program that does not interpret JavaScript, a special information file must be included in the format described below.
  • Page 141: Script Grammar

    JAR Installation File RelativePath { %temp%/setup.hlp } win32/setup.cab { RelativePath { %temp%/setup.cab } WIN95::x86 { EquivalentPlatform {WINNT::x86} SUNOS:5.5.1:sparc { ModuleName { "Fortezza UNIX Module" } ModuleFile { unix/fort.so } DefaultMechanismFlags{0x0001} CipherEnableFlags{0x0001} Files { unix/fort.so { RelativePath{%root%/lib/fort.so} AbsolutePath{/usr/local/netscape/lib/fort.so} FilePermissions{555} xplat/instr.html { RelativePath{%root%/docs/inst.html} AbsolutePath{/usr/local/netscape/docs/inst.html} FilePermissions{555}...
  • Page 142: Keys

    Keys string --> simple_string " complex_string " simple_string --> [^ \t\n\""{""}"]+ (No whitespace, quotes, or braces.) complex_string --> ([^\"\\\r\n]|(\\\")|(\\\\))+ (Quotes and backslashes must be escaped with a backslash. A complex string must not include newlines or carriage returns.) Outside of complex strings, all white space (for example, spaces, tabs, and carriage returns) is considered equal and is used only to delimit tokens.
  • Page 143 Keys Platforms (required) Gives a list of platforms. Each entry in the list is itself a key-value pair: the key is the name of the platform and the value list contains various attributes of the platform. The ModuleName, ModuleFile, and Files attributes must be specified for each platform unless an EquivalentPlatform attribute is specified.
  • Page 144: Per-Platform Keys

    Keys Per-Platform Keys These keys have meaning only within the value list of an entry in the Platforms list. Description (required) Gives the common name for the module. This name will be used ModuleName to reference the module from Netscape Communicator, the Security Module Database tool ( ), servers, or any other modutil...
  • Page 145: Per-File Keys

    Keys Specifies mechanisms for which this module will be a default provider. DefaultMechanismFlags This key-value pair is a bitstring specified in hexadecimal (0x) format. It is constructed as a bitwise OR of the following constants. If the DefaultMechanismFlags entry is omitted, the value defaults to 0x0. RSA: 0x00000001 DSA:...
  • Page 146: Examples

    Examples Specifies the destination directory of the file, relative to some directory RelativePath decided at install time. Two variables can be used in the relative path: "%root%" and "%temp%". "%root%" is replaced at run time with the directory relative to which files should be installed; for example, it may Netscape Communicator be the server’s root directory or the root...
  • Page 147: Creating Database Files

    Examples • Enabling a Slot • Enabling FIPS Compliance • Adding a Cryptographic Module • Installing a Cryptographic Module from a JAR File • Changing the Password on a Token Creating Database Files This example creates a set of security management database files in the specified directory: modutil -create -dbdir c:\databases The Security Module Database Tool displays a warning:...
  • Page 148: Setting A Default Provider

    Examples PKCS #11 Version 2.0 Library Version: 4.0 Cipher Enable Flags: None Default Mechanism Flags: RSA:DSA:RC2:RC4:DES:SHA1:MD5:MD2 Slot: Communicator Internal Cryptographic Services Version 4.0 Manufacturer: Netscape Communications Corp Type: Software Version Number: 4.1 Firmware Version: 0.0 Status: Enabled Token Name: Communicator Generic Crypto Svcs Token Manufacturer: Netscape Communications Corp Token Model: Libsec 4.0 Token Serial Number: 0000000000000000...
  • Page 149: Enabling A Slot

    Examples The Security Module Database Tool displays a warning: WARNING: Performing this operation while a Netscape product is running could cause corruption of your security databases. If a Netscape product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter>...
  • Page 150: Adding A Cryptographic Module

    Examples WARNING: Performing this operation while a Netscape product is running could cause corruption of your security databases. If a Netscape product is currently running, you should exit the product before continuing this operation. Type 'q <enter>' to abort, or <enter>...
  • Page 151 Examples RelativePath{ %root%/system32/crypto.dll } setup.exe { Executable RelativePath{ %temp%/setup.exe } Win95::x86 { EquivalentPlatform { Winnt::x86 } To install from the script, use the following command. The root directory should be the Windows root directory (for example, , or c:\\windows c:\\winnt C:\modutil>...
  • Page 152: Changing The Password On A Token

    Examples Using installation parameters for platform WinNT::x86 Installed file crypto.dll to C:/winnt/system32/crypto.dll Installed file setup.exe to ./pk11inst.dir/setup.exe Executing "./pk11inst.dir/setup.exe"... "./pk11inst.dir/setup.exe" executed successfully Installed module "Cryptorific Module" into module database Installation completed successfully C:\modutil> Changing the Password on a Token This example changes the password for a token on an existing module. C:\modutil>...
  • Page 153: Index

    Index Binary to ASCII 57 Certificate Database tool 67 adding dumpasn1 16 new entries to the password cache 21 extension joiner 39 ASCII to Binary tool 55 for adding extensions to CMS certificates 39 example 56 Key Database tool 79 location 55 killproc tool 16, 25 syntax 55...
  • Page 154 ExtensionJoiner tool 39 password cache tool for managing 19 extensions tool for joining 39 Password Cache utility 19 tools for generating 39 adding new entries 21 changing passwords 22 ExtJoiner tool deleting entries 23 example 40 listing contents 21 location 40 syntax 20 syntax 40 usage 20...
  • Page 155 location 135 syntax 136 usage 139 setpin command 28 SSL Debugging tool 115 examples 117 location 115 syntax 116 usage tips 127 SSL Strength tool 129 examples 132 location 129 syntax 129 usage 130 terms used in this book 11 type styles used in this book 11 typestyles used in this book 11 Index...

This manual is also suitable for:

Certificate management system 6.0

Table of Contents