| <?xml version="1.0" encoding="UTF-8"?> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [ |
| <!ENTITY date SYSTEM "date.xml"> |
| <!ENTITY version SYSTEM "version.xml"> |
| ]> |
| |
| <refentry id="signver"> |
| |
| <refentryinfo> |
| <date>&date;</date> |
| <title>NSS Security Tools</title> |
| <productname>nss-tools</productname> |
| <productnumber>&version;</productnumber> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>SIGNVER</refentrytitle> |
| <manvolnum>1</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>signver</refname> |
| <refpurpose>Verify a detached PKCS#7 signature for a file.</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>signtool</command> |
| <group choice="plain"> |
| <arg choice="plain">-A</arg> |
| <arg choice="plain">-V</arg> |
| </group> |
| <arg choice="plain">-d <replaceable>directory</replaceable></arg> |
| <arg>-a</arg> |
| <arg>-i <replaceable>input_file</replaceable></arg> |
| <arg>-o <replaceable>output_file</replaceable></arg> |
| <arg>-s <replaceable>signature_file</replaceable></arg> |
| <arg>-v</arg> |
| </cmdsynopsis> |
| </refsynopsisdiv> |
| |
| <refsection> |
| <title>STATUS</title> |
| <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> |
| </para> |
| </refsection> |
| |
| <refsection id="description"> |
| <title>Description</title> |
| |
| <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> |
| </refsection> |
| |
| <refsection id="options"> |
| <title>Options</title> |
| <variablelist> |
| <varlistentry> |
| <term>-A</term> |
| <listitem><para>Displays all of the information in the PKCS#7 signature.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>-V</term> |
| <listitem><para>Verifies the digital signature.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>-d <emphasis>directory</emphasis></term> |
| <listitem><para>Specify the database directory which contains the certificates and keys.</para> |
| <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>dbm:</command> is not used, then the tool assumes that the given databases are in the SQLite format.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>-a</term> |
| <listitem><para>Sets that the given signature file is in ASCII format.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>-i <emphasis>input_file</emphasis></term> |
| <listitem><para>Gives the input file for the object with signed data.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>-o <emphasis>output_file</emphasis></term> |
| <listitem><para>Gives the output file to which to write the results.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>-s <emphasis>signature_file</emphasis></term> |
| <listitem><para>Gives the input file for the digital signature.</para></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term>-v</term> |
| <listitem><para>Enables verbose output.</para></listitem> |
| </varlistentry> |
| </variablelist> |
| </refsection> |
| |
| <refsection id="examples"> |
| <title>Extended Examples</title> |
| <refsection><title>Verifying a Signature</title> |
| <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> |
| <programlisting>signver -V -s <replaceable>signature_file</replaceable> -i <replaceable>signed_file</replaceable> -d /home/my/sharednssdb |
| |
| signatureValid=yes</programlisting> |
| </refsection> |
| |
| <refsection><title>Printing Signature Data</title> |
| <para> |
| 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. |
| </para> |
| <programlisting>signver -A -s <replaceable>signature_file</replaceable> -o <replaceable>output_file</replaceable></programlisting> |
| </refsection> |
| </refsection> |
| |
| <refsection id="databases"><title>NSS Database Types</title> |
| <para>NSS originally used BerkeleyDB databases to store security information. |
| The last versions of these <emphasis>legacy</emphasis> databases are:</para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| cert8.db for certificates |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| key3.db for keys |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| secmod.db for PKCS #11 module information |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| <para>BerkeleyDB has performance limitations, though, which prevent it from being easily used by multiple applications simultaneously. NSS has |
| 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 |
| requires more flexibility to provide a truly shared security database.</para> |
| |
| <para>In 2009, NSS introduced a new set of databases that are SQLite databases rather than |
| BerkleyDB. These new databases provide more accessibility and performance:</para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| cert9.db for certificates |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| key4.db for keys |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| pkcs11.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| <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> |
| |
| <para>By default, the tools (<command>certutil</command>, <command>pk12util</command>, <command>modutil</command>) assume that the given security databases use the SQLite type |
| Using the legacy databases must be manually specified by using the <command>dbm:</command> prefix with the given security directory. For example:</para> |
| |
| <programlisting># signver -A -s <replaceable>signature</replaceable> -d dbm:/home/my/sharednssdb</programlisting> |
| |
| <para>To set the legacy database type as the default type for the tools, set the <envar>NSS_DEFAULT_DB_TYPE</envar> environment variable to <envar>dbm</envar>:</para> |
| <programlisting>export NSS_DEFAULT_DB_TYPE="dbm"</programlisting> |
| |
| <para>This line can be added to the <filename>~/.bashrc</filename> file to make the change permanent for the user.</para> |
| |
| <itemizedlist> |
| <listitem> |
| <para> |
| https://wiki.mozilla.org/NSS_Shared_DB_Howto</para> |
| </listitem> |
| </itemizedlist> |
| <para>For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:</para> |
| <itemizedlist> |
| <listitem> |
| <para> |
| https://wiki.mozilla.org/NSS_Shared_DB |
| </para> |
| </listitem> |
| </itemizedlist> |
| </refsection> |
| |
| <refsection id="seealso"> |
| <title>See Also</title> |
| <para>signtool (1)</para> |
| |
| <para>The NSS wiki has information on the new database design and how to configure applications to use it.</para> |
| <itemizedlist> |
| <listitem> |
| <para>Setting up the shared NSS database</para> |
| <para>https://wiki.mozilla.org/NSS_Shared_DB_Howto</para> |
| </listitem> |
| <listitem> |
| <para> |
| Engineering and technical information about the shared NSS database |
| </para> |
| <para> |
| https://wiki.mozilla.org/NSS_Shared_DB |
| </para> |
| </listitem> |
| </itemizedlist> |
| </refsection> |
| |
| <!-- don't change --> |
| <refsection id="resources"> |
| <title>Additional Resources</title> |
| <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> |
| <para>Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto</para> |
| <para>IRC: Freenode at #dogtag-pki</para> |
| </refsection> |
| |
| <!-- fill in your name first; keep the other names for reference --> |
| <refsection id="authors"> |
| <title>Authors</title> |
| <para>The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google.</para> |
| <para> |
| Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey <dlackey@redhat.com>. |
| </para> |
| </refsection> |
| |
| <!-- don't change --> |
| <refsection id="license"> |
| <title>LICENSE</title> |
| <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/. |
| </para> |
| </refsection> |
| |
| </refentry> |