summaryrefslogtreecommitdiffstats
path: root/security/nss/doc/nroff/signver.1
diff options
context:
space:
mode:
Diffstat (limited to 'security/nss/doc/nroff/signver.1')
-rw-r--r--security/nss/doc/nroff/signver.1320
1 files changed, 320 insertions, 0 deletions
diff --git a/security/nss/doc/nroff/signver.1 b/security/nss/doc/nroff/signver.1
new file mode 100644
index 000000000..ad92c11a6
--- /dev/null
+++ b/security/nss/doc/nroff/signver.1
@@ -0,0 +1,320 @@
+'\" t
+.\" Title: SIGNVER
+.\" Author: [see the "Authors" section]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Date: 5 June 2014
+.\" Manual: NSS Security Tools
+.\" Source: nss-tools
+.\" Language: English
+.\"
+.TH "SIGNVER" "1" "5 June 2014" "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 added to the
+~/\&.bashrc
+file to make the change permanent for the user\&.
+.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, Sun, Oracle, Mozilla, and Google\&.
+.PP
+Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&.
+.SH "LICENSE"
+.PP
+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/\&.
+.SH "NOTES"
+.IP " 1." 4
+Mozilla NSS bug 836477
+.RS 4
+\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477
+.RE