Netscape Certificate Management System Administrator's Guide:

% signtool -L 

using certificate directory: /u/jsmith/.netscape 

S Certificates 

- ------------ 

  BBN Certificate Services CA Root 1 

  IBM World Registry CA 

  VeriSign Class 1 CA - Individual Subscriber - VeriSign, Inc. 

  GTE CyberTrust Root CA 

  Uptime Group Plc. Class 4 CA 

* Verisign Object Signing Cert 

  Integrion CA 

  GTE CyberTrust Secure Server CA 

  AT&T Directory Services 

* test object signing cert 

  Uptime Group Plc. Class 1 CA 

  VeriSign Class 1 Primary CA 

- ------------ 

Certificates that can be used to sign objects have *'s to their left. 

%

In the above example, two signing certificates are displayed: Verisign Object Signing Cert and test object signing cert.

You use the -l option to get a list of signing certificates only, including the signing CA for each, as shown in this Unix example:

% signtool -l

using certificate directory: /u/jsmith/.netscape

Object signing certificates

---------------------------------------

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"

Signing a File

To sign a file using Netscape Signing Tool, follow these steps:

1. Create an empty directory.

% mkdir signdir

2. Put some file into it.

% echo boo > signdir/test.f

3. Specify the name of your object-signing certificate and sign the directory.

If you are using Unix, this example assumes you have put your .db files in the
~/.netscape directory, as explained in "Setting Up Your Certificate".

% signtool -k MySignCert -Z testjar.jar signdir



using key "MySignCert"

using certificate directory: /u/jsmith/.netscape

Generating signdir/META-INF/manifest.mf file..

--> test.f

adding signdir/test.f to testjar.jar

Generating signtool.sf file..

Enter Password or Pin for "Communicator Certificate DB":

4. At the prompt, type the password to your private-key database.

If it accepts the password, signtool responds as follows:

adding signdir/META-INF/manifest.mf to testjar.jar

adding signdir/META-INF/signtool.sf to testjar.jar

adding signdir/META-INF/signtool.rsa to testjar.jar

tree "signdir" signed successfully

5. 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. For example, here's a Windows script that starts with an unsigned JAR file, unpackages it, signs it, and then repackages it:

rem Expand the jar file into a new directory

unzip -qq myjar.jar -d signjar

del myjar.jar

rem Sign everything in the new directory and recompress

signtool -k MySignCert -Z myjar.jar signdir

Using Netscape Signing Tool with a ZIP Utility

To use Netscape Signing Tool with a ZIP utility, you must have the utility in your path environment variable. You should use the zip.exe utility rather than pkzip.exe, which cannot handle long filenames.

You can use a ZIP utility instead of the -Z option to package a signed archive into a JAR file after you have signed it:

% cd signdir 

% zip -r ../myjar.jar * 

  adding: META-INF/ (stored 0%) 

  adding: META-INF/manifest.mf (deflated 15%) 

  adding: META-INF/signtool.sf (deflated 28%) 

  adding: META-INF/signtool.rsa (stored 0%) 

  adding: text.txt (stored 0%) 

%

Tips and Techniques

If you are storing JAR files or their components in CVS, store them as binary files.

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.

The command signtool -L should list your object-signing certificate with an asterisk (*) beside it. If it doesn't, you cannot sign files.

If you are having problems using the JAR file from within Navigator, check signtool -v on your final archive.

Don't use Netscape Signing Tool's -G option while Communicator is running. The -G option writes to the security databases as it generates certificates, and corruption could occur if Communicator simultaneously attempts to write to these files. All other Netscape Signing Tool options are read-only and can't harm these files.

If you see the error Unknown issuer, you need to get the certificate of the certificate authority that issued your signing certificate. Alternatively, you may have the certificate authority's certificate, but it may not be trusted for object signing.

If you see the error Issuer not trusted, open Communicator on the system you used when you obtained the certificate and follow these steps:

Click the Security button in a Navigator window.

Click Signers under Certificates in the left frame.

