security/nss/doc/signver.xml

   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 &lt;emaldona@redhat.com>, Deon Lackey &lt;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>