michael@0: '\" t
michael@0: .\"     Title: SIGNVER
michael@0: .\"    Author: [see the "Authors" section]
michael@0: .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
michael@0: .\"      Date:  5 June 2014
michael@0: .\"    Manual: NSS Security Tools
michael@0: .\"    Source: nss-tools
michael@0: .\"  Language: English
michael@0: .\"
michael@0: .TH "SIGNVER" "1" "5 June 2014" "nss-tools" "NSS Security Tools"
michael@0: .\" -----------------------------------------------------------------
michael@0: .\" * Define some portability stuff
michael@0: .\" -----------------------------------------------------------------
michael@0: .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
michael@0: .\" http://bugs.debian.org/507673
michael@0: .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
michael@0: .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
michael@0: .ie \n(.g .ds Aq \(aq
michael@0: .el       .ds Aq '
michael@0: .\" -----------------------------------------------------------------
michael@0: .\" * set default formatting
michael@0: .\" -----------------------------------------------------------------
michael@0: .\" disable hyphenation
michael@0: .nh
michael@0: .\" disable justification (adjust text to left margin only)
michael@0: .ad l
michael@0: .\" -----------------------------------------------------------------
michael@0: .\" * MAIN CONTENT STARTS HERE *
michael@0: .\" -----------------------------------------------------------------
michael@0: .SH "NAME"
michael@0: signver \- Verify a detached PKCS#7 signature for a file\&.
michael@0: .SH "SYNOPSIS"
michael@0: .HP \w'\fBsigntool\fR\ 'u
michael@0: \fBsigntool\fR \-A | \-V  \-d\ \fIdirectory\fR [\-a] [\-i\ \fIinput_file\fR] [\-o\ \fIoutput_file\fR] [\-s\ \fIsignature_file\fR] [\-v]
michael@0: .SH "STATUS"
michael@0: .PP
michael@0: This documentation is still work in progress\&. Please contribute to the initial review in
michael@0: \m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2
michael@0: .SH "DESCRIPTION"
michael@0: .PP
michael@0: The Signature Verification Tool,
michael@0: \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\&.
michael@0: .SH "OPTIONS"
michael@0: .PP
michael@0: \-A
michael@0: .RS 4
michael@0: Displays all of the information in the PKCS#7 signature\&.
michael@0: .RE
michael@0: .PP
michael@0: \-V
michael@0: .RS 4
michael@0: Verifies the digital signature\&.
michael@0: .RE
michael@0: .PP
michael@0: \-d [sql:]\fIdirectory\fR
michael@0: .RS 4
michael@0: Specify the database directory which contains the certificates and keys\&.
michael@0: .sp
michael@0: \fBsignver\fR
michael@0: supports two types of databases: the legacy security databases (cert8\&.db,
michael@0: key3\&.db, and
michael@0: secmod\&.db) and new SQLite databases (cert9\&.db,
michael@0: key4\&.db, and
michael@0: pkcs11\&.txt)\&. If the prefix
michael@0: \fBsql:\fR
michael@0: is not used, then the tool assumes that the given databases are in the old format\&.
michael@0: .RE
michael@0: .PP
michael@0: \-a
michael@0: .RS 4
michael@0: Sets that the given signature file is in ASCII format\&.
michael@0: .RE
michael@0: .PP
michael@0: \-i \fIinput_file\fR
michael@0: .RS 4
michael@0: Gives the input file for the object with signed data\&.
michael@0: .RE
michael@0: .PP
michael@0: \-o \fIoutput_file\fR
michael@0: .RS 4
michael@0: Gives the output file to which to write the results\&.
michael@0: .RE
michael@0: .PP
michael@0: \-s \fIsignature_file\fR
michael@0: .RS 4
michael@0: Gives the input file for the digital signature\&.
michael@0: .RE
michael@0: .PP
michael@0: \-v
michael@0: .RS 4
michael@0: Enables verbose output\&.
michael@0: .RE
michael@0: .SH "EXTENDED EXAMPLES"
michael@0: .SS "Verifying a Signature"
michael@0: .PP
michael@0: The
michael@0: \fB\-V\fR
michael@0: option verifies that the signature in a given signature file is valid when used to sign the given object (from the input file)\&.
michael@0: .sp
michael@0: .if n \{\
michael@0: .RS 4
michael@0: .\}
michael@0: .nf
michael@0: signver \-V \-s \fIsignature_file\fR \-i \fIsigned_file\fR \-d sql:/home/my/sharednssdb
michael@0: 
michael@0: signatureValid=yes
michael@0: .fi
michael@0: .if n \{\
michael@0: .RE
michael@0: .\}
michael@0: .SS "Printing Signature Data"
michael@0: .PP
michael@0: The
michael@0: \fB\-A\fR
michael@0: option prints all of the information contained in a signature file\&. Using the
michael@0: \fB\-o\fR
michael@0: option prints the signature file information to the given output file rather than stdout\&.
michael@0: .sp
michael@0: .if n \{\
michael@0: .RS 4
michael@0: .\}
michael@0: .nf
michael@0: signver \-A \-s \fIsignature_file\fR \-o \fIoutput_file\fR
michael@0: .fi
michael@0: .if n \{\
michael@0: .RE
michael@0: .\}
michael@0: .SH "NSS DATABASE TYPES"
michael@0: .PP
michael@0: NSS originally used BerkeleyDB databases to store security information\&. The last versions of these
michael@0: \fIlegacy\fR
michael@0: databases are:
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: cert8\&.db for certificates
michael@0: .RE
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: key3\&.db for keys
michael@0: .RE
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: secmod\&.db for PKCS #11 module information
michael@0: .RE
michael@0: .PP
michael@0: 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\&.
michael@0: .PP
michael@0: In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkleyDB\&. These new databases provide more accessibility and performance:
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: cert9\&.db for certificates
michael@0: .RE
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: key4\&.db for keys
michael@0: .RE
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory
michael@0: .RE
michael@0: .PP
michael@0: Because the SQLite databases are designed to be shared, these are the
michael@0: \fIshared\fR
michael@0: database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&.
michael@0: .PP
michael@0: By default, the tools (\fBcertutil\fR,
michael@0: \fBpk12util\fR,
michael@0: \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
michael@0: \fBsql:\fR
michael@0: prefix with the given security directory\&. For example:
michael@0: .sp
michael@0: .if n \{\
michael@0: .RS 4
michael@0: .\}
michael@0: .nf
michael@0: # signver \-A \-s \fIsignature\fR \-d sql:/home/my/sharednssdb
michael@0: .fi
michael@0: .if n \{\
michael@0: .RE
michael@0: .\}
michael@0: .PP
michael@0: To set the shared database type as the default type for the tools, set the
michael@0: \fBNSS_DEFAULT_DB_TYPE\fR
michael@0: environment variable to
michael@0: \fBsql\fR:
michael@0: .sp
michael@0: .if n \{\
michael@0: .RS 4
michael@0: .\}
michael@0: .nf
michael@0: export NSS_DEFAULT_DB_TYPE="sql"
michael@0: .fi
michael@0: .if n \{\
michael@0: .RE
michael@0: .\}
michael@0: .PP
michael@0: This line can be added to the
michael@0: ~/\&.bashrc
michael@0: file to make the change permanent for the user\&.
michael@0: .PP
michael@0: 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:
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto
michael@0: .RE
michael@0: .PP
michael@0: For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: https://wiki\&.mozilla\&.org/NSS_Shared_DB
michael@0: .RE
michael@0: .SH "SEE ALSO"
michael@0: .PP
michael@0: signtool (1)
michael@0: .PP
michael@0: The NSS wiki has information on the new database design and how to configure applications to use it\&.
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: Setting up the shared NSS database
michael@0: .sp
michael@0: https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto
michael@0: .RE
michael@0: .sp
michael@0: .RS 4
michael@0: .ie n \{\
michael@0: \h'-04'\(bu\h'+03'\c
michael@0: .\}
michael@0: .el \{\
michael@0: .sp -1
michael@0: .IP \(bu 2.3
michael@0: .\}
michael@0: Engineering and technical information about the shared NSS database
michael@0: .sp
michael@0: https://wiki\&.mozilla\&.org/NSS_Shared_DB
michael@0: .RE
michael@0: .SH "ADDITIONAL RESOURCES"
michael@0: .PP
michael@0: For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at
michael@0: \m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&.
michael@0: .PP
michael@0: Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto
michael@0: .PP
michael@0: IRC: Freenode at #dogtag\-pki
michael@0: .SH "AUTHORS"
michael@0: .PP
michael@0: The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&.
michael@0: .PP
michael@0: Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&.
michael@0: .SH "LICENSE"
michael@0: .PP
michael@0: 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/\&.
michael@0: .SH "NOTES"
michael@0: .IP " 1." 4
michael@0: Mozilla NSS bug 836477
michael@0: .RS 4
michael@0: \%https://bugzilla.mozilla.org/show_bug.cgi?id=836477
michael@0: .RE