The Tor Browser / file comparison
comparison: security/nss/doc/signver.xml
security/nss/doc/signver.xml
- changeset 0
- 6474c204b198
equal
deleted
inserted
replaced
| -1:000000000000 | 0:53d7ec402ab2 |
|---|---|
| 1 <?xml version="1.0" encoding="UTF-8"?> | |
| 2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" | |
| 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ | |
| 4 <!ENTITY date SYSTEM "date.xml"> | |
| 5 <!ENTITY version SYSTEM "version.xml"> | |
| 6 ]> | |
| 7 | |
| 8 <refentry id="signver"> | |
| 9 | |
| 10 <refentryinfo> | |
| 11 <date>&date;</date> | |
| 12 <title>NSS Security Tools</title> | |
| 13 <productname>nss-tools</productname> | |
| 14 <productnumber>&version;</productnumber> | |
| 15 </refentryinfo> | |
| 16 | |
| 17 <refmeta> | |
| 18 <refentrytitle>SIGNVER</refentrytitle> | |
| 19 <manvolnum>1</manvolnum> | |
| 20 </refmeta> | |
| 21 | |
| 22 <refnamediv> | |
| 23 <refname>signver</refname> | |
| 24 <refpurpose>Verify a detached PKCS#7 signature for a file.</refpurpose> | |
| 25 </refnamediv> | |
| 26 | |
| 27 <refsynopsisdiv> | |
| 28 <cmdsynopsis> | |
| 29 <command>signtool</command> | |
| 30 <group choice="plain"> | |
| 31 <arg choice="plain">-A</arg> | |
| 32 <arg choice="plain">-V</arg> | |
| 33 </group> | |
| 34 <arg choice="plain">-d <replaceable>directory</replaceable></arg> | |
| 35 <arg>-a</arg> | |
| 36 <arg>-i <replaceable>input_file</replaceable></arg> | |
| 37 <arg>-o <replaceable>output_file</replaceable></arg> | |
| 38 <arg>-s <replaceable>signature_file</replaceable></arg> | |
| 39 <arg>-v</arg> | |
| 40 </cmdsynopsis> | |
| 41 </refsynopsisdiv> | |
| 42 | |
| 43 <refsection> | |
| 44 <title>STATUS</title> | |
| 45 <para>This documentation is still work in progress. Please contribute to the initial review in <ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=836477">Mozilla NSS bug 836477</ulink> | |
| 46 </para> | |
| 47 </refsection> | |
| 48 | |
| 49 <refsection id="description"> | |
| 50 <title>Description</title> | |
| 51 | |
| 52 <para>The Signature Verification Tool, <command>signver</command>, is a simple command-line utility that unpacks a base-64-encoded PKCS#7 signed object and verifies the digital signature using standard cryptographic techniques. The Signature Verification Tool can also display the contents of the signed object.</para> | |
| 53 </refsection> | |
| 54 | |
| 55 <refsection id="options"> | |
| 56 <title>Options</title> | |
| 57 <variablelist> | |
| 58 <varlistentry> | |
| 59 <term>-A</term> | |
| 60 <listitem><para>Displays all of the information in the PKCS#7 signature.</para></listitem> | |
| 61 </varlistentry> | |
| 62 <varlistentry> | |
| 63 <term>-V</term> | |
| 64 <listitem><para>Verifies the digital signature.</para></listitem> | |
| 65 </varlistentry> | |
| 66 <varlistentry> | |
| 67 <term>-d [sql:]<emphasis>directory</emphasis></term> | |
| 68 <listitem><para>Specify the database directory which contains the certificates and keys.</para> | |
| 69 <para><command>signver</command> supports two types of databases: the legacy security databases (<filename>cert8.db</filename>, <filename>key3.db</filename>, and <filename>secmod.db</filename>) and new SQLite databases (<filename>cert9.db</filename>, <filename>key4.db</filename>, and <filename>pkcs11.txt</filename>). If the prefix <command>sql:</command> is not used, then the tool assumes that the given databases are in the old format.</para></listitem> | |
| 70 </varlistentry> | |
| 71 <varlistentry> | |
| 72 <term>-a</term> | |
| 73 <listitem><para>Sets that the given signature file is in ASCII format.</para></listitem> | |
| 74 </varlistentry> | |
| 75 <varlistentry> | |
| 76 <term>-i <emphasis>input_file</emphasis></term> | |
| 77 <listitem><para>Gives the input file for the object with signed data.</para></listitem> | |
| 78 </varlistentry> | |
| 79 <varlistentry> | |
| 80 <term>-o <emphasis>output_file</emphasis></term> | |
| 81 <listitem><para>Gives the output file to which to write the results.</para></listitem> | |
| 82 </varlistentry> | |
| 83 <varlistentry> | |
| 84 <term>-s <emphasis>signature_file</emphasis></term> | |
| 85 <listitem><para>Gives the input file for the digital signature.</para></listitem> | |
| 86 </varlistentry> | |
| 87 <varlistentry> | |
| 88 <term>-v</term> | |
| 89 <listitem><para>Enables verbose output.</para></listitem> | |
| 90 </varlistentry> | |
| 91 </variablelist> | |
| 92 </refsection> | |
| 93 | |
| 94 <refsection id="examples"> | |
| 95 <title>Extended Examples</title> | |
| 96 <refsection><title>Verifying a Signature</title> | |
| 97 <para>The <option>-V</option> option verifies that the signature in a given signature file is valid when used to sign the given object (from the input file).</para> | |
| 98 <programlisting>signver -V -s <replaceable>signature_file</replaceable> -i <replaceable>signed_file</replaceable> -d sql:/home/my/sharednssdb | |
| 99 | |
| 100 signatureValid=yes</programlisting> | |
| 101 </refsection> | |
| 102 | |
| 103 <refsection><title>Printing Signature Data</title> | |
| 104 <para> | |
| 105 The <option>-A</option> option prints all of the information contained in a signature file. Using the <option>-o</option> option prints the signature file information to the given output file rather than stdout. | |
| 106 </para> | |
| 107 <programlisting>signver -A -s <replaceable>signature_file</replaceable> -o <replaceable>output_file</replaceable></programlisting> | |
| 108 </refsection> | |
| 109 </refsection> | |
| 110 | |
| 111 <refsection id="databases"><title>NSS Database Types</title> | |
| 112 <para>NSS originally used BerkeleyDB databases to store security information. | |
| 113 The last versions of these <emphasis>legacy</emphasis> databases are:</para> | |
| 114 <itemizedlist> | |
| 115 <listitem> | |
| 116 <para> | |
| 117 cert8.db for certificates | |
| 118 </para> | |
| 119 </listitem> | |
| 120 <listitem> | |
| 121 <para> | |
| 122 key3.db for keys | |
| 123 </para> | |
| 124 </listitem> | |
| 125 <listitem> | |
| 126 <para> | |
| 127 secmod.db for PKCS #11 module information | |
| 128 </para> | |
| 129 </listitem> | |
| 130 </itemizedlist> | |
| 131 | |
| 132 <para>BerkeleyDB has performance limitations, though, which prevent it from being easily used by multiple applications simultaneously. NSS has | |
| 133 some flexibility that allows applications to use their own, independent database engine while keeping a shared database and working around the access issues. Still, NSS | |
| 134 requires more flexibility to provide a truly shared security database.</para> | |
| 135 | |
| 136 <para>In 2009, NSS introduced a new set of databases that are SQLite databases rather than | |
| 137 BerkleyDB. These new databases provide more accessibility and performance:</para> | |
| 138 <itemizedlist> | |
| 139 <listitem> | |
| 140 <para> | |
| 141 cert9.db for certificates | |
| 142 </para> | |
| 143 </listitem> | |
| 144 <listitem> | |
| 145 <para> | |
| 146 key4.db for keys | |
| 147 </para> | |
| 148 </listitem> | |
| 149 <listitem> | |
| 150 <para> | |
| 151 pkcs11.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory | |
| 152 </para> | |
| 153 </listitem> | |
| 154 </itemizedlist> | |
| 155 | |
| 156 <para>Because the SQLite databases are designed to be shared, these are the <emphasis>shared</emphasis> database type. The shared database type is preferred; the legacy format is included for backward compatibility.</para> | |
| 157 | |
| 158 <para>By default, the tools (<command>certutil</command>, <command>pk12util</command>, <command>modutil</command>) assume that the given security databases follow the more common legacy type. | |
| 159 Using the SQLite databases must be manually specified by using the <command>sql:</command> prefix with the given security directory. For example:</para> | |
| 160 | |
| 161 <programlisting># signver -A -s <replaceable>signature</replaceable> -d sql:/home/my/sharednssdb</programlisting> | |
| 162 | |
| 163 <para>To set the shared database type as the default type for the tools, set the <envar>NSS_DEFAULT_DB_TYPE</envar> environment variable to <envar>sql</envar>:</para> | |
| 164 <programlisting>export NSS_DEFAULT_DB_TYPE="sql"</programlisting> | |
| 165 | |
| 166 <para>This line can be added to the <filename>~/.bashrc</filename> file to make the change permanent for the user.</para> | |
| 167 | |
| 168 <para>Most applications do not use the shared database by default, but they can be configured to use them. For example, this how-to article covers how to configure Firefox and Thunderbird to use the new shared NSS databases:</para> | |
| 169 <itemizedlist> | |
| 170 <listitem> | |
| 171 <para> | |
| 172 https://wiki.mozilla.org/NSS_Shared_DB_Howto</para> | |
| 173 </listitem> | |
| 174 </itemizedlist> | |
| 175 <para>For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:</para> | |
| 176 <itemizedlist> | |
| 177 <listitem> | |
| 178 <para> | |
| 179 https://wiki.mozilla.org/NSS_Shared_DB | |
| 180 </para> | |
| 181 </listitem> | |
| 182 </itemizedlist> | |
| 183 </refsection> | |
| 184 | |
| 185 <refsection id="seealso"> | |
| 186 <title>See Also</title> | |
| 187 <para>signtool (1)</para> | |
| 188 | |
| 189 <para>The NSS wiki has information on the new database design and how to configure applications to use it.</para> | |
| 190 <itemizedlist> | |
| 191 <listitem> | |
| 192 <para>Setting up the shared NSS database</para> | |
| 193 <para>https://wiki.mozilla.org/NSS_Shared_DB_Howto</para> | |
| 194 </listitem> | |
| 195 <listitem> | |
| 196 <para> | |
| 197 Engineering and technical information about the shared NSS database | |
| 198 </para> | |
| 199 <para> | |
| 200 https://wiki.mozilla.org/NSS_Shared_DB | |
| 201 </para> | |
| 202 </listitem> | |
| 203 </itemizedlist> | |
| 204 </refsection> | |
| 205 | |
| 206 <!-- don't change --> | |
| 207 <refsection id="resources"> | |
| 208 <title>Additional Resources</title> | |
| 209 <para>For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at <ulink url="http://www.mozilla.org/projects/security/pki/nss/">http://www.mozilla.org/projects/security/pki/nss/</ulink>. The NSS site relates directly to NSS code changes and releases.</para> | |
| 210 <para>Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto</para> | |
| 211 <para>IRC: Freenode at #dogtag-pki</para> | |
| 212 </refsection> | |
| 213 | |
| 214 <!-- fill in your name first; keep the other names for reference --> | |
| 215 <refsection id="authors"> | |
| 216 <title>Authors</title> | |
| 217 <para>The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google.</para> | |
| 218 <para> | |
| 219 Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey <dlackey@redhat.com>. | |
| 220 </para> | |
| 221 </refsection> | |
| 222 | |
| 223 <!-- don't change --> | |
| 224 <refsection id="license"> | |
| 225 <title>LICENSE</title> | |
| 226 <para>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/. | |
| 227 </para> | |
| 228 </refsection> | |
| 229 | |
| 230 </refentry> |
