'\" 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