gecko/security/nss/doc/nroff/signver.1

'\" t
.\"     Title: SIGNVER
.\"    Author: [see the "Authors" section]
.\" Generator: DocBook XSL Stylesheets v1.77.1 <http://docbook.sf.net/>
.\"      Date: 15 February 2013
.\"    Manual: NSS Security Tools
.\"    Source: nss-tools
.\"  Language: English
.\"
.TH "SIGNVER" "1" "15 February 2013" "nss-tools" "NSS Security Tools"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
signver \- Verify a detached PKCS#7 signature for a file\&.
.SH "SYNOPSIS"
.HP \w'\fBsigntool\fR\ 'u
\fBsigntool\fR \-A | \-V  \-d\ \fIdirectory\fR [\-a] [\-i\ \fIinput_file\fR] [\-o\ \fIoutput_file\fR] [\-s\ \fIsignature_file\fR] [\-v]
.SH "STATUS"
.PP
This documentation is still work in progress\&. Please contribute to the initial review in
\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2
.SH "DESCRIPTION"
.PP
The Signature Verification Tool,
\fBsignver\fR, 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\&.
.SH "OPTIONS"
.PP
\-A
.RS 4
Displays all of the information in the PKCS#7 signature\&.
.RE
.PP
\-V
.RS 4
Verifies the digital signature\&.
.RE
.PP
\-d [sql:]\fIdirectory\fR
.RS 4
Specify the database directory which contains the certificates and keys\&.
.sp
\fBsignver\fR
supports two types of databases: the legacy security databases (cert8\&.db,
key3\&.db, and
secmod\&.db) and new SQLite databases (cert9\&.db,
key4\&.db, and
pkcs11\&.txt)\&. If the prefix
\fBsql:\fR
is not used, then the tool assumes that the given databases are in the old format\&.
.RE
.PP
\-a
.RS 4
Sets that the given signature file is in ASCII format\&.
.RE
.PP
\-i \fIinput_file\fR
.RS 4
Gives the input file for the object with signed data\&.
.RE
.PP
\-o \fIoutput_file\fR
.RS 4
Gives the output file to which to write the results\&.
.RE
.PP
\-s \fIsignature_file\fR
.RS 4
Gives the input file for the digital signature\&.
.RE
.PP
\-v
.RS 4
Enables verbose output\&.
.RE
.SH "EXTENDED EXAMPLES"
.SS "Verifying a Signature"
.PP
The
\fB\-V\fR
option verifies that the signature in a given signature file is valid when used to sign the given object (from the input file)\&.
.sp
.if n \{\
.RS 4
.\}
.nf
signver \-V \-s \fIsignature_file\fR \-i \fIsigned_file\fR \-d sql:/home/my/sharednssdb

signatureValid=yes
.fi
.if n \{\
.RE
.\}
.SS "Printing Signature Data"
.PP
The
\fB\-A\fR
option prints all of the information contained in a signature file\&. Using the
\fB\-o\fR
option prints the signature file information to the given output file rather than stdout\&.
.sp
.if n \{\
.RS 4
.\}
.nf
signver \-A \-s \fIsignature_file\fR \-o \fIoutput_file\fR
.fi
.if n \{\
.RE
.\}
.SH "NSS DATABASE TYPES"
.PP
NSS originally used BerkeleyDB databases to store security information\&. The last versions of these
\fIlegacy\fR
databases are:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cert8\&.db for certificates
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
key3\&.db for keys
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
secmod\&.db for PKCS #11 module information
.RE
.PP
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\&.
.PP
In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkleyDB\&. These new databases provide more accessibility and performance:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
cert9\&.db for certificates
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
key4\&.db for keys
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory
.RE
.PP
Because the SQLite databases are designed to be shared, these are the
\fIshared\fR
database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&.
.PP
By default, the tools (\fBcertutil\fR,
\fBpk12util\fR,
\fBmodutil\fR) assume that the given security databases follow the more common legacy type\&. Using the SQLite databases must be manually specified by using the
\fBsql:\fR
prefix with the given security directory\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
# signver \-A \-s \fIsignature\fR \-d sql:/home/my/sharednssdb
.fi
.if n \{\
.RE
.\}
.PP
To set the shared database type as the default type for the tools, set the
\fBNSS_DEFAULT_DB_TYPE\fR
environment variable to
\fBsql\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
export NSS_DEFAULT_DB_TYPE="sql"
.fi
.if n \{\
.RE
.\}
.PP
This line can be set added to the
~/\&.bashrc
file to make the change permanent\&.
.PP
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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto
.RE
.PP
For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
https://wiki\&.mozilla\&.org/NSS_Shared_DB
.RE
.SH "SEE ALSO"
.PP
signtool (1)
.PP
The NSS wiki has information on the new database design and how to configure applications to use it\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Setting up the shared NSS database
.sp
https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Engineering and technical information about the shared NSS database
.sp
https://wiki\&.mozilla\&.org/NSS_Shared_DB
.RE
.SH "ADDITIONAL RESOURCES"
.PP
For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at
\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&.
.PP
Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto
.PP
IRC: Freenode at #dogtag\-pki
.SH "AUTHORS"
.PP
The NSS tools were written and maintained by developers with Netscape, Red Hat, and Sun\&.
.PP
Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&.
.SH "LICENSE"
.PP
Licensed under the Mozilla Public License, version 1\&.1, and/or the GNU General Public License, version 2 or later, and/or the GNU Lesser General Public License, version 2\&.1 or later\&.
.SH "NOTES"
.IP " 1." 4
Mozilla NSS bug 836477
.RS 4
\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477
.RE