The Tor Browser: security/nss/doc/nroff/signver.1@b8a032363ba2

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

     1 '\" t

     2 .\"     Title: SIGNVER

     3 .\"    Author: [see the "Authors" section]

     4 .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>

     5 .\"      Date:  5 June 2014

     6 .\"    Manual: NSS Security Tools

     7 .\"    Source: nss-tools

     8 .\"  Language: English

     9 .\"

    10 .TH "SIGNVER" "1" "5 June 2014" "nss-tools" "NSS Security Tools"

    11 .\" -----------------------------------------------------------------

    12 .\" * Define some portability stuff

    13 .\" -----------------------------------------------------------------

    14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    15 .\" http://bugs.debian.org/507673

    16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html

    17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    18 .ie \n(.g .ds Aq \(aq

    19 .el       .ds Aq '

    20 .\" -----------------------------------------------------------------

    21 .\" * set default formatting

    22 .\" -----------------------------------------------------------------

    23 .\" disable hyphenation

    24 .nh

    25 .\" disable justification (adjust text to left margin only)

    26 .ad l

    27 .\" -----------------------------------------------------------------

    28 .\" * MAIN CONTENT STARTS HERE *

    29 .\" -----------------------------------------------------------------

    30 .SH "NAME"

    31 signver \- Verify a detached PKCS#7 signature for a file\&.

    32 .SH "SYNOPSIS"

    33 .HP \w'\fBsigntool\fR\ 'u

    34 \fBsigntool\fR \-A | \-V  \-d\ \fIdirectory\fR [\-a] [\-i\ \fIinput_file\fR] [\-o\ \fIoutput_file\fR] [\-s\ \fIsignature_file\fR] [\-v]

    35 .SH "STATUS"

    36 .PP

    37 This documentation is still work in progress\&. Please contribute to the initial review in

    38 \m[blue]\fBMozilla NSS bug 836477\fR\m[]\&\s-2\u[1]\d\s+2

    39 .SH "DESCRIPTION"

    40 .PP

    41 The Signature Verification Tool,

    42 \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\&.

    43 .SH "OPTIONS"

    44 .PP

    45 \-A

    46 .RS 4

    47 Displays all of the information in the PKCS#7 signature\&.

    48 .RE

    49 .PP

    50 \-V

    51 .RS 4

    52 Verifies the digital signature\&.

    53 .RE

    54 .PP

    55 \-d [sql:]\fIdirectory\fR

    56 .RS 4

    57 Specify the database directory which contains the certificates and keys\&.

    58 .sp

    59 \fBsignver\fR

    60 supports two types of databases: the legacy security databases (cert8\&.db,

    61 key3\&.db, and

    62 secmod\&.db) and new SQLite databases (cert9\&.db,

    63 key4\&.db, and

    64 pkcs11\&.txt)\&. If the prefix

    65 \fBsql:\fR

    66 is not used, then the tool assumes that the given databases are in the old format\&.

    67 .RE

    68 .PP

    69 \-a

    70 .RS 4

    71 Sets that the given signature file is in ASCII format\&.

    72 .RE

    73 .PP

    74 \-i \fIinput_file\fR

    75 .RS 4

    76 Gives the input file for the object with signed data\&.

    77 .RE

    78 .PP

    79 \-o \fIoutput_file\fR

    80 .RS 4

    81 Gives the output file to which to write the results\&.

    82 .RE

    83 .PP

    84 \-s \fIsignature_file\fR

    85 .RS 4

    86 Gives the input file for the digital signature\&.

    87 .RE

    88 .PP

    89 \-v

    90 .RS 4

    91 Enables verbose output\&.

    92 .RE

    93 .SH "EXTENDED EXAMPLES"

    94 .SS "Verifying a Signature"

    95 .PP

    96 The

    97 \fB\-V\fR

    98 option verifies that the signature in a given signature file is valid when used to sign the given object (from the input file)\&.

    99 .sp

   100 .if n \{\

   101 .RS 4

   102 .\}

   103 .nf

   104 signver \-V \-s \fIsignature_file\fR \-i \fIsigned_file\fR \-d sql:/home/my/sharednssdb

   106 signatureValid=yes

   107 .fi

   108 .if n \{\

   109 .RE

   110 .\}

   111 .SS "Printing Signature Data"

   112 .PP

   113 The

   114 \fB\-A\fR

   115 option prints all of the information contained in a signature file\&. Using the

   116 \fB\-o\fR

   117 option prints the signature file information to the given output file rather than stdout\&.

   118 .sp

   119 .if n \{\

   120 .RS 4

   121 .\}

   122 .nf

   123 signver \-A \-s \fIsignature_file\fR \-o \fIoutput_file\fR

   124 .fi

   125 .if n \{\

   126 .RE

   127 .\}

   128 .SH "NSS DATABASE TYPES"

   129 .PP

   130 NSS originally used BerkeleyDB databases to store security information\&. The last versions of these

   131 \fIlegacy\fR

   132 databases are:

   133 .sp

   134 .RS 4

   135 .ie n \{\

   136 \h'-04'\(bu\h'+03'\c

   137 .\}

   138 .el \{\

   139 .sp -1

   140 .IP \(bu 2.3

   141 .\}

   142 cert8\&.db for certificates

   143 .RE

   144 .sp

   145 .RS 4

   146 .ie n \{\

   147 \h'-04'\(bu\h'+03'\c

   148 .\}

   149 .el \{\

   150 .sp -1

   151 .IP \(bu 2.3

   152 .\}

   153 key3\&.db for keys

   154 .RE

   155 .sp

   156 .RS 4

   157 .ie n \{\

   158 \h'-04'\(bu\h'+03'\c

   159 .\}

   160 .el \{\

   161 .sp -1

   162 .IP \(bu 2.3

   163 .\}

   164 secmod\&.db for PKCS #11 module information

   165 .RE

   166 .PP

   167 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\&.

   168 .PP

   169 In 2009, NSS introduced a new set of databases that are SQLite databases rather than BerkleyDB\&. These new databases provide more accessibility and performance:

   170 .sp

   171 .RS 4

   172 .ie n \{\

   173 \h'-04'\(bu\h'+03'\c

   174 .\}

   175 .el \{\

   176 .sp -1

   177 .IP \(bu 2.3

   178 .\}

   179 cert9\&.db for certificates

   180 .RE

   181 .sp

   182 .RS 4

   183 .ie n \{\

   184 \h'-04'\(bu\h'+03'\c

   185 .\}

   186 .el \{\

   187 .sp -1

   188 .IP \(bu 2.3

   189 .\}

   190 key4\&.db for keys

   191 .RE

   192 .sp

   193 .RS 4

   194 .ie n \{\

   195 \h'-04'\(bu\h'+03'\c

   196 .\}

   197 .el \{\

   198 .sp -1

   199 .IP \(bu 2.3

   200 .\}

   201 pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory

   202 .RE

   203 .PP

   204 Because the SQLite databases are designed to be shared, these are the

   205 \fIshared\fR

   206 database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&.

   207 .PP

   208 By default, the tools (\fBcertutil\fR,

   209 \fBpk12util\fR,

   210 \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

   211 \fBsql:\fR

   212 prefix with the given security directory\&. For example:

   213 .sp

   214 .if n \{\

   215 .RS 4

   216 .\}

   217 .nf

   218 # signver \-A \-s \fIsignature\fR \-d sql:/home/my/sharednssdb

   219 .fi

   220 .if n \{\

   221 .RE

   222 .\}

   223 .PP

   224 To set the shared database type as the default type for the tools, set the

   225 \fBNSS_DEFAULT_DB_TYPE\fR

   226 environment variable to

   227 \fBsql\fR:

   228 .sp

   229 .if n \{\

   230 .RS 4

   231 .\}

   232 .nf

   233 export NSS_DEFAULT_DB_TYPE="sql"

   234 .fi

   235 .if n \{\

   236 .RE

   237 .\}

   238 .PP

   239 This line can be added to the

   240 ~/\&.bashrc

   241 file to make the change permanent for the user\&.

   242 .PP

   243 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:

   244 .sp

   245 .RS 4

   246 .ie n \{\

   247 \h'-04'\(bu\h'+03'\c

   248 .\}

   249 .el \{\

   250 .sp -1

   251 .IP \(bu 2.3

   252 .\}

   253 https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto

   254 .RE

   255 .PP

   256 For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:

   257 .sp

   258 .RS 4

   259 .ie n \{\

   260 \h'-04'\(bu\h'+03'\c

   261 .\}

   262 .el \{\

   263 .sp -1

   264 .IP \(bu 2.3

   265 .\}

   266 https://wiki\&.mozilla\&.org/NSS_Shared_DB

   267 .RE

   268 .SH "SEE ALSO"

   269 .PP

   270 signtool (1)

   271 .PP

   272 The NSS wiki has information on the new database design and how to configure applications to use it\&.

   273 .sp

   274 .RS 4

   275 .ie n \{\

   276 \h'-04'\(bu\h'+03'\c

   277 .\}

   278 .el \{\

   279 .sp -1

   280 .IP \(bu 2.3

   281 .\}

   282 Setting up the shared NSS database

   283 .sp

   284 https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto

   285 .RE

   286 .sp

   287 .RS 4

   288 .ie n \{\

   289 \h'-04'\(bu\h'+03'\c

   290 .\}

   291 .el \{\

   292 .sp -1

   293 .IP \(bu 2.3

   294 .\}

   295 Engineering and technical information about the shared NSS database

   296 .sp

   297 https://wiki\&.mozilla\&.org/NSS_Shared_DB

   298 .RE

   299 .SH "ADDITIONAL RESOURCES"

   300 .PP

   301 For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at

   302 \m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&.

   303 .PP

   304 Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto

   305 .PP

   306 IRC: Freenode at #dogtag\-pki

   307 .SH "AUTHORS"

   308 .PP

   309 The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&.

   310 .PP

   311 Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&.

   312 .SH "LICENSE"

   313 .PP

   314 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/\&.

   315 .SH "NOTES"

   316 .IP " 1." 4

   317 Mozilla NSS bug 836477

   318 .RS 4

   319 \%https://bugzilla.mozilla.org/show_bug.cgi?id=836477

   320 .RE

The Tor Browser / file revision

security/nss/doc/nroff/signver.1@b8a032363ba2

security/nss/doc/nroff/signver.1