Select the CA that issued your signing certificate.

Click the Edit button.

Select the "Accept this Certificate Authority for Certifying software developers" checkbox.

Click OK.

You then need to transfer the cert7.db file to the appropriate directory on the system on which you are running Netscape Signing Tool, as described in "Setting Up Your Certificate".

SignTool Syntax and Options

This section summarizes the syntax and options for Netscape Signing Tool 1.2.

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.

Each argument for each signtool option must be in quotes if it contains any spaces or other nonalphanumeric characters.

Command Options

Command File Syntax

Entries in a Netscape Signing Tool command file have this general format:

keyword=value

Everything before the = sign on a single line is a keyword, and everything from the = sign to the end of line is a value. The value may include = signs; only the first = sign on a line is interpreted. Blank lines are ignored, but white space on a line with keywords and values is assumed to be part of the keyword (if it comes before the equal sign) or part of the value (if it comes after the first equal sign). Keywords are case insensitive, values are generally case sensitive. Since the = sign and newline delimit the value, it should not be quoted.

Command File Keywords and Example

Here are the command file keywords and their values:


Keyword	Value
basename	Same as -b option.
compression	Same as -c option.
certdir	Same as -d option.
extension	Same as -e option.
generate	Same as -G option.
installscript	Same as -i option.
javascriptdir	Same as -j option.
htmldir	Same as -J option.
certname	Nickname of certificate, as with -k and -l -k options.
signdir	The directory to be signed, as with -k option.
list	Same as -l option. Value is ignored, but = sign must be present.
listall	Same as -L option. Value is ignored, but = sign must be present.
metafile	Same as -m option.
modules	Same as -M option. Value is ignored, but = sign must be present.
optimize	Same as -o option. Value is ignored, but = sign must be present.
password	Same as -p option.
keysize	Same as -s option.
token	Same as -t option.
verify	Same as -v option.
who	Same as -w option.
exclude	Same as -x option.
notime	Same as -z option. value is ignored, but = sign must be present.
jarfile	Same as -Z option.
outfile	Name of a file to which output and error messages will be redirected. This option has no command-line equivalent.

Here's an example of the use of the command file. The command

signtool -d c:\netscape\users\james -k mycert -Z myjar.jar signdir > output.txt

becomes

signtool -f somefile

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. Instead, they are self-signed. In addition, a single test signing certificate functions as both an object-signing certificate and a CA. When you are using it to sign objects, it behaves like an object-signing certificate. When it is imported into browser software such as Communicator, it behaves like an object-signing CA.

Generating the Keys and Certificate

The signtool option -G generates a new public-private key pair and certificate. It takes the nickname of the new certificate as an argument. The newly generated keys and certificate are installed into the key and certificate databases in the directory specified by the -d option. With the NT version of Netscape Signing Tool, you must use the -d option with the -G option. With the Unix version of Netscape Signing Tool, omitting the -d option causes the tool to install the keys and certificate in the Communicator key and certificate databases. In all cases, the certificate is also output to a file named x509.cacert, which has the MIME-type application/x-x509-ca-cert.

Important Before installing new keys and certificates in the key and certificate databases, you must set the database password (if you have not done so already). To set the password for the key and certificate databases currently being used by Communicator, click the Security icon in the Communicator toolbar, click Passwords, and click Set Password to create a password.

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. Netscape Signing Tool prompts you for this information when you run the command with the -G option. However, all of the requested fields are optional for test certificates. If you do not enter a common name, the tool provides a default name. In the following example, the user input is in boldface:

% signtool -G MyTestCert

using certificate directory: /u/someuser/.netscape

Enter certificate information. All fields are optional. Acceptable

characters are numbers, letters, spaces, and apostrophes.

certificate common name: Test Object Signing Certificate

organization: Netscape Communications Corp.

organization unit: Server Products Division

state or province: California

country (must be exactly 2 characters): US

username: someuser

email address: someuser@netscape.com

