| SIGNTOOL(1) | NSS Security Tools | SIGNTOOL(1) |
signtool - Digitally sign objects and files.
signtool [[-b basename]] [[-c Compression Level]] [[-d cert-dir]] [[-e extension]] [[-f filename]] [[-i installer script]] [[-h]] [[-H]] [[-v]] [[-w]] [[-G nickname]] [[-J]] [[-j directory]] [-k keyName] [[--keysize | -s size]] [[-l]] [[-L]] [[-M]] [[-m metafile]] [[--norecurse]] [[-O]] [[-o]] [[--outfile]] [[-p password]] [[-t|--token tokenname]] [[-z]] [[-X]] [[-x name]] [[--verbose value]] [[--leavearc]] [[-Z jarfile]] [directory-tree] [archive]
This documentation is still work in progress. Please contribute to the initial review in Mozilla NSS bug 836477[1]
The Signing Tool, signtool, creates digital signatures and uses a Java Archive (JAR) file to associate the signatures with files in a directory. Electronic software distribution over any network involves potential security problems. To help address some of these problems, you can associate digital signatures with the files in a JAR archive. Digital signatures allow SSL-enabled clients to perform two important operations:
* Confirm the identity of the individual, company, or other entity whose digital signature is associated with the files
* Check whether the files have been tampered with since being signed
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.
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.
Before you can use Netscape Signing Tool to sign files, you must have an object-signing certificate, which is a special certificate whose associated private key is used to create digital signatures. For testing purposes only, you can create an object-signing certificate with Netscape Signing Tool 1.3. 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:
* An independent certificate authority (CA) that authenticates your identity and charges you a fee. You typically get a certificate from an independent CA if you want to sign software that will be distributed over the Internet.
* 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. If the certificate authority's certificate isn't already installed in your copy of Communicator, you typically install it by clicking the appropriate link on the certificate authority's web site, for example on the page from which you initiated enrollment for your signing certificate. This is the case for some test certificates, as well as certificates issued by Netscape Certificate Management System: you must download the the CA certificate in addition to obtaining your own signing certificate. CA certificates for several certificate authorities are preinstalled in the Communicator certificate database.
When you receive an object-signing certificate for your own use, it is automatically installed in your copy of the Communicator client software. Communicator supports the public-key cryptography standard known as PKCS #12, which governs key portability. You can, for example, move an object-signing certificate and its associated private key from one computer to another on a credit-card-sized device called a smart card.
-b basename
-c#
-d certdir
-e extension
-f commandfile
-G nickname
-i scriptname
-J
-j directory
-k key ... directory
-l
-L
--leavearc
-m metafile
-M
--norecurse
-o
--outfile outputfile
-p password
-s keysize
-t token
-v archive
--verbosity value
-w archive
-x directory
-z
-Z jarfile
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.
Subsection
basename
compression
certdir
extension
generate
installscript
javascriptdir
htmldir
certname
signdir
list
listall
metafile
modules
optimize
password
keysize
token
verify
who
exclude
notime
jarfile
outfile
The following example will do this and that
Listing Available Signing Certificates
You use the -L option to list the nicknames for all available certificates and check which ones are signing certificates.
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.
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.
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 the -L option.
Signing a File
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.
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": 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
4. 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
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%)
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.
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 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: -----------------------------------------------
Using Netscape Signing Tool and a Smart Card to Sign Files
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
Verifying FIPS Mode
Use the -M option to verify that you are using the FIPS-140-1 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 -----------------------------------------------
signver (1)
The NSS wiki has information on the new database design and how to configure applications to use it.
For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates directly to NSS code changes and releases.
Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto
IRC: Freenode at #dogtag-pki
The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google.
Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey <dlackey@redhat.com>.
Licensed under the Mozilla Public License, v. 2.0. If a copy of the MPL was not distributed with this file, You can obtain one at http://mozilla.org/MPL/2.0/.
| 19 May 2021 | nss-tools |