nss-3.73/nss/doc/nroff/signver.1 - manifest_repos/nss - Git at Google

 '\" t
 .\"     Title: SIGNVER
 .\"    Author: [see the "Authors" section]
 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
 .\"      Date: 19 May 2021
 .\"    Manual: NSS Security Tools
 .\"    Source: nss-tools
 .\"  Language: English
 .\"
 .TH "SIGNVER" "1" "19 May 2021" "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 \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
 \fBdbm:\fR
 is not used, then the tool assumes that the given databases are in the SQLite 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 /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 use the SQLite type Using the legacy databases must be manually specified by using the
 \fBdbm:\fR
 prefix with the given security directory\&. For example:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 # signver \-A \-s \fIsignature\fR \-d dbm:/home/my/sharednssdb
 .fi
 .if n \{\
 .RE
 .\}
 .PP
 To set the legacy database type as the default type for the tools, set the
 \fBNSS_DEFAULT_DB_TYPE\fR
 environment variable to
 \fBdbm\fR:
 .sp
 .if n \{\
 .RS 4
 .\}
 .nf
 export NSS_DEFAULT_DB_TYPE="dbm"
 .fi
 .if n \{\
 .RE
 .\}
 .PP
 This line can be added to the
 ~/\&.bashrc
 file to make the change permanent for the user\&.
 .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
	'\" t
	.\" Title: SIGNVER
	.\" Author: [see the "Authors" section]
	.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
	.\" Date: 19 May 2021
	.\" Manual: NSS Security Tools
	.\" Source: nss-tools
	.\" Language: English
	.\"
	.TH "SIGNVER" "1" "19 May 2021" "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 \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
	\fBdbm:\fR
	is not used, then the tool assumes that the given databases are in the SQLite 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 /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 use the SQLite type Using the legacy databases must be manually specified by using the
	\fBdbm:\fR
	prefix with the given security directory\&. For example:
	.sp
	.if n \{\
	.RS 4
	.\}
	.nf
	# signver \-A \-s \fIsignature\fR \-d dbm:/home/my/sharednssdb
	.fi
	.if n \{\
	.RE
	.\}
	.PP
	To set the legacy database type as the default type for the tools, set the
	\fBNSS_DEFAULT_DB_TYPE\fR
	environment variable to
	\fBdbm\fR:
	.sp
	.if n \{\
	.RS 4
	.\}
	.nf
	export NSS_DEFAULT_DB_TYPE="dbm"
	.fi
	.if n \{\
	.RE
	.\}
	.PP
	This line can be added to the
	~/\&.bashrc
	file to make the change permanent for the user\&.
	.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