Enter Password or Pin for "Communicator Certificate DB": [Password will 
not echo]

generated public/private key pair

certificate request generated

certificate has been signed

certificate "MyTestCert" added to database

Exported certificate to x509.raw and x509.cacert.

%

The certificate information is read from standard input. Therefore, the information can be read from a file using the redirection operator (<) in some operating systems. To create a file for this purpose, enter each of the seven input fields, in order, on a separate line. Make sure there is a newline character at the end of the last line. Then run signtool with standard input redirected from your file as follows:

% signtool -G MyTestCert <inputfile

The prompts show up on the screen, but the responses will be automatically read from the file. The password will still be read from the console unless you use the -p option to give the password on the command line.

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

Using the -M Option to List Smart Cards

Using Netscape Signing Tool and a Smart Card to Sign Files

What Is a Smart Card?

A smart card (sometimes called a token) is a credit-card-sized card, a key, or other easily removable device that can be used for cryptographic operations and for storing certificates. Smart cards are portable and must be physically inserted in an appropriate smart card reader attached to a computer for use with Communicator software running on that computer. Smart cards extend the private-key protection provided by Communicator, since private keys stored on the card require the card's presence as well as the password to the private-key database.

Navigator and Netscape Signing Tool support PKCS #11, a cryptographic standard developed to support services provided by smart cards. Before purchasing a smart card for use with Communicator, you should ensure that your vendor provides a PKCS #11 driver that has been tested with Communicator on your platform. Tested brands include Litronic Netsign and Datakey's SignaSURE.

Setting Up a Smart Card

Connect the smart card reader according to the manufacturer instructions. You may need to reset the smart card to a default state using the manufacturer's configuration utility. Not all smart cards require this step.

Smart cards designed for use with Communicator come with a software driver that you should install in your computer according to the manufacturer's instructions. You can then add the driver (also called a cryptographic module) to Communicator as follows:

Make sure the smart card is inserted in the smart card reader.

Click the Security button near the top of a Navigator window.

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. For Windows systems, this is a dynamic linked library (DLL). You don't have to type the entire path, but you may.

Click OK.

If Communicator asks for it, type the smart card password.

Select the module you've just installed and click the View/Edit button.

Make sure the displayed information is correct for the smart card you just installed.

Select the name of the smart card.

Click the More Info button and examine that information as well.

