From 43a97878ce14b72f0981164f87f2e35e14151312 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 11:22:09 +0200 Subject: Adding upstream version 110.0.1. Signed-off-by: Daniel Baumann --- .../nss/doc/rst/legacy/tools/signtool/index.rst | 547 +++++++++++++++++++++ 1 file changed, 547 insertions(+) create mode 100644 security/nss/doc/rst/legacy/tools/signtool/index.rst (limited to 'security/nss/doc/rst/legacy/tools/signtool/index.rst') diff --git a/security/nss/doc/rst/legacy/tools/signtool/index.rst b/security/nss/doc/rst/legacy/tools/signtool/index.rst new file mode 100644 index 0000000000..428f491a98 --- /dev/null +++ b/security/nss/doc/rst/legacy/tools/signtool/index.rst @@ -0,0 +1,547 @@ +.. _mozilla_projects_nss_tools_signtool: + +NSS tools : signtool +==================== + +.. container:: + + | Name + |    signtool — Digitally sign objects and files. + | Synopsis + |    signtool [-k keyName] `-h <-h>`__ `-H <-H>`__ `-l <-l>`__ `-L <-L>`__ `-M <-M>`__ + `-v <-v>`__ `-w <-w>`__ + |    `-G nickname <-G_nickname>`__ `-s size <--keysize>`__ `-b basename <-b_basename>`__ [[-c + Compression + |    Level] ] [[-d cert-dir] ] [[-i installer script] ] [[-m metafile] ] [[-x + |    name] ] [[-f filename] ] [[-t|--token tokenname] ] [[-e extension] ] [[-o] + |    ] [[-z] ] [[-X] ] [[--outfile] ] [[--verbose value] ] [[--norecurse] ] + |    [[--leavearc] ] [[-j directory] ] [[-Z jarfile] ] [[-O] ] [[-p password] ] + |    [directory-tree] [archive] + | Description + |    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 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. + | Options + |    -b basename + |            Specifies the base filename for the .rsa and .sf files in the + |            META-INF directory to conform with the JAR format. For example, -b + |            signatures causes the files to be named signatures.rsa and + |            signatures.sf. The default is signtool. + |    -c# + |            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. If the -c# option is not used with either the -J + |            or the -Z option, the default compression value used by both the + |            -J and -Z options is 6. + |    -d certdir + |            Specifies your certificate database directory; that is, the + |            directory in which you placed your key3.db and cert7.db files. To + |            specify the current directory, use "-d." (including the period). + |            The Unix version of signtool assumes ~/.netscape unless told + |            otherwise. The NT version of signtool always requires the use of + |            the -d option to specify where the database files are located. + |    -e extension + |            Tells signtool to sign only files with the given extension; for + |            example, use -e".class" to sign only Java class files. Note that + |            with Netscape Signing Tool version 1.1 and later this option can + |            appear multiple times on one command line, making it possible to + |            specify multiple file types or classes to include. + |    -f commandfile + |            Specifies a text file containing Netscape Signing Tool options and + |            arguments in keyword=value format. All options and arguments can + |            be expressed through this file. For more information about the + |            syntax used with this file, see "Tips and Techniques". + |    -i scriptname + |            Specifies the name of an installer script for SmartUpdate. This + |            script installs files from the JAR archive in the local system + |            after SmartUpdate has validated the digital signature. For more + |            details, see the description of -m that follows. The -i option + |            provides a straightforward way to provide this information if you + |            don't need to specify any metadata other than an installer script. + |    -j directory + |            Specifies a special JavaScript directory. This option causes the + |            specified directory to be signed and tags its entries as inline + |            JavaScript. This special type of entry does not have to appear in + |            the JAR file itself. Instead, it is located in the HTML page + |            containing the inline scripts. When you use signtool -v, these + |            entries are displayed with the string NOT PRESENT. + |    -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. + |            Thus, it is possible to write signtool -k MyCert -d . signdir You + |            may have trouble if the nickname contains a single quotation mark. + |            To avoid problems, escape the quotation mark using the escape + |            conventions for your platform. It's also possible to use the -k + |            option without signing any files or specifying a directory. For + |            example, you can use it with the -l option to get detailed + |            information about a particular signing certificate. + |    -G nickname + |            Generates a new private-public key pair and corresponding + |            object-signing certificate with the given nickname. 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. If you are installing the keys and certificate in the + |            Communicator databases, you must exit Communicator before using + |            this option; otherwise, you risk corrupting the 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. Unlike + |            certificates normally used to sign finished code to be distributed + |            over a network, a test certificate created with -G is not signed + |            by a recognized certificate authority. Instead, it is 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 and cannot be used to sign + |            objects. The -G option is available in Netscape Signing Tool 1.0 + |            and later versions only. By default, it produces only RSA + |            certificates with 1024-byte keys in the internal token. However, + |            you can use the -s option specify the required key size and the -t + |            option to specify the token. For more information about the use of + |            the -G option, see "Generating Test Object-Signing + |            Certificates""Generating Test Object-Signing Certificates" on page + |            1241. + |    -l + |            Lists signing certificates, including issuing CAs. If any of your + |            certificates are expired or invalid, the list will so specify. + |            This option can be used with the -k option to list detailed + |            information about a particular signing certificate. The -l option + |            is available in Netscape Signing Tool 1.0 and later versions only. + |    -J + |            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. The -J + |            option cannot be used at the same time as the -Z option. If the + |            -c# option is not used with the -J option, the default compression + |            value is 6. Note that versions 1.1 and later of Netscape Signing + |            Tool correctly recognizes the CODEBASE attribute, allows paths to + |            be expressed for the CLASS and SRC attributes instead of filenames + |            only, processes LINK tags and parses HTML correctly, and offers + |            clearer error messages. + |    -L + |            Lists the certificates in your database. An asterisk appears to + |            the left of the nickname for any certificate that can be used to + |            sign objects with signtool. + |    --leavearc + |            Retains the temporary .arc (archive) directories that the -J + |            option creates. These directories are automatically erased by + |            default. Retaining the temporary directories can be an aid to + |            debugging. + |    -m metafile + |            Specifies the name of a metadata control file. Metadata is signed + |            information attached either to the JAR archive itself or to files + |            within the archive. This metadata can be any ASCII string, but is + |            used mainly for specifying an installer script. The metadata file + |            contains one entry per line, each with three fields: field #1: + |            file specification, or + if you want to specify global metadata + |            (that is, metadata about the JAR archive itself or all entries in + |            the archive) field #2: the name of the data you are specifying; + |            for example: Install-Script field #3: data corresponding to the + |            name in field #2 For example, the -i option uses the equivalent of + |            this line: + Install-Script: script.js This example associates a + |            MIME type with a file: movie.qt MIME-Type: video/quicktime For + |            information about the way installer script information appears in + |            the manifest file for a JAR archive, see The JAR Format on + |            Netscape DevEdge. + |    -M + |            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". For information on using the -M option to verify + |            FIPS-140-1 validated mode, see "Netscape Signing Tool and + |            FIPS-140-1". + |    --norecurse + |            Blocks recursion into subdirectories when signing a directory's + |            contents or when parsing HTML. + |    -o + |            Optimizes the archive for size. Use this only if you are signing + |            very large archives containing hundreds of files. This option + |            makes the manifest files (required by the JAR format) considerably + |            smaller, but they contain slightly less information. + |    --outfile outputfile + |            Specifies a file to receive redirected output from Netscape + |            Signing Tool. + |    -p password + |            Specifies a password for the private-key database. Note that the + |            password entered on the command line is displayed as plain text. + |    -s keysize + |            Specifies the size of the key for generated certificate. Use the + |            -M option to find out what tokens are available. The -s option can + |            be used with the -G option only. + |    -t token + |            Specifies which available token should generate the key and + |            receive the certificate. Use the -M option to find out what tokens + |            are available. The -t option can be used with the -G option only. + |    -v archive + |            Displays the contents of an archive and verifies the cryptographic + |            integrity of the digital signatures it contains and the files with + |            which they are associated. This includes checking that the + |            certificate for the issuer of the object-signing certificate is + |            listed in the certificate database, that the CA's digital + |            signature on the object-signing certificate is valid, that the + |            relevant certificates have not expired, and so on. + |    --verbosity value + |            Sets the quantity of information Netscape Signing Tool generates + |            in operation. A value of 0 (zero) is the default and gives full + |            information. A value of -1 suppresses most messages, but not error + |            messages. + |    -w archive + |            Displays the names of signers of any files in the archive. + |    -x directory + |            Excludes the specified directory from signing. Note that with + |            Netscape Signing Tool version 1.1 and later this option can appear + |            multiple times on one command line, making it possible to specify + |            several particular directories to exclude. + |    -z + |            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. You must specify this + |            option if you want signtool to create the JAR file; it does not do + |            so automatically. If you don't specify -Z, you must use an + |            external ZIP tool to create the JAR file. The -Z option cannot be + |            used at the same time as the -J option. If the -c# option is not + |            used with the -Z option, the default compression value is 6. + | The Command File Format + |    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 + |            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. + | Extended Examples + |    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 + |  ----------------------------------------------- + | See Also + |    signver (1) + |    The NSS wiki has information on the new database design and how to + |    configure applications to use it. + |      o https://wiki.mozilla.org/NSS_Shared_DB_Howto + |      o https://wiki.mozilla.org/NSS_Shared_DB + | Additional Resources + |    For information about NSS and other tools related to NSS (like JSS), check + |    out the NSS project wiki at + |    + [1]\ `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 + | Authors + |    The NSS tools were written and maintained by developers with Netscape, Red + |    Hat, and Sun. + |    Authors: Elio Maldonado , Deon Lackey + |    . + | Copyright + |    (c) 2010, Red Hat, Inc. Licensed under the GNU Public License version 2. + | References + |    Visible links + |    1. + `http://www.mozilla.org/projects/security/pki/nss/ `__ \ No newline at end of file -- cgit v1.2.3