Complete Contents |
About This Guide
PART 1: Netscape Certificate Management System
Chapter 1: Introduction to Certificate Management System
Chapter 2: Administration Tasks and Tool
Chapter 3: Configuration
PART 2: Managing Certificate Management System
Chapter 4: Installing and Uninstalling Instances
Chapter 5: Starting and Stopping Instances
PART 3: System-Level Configuration
Chapter 6: Configuring Ports, Database, and SMTP Settings
Chapter 7: Managing Privileged Users and Groups
Chapter 8: Keys and Certificates
PART 4: Authentication
Chapter 9: Introduction to Authentication
Chapter 10: Using the PIN Generator Tool
Chapter 11: Configuring Authentication for End Entities
Chapter 12: Developing Authentication Plug-ins
PART 5: Job Scheduling and Notification
Chapter 13: Introduction to Job Scheduling and Notifications
Chapter 14: Configuring Jobs
PART 6: Policies
Chapter 15: Introduction to Policies
Chapter 16: Configuring Policies
PART 7: LDAP Publishing
Chapter 17: Introduction to LDAP Publishing
Chapter 18: Configuring Subsystems for LDAP Publishing
Chapter 19: Publishing CRLs
PART 8: Agent and End-Entity Interfaces
Chapter 20: Introduction to End-Entity and Agent Interfaces
Chapter 21: Customizing End-Entity and Agent Interfaces
PART 9: Logs
Chapter 22: Introduction to Logs
Chapter 23: Managing Logs
PART 10: Issuance and Management of End-Entity Certificates
Chapter 24: Issuing and Managing End-Entity Certificates
Chapter 25: Recovering Encrypted Data
PART 11: Appendixes
Appendix A: Distinguished Names
Appendix B: Backing Up and Restoring Data
Appendix C: Command-Line Utilities
Appendix D: Certificate Database Tool
Appendix E: Key Database Tool
Appendix F: Netscape Signing Tool
Appendix G: SSL Strength Tool
Appendix H: SSL Debugging Tool
Appendix F Netscape Signing Tool
|Introduction to Netscape Signing Tool|
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. For information about obtaining an object-signing certificate, see Object-Signing Tools at this URL:http://developer.netscape.com/docs/manuals/index.html?content=security.html An individual file can potentially be signed with multiple digital signatures. For example, a commercial software developer might sign the files that constitute a software product to prove that the files are indeed from a particular company. A network administrator manager might sign the same files with an additional digital signature based on a company-generated certificate to indicate that the product is approved for use within the company. The significance of a digital signature is comparable to the significance of a handwritten signature. Once you have signed a file, it is difficult to claim later that you didn't sign it. In some situations, a digital signature may be considered as legally binding as a handwritten signature. Therefore, you should take great care to ensure that you can stand behind any file you sign and distribute. For example, if you are a software developer, you should test your code to make sure it is virus-free before signing it. Similarly, if you are a network administrator, you should make sure, before signing any code, that it comes from a reliable source and will run correctly with the software installed on the machines to which you are distributing it. Object-Signing Certificates For testing purposes only, you can create an object-signing certificate with Netscape Signing Tool 1.2. When testing is finished and you are ready to disitribute your software, you should obtain an object-signing certificate from one of two kinds of sources:
|Using Netscape Signing Tool|
This section describes how to use Netscape Signing Tool to create digital signatures for files in a directory and to associate the signatures with the files according to the JAR format. Netscape Signing Tool also provides an option that automatically creates a JAR file containing the directory; this option was not implemented in pre-1.0 versions. For maximum flexibility, and for compatibility with scripts that used earlier versions of Netscape Signing Tool, you can still use a ZIP utility to create the JAR file.
These instructions apply to an object-signing certificate obtained from a third party or an in-house CA for use in signing finished code. During development, you may wish to use a special certificate generated by Netscape Signing Tool for testing purposes.If you obtained your object-signing certificate while running Communicator on a system that's different from the system on which you intend to sign files, you need to copy your certificate and private key files to the new system. Communicator's certificate and key databases are portable among all platforms. On the computer where you ran Communicator to get the object-signing certificate, locate the files key3.db and cert7.db. For example, on a typical Windows NT system, these files are found at C:\Program Files\NETSCAPE\USERS\username\. You must copy these files to the system where you intend to sign pages. (If you use FTP, be sure to transfer in binary mode.) If you are running Netscape Signing Tool on a Unix system and you don't already have a ~/.netscape directory, first run Communicator once to create one. If you want to maintain whatever certificates are already in your ~/.netscape directory, put the existing key3.db and cert7.db files in some other directory before replacing them with the versions that include the object-signing certificate you want to use with Netscape Signing Tool. If you are using Unix, set up an alias to call signtool, or place it in your path. If you are using Windows 95 or NT, the signtool executable doesn't know where your certificates are, so either put the key3.db and cert7.db files in the current directory and use "-d." or use -d to point to the directory in which they are located. Warning. Keep copies of the key3.db and cert7.db files somewhere separate from the copies you use with the signtool executable. This ensures that you won't lose your certificates if you accidentally damage the files. If your keys are on external tokens, such as smart cards, you should keep a copy the secmod.db file.
% signtool -LYou 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 -l1. Create an empty directory.
% mkdir signdir
% echo boo > signdir/test.f
If you are using Unix, this example assumes you have put your .db files in
% signtool -k MySignCert -Z testjar.jar signdir
If it accepts the password, signtool responds as follows:
adding signdir/META-INF/manifest.mf to testjar.jar
% signtool -v testjar.jar
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
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
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.
signtool optionsEach argument for each signtool option must be in quotes if it contains any spaces or other nonalphanumeric characters. Command Options
signtool -d c:\netscape\users\james -k mycert -Z myjar.jar signdir > output.txtsigntool -f somefile where somefile contains the following lines:
|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
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.
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:
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.
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.)
% signtool -d "c:\netscape\users\jsmith" -MThe 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.
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:
% signtool -d "c:\netscape\users\jsmith" -M% 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
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.
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.
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.
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.
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.
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.