1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/doc/nroff/signver.1 Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,320 @@
1.4 +'\" t
1.5 +.\" Title: SIGNVER
1.6 +.\" Author: [see the "Authors" section]
1.7 +.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
1.8 +.\" Date: 5 June 2014
1.9 +.\" Manual: NSS Security Tools
1.10 +.\" Source: nss-tools
1.11 +.\" Language: English
1.12 +.\"
1.13 +.TH "SIGNVER" "1" "5 June 2014" "nss-tools" "NSS Security Tools"
1.14 +.\" -----------------------------------------------------------------
1.15 +.\" * Define some portability stuff
1.16 +.\" -----------------------------------------------------------------
1.17 +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.18 +.\" http://bugs.debian.org/507673
1.19 +.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
1.20 +.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1.21 +.ie \n(.g .ds Aq \(aq
1.22 +.el .ds Aq '
1.23 +.\" -----------------------------------------------------------------
1.24 +.\" * set default formatting
1.25 +.\" -----------------------------------------------------------------
1.26 +.\" disable hyphenation
1.27 +.nh
1.28 +.\" disable justification (adjust text to left margin only)
1.29 +.ad l
1.30 +.\" -----------------------------------------------------------------
1.31 +.\" * MAIN CONTENT STARTS HERE *
1.32 +.\" -----------------------------------------------------------------
1.33 +.SH "NAME"
1.34 +signver \- Verify a detached PKCS#7 signature for a file\&.
1.35 +.SH "SYNOPSIS"
1.36 +.HP \w'\fBsigntool\fR\ 'u
1.37 +\fBsigntool\fR \-A | \-V \-d\ \fIdirectory\fR [\-a] [\-i\ \fIinput_file\fR] [\-o\ \fIoutput_file\fR] [\-s\ \fIsignature_file\fR] [\-v]
1.38 +.SH "STATUS"
1.39 +.PP
1.40 +This documentation is still work in progress\&. Please contribute to the initial review in
1.41 +\m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2
1.42 +.SH "DESCRIPTION"
1.43 +.PP
1.44 +The Signature Verification Tool,
1.45 +\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\&.
1.46 +.SH "OPTIONS"
1.47 +.PP
1.48 +\-A
1.49 +.RS 4
1.50 +Displays all of the information in the PKCS#7 signature\&.
1.51 +.RE
1.52 +.PP
1.53 +\-V
1.54 +.RS 4
1.55 +Verifies the digital signature\&.
1.56 +.RE
1.57 +.PP
1.58 +\-d [sql:]\fIdirectory\fR
1.59 +.RS 4
1.60 +Specify the database directory which contains the certificates and keys\&.
1.61 +.sp
1.62 +\fBsignver\fR
1.63 +supports two types of databases: the legacy security databases (cert8\&.db,
1.64 +key3\&.db, and
1.65 +secmod\&.db) and new SQLite databases (cert9\&.db,
1.66 +key4\&.db, and
1.67 +pkcs11\&.txt)\&. If the prefix
1.68 +\fBsql:\fR
1.69 +is not used, then the tool assumes that the given databases are in the old format\&.
1.70 +.RE
1.71 +.PP
1.72 +\-a
1.73 +.RS 4
1.74 +Sets that the given signature file is in ASCII format\&.
1.75 +.RE
1.76 +.PP
1.77 +\-i \fIinput_file\fR
1.78 +.RS 4
1.79 +Gives the input file for the object with signed data\&.
1.80 +.RE
1.81 +.PP
1.82 +\-o \fIoutput_file\fR
1.83 +.RS 4
1.84 +Gives the output file to which to write the results\&.
1.85 +.RE
1.86 +.PP
1.87 +\-s \fIsignature_file\fR
1.88 +.RS 4
1.89 +Gives the input file for the digital signature\&.
1.90 +.RE
1.91 +.PP
1.92 +\-v
1.93 +.RS 4
1.94 +Enables verbose output\&.
1.95 +.RE
1.96 +.SH "EXTENDED EXAMPLES"
1.97 +.SS "Verifying a Signature"
1.98 +.PP
1.99 +The
1.100 +\fB\-V\fR
1.101 +option verifies that the signature in a given signature file is valid when used to sign the given object (from the input file)\&.
1.102 +.sp
1.103 +.if n \{\
1.104 +.RS 4
1.105 +.\}
1.106 +.nf
1.107 +signver \-V \-s \fIsignature_file\fR \-i \fIsigned_file\fR \-d sql:/home/my/sharednssdb
1.108 +
1.109 +signatureValid=yes
1.110 +.fi
1.111 +.if n \{\
1.112 +.RE
1.113 +.\}
1.114 +.SS "Printing Signature Data"
1.115 +.PP
1.116 +The
1.117 +\fB\-A\fR
1.118 +option prints all of the information contained in a signature file\&. Using the
1.119 +\fB\-o\fR
1.120 +option prints the signature file information to the given output file rather than stdout\&.
1.121 +.sp
1.122 +.if n \{\
1.123 +.RS 4
1.124 +.\}
1.125 +.nf
1.126 +signver \-A \-s \fIsignature_file\fR \-o \fIoutput_file\fR
1.127 +.fi
1.128 +.if n \{\
1.129 +.RE
1.130 +.\}
1.131 +.SH "NSS DATABASE TYPES"
1.132 +.PP
1.133 +NSS originally used BerkeleyDB databases to store security information\&. The last versions of these
1.134 +\fIlegacy\fR
1.135 +databases are:
1.136 +.sp
1.137 +.RS 4
1.138 +.ie n \{\
1.139 +\h'-04'\(bu\h'+03'\c
1.140 +.\}
1.141 +.el \{\
1.142 +.sp -1
1.143 +.IP \(bu 2.3
1.144 +.\}
1.145 +cert8\&.db for certificates
1.146 +.RE
1.147 +.sp
1.148 +.RS 4
1.149 +.ie n \{\
1.150 +\h'-04'\(bu\h'+03'\c
1.151 +.\}
1.152 +.el \{\
1.153 +.sp -1
1.154 +.IP \(bu 2.3
1.155 +.\}
1.156 +key3\&.db for keys
1.157 +.RE
1.158 +.sp
1.159 +.RS 4
1.160 +.ie n \{\
1.161 +\h'-04'\(bu\h'+03'\c
1.162 +.\}
1.163 +.el \{\
1.164 +.sp -1
1.165 +.IP \(bu 2.3
1.166 +.\}
1.167 +secmod\&.db for PKCS #11 module information
1.168 +.RE
1.169 +.PP
1.170 +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\&.
1.171 +.PP
1.172 +In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkleyDB\&. These new databases provide more accessibility and performance:
1.173 +.sp
1.174 +.RS 4
1.175 +.ie n \{\
1.176 +\h'-04'\(bu\h'+03'\c
1.177 +.\}
1.178 +.el \{\
1.179 +.sp -1
1.180 +.IP \(bu 2.3
1.181 +.\}
1.182 +cert9\&.db for certificates
1.183 +.RE
1.184 +.sp
1.185 +.RS 4
1.186 +.ie n \{\
1.187 +\h'-04'\(bu\h'+03'\c
1.188 +.\}
1.189 +.el \{\
1.190 +.sp -1
1.191 +.IP \(bu 2.3
1.192 +.\}
1.193 +key4\&.db for keys
1.194 +.RE
1.195 +.sp
1.196 +.RS 4
1.197 +.ie n \{\
1.198 +\h'-04'\(bu\h'+03'\c
1.199 +.\}
1.200 +.el \{\
1.201 +.sp -1
1.202 +.IP \(bu 2.3
1.203 +.\}
1.204 +pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory
1.205 +.RE
1.206 +.PP
1.207 +Because the SQLite databases are designed to be shared, these are the
1.208 +\fIshared\fR
1.209 +database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&.
1.210 +.PP
1.211 +By default, the tools (\fBcertutil\fR,
1.212 +\fBpk12util\fR,
1.213 +\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
1.214 +\fBsql:\fR
1.215 +prefix with the given security directory\&. For example:
1.216 +.sp
1.217 +.if n \{\
1.218 +.RS 4
1.219 +.\}
1.220 +.nf
1.221 +# signver \-A \-s \fIsignature\fR \-d sql:/home/my/sharednssdb
1.222 +.fi
1.223 +.if n \{\
1.224 +.RE
1.225 +.\}
1.226 +.PP
1.227 +To set the shared database type as the default type for the tools, set the
1.228 +\fBNSS_DEFAULT_DB_TYPE\fR
1.229 +environment variable to
1.230 +\fBsql\fR:
1.231 +.sp
1.232 +.if n \{\
1.233 +.RS 4
1.234 +.\}
1.235 +.nf
1.236 +export NSS_DEFAULT_DB_TYPE="sql"
1.237 +.fi
1.238 +.if n \{\
1.239 +.RE
1.240 +.\}
1.241 +.PP
1.242 +This line can be added to the
1.243 +~/\&.bashrc
1.244 +file to make the change permanent for the user\&.
1.245 +.PP
1.246 +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:
1.247 +.sp
1.248 +.RS 4
1.249 +.ie n \{\
1.250 +\h'-04'\(bu\h'+03'\c
1.251 +.\}
1.252 +.el \{\
1.253 +.sp -1
1.254 +.IP \(bu 2.3
1.255 +.\}
1.256 +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto
1.257 +.RE
1.258 +.PP
1.259 +For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:
1.260 +.sp
1.261 +.RS 4
1.262 +.ie n \{\
1.263 +\h'-04'\(bu\h'+03'\c
1.264 +.\}
1.265 +.el \{\
1.266 +.sp -1
1.267 +.IP \(bu 2.3
1.268 +.\}
1.269 +https://wiki\&.mozilla\&.org/NSS_Shared_DB
1.270 +.RE
1.271 +.SH "SEE ALSO"
1.272 +.PP
1.273 +signtool (1)
1.274 +.PP
1.275 +The NSS wiki has information on the new database design and how to configure applications to use it\&.
1.276 +.sp
1.277 +.RS 4
1.278 +.ie n \{\
1.279 +\h'-04'\(bu\h'+03'\c
1.280 +.\}
1.281 +.el \{\
1.282 +.sp -1
1.283 +.IP \(bu 2.3
1.284 +.\}
1.285 +Setting up the shared NSS database
1.286 +.sp
1.287 +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto
1.288 +.RE
1.289 +.sp
1.290 +.RS 4
1.291 +.ie n \{\
1.292 +\h'-04'\(bu\h'+03'\c
1.293 +.\}
1.294 +.el \{\
1.295 +.sp -1
1.296 +.IP \(bu 2.3
1.297 +.\}
1.298 +Engineering and technical information about the shared NSS database
1.299 +.sp
1.300 +https://wiki\&.mozilla\&.org/NSS_Shared_DB
1.301 +.RE
1.302 +.SH "ADDITIONAL RESOURCES"
1.303 +.PP
1.304 +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at
1.305 +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&.
1.306 +.PP
1.307 +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto
1.308 +.PP
1.309 +IRC: Freenode at #dogtag\-pki
1.310 +.SH "AUTHORS"
1.311 +.PP
1.312 +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&.
1.313 +.PP
1.314 +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&.
1.315 +.SH "LICENSE"
1.316 +.PP
1.317 +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/\&.
1.318 +.SH "NOTES"
1.319 +.IP " 1." 4
1.320 +Mozilla NSS bug 836477
1.321 +.RS 4
1.322 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477
1.323 +.RE
