1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/doc/nroff/pk12util.1 Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,1040 @@
1.4 +'\" t
1.5 +.\" Title: PK12UTIL
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 "PK12UTIL" "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 +pk12util \- Export and import keys and certificate to or from a PKCS #12 file and the NSS database
1.35 +.SH "SYNOPSIS"
1.36 +.HP \w'\fBpk12util\fR\ 'u
1.37 +\fBpk12util\fR [\-i\ p12File|\-l\ p12File|\-o\ p12File] [\-d\ [sql:]directory] [\-h\ tokenname] [\-P\ dbprefix] [\-r] [\-v] [\-k\ slotPasswordFile|\-K\ slotPassword] [\-w\ p12filePasswordFile|\-W\ p12filePassword]
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 PKCS #12 utility,
1.45 +\fBpk12util\fR, enables sharing certificates among any server that supports PKCS#12\&. The tool can import certificates and keys from PKCS#12 files into security databases, export certificates, and list certificates and keys\&.
1.46 +.SH "OPTIONS AND ARGUMENTS"
1.47 +.PP
1.48 +\fBOptions\fR
1.49 +.PP
1.50 +\-i p12file
1.51 +.RS 4
1.52 +Import keys and certificates from a PKCS#12 file into a security database\&.
1.53 +.RE
1.54 +.PP
1.55 +\-l p12file
1.56 +.RS 4
1.57 +List the keys and certificates in PKCS#12 file\&.
1.58 +.RE
1.59 +.PP
1.60 +\-o p12file
1.61 +.RS 4
1.62 +Export keys and certificates from the security database to a PKCS#12 file\&.
1.63 +.RE
1.64 +.PP
1.65 +\fBArguments\fR
1.66 +.PP
1.67 +\-c keyCipher
1.68 +.RS 4
1.69 +Specify the key encryption algorithm\&.
1.70 +.RE
1.71 +.PP
1.72 +\-C certCipher
1.73 +.RS 4
1.74 +Specify the key cert (overall package) encryption algorithm\&.
1.75 +.RE
1.76 +.PP
1.77 +\-d [sql:]directory
1.78 +.RS 4
1.79 +Specify the database directory into which to import to or export from certificates and keys\&.
1.80 +.sp
1.81 +\fBpk12util\fR
1.82 +supports two types of databases: the legacy security databases (cert8\&.db,
1.83 +key3\&.db, and
1.84 +secmod\&.db) and new SQLite databases (cert9\&.db,
1.85 +key4\&.db, and
1.86 +pkcs11\&.txt)\&. If the prefix
1.87 +\fBsql:\fR
1.88 +is not used, then the tool assumes that the given databases are in the old format\&.
1.89 +.RE
1.90 +.PP
1.91 +\-h tokenname
1.92 +.RS 4
1.93 +Specify the name of the token to import into or export from\&.
1.94 +.RE
1.95 +.PP
1.96 +\-k slotPasswordFile
1.97 +.RS 4
1.98 +Specify the text file containing the slot\*(Aqs password\&.
1.99 +.RE
1.100 +.PP
1.101 +\-K slotPassword
1.102 +.RS 4
1.103 +Specify the slot\*(Aqs password\&.
1.104 +.RE
1.105 +.PP
1.106 +\-m | \-\-key\-len keyLength
1.107 +.RS 4
1.108 +Specify the desired length of the symmetric key to be used to encrypt the private key\&.
1.109 +.RE
1.110 +.PP
1.111 +\-n | \-\-cert\-key\-len certKeyLength
1.112 +.RS 4
1.113 +Specify the desired length of the symmetric key to be used to encrypt the certificates and other meta\-data\&.
1.114 +.RE
1.115 +.PP
1.116 +\-n certname
1.117 +.RS 4
1.118 +Specify the nickname of the cert and private key to export\&.
1.119 +.RE
1.120 +.PP
1.121 +\-P prefix
1.122 +.RS 4
1.123 +Specify the prefix used on the certificate and key databases\&. This option is provided as a special case\&. Changing the names of the certificate and key databases is not recommended\&.
1.124 +.RE
1.125 +.PP
1.126 +\-r
1.127 +.RS 4
1.128 +Dumps all of the data in raw (binary) form\&. This must be saved as a DER file\&. The default is to return information in a pretty\-print ASCII format, which displays the information about the certificates and public keys in the p12 file\&.
1.129 +.RE
1.130 +.PP
1.131 +\-v
1.132 +.RS 4
1.133 +Enable debug logging when importing\&.
1.134 +.RE
1.135 +.PP
1.136 +\-w p12filePasswordFile
1.137 +.RS 4
1.138 +Specify the text file containing the pkcs #12 file password\&.
1.139 +.RE
1.140 +.PP
1.141 +\-W p12filePassword
1.142 +.RS 4
1.143 +Specify the pkcs #12 file password\&.
1.144 +.RE
1.145 +.SH "RETURN CODES"
1.146 +.sp
1.147 +.RS 4
1.148 +.ie n \{\
1.149 +\h'-04'\(bu\h'+03'\c
1.150 +.\}
1.151 +.el \{\
1.152 +.sp -1
1.153 +.IP \(bu 2.3
1.154 +.\}
1.155 +0 \- No error
1.156 +.RE
1.157 +.sp
1.158 +.RS 4
1.159 +.ie n \{\
1.160 +\h'-04'\(bu\h'+03'\c
1.161 +.\}
1.162 +.el \{\
1.163 +.sp -1
1.164 +.IP \(bu 2.3
1.165 +.\}
1.166 +1 \- User Cancelled
1.167 +.RE
1.168 +.sp
1.169 +.RS 4
1.170 +.ie n \{\
1.171 +\h'-04'\(bu\h'+03'\c
1.172 +.\}
1.173 +.el \{\
1.174 +.sp -1
1.175 +.IP \(bu 2.3
1.176 +.\}
1.177 +2 \- Usage error
1.178 +.RE
1.179 +.sp
1.180 +.RS 4
1.181 +.ie n \{\
1.182 +\h'-04'\(bu\h'+03'\c
1.183 +.\}
1.184 +.el \{\
1.185 +.sp -1
1.186 +.IP \(bu 2.3
1.187 +.\}
1.188 +6 \- NLS init error
1.189 +.RE
1.190 +.sp
1.191 +.RS 4
1.192 +.ie n \{\
1.193 +\h'-04'\(bu\h'+03'\c
1.194 +.\}
1.195 +.el \{\
1.196 +.sp -1
1.197 +.IP \(bu 2.3
1.198 +.\}
1.199 +8 \- Certificate DB open error
1.200 +.RE
1.201 +.sp
1.202 +.RS 4
1.203 +.ie n \{\
1.204 +\h'-04'\(bu\h'+03'\c
1.205 +.\}
1.206 +.el \{\
1.207 +.sp -1
1.208 +.IP \(bu 2.3
1.209 +.\}
1.210 +9 \- Key DB open error
1.211 +.RE
1.212 +.sp
1.213 +.RS 4
1.214 +.ie n \{\
1.215 +\h'-04'\(bu\h'+03'\c
1.216 +.\}
1.217 +.el \{\
1.218 +.sp -1
1.219 +.IP \(bu 2.3
1.220 +.\}
1.221 +10 \- File initialization error
1.222 +.RE
1.223 +.sp
1.224 +.RS 4
1.225 +.ie n \{\
1.226 +\h'-04'\(bu\h'+03'\c
1.227 +.\}
1.228 +.el \{\
1.229 +.sp -1
1.230 +.IP \(bu 2.3
1.231 +.\}
1.232 +11 \- Unicode conversion error
1.233 +.RE
1.234 +.sp
1.235 +.RS 4
1.236 +.ie n \{\
1.237 +\h'-04'\(bu\h'+03'\c
1.238 +.\}
1.239 +.el \{\
1.240 +.sp -1
1.241 +.IP \(bu 2.3
1.242 +.\}
1.243 +12 \- Temporary file creation error
1.244 +.RE
1.245 +.sp
1.246 +.RS 4
1.247 +.ie n \{\
1.248 +\h'-04'\(bu\h'+03'\c
1.249 +.\}
1.250 +.el \{\
1.251 +.sp -1
1.252 +.IP \(bu 2.3
1.253 +.\}
1.254 +13 \- PKCS11 get slot error
1.255 +.RE
1.256 +.sp
1.257 +.RS 4
1.258 +.ie n \{\
1.259 +\h'-04'\(bu\h'+03'\c
1.260 +.\}
1.261 +.el \{\
1.262 +.sp -1
1.263 +.IP \(bu 2.3
1.264 +.\}
1.265 +14 \- PKCS12 decoder start error
1.266 +.RE
1.267 +.sp
1.268 +.RS 4
1.269 +.ie n \{\
1.270 +\h'-04'\(bu\h'+03'\c
1.271 +.\}
1.272 +.el \{\
1.273 +.sp -1
1.274 +.IP \(bu 2.3
1.275 +.\}
1.276 +15 \- error read from import file
1.277 +.RE
1.278 +.sp
1.279 +.RS 4
1.280 +.ie n \{\
1.281 +\h'-04'\(bu\h'+03'\c
1.282 +.\}
1.283 +.el \{\
1.284 +.sp -1
1.285 +.IP \(bu 2.3
1.286 +.\}
1.287 +16 \- pkcs12 decode error
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 +17 \- pkcs12 decoder verify error
1.299 +.RE
1.300 +.sp
1.301 +.RS 4
1.302 +.ie n \{\
1.303 +\h'-04'\(bu\h'+03'\c
1.304 +.\}
1.305 +.el \{\
1.306 +.sp -1
1.307 +.IP \(bu 2.3
1.308 +.\}
1.309 +18 \- pkcs12 decoder validate bags error
1.310 +.RE
1.311 +.sp
1.312 +.RS 4
1.313 +.ie n \{\
1.314 +\h'-04'\(bu\h'+03'\c
1.315 +.\}
1.316 +.el \{\
1.317 +.sp -1
1.318 +.IP \(bu 2.3
1.319 +.\}
1.320 +19 \- pkcs12 decoder import bags error
1.321 +.RE
1.322 +.sp
1.323 +.RS 4
1.324 +.ie n \{\
1.325 +\h'-04'\(bu\h'+03'\c
1.326 +.\}
1.327 +.el \{\
1.328 +.sp -1
1.329 +.IP \(bu 2.3
1.330 +.\}
1.331 +20 \- key db conversion version 3 to version 2 error
1.332 +.RE
1.333 +.sp
1.334 +.RS 4
1.335 +.ie n \{\
1.336 +\h'-04'\(bu\h'+03'\c
1.337 +.\}
1.338 +.el \{\
1.339 +.sp -1
1.340 +.IP \(bu 2.3
1.341 +.\}
1.342 +21 \- cert db conversion version 7 to version 5 error
1.343 +.RE
1.344 +.sp
1.345 +.RS 4
1.346 +.ie n \{\
1.347 +\h'-04'\(bu\h'+03'\c
1.348 +.\}
1.349 +.el \{\
1.350 +.sp -1
1.351 +.IP \(bu 2.3
1.352 +.\}
1.353 +22 \- cert and key dbs patch error
1.354 +.RE
1.355 +.sp
1.356 +.RS 4
1.357 +.ie n \{\
1.358 +\h'-04'\(bu\h'+03'\c
1.359 +.\}
1.360 +.el \{\
1.361 +.sp -1
1.362 +.IP \(bu 2.3
1.363 +.\}
1.364 +23 \- get default cert db error
1.365 +.RE
1.366 +.sp
1.367 +.RS 4
1.368 +.ie n \{\
1.369 +\h'-04'\(bu\h'+03'\c
1.370 +.\}
1.371 +.el \{\
1.372 +.sp -1
1.373 +.IP \(bu 2.3
1.374 +.\}
1.375 +24 \- find cert by nickname error
1.376 +.RE
1.377 +.sp
1.378 +.RS 4
1.379 +.ie n \{\
1.380 +\h'-04'\(bu\h'+03'\c
1.381 +.\}
1.382 +.el \{\
1.383 +.sp -1
1.384 +.IP \(bu 2.3
1.385 +.\}
1.386 +25 \- create export context error
1.387 +.RE
1.388 +.sp
1.389 +.RS 4
1.390 +.ie n \{\
1.391 +\h'-04'\(bu\h'+03'\c
1.392 +.\}
1.393 +.el \{\
1.394 +.sp -1
1.395 +.IP \(bu 2.3
1.396 +.\}
1.397 +26 \- PKCS12 add password itegrity error
1.398 +.RE
1.399 +.sp
1.400 +.RS 4
1.401 +.ie n \{\
1.402 +\h'-04'\(bu\h'+03'\c
1.403 +.\}
1.404 +.el \{\
1.405 +.sp -1
1.406 +.IP \(bu 2.3
1.407 +.\}
1.408 +27 \- cert and key Safes creation error
1.409 +.RE
1.410 +.sp
1.411 +.RS 4
1.412 +.ie n \{\
1.413 +\h'-04'\(bu\h'+03'\c
1.414 +.\}
1.415 +.el \{\
1.416 +.sp -1
1.417 +.IP \(bu 2.3
1.418 +.\}
1.419 +28 \- PKCS12 add cert and key error
1.420 +.RE
1.421 +.sp
1.422 +.RS 4
1.423 +.ie n \{\
1.424 +\h'-04'\(bu\h'+03'\c
1.425 +.\}
1.426 +.el \{\
1.427 +.sp -1
1.428 +.IP \(bu 2.3
1.429 +.\}
1.430 +29 \- PKCS12 encode error
1.431 +.RE
1.432 +.SH "EXAMPLES"
1.433 +.PP
1.434 +\fBImporting Keys and Certificates\fR
1.435 +.PP
1.436 +The most basic usage of
1.437 +\fBpk12util\fR
1.438 +for importing a certificate or key is the PKCS#12 input file (\fB\-i\fR) and some way to specify the security database being accessed (either
1.439 +\fB\-d\fR
1.440 +for a directory or
1.441 +\fB\-h\fR
1.442 +for a token)\&.
1.443 +.PP
1.444 +pk12util \-i p12File [\-h tokenname] [\-v] [\-d [sql:]directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword]
1.445 +.PP
1.446 +For example:
1.447 +.PP
1.448 +
1.449 +.sp
1.450 +.if n \{\
1.451 +.RS 4
1.452 +.\}
1.453 +.nf
1.454 +# pk12util \-i /tmp/cert\-files/users\&.p12 \-d sql:/home/my/sharednssdb
1.455 +
1.456 +Enter a password which will be used to encrypt your keys\&.
1.457 +The password should be at least 8 characters long,
1.458 +and should contain at least one non\-alphabetic character\&.
1.459 +
1.460 +Enter new password:
1.461 +Re\-enter password:
1.462 +Enter password for PKCS12 file:
1.463 +pk12util: PKCS12 IMPORT SUCCESSFUL
1.464 +.fi
1.465 +.if n \{\
1.466 +.RE
1.467 +.\}
1.468 +.PP
1.469 +\fBExporting Keys and Certificates\fR
1.470 +.PP
1.471 +Using the
1.472 +\fBpk12util\fR
1.473 +command to export certificates and keys requires both the name of the certificate to extract from the database (\fB\-n\fR) and the PKCS#12\-formatted output file to write to\&. There are optional parameters that can be used to encrypt the file to protect the certificate material\&.
1.474 +.PP
1.475 +pk12util \-o p12File \-n certname [\-c keyCipher] [\-C certCipher] [\-m|\-\-key_len keyLen] [\-n|\-\-cert_key_len certKeyLen] [\-d [sql:]directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword]
1.476 +.PP
1.477 +For example:
1.478 +.sp
1.479 +.if n \{\
1.480 +.RS 4
1.481 +.\}
1.482 +.nf
1.483 +# pk12util \-o certs\&.p12 \-n Server\-Cert \-d sql:/home/my/sharednssdb
1.484 +Enter password for PKCS12 file:
1.485 +Re\-enter password:
1.486 +.fi
1.487 +.if n \{\
1.488 +.RE
1.489 +.\}
1.490 +.PP
1.491 +\fBListing Keys and Certificates\fR
1.492 +.PP
1.493 +The information in a
1.494 +\&.p12
1.495 +file are not human\-readable\&. The certificates and keys in the file can be printed (listed) in a human\-readable pretty\-print format that shows information for every certificate and any public keys in the
1.496 +\&.p12
1.497 +file\&.
1.498 +.PP
1.499 +pk12util \-l p12File [\-h tokenname] [\-r] [\-d [sql:]directory] [\-P dbprefix] [\-k slotPasswordFile|\-K slotPassword] [\-w p12filePasswordFile|\-W p12filePassword]
1.500 +.PP
1.501 +For example, this prints the default ASCII output:
1.502 +.sp
1.503 +.if n \{\
1.504 +.RS 4
1.505 +.\}
1.506 +.nf
1.507 +# pk12util \-l certs\&.p12
1.508 +
1.509 +Enter password for PKCS12 file:
1.510 +Key(shrouded):
1.511 + Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID
1.512 +
1.513 + Encryption algorithm: PKCS #12 V2 PBE With SHA\-1 And 3KEY Triple DES\-CBC
1.514 + Parameters:
1.515 + Salt:
1.516 + 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
1.517 + Iteration Count: 1 (0x1)
1.518 +Certificate:
1.519 + Data:
1.520 + Version: 3 (0x2)
1.521 + Serial Number: 13 (0xd)
1.522 + Signature Algorithm: PKCS #1 SHA\-1 With RSA Encryption
1.523 + Issuer: "E=personal\-freemail@thawte\&.com,CN=Thawte Personal Freemail C
1.524 + A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T
1.525 + own,ST=Western Cape,C=ZA"
1.526 +
1.527 +.fi
1.528 +.if n \{\
1.529 +.RE
1.530 +.\}
1.531 +.PP
1.532 +Alternatively, the
1.533 +\fB\-r\fR
1.534 +prints the certificates and then exports them into separate DER binary files\&. This allows the certificates to be fed to another application that supports
1.535 +\&.p12
1.536 +files\&. Each certificate is written to a sequentially\-number file, beginning with
1.537 +file0001\&.der
1.538 +and continuing through
1.539 +file000N\&.der, incrementing the number for every certificate:
1.540 +.sp
1.541 +.if n \{\
1.542 +.RS 4
1.543 +.\}
1.544 +.nf
1.545 +pk12util \-l test\&.p12 \-r
1.546 +Enter password for PKCS12 file:
1.547 +Key(shrouded):
1.548 + Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID
1.549 +
1.550 + Encryption algorithm: PKCS #12 V2 PBE With SHA\-1 And 3KEY Triple DES\-CBC
1.551 + Parameters:
1.552 + Salt:
1.553 + 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f
1.554 + Iteration Count: 1 (0x1)
1.555 +Certificate Friendly Name: Thawte Personal Freemail Issuing CA \- Thawte Consulting
1.556 +
1.557 +Certificate Friendly Name: Thawte Freemail Member\*(Aqs Thawte Consulting (Pty) Ltd\&. ID
1.558 +
1.559 +.fi
1.560 +.if n \{\
1.561 +.RE
1.562 +.\}
1.563 +.SH "PASSWORD ENCRYPTION"
1.564 +.PP
1.565 +PKCS#12 provides for not only the protection of the private keys but also the certificate and meta\-data associated with the keys\&. Password\-based encryption is used to protect private keys on export to a PKCS#12 file and, optionally, the entire package\&. If no algorithm is specified, the tool defaults to using
1.566 +\fBPKCS12 V2 PBE with SHA1 and 3KEY Triple DES\-cbc\fR
1.567 +for private key encryption\&.
1.568 +\fBPKCS12 V2 PBE with SHA1 and 40 Bit RC4\fR
1.569 +is the default for the overall package encryption when not in FIPS mode\&. When in FIPS mode, there is no package encryption\&.
1.570 +.PP
1.571 +The private key is always protected with strong encryption by default\&.
1.572 +.PP
1.573 +Several types of ciphers are supported\&.
1.574 +.PP
1.575 +Symmetric CBC ciphers for PKCS#5 V2
1.576 +.RS 4
1.577 +.sp
1.578 +.RS 4
1.579 +.ie n \{\
1.580 +\h'-04'\(bu\h'+03'\c
1.581 +.\}
1.582 +.el \{\
1.583 +.sp -1
1.584 +.IP \(bu 2.3
1.585 +.\}
1.586 +DES\-CBC
1.587 +.RE
1.588 +.sp
1.589 +.RS 4
1.590 +.ie n \{\
1.591 +\h'-04'\(bu\h'+03'\c
1.592 +.\}
1.593 +.el \{\
1.594 +.sp -1
1.595 +.IP \(bu 2.3
1.596 +.\}
1.597 +RC2\-CBC
1.598 +.RE
1.599 +.sp
1.600 +.RS 4
1.601 +.ie n \{\
1.602 +\h'-04'\(bu\h'+03'\c
1.603 +.\}
1.604 +.el \{\
1.605 +.sp -1
1.606 +.IP \(bu 2.3
1.607 +.\}
1.608 +RC5\-CBCPad
1.609 +.RE
1.610 +.sp
1.611 +.RS 4
1.612 +.ie n \{\
1.613 +\h'-04'\(bu\h'+03'\c
1.614 +.\}
1.615 +.el \{\
1.616 +.sp -1
1.617 +.IP \(bu 2.3
1.618 +.\}
1.619 +DES\-EDE3\-CBC (the default for key encryption)
1.620 +.RE
1.621 +.sp
1.622 +.RS 4
1.623 +.ie n \{\
1.624 +\h'-04'\(bu\h'+03'\c
1.625 +.\}
1.626 +.el \{\
1.627 +.sp -1
1.628 +.IP \(bu 2.3
1.629 +.\}
1.630 +AES\-128\-CBC
1.631 +.RE
1.632 +.sp
1.633 +.RS 4
1.634 +.ie n \{\
1.635 +\h'-04'\(bu\h'+03'\c
1.636 +.\}
1.637 +.el \{\
1.638 +.sp -1
1.639 +.IP \(bu 2.3
1.640 +.\}
1.641 +AES\-192\-CBC
1.642 +.RE
1.643 +.sp
1.644 +.RS 4
1.645 +.ie n \{\
1.646 +\h'-04'\(bu\h'+03'\c
1.647 +.\}
1.648 +.el \{\
1.649 +.sp -1
1.650 +.IP \(bu 2.3
1.651 +.\}
1.652 +AES\-256\-CBC
1.653 +.RE
1.654 +.sp
1.655 +.RS 4
1.656 +.ie n \{\
1.657 +\h'-04'\(bu\h'+03'\c
1.658 +.\}
1.659 +.el \{\
1.660 +.sp -1
1.661 +.IP \(bu 2.3
1.662 +.\}
1.663 +CAMELLIA\-128\-CBC
1.664 +.RE
1.665 +.sp
1.666 +.RS 4
1.667 +.ie n \{\
1.668 +\h'-04'\(bu\h'+03'\c
1.669 +.\}
1.670 +.el \{\
1.671 +.sp -1
1.672 +.IP \(bu 2.3
1.673 +.\}
1.674 +CAMELLIA\-192\-CBC
1.675 +.RE
1.676 +.sp
1.677 +.RS 4
1.678 +.ie n \{\
1.679 +\h'-04'\(bu\h'+03'\c
1.680 +.\}
1.681 +.el \{\
1.682 +.sp -1
1.683 +.IP \(bu 2.3
1.684 +.\}
1.685 +CAMELLIA\-256\-CBC
1.686 +.RE
1.687 +.RE
1.688 +.PP
1.689 +PKCS#12 PBE ciphers
1.690 +.RS 4
1.691 +.sp
1.692 +.RS 4
1.693 +.ie n \{\
1.694 +\h'-04'\(bu\h'+03'\c
1.695 +.\}
1.696 +.el \{\
1.697 +.sp -1
1.698 +.IP \(bu 2.3
1.699 +.\}
1.700 +PKCS #12 PBE with Sha1 and 128 Bit RC4
1.701 +.RE
1.702 +.sp
1.703 +.RS 4
1.704 +.ie n \{\
1.705 +\h'-04'\(bu\h'+03'\c
1.706 +.\}
1.707 +.el \{\
1.708 +.sp -1
1.709 +.IP \(bu 2.3
1.710 +.\}
1.711 +PKCS #12 PBE with Sha1 and 40 Bit RC4
1.712 +.RE
1.713 +.sp
1.714 +.RS 4
1.715 +.ie n \{\
1.716 +\h'-04'\(bu\h'+03'\c
1.717 +.\}
1.718 +.el \{\
1.719 +.sp -1
1.720 +.IP \(bu 2.3
1.721 +.\}
1.722 +PKCS #12 PBE with Sha1 and Triple DES CBC
1.723 +.RE
1.724 +.sp
1.725 +.RS 4
1.726 +.ie n \{\
1.727 +\h'-04'\(bu\h'+03'\c
1.728 +.\}
1.729 +.el \{\
1.730 +.sp -1
1.731 +.IP \(bu 2.3
1.732 +.\}
1.733 +PKCS #12 PBE with Sha1 and 128 Bit RC2 CBC
1.734 +.RE
1.735 +.sp
1.736 +.RS 4
1.737 +.ie n \{\
1.738 +\h'-04'\(bu\h'+03'\c
1.739 +.\}
1.740 +.el \{\
1.741 +.sp -1
1.742 +.IP \(bu 2.3
1.743 +.\}
1.744 +PKCS #12 PBE with Sha1 and 40 Bit RC2 CBC
1.745 +.RE
1.746 +.sp
1.747 +.RS 4
1.748 +.ie n \{\
1.749 +\h'-04'\(bu\h'+03'\c
1.750 +.\}
1.751 +.el \{\
1.752 +.sp -1
1.753 +.IP \(bu 2.3
1.754 +.\}
1.755 +PKCS12 V2 PBE with SHA1 and 128 Bit RC4
1.756 +.RE
1.757 +.sp
1.758 +.RS 4
1.759 +.ie n \{\
1.760 +\h'-04'\(bu\h'+03'\c
1.761 +.\}
1.762 +.el \{\
1.763 +.sp -1
1.764 +.IP \(bu 2.3
1.765 +.\}
1.766 +PKCS12 V2 PBE with SHA1 and 40 Bit RC4 (the default for non\-FIPS mode)
1.767 +.RE
1.768 +.sp
1.769 +.RS 4
1.770 +.ie n \{\
1.771 +\h'-04'\(bu\h'+03'\c
1.772 +.\}
1.773 +.el \{\
1.774 +.sp -1
1.775 +.IP \(bu 2.3
1.776 +.\}
1.777 +PKCS12 V2 PBE with SHA1 and 3KEY Triple DES\-cbc
1.778 +.RE
1.779 +.sp
1.780 +.RS 4
1.781 +.ie n \{\
1.782 +\h'-04'\(bu\h'+03'\c
1.783 +.\}
1.784 +.el \{\
1.785 +.sp -1
1.786 +.IP \(bu 2.3
1.787 +.\}
1.788 +PKCS12 V2 PBE with SHA1 and 2KEY Triple DES\-cbc
1.789 +.RE
1.790 +.sp
1.791 +.RS 4
1.792 +.ie n \{\
1.793 +\h'-04'\(bu\h'+03'\c
1.794 +.\}
1.795 +.el \{\
1.796 +.sp -1
1.797 +.IP \(bu 2.3
1.798 +.\}
1.799 +PKCS12 V2 PBE with SHA1 and 128 Bit RC2 CBC
1.800 +.RE
1.801 +.sp
1.802 +.RS 4
1.803 +.ie n \{\
1.804 +\h'-04'\(bu\h'+03'\c
1.805 +.\}
1.806 +.el \{\
1.807 +.sp -1
1.808 +.IP \(bu 2.3
1.809 +.\}
1.810 +PKCS12 V2 PBE with SHA1 and 40 Bit RC2 CBC
1.811 +.RE
1.812 +.RE
1.813 +.PP
1.814 +PKCS#5 PBE ciphers
1.815 +.RS 4
1.816 +.sp
1.817 +.RS 4
1.818 +.ie n \{\
1.819 +\h'-04'\(bu\h'+03'\c
1.820 +.\}
1.821 +.el \{\
1.822 +.sp -1
1.823 +.IP \(bu 2.3
1.824 +.\}
1.825 +PKCS #5 Password Based Encryption with MD2 and DES CBC
1.826 +.RE
1.827 +.sp
1.828 +.RS 4
1.829 +.ie n \{\
1.830 +\h'-04'\(bu\h'+03'\c
1.831 +.\}
1.832 +.el \{\
1.833 +.sp -1
1.834 +.IP \(bu 2.3
1.835 +.\}
1.836 +PKCS #5 Password Based Encryption with MD5 and DES CBC
1.837 +.RE
1.838 +.sp
1.839 +.RS 4
1.840 +.ie n \{\
1.841 +\h'-04'\(bu\h'+03'\c
1.842 +.\}
1.843 +.el \{\
1.844 +.sp -1
1.845 +.IP \(bu 2.3
1.846 +.\}
1.847 +PKCS #5 Password Based Encryption with SHA1 and DES CBC
1.848 +.RE
1.849 +.RE
1.850 +.PP
1.851 +With PKCS#12, the crypto provider may be the soft token module or an external hardware module\&. If the cryptographic module does not support the requested algorithm, then the next best fit will be selected (usually the default)\&. If no suitable replacement for the desired algorithm can be found, the tool returns the error
1.852 +\fIno security module can perform the requested operation\fR\&.
1.853 +.SH "NSS DATABASE TYPES"
1.854 +.PP
1.855 +NSS originally used BerkeleyDB databases to store security information\&. The last versions of these
1.856 +\fIlegacy\fR
1.857 +databases are:
1.858 +.sp
1.859 +.RS 4
1.860 +.ie n \{\
1.861 +\h'-04'\(bu\h'+03'\c
1.862 +.\}
1.863 +.el \{\
1.864 +.sp -1
1.865 +.IP \(bu 2.3
1.866 +.\}
1.867 +cert8\&.db for certificates
1.868 +.RE
1.869 +.sp
1.870 +.RS 4
1.871 +.ie n \{\
1.872 +\h'-04'\(bu\h'+03'\c
1.873 +.\}
1.874 +.el \{\
1.875 +.sp -1
1.876 +.IP \(bu 2.3
1.877 +.\}
1.878 +key3\&.db for keys
1.879 +.RE
1.880 +.sp
1.881 +.RS 4
1.882 +.ie n \{\
1.883 +\h'-04'\(bu\h'+03'\c
1.884 +.\}
1.885 +.el \{\
1.886 +.sp -1
1.887 +.IP \(bu 2.3
1.888 +.\}
1.889 +secmod\&.db for PKCS #11 module information
1.890 +.RE
1.891 +.PP
1.892 +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.893 +.PP
1.894 +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.895 +.sp
1.896 +.RS 4
1.897 +.ie n \{\
1.898 +\h'-04'\(bu\h'+03'\c
1.899 +.\}
1.900 +.el \{\
1.901 +.sp -1
1.902 +.IP \(bu 2.3
1.903 +.\}
1.904 +cert9\&.db for certificates
1.905 +.RE
1.906 +.sp
1.907 +.RS 4
1.908 +.ie n \{\
1.909 +\h'-04'\(bu\h'+03'\c
1.910 +.\}
1.911 +.el \{\
1.912 +.sp -1
1.913 +.IP \(bu 2.3
1.914 +.\}
1.915 +key4\&.db for keys
1.916 +.RE
1.917 +.sp
1.918 +.RS 4
1.919 +.ie n \{\
1.920 +\h'-04'\(bu\h'+03'\c
1.921 +.\}
1.922 +.el \{\
1.923 +.sp -1
1.924 +.IP \(bu 2.3
1.925 +.\}
1.926 +pkcs11\&.txt, which is listing of all of the PKCS #11 modules contained in a new subdirectory in the security databases directory
1.927 +.RE
1.928 +.PP
1.929 +Because the SQLite databases are designed to be shared, these are the
1.930 +\fIshared\fR
1.931 +database type\&. The shared database type is preferred; the legacy format is included for backward compatibility\&.
1.932 +.PP
1.933 +By default, the tools (\fBcertutil\fR,
1.934 +\fBpk12util\fR,
1.935 +\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.936 +\fBsql:\fR
1.937 +prefix with the given security directory\&. For example:
1.938 +.sp
1.939 +.if n \{\
1.940 +.RS 4
1.941 +.\}
1.942 +.nf
1.943 +# pk12util \-i /tmp/cert\-files/users\&.p12 \-d sql:/home/my/sharednssdb
1.944 +.fi
1.945 +.if n \{\
1.946 +.RE
1.947 +.\}
1.948 +.PP
1.949 +To set the shared database type as the default type for the tools, set the
1.950 +\fBNSS_DEFAULT_DB_TYPE\fR
1.951 +environment variable to
1.952 +\fBsql\fR:
1.953 +.sp
1.954 +.if n \{\
1.955 +.RS 4
1.956 +.\}
1.957 +.nf
1.958 +export NSS_DEFAULT_DB_TYPE="sql"
1.959 +.fi
1.960 +.if n \{\
1.961 +.RE
1.962 +.\}
1.963 +.PP
1.964 +This line can be set added to the
1.965 +~/\&.bashrc
1.966 +file to make the change permanent\&.
1.967 +.PP
1.968 +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.969 +.sp
1.970 +.RS 4
1.971 +.ie n \{\
1.972 +\h'-04'\(bu\h'+03'\c
1.973 +.\}
1.974 +.el \{\
1.975 +.sp -1
1.976 +.IP \(bu 2.3
1.977 +.\}
1.978 +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto
1.979 +.RE
1.980 +.PP
1.981 +For an engineering draft on the changes in the shared NSS databases, see the NSS project wiki:
1.982 +.sp
1.983 +.RS 4
1.984 +.ie n \{\
1.985 +\h'-04'\(bu\h'+03'\c
1.986 +.\}
1.987 +.el \{\
1.988 +.sp -1
1.989 +.IP \(bu 2.3
1.990 +.\}
1.991 +https://wiki\&.mozilla\&.org/NSS_Shared_DB
1.992 +.RE
1.993 +.SH "SEE ALSO"
1.994 +.PP
1.995 +certutil (1)
1.996 +.PP
1.997 +modutil (1)
1.998 +.PP
1.999 +The NSS wiki has information on the new database design and how to configure applications to use it\&.
1.1000 +.sp
1.1001 +.RS 4
1.1002 +.ie n \{\
1.1003 +\h'-04'\(bu\h'+03'\c
1.1004 +.\}
1.1005 +.el \{\
1.1006 +.sp -1
1.1007 +.IP \(bu 2.3
1.1008 +.\}
1.1009 +https://wiki\&.mozilla\&.org/NSS_Shared_DB_Howto
1.1010 +.RE
1.1011 +.sp
1.1012 +.RS 4
1.1013 +.ie n \{\
1.1014 +\h'-04'\(bu\h'+03'\c
1.1015 +.\}
1.1016 +.el \{\
1.1017 +.sp -1
1.1018 +.IP \(bu 2.3
1.1019 +.\}
1.1020 +https://wiki\&.mozilla\&.org/NSS_Shared_DB
1.1021 +.RE
1.1022 +.SH "ADDITIONAL RESOURCES"
1.1023 +.PP
1.1024 +For information about NSS and other tools related to NSS (like JSS), check out the NSS project wiki at
1.1025 +\m[blue]\fBhttp://www\&.mozilla\&.org/projects/security/pki/nss/\fR\m[]\&. The NSS site relates directly to NSS code changes and releases\&.
1.1026 +.PP
1.1027 +Mailing lists: https://lists\&.mozilla\&.org/listinfo/dev\-tech\-crypto
1.1028 +.PP
1.1029 +IRC: Freenode at #dogtag\-pki
1.1030 +.SH "AUTHORS"
1.1031 +.PP
1.1032 +The NSS tools were written and maintained by developers with Netscape, Red Hat, Sun, Oracle, Mozilla, and Google\&.
1.1033 +.PP
1.1034 +Authors: Elio Maldonado <emaldona@redhat\&.com>, Deon Lackey <dlackey@redhat\&.com>\&.
1.1035 +.SH "LICENSE"
1.1036 +.PP
1.1037 +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.1038 +.SH "NOTES"
1.1039 +.IP " 1." 4
1.1040 +Mozilla NSS bug 836477
1.1041 +.RS 4
1.1042 +\%https://bugzilla.mozilla.org/show_bug.cgi?id=836477
1.1043 +.RE