If the state of the smart card (shown near the bottom of the More Info window) is Not Logged In, click OK and then click the Login button. Otherwise, just click OK. (Logging in allows you to install your signing certificate on the smart card. The smart card doesn't have to be logged in within Communicator for you to use it with Netscape Signing Tool.)

Click OK again.

After you have activated the smart card, use Communicator to visit the web site for the certificate authority (CA) you want to use and request a signing certificate.

When you submit your information to the certificate authority, Communicator asks you to select the card or database you wish to use to generate your private key. You should select the name of your smart card.

Your system then generates a public-private key pair and submits your request to the CA. When you receive the certificate, it is installed directly onto the card and travels with that smart card. However, you will be unable to use the certificate unless the smart card is inserted in the appropriate reader and you have entered its password correctly.

Using the -M Option to List Smart Cards

You can use the -M 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. Netscape Internal PKCS #11 Module 

			  (this module is internally loaded) 

			  slots: 2 slots attached 

			  status: loaded 

	  slot: Communicator Internal Cryptographic Services Version 4.0 

	 token: Communicator Generic Crypto Svcs 

	  slot: Communicator User Private Key and Certificate Services 

	 token: Communicator Certificate DB 

	2. CryptOS 

			  (this is an external module) 

 DLL name: core32 

	 slots: 1 slots attached 

	status: loaded 

	  slot: Litronic 210 

	 token: 

	3. Datakey SignaSURE 

			  (this is an external module) 

 DLL name: dkck232.dll 

	 slots: 1 slots attached 

	status: loaded 

	 slot: Datakey Reader 

	 token: <username> 

	-----------------------------------------------

Using Netscape Signing Tool and a Smart Card to Sign Files

Before you try to use Netscape Signing Tool with a smart card, try using it to sign a file without a smart card as described in "Using Netscape Signing Tool".

The signtool command normally takes an argument of the -k option to specify a signing certificate. To sign with a smart card, you supply only the fully qualified name of the certificate.

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 "MyCard:My Signing Cert". You use this name with the -k argument as follows:

signtool -k "MyCard:My Signing Cert" directory

where directory is the directory tree you want to sign. signtool asks you for two passwords: the password that protects the Communicator certificate database and the password that protects your smart card. If the passwords are correct, signtool signs the files in the directory.

Netscape Signing Tool and FIPS-140-1

This section describes how to use Netscape Signing Tool in FIPS-140-1 validated mode. FIPS 140-1 is a U.S. government standard for implementations of cryptographic modules--that is, hardware or software that encrypts and decrypts data or performs other cryptographic operations (such as creating or verifying digital signatures). Many products sold to the U.S. government must comply with one or more of the FIPS standards.

Using FIPS-140 Mode

Verifying FIPS Mode

For general information on FIPS standards and Netscape FIPS-140-1 validation, see the FIPS 140-1 FAQ.

Using FIPS-140 Mode

Netscape Signing Tool is FIPS-140-1 validated when it uses the FIPS-validated Netscape cryptographic module. The FIPS module can be activated and deactivated from within Communicator. Communicator stores the module choice in the security module database (called secmod.db on Windows platforms and secmodule.db on Unix platforms). This database is stored in the same directory as your certificate database (cert7.db) and key database (key3.db), as indicated by the -d option of Netscape Signing Tool.

Before using Netscape Signing Tool in FIPS-validated mode, you must use Navigator to switch to FIPS mode. For information on how to do this, see Operating Netscape Navigator in FIPS PUB-140-1 Compliant Mode on Netscape DevEdge.

After switching the Navigator cryptographic module to FIPS mode, you have two choices:

Use the same security module database from Netscape Signing Tool (by specifying the same directory with the -d option).

Make a copy of Communicator's security module database and place it in Netscape Signing Tool's database directory.

Verifying FIPS Mode

Use the -M option to verify that you are using the FIPS-140-1 module.

This Unix example shows that Netscape Signing Tool is using a non-FIPS module:

% signtool -d "c:\netscape\users\jsmith" -M

using certificate directory: c:\netscape\users\jsmith

Listing of PKCS11 modules

-----------------------------------------------

  1. Netscape Internal PKCS #11 Module

          (this module is internally loaded)

          slots: 2 slots attached

          status: loaded

    slot: Communicator Internal Cryptographic Services Version 4.0

   token: Communicator Generic Crypto Svcs

    slot: Communicator User Private Key and Certificate Services

   token: Communicator Certificate DB

-----------------------------------------------

This Unix example shows that Netscape Signing Tool is using a FIPS-140-1 module:

% signtool -d "c:\netscape\users\jsmith" -M
using certificate directory: c:\netscape\users\jsmith
Enter Password or Pin for "Communicator Certificate DB": [password will not echo]
Listing of PKCS11 modules
-----------------------------------------------
1. Netscape Internal FIPS PKCS #11 Module
(this module is internally loaded)
slots: 1 slots attached
status: loaded
slot: Netscape Internal FIPS-140-1 Cryptographic Services
token: Communicator Certificate DB
-----------------------------------------------

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.

Netscape Signing Tool 1.x and Communicator 4.x are designed to read only the cert7.db files used by Communicator 4.x. If it happens that a certificate gets downloaded with Navigator 3.x after Communicator 4.x was installed and run, that certificate is recorded in a database of the older (3.x) format. While Communicator does automatically convert Navigator's cert5.db and key.db databases to the cert7.db and key3.db formats the first time it runs, it does not do so again.

To get a certificate into the new database from an old one requires forcing Communicator to reinitialize its cert7.db file as it does at first run-time. This requires that the certificates in the current cert7.db file be exported for later re-importing.

Click the Security Info button on the Communicator toolbar.

Click Yours under Certificates in the left panel, and select a certificate to export.

Click Export and save a PKCS #12 copy of the certificate to a safe location (if no copy already exists).

Repeat steps 2 and 3 for each certificate present.

Exit Communicator completely.

Move the cert7.db and key3.db files from your user profile directory to a backup directory. This is a safety measure: these files shouldn't be needed again. Once the following steps are successfully completed, and you have used signtool -l to verify that the upgraded cert7.db file has the right certificates, you can discard these backup copies.

Copy Navigator's cert5.db and key.db files to your Communicator user-profile directory.

Restart Communicator. It automatically upgrades the older database files, including their contents.

Click the Security Info button on the Communicator toolbar, then click Yours under Certificates in the left panel.

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 -l and -k options report "Unable to find issuer certificate" or "Unknown user" errors.

Netscape Signing Tool 1.x reads the cert7.db files used by Communicator 4.x. Normally, cert7.db files record a certificate's complete certificate chain information using the PKCS #7 cryptographic message-syntax standard. However, Navigator 3.x wasn't designed to properly use this standard (it wasn't in wide use yet). Therefore, certificates used by Communicator 4.x that were originally imported with Navigator 3.x may not have all the certificate chain information required for object signing.

In the case of VeriSign Class 2 or Class 3 certificates, the missing portion of the chain is the intermediate node, since the root is provided with Communicator by default and the leaf is included in the existing certificate information. To get the intermediate portion, use Communicator 4.x and click these links for VeriSign Class 2 or VeriSign Class 3 certificate authority updates.

When trying to read a JAR file into Communicator 4.05 the error message "Inconsistent files in manifest" appears in the Java console.

Communicator 4.05 (and only that version) has a bug that makes it sensitive to the case of the JAR manifest's filename as stored in the META-INF directory. Version 4.05 requires the filename to be all lowercase. Although the JAR specification calls for case insensitivity and Netscape Signing Tool does generate a lowercase filename, an uppercase filename can appear if another tool is used to create the JAR, or case translation occurs on the Windows platform.

This problem can be repaired by re-signing the JAR with Netscape Signing Tool, or by unzipping the file and changing MANIFEST.MF to manifest.mf.

How can users change the nicknames of their own certificates?

For convenience, users may want to shorten the nicknames of some of the certificates they use. While certificates cannot be renamed directly, it may be possible to replace them and give the replacement a new name.

Note that this process can present a risk because it requires the user to delete a certificate before replacing it, and if the replacement fails and there is no backup certificate, the certificate is lost.

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. Note that the certificate's corresponding private key isn't deleted, just the certificate itself.

Retrieve the certificate again from the Certificate Authority. The specific procedure for doing this depends on the Certificate Authority being used. Be very sure that the replacement is the correct one.

Enter a new name for the certificate when downloading it.

Note: The Export and Import buttons in the Security Info dialog box can't be used to change certificate nicknames. These functions can affect only a certificate's exported PKCS #12 filename.

When I click the Security icon in the Communicator toolbar, click Yours under Certificates, select my object-signing certificate, and click Verify, Communicator informs me that the certificate is not valid. Why?

This is a common occurrence. The Verify button works with S/MIME certificates only. It does not work with object-signing certificates.

To verify an object-signing certificate, use

signtool -l -k nickname

where nickname is the nickname of the certificate you want to verify.

I get the following error when trying to create a test certificate:

failure authenticating to key database .: Security I/O error.

This error typically means that you have not yet set a password for the certificate database. To set the password for the Communicator database, click the Security icon in the Communicator toolbar, click Passwords, and click Set Password to create a password.

Objects to be signed will be stored and used long-term, well after the certificates used for signing have expired. Will signed objects still be trusted even after their object-signing certificates have expired?

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. Note that this would not be true, however, if an object was signed using the -z option which omits the original timestamp and forces validation to rely on the current status of the certificate chain.