1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/doc/signver.xml Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,230 @@
1.4 +<?xml version="1.0" encoding="UTF-8"?>
1.5 +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
1.6 + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
1.7 +<!ENTITY date SYSTEM "date.xml">
1.8 +<!ENTITY version SYSTEM "version.xml">
1.9 +]>
1.10 +
1.11 +<refentry id="signver">
1.12 +
1.13 + <refentryinfo>
1.14 + <date>&date;</date>
1.15 + <title>NSS Security Tools</title>
1.16 + <productname>nss-tools</productname>
1.17 + <productnumber>&version;</productnumber>
1.18 + </refentryinfo>
1.19 +
1.20 + <refmeta>
1.21 + <refentrytitle>SIGNVER</refentrytitle>
1.22 + <manvolnum>1</manvolnum>
1.23 + </refmeta>
1.24 +
1.25 + <refnamediv>
1.26 + <refname>signver</refname>
1.27 + <refpurpose>Verify a detached PKCS#7 signature for a file.</refpurpose>
1.28 + </refnamediv>
1.29 +
1.30 + <refsynopsisdiv>
1.31 + <cmdsynopsis>
1.32 + <command>signtool</command>
1.33 + <group choice="plain">
1.34 + <arg choice="plain">-A</arg>
1.35 + <arg choice="plain">-V</arg>
1.36 + </group>
1.37 + <arg choice="plain">-d <replaceable>directory</replaceable></arg>
1.38 + <arg>-a</arg>
1.39 + <arg>-i <replaceable>input_file</replaceable></arg>
1.40 + <arg>-o <replaceable>output_file</replaceable></arg>
1.41 + <arg>-s <replaceable>signature_file</replaceable></arg>
1.42 + <arg>-v</arg>
1.43 + </cmdsynopsis>
1.44 + </refsynopsisdiv>
1.45 +
1.46 + <refsection>
1.47 + <title>STATUS</title>
1.48 + <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>
1.49 + </para>
1.50 + </refsection>
1.51 +
1.52 + <refsection id="description">
1.53 + <title>Description</title>
1.54 +
1.55 + <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>
1.56 + </refsection>
1.57 +
1.58 + <refsection id="options">
1.59 + <title>Options</title>
1.60 + <variablelist>
1.61 + <varlistentry>
1.62 + <term>-A</term>
1.63 + <listitem><para>Displays all of the information in the PKCS#7 signature.</para></listitem>
1.64 + </varlistentry>
1.65 + <varlistentry>
1.66 + <term>-V</term>
1.67 + <listitem><para>Verifies the digital signature.</para></listitem>
1.68 + </varlistentry>
1.69 + <varlistentry>
1.70 + <term>-d [sql:]<emphasis>directory</emphasis></term>
1.71 + <listitem><para>Specify the database directory which contains the certificates and keys.</para>
1.72 + <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>
1.73 + </varlistentry>
1.74 + <varlistentry>
1.75 + <term>-a</term>
1.76 + <listitem><para>Sets that the given signature file is in ASCII format.</para></listitem>
1.77 + </varlistentry>
1.78 + <varlistentry>
1.79 + <term>-i <emphasis>input_file</emphasis></term>
1.80 + <listitem><para>Gives the input file for the object with signed data.</para></listitem>
1.81 + </varlistentry>
1.82 + <varlistentry>
1.83 + <term>-o <emphasis>output_file</emphasis></term>
1.84 + <listitem><para>Gives the output file to which to write the results.</para></listitem>
1.85 + </varlistentry>
1.86 + <varlistentry>
1.87 + <term>-s <emphasis>signature_file</emphasis></term>
1.88 + <listitem><para>Gives the input file for the digital signature.</para></listitem>
1.89 + </varlistentry>
1.90 + <varlistentry>
1.91 + <term>-v</term>
1.92 + <listitem><para>Enables verbose output.</para></listitem>
1.93 + </varlistentry>
1.94 + </variablelist>
1.95 + </refsection>
1.96 +
1.97 + <refsection id="examples">
1.98 + <title>Extended Examples</title>
1.99 + <refsection><title>Verifying a Signature</title>
1.100 + <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>
1.101 +<programlisting>signver -V -s <replaceable>signature_file</replaceable> -i <replaceable>signed_file</replaceable> -d sql:/home/my/sharednssdb
1.102 +
1.103 +signatureValid=yes</programlisting>
1.104 + </refsection>
1.105 +
1.106 + <refsection><title>Printing Signature Data</title>
1.107 + <para>
1.108 + 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.
1.109 + </para>
1.110 +<programlisting>signver -A -s <replaceable>signature_file</replaceable> -o <replaceable>output_file</replaceable></programlisting>
1.111 + </refsection>
1.112 + </refsection>
1.113 +
1.114 +<refsection id="databases"><title>NSS Database Types</title>
1.115 +<para>NSS originally used BerkeleyDB databases to store security information.
1.116 +The last versions of these <emphasis>legacy</emphasis> databases are:</para>
1.117 +<itemizedlist>
1.118 + <listitem>
1.119 + <para>
1.120 + cert8.db for certificates
1.121 + </para>
1.122 + </listitem>
1.123 + <listitem>
1.124 + <para>
1.125 + key3.db for keys
1.126 + </para>
1.127 + </listitem>
1.128 + <listitem>
1.129 + <para>
1.130 + secmod.db for PKCS #11 module information
1.131 + </para>
1.132 + </listitem>
1.133 +</itemizedlist>
1.134 +
1.135 +<para>BerkeleyDB has performance limitations, though, which prevent it from being easily used by multiple applications simultaneously. NSS has
1.136 +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
1.137 +requires more flexibility to provide a truly shared security database.</para>
1.138 +
1.139 +<para>In 2009, NSS introduced a new set of databases that are SQLite databases rather than
1.140 +BerkleyDB. These new databases provide more accessibility and performance:</para>
1.141 +<itemizedlist>
1.142 + <listitem>
1.143 + <para>
1.144 + cert9.db for certificates
1.145 + </para>
1.146 + </listitem>
1.147 + <listitem>
1.148 + <para>
1.149 + key4.db for keys
1.150 + </para>
1.151 + </listitem>
1.152 + <listitem>
1.153 + <para>
1.154 + pkcs11.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory
1.155 + </para>
1.156 + </listitem>
1.157 +</itemizedlist>
1.158 +
1.159 +<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>
1.160 +
1.161 +<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.
1.162 +Using the SQLite databases must be manually specified by using the <command>sql:</command> prefix with the given security directory. For example:</para>
1.163 +
1.164 +<programlisting># signver -A -s <replaceable>signature</replaceable> -d sql:/home/my/sharednssdb</programlisting>
1.165 +
1.166 +<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>
1.167 +<programlisting>export NSS_DEFAULT_DB_TYPE="sql"</programlisting>
1.168 +
1.169 +<para>This line can be added to the <filename>~/.bashrc</filename> file to make the change permanent for the user.</para>
1.170 +
1.171 +<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>
1.172 +<itemizedlist>
1.173 + <listitem>
1.174 + <para>
1.175 + https://wiki.mozilla.org/NSS_Shared_DB_Howto</para>
1.176 + </listitem>
1.177 +</itemizedlist>
1.178 +<para>For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:</para>
1.179 +<itemizedlist>
1.180 + <listitem>
1.181 + <para>
1.182 + https://wiki.mozilla.org/NSS_Shared_DB
1.183 + </para>
1.184 + </listitem>
1.185 +</itemizedlist>
1.186 +</refsection>
1.187 +
1.188 + <refsection id="seealso">
1.189 + <title>See Also</title>
1.190 + <para>signtool (1)</para>
1.191 +
1.192 + <para>The NSS wiki has information on the new database design and how to configure applications to use it.</para>
1.193 + <itemizedlist>
1.194 + <listitem>
1.195 + <para>Setting up the shared NSS database</para>
1.196 + <para>https://wiki.mozilla.org/NSS_Shared_DB_Howto</para>
1.197 + </listitem>
1.198 + <listitem>
1.199 + <para>
1.200 + Engineering and technical information about the shared NSS database
1.201 + </para>
1.202 + <para>
1.203 + https://wiki.mozilla.org/NSS_Shared_DB
1.204 + </para>
1.205 + </listitem>
1.206 + </itemizedlist>
1.207 + </refsection>
1.208 +
1.209 +<!-- don't change -->
1.210 + <refsection id="resources">
1.211 + <title>Additional Resources</title>
1.212 + <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>
1.213 + <para>Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto</para>
1.214 + <para>IRC: Freenode at #dogtag-pki</para>
1.215 + </refsection>
1.216 +
1.217 +<!-- fill in your name first; keep the other names for reference -->
1.218 + <refsection id="authors">
1.219 + <title>Authors</title>
1.220 + <para>The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google.</para>
1.221 + <para>
1.222 + Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey <dlackey@redhat.com>.
1.223 + </para>
1.224 + </refsection>
1.225 +
1.226 +<!-- don't change -->
1.227 + <refsection id="license">
1.228 + <title>LICENSE</title>
1.229 + <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/.
1.230 + </para>
1.231 + </refsection>
1.232 +
1.233 +</refentry>
