diff options
Diffstat (limited to 'security/nss/doc/signver.xml')
| -rw-r--r-- | security/nss/doc/signver.xml | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/security/nss/doc/signver.xml b/security/nss/doc/signver.xml new file mode 100644 index 000000000..e645e9190 --- /dev/null +++ b/security/nss/doc/signver.xml @@ -0,0 +1,230 @@ +<?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 [sql:]<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>sql:</command> is not used, then the tool assumes that the given databases are in the old 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 sql:/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 follow the more common legacy type. +Using the SQLite databases must be manually specified by using the <command>sql:</command> prefix with the given security directory. For example:</para> + +<programlisting># signver -A -s <replaceable>signature</replaceable> -d sql:/home/my/sharednssdb</programlisting> + +<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> +<programlisting>export NSS_DEFAULT_DB_TYPE="sql"</programlisting> + +<para>This line can be added to the <filename>~/.bashrc</filename> file to make the change permanent for the user.</para> + +<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> +<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> |