index.rst (13204B)
1 .. _mozilla_projects_nss_reference_nss_tools_:_pk12util: 2 3 NSS tools : pk12util 4 ==================== 5 6 .. container:: 7 8 NSS tools : pk12util 9 10 Name 11 12 | pk12util — Export and import keys and certificate to or from a PKCS #12 13 | file and the NSS database 14 15 Synopsis 16 17 pk12util [-i p12File|-l p12File|-o p12File] [-d [sql:]directory] [-h tokenname] [-P dbprefix] 18 [-r] [-v] [-k slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] 19 20 Description 21 22 | The PKCS #12 utility, pk12util, enables sharing certificates among any 23 | server that supports PKCS#12. The tool can import certificates and keys 24 | from PKCS#12 files into security databases, export certificates, and list 25 | certificates and keys. 26 27 Options and Arguments 28 29 Options 30 31 -i p12file 32 33 | Import keys and certificates from a PKCS#12 file into a security 34 | database. 35 36 -l p12file 37 38 List the keys and certificates in PKCS#12 file. 39 40 -o p12file 41 42 | Export keys and certificates from the security database to a 43 | PKCS#12 file. 44 45 Arguments 46 47 -c keyCipher 48 49 Specify the key encryption algorithm. 50 51 -C certCipher 52 53 Specify the key cert (overall package) encryption algorithm. 54 55 | 56 | -d [sql:]directory 57 58 | Specify the database directory into which to import to or export 59 | from certificates and keys. 60 61 | pk12util supports two types of databases: the legacy security 62 | databases (cert8.db, key3.db, and secmod.db) and new SQLite 63 | databases (cert9.db, key4.db, and pkcs11.txt). If the prefix sql: 64 | is not used, then the tool assumes that the given databases are in 65 | the old format. 66 67 -h tokenname 68 69 Specify the name of the token to import into or export from. 70 71 -k slotPasswordFile 72 73 Specify the text file containing the slot's password. 74 75 -K slotPassword 76 77 Specify the slot's password. 78 79 -m \| --key-len keyLength 80 81 | Specify the desired length of the symmetric key to be used to 82 | encrypt the private key. 83 84 -n \| --cert-key-len certKeyLength 85 86 | Specify the desired length of the symmetric key to be used to 87 | encrypt the certificates and other meta-data. 88 89 -n certname 90 91 Specify the nickname of the cert and private key to export. 92 93 -P prefix 94 95 | Specify the prefix used on the certificate and key databases. This 96 | option is provided as a special case. Changing the names of the 97 | certificate and key databases is not recommended. 98 99 -r 100 101 | Dumps all of the data in raw (binary) form. This must be saved as 102 | a DER file. The default is to return information in a pretty-print 103 | ASCII format, which displays the information about the 104 | certificates and public keys in the p12 file. 105 106 -v 107 108 Enable debug logging when importing. 109 110 -w p12filePasswordFile 111 112 Specify the text file containing the pkcs #12 file password. 113 114 -W p12filePassword 115 116 Specify the pkcs #12 file password. 117 118 Return Codes 119 120 o 0 - No error 121 122 o 1 - User Cancelled 123 124 o 2 - Usage error 125 126 o 6 - NLS init error 127 128 o 8 - Certificate DB open error 129 130 o 9 - Key DB open error 131 132 o 10 - File initialization error 133 134 o 11 - Unicode conversion error 135 136 o 12 - Temporary file creation error 137 138 o 13 - PKCS11 get slot error 139 140 o 14 - PKCS12 decoder start error 141 142 o 15 - error read from import file 143 144 o 16 - pkcs12 decode error 145 146 o 17 - pkcs12 decoder verify error 147 148 o 18 - pkcs12 decoder validate bags error 149 150 o 19 - pkcs12 decoder import bags error 151 152 o 20 - key db conversion version 3 to version 2 error 153 154 o 21 - cert db conversion version 7 to version 5 error 155 156 o 22 - cert and key dbs patch error 157 158 o 23 - get default cert db error 159 160 o 24 - find cert by nickname error 161 162 o 25 - create export context error 163 164 o 26 - PKCS12 add password itegrity error 165 166 o 27 - cert and key Safes creation error 167 168 o 28 - PKCS12 add cert and key error 169 170 o 29 - PKCS12 encode error 171 172 Examples 173 174 Importing Keys and Certificates 175 176 | The most basic usage of pk12util for importing a certificate or key is the 177 | PKCS#12 input file (-i) and some way to specify the security database 178 | being accessed (either -d for a directory or -h for a token). 179 180 pk12util -i p12File [-h tokenname] [-v] [-d [sql:]directory] [-P dbprefix] [-k 181 slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] 182 183 For example: 184 185 # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb 186 187 | Enter a password which will be used to encrypt your keys. 188 | The password should be at least 8 characters long, 189 | and should contain at least one non-alphabetic character. 190 191 | Enter new password: 192 | Re-enter password: 193 | Enter password for PKCS12 file: 194 | pk12util: PKCS12 IMPORT SUCCESSFUL 195 196 Exporting Keys and Certificates 197 198 | Using the pk12util command to export certificates and keys requires both 199 | the name of the certificate to extract from the database (-n) and the 200 | PKCS#12-formatted output file to write to. There are optional parameters 201 | that can be used to encrypt the file to protect the certificate material. 202 203 pk12util -o p12File -n certname [-c keyCipher] [-C certCipher] [-m|--key_len keyLen] 204 [-n|--cert_key_len certKeyLen] [-d [sql:]directory] [-P dbprefix] [-k slotPasswordFile|-K 205 slotPassword] [-w p12filePasswordFile|-W p12filePassword] 206 207 For example: 208 209 | # pk12util -o certs.p12 -n Server-Cert -d sql:/home/my/sharednssdb 210 | Enter password for PKCS12 file: 211 | Re-enter password: 212 213 Listing Keys and Certificates 214 215 | The information in a .p12 file are not human-readable. The certificates 216 | and keys in the file can be printed (listed) in a human-readable 217 | pretty-print format that shows information for every certificate and any 218 | public keys in the .p12 file. 219 220 pk12util -l p12File [-h tokenname] [-r] [-d [sql:]directory] [-P dbprefix] [-k 221 slotPasswordFile|-K slotPassword] [-w p12filePasswordFile|-W p12filePassword] 222 223 For example, this prints the default ASCII output: 224 225 # pk12util -l certs.p12 226 227 | Enter password for PKCS12 file: 228 | Key(shrouded): 229 | Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID 230 231 | Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC 232 | Parameters: 233 | Salt: 234 | 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f 235 | Iteration Count: 1 (0x1) 236 | Certificate: 237 | Data: 238 | Version: 3 (0x2) 239 | Serial Number: 13 (0xd) 240 | Signature Algorithm: PKCS #1 SHA-1 With RSA Encryption 241 | Issuer: "E=personal-freemail@thawte.com,CN=Thawte Personal Freemail C 242 | A,OU=Certification Services Division,O=Thawte Consulting,L=Cape T 243 | own,ST=Western Cape,C=ZA" 244 245 | Alternatively, the -r prints the certificates and then exports them into 246 | separate DER binary files. This allows the certificates to be fed to 247 | another application that supports .p12 files. Each certificate is written 248 | to a sequentially-number file, beginning with file0001.der and continuing 249 | through file000N.der, incrementing the number for every certificate: 250 251 | # pk12util -l test.p12 -r 252 | Enter password for PKCS12 file: 253 | Key(shrouded): 254 | Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID 255 256 | Encryption algorithm: PKCS #12 V2 PBE With SHA-1 And 3KEY Triple DES-CBC 257 | Parameters: 258 | Salt: 259 | 45:2e:6a:a0:03:4d:7b:a1:63:3c:15:ea:67:37:62:1f 260 | Iteration Count: 1 (0x1) 261 | Certificate Friendly Name: Thawte Personal Freemail Issuing CA - Thawte Consulting 262 263 Certificate Friendly Name: Thawte Freemail Member's Thawte Consulting (Pty) Ltd. ID 264 265 Password Encryption 266 267 | PKCS#12 provides for not only the protection of the private keys but also 268 | the certificate and meta-data associated with the keys. Password-based 269 | encryption is used to protect private keys on export to a PKCS#12 file 270 | and, optionally, the entire package. If no algorithm is specified, the 271 | tool defaults to using PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc for 272 | private key encryption. PKCS12 V2 PBE with SHA1 and 40 Bit RC4 is the 273 | default for the overall package encryption when not in FIPS mode. When in 274 | FIPS mode, there is no package encryption. 275 276 The private key is always protected with strong encryption by default. 277 278 Several types of ciphers are supported. 279 280 Symmetric CBC ciphers for PKCS#5 V2 281 282 o DES-CBC 283 284 o RC2-CBC 285 286 o RC5-CBCPad 287 288 o DES-EDE3-CBC (the default for key encryption) 289 290 o AES-128-CBC 291 292 o AES-192-CBC 293 294 o AES-256-CBC 295 296 o CAMELLIA-128-CBC 297 298 o CAMELLIA-192-CBC 299 300 o CAMELLIA-256-CBC 301 302 PKCS#12 PBE ciphers 303 304 o PKCS #12 PBE with Sha1 and 128 Bit RC4 305 306 o PKCS #12 PBE with Sha1 and 40 Bit RC4 307 308 o PKCS #12 PBE with Sha1 and Triple DES CBC 309 310 o PKCS #12 PBE with Sha1 and 128 Bit RC2 CBC 311 312 o PKCS #12 PBE with Sha1 and 40 Bit RC2 CBC 313 314 o PKCS12 V2 PBE with SHA1 and 128 Bit RC4 315 316 | o PKCS12 V2 PBE with SHA1 and 40 Bit RC4 (the default for 317 | non-FIPS mode) 318 319 o PKCS12 V2 PBE with SHA1 and 3KEY Triple DES-cbc 320 321 o PKCS12 V2 PBE with SHA1 and 2KEY Triple DES-cbc 322 323 o PKCS12 V2 PBE with SHA1 and 128 Bit RC2 CBC 324 325 o PKCS12 V2 PBE with SHA1 and 40 Bit RC2 CBC 326 327 PKCS#5 PBE ciphers 328 329 o PKCS #5 Password Based Encryption with MD2 and DES CBC 330 331 o PKCS #5 Password Based Encryption with MD5 and DES CBC 332 333 o PKCS #5 Password Based Encryption with SHA1 and DES CBC 334 335 | With PKCS#12, the crypto provider may be the soft token module or an 336 | external hardware module. If the cryptographic module does not support the 337 | requested algorithm, then the next best fit will be selected (usually the 338 | default). If no suitable replacement for the desired algorithm can be 339 | found, the tool returns the error no security module can perform the 340 | requested operation. 341 342 NSS Database Types 343 344 | NSS originally used BerkeleyDB databases to store security information. 345 | The last versions of these legacy databases are: 346 347 o cert8.db for certificates 348 349 o key3.db for keys 350 351 o secmod.db for PKCS #11 module information 352 353 | BerkeleyDB has performance limitations, though, which prevent it from 354 | being easily used by multiple applications simultaneously. NSS has some 355 | flexibility that allows applications to use their own, independent 356 | database engine while keeping a shared database and working around the 357 | access issues. Still, NSS requires more flexibility to provide a truly 358 | shared security database. 359 360 | In 2009, NSS introduced a new set of databases that are SQLite databases 361 | rather than BerkleyDB. These new databases provide more accessibility and 362 | performance: 363 364 o cert9.db for certificates 365 366 o key4.db for keys 367 368 | o pkcs11.txt, which is listing of all of the PKCS #11 modules contained 369 | in a new subdirectory in the security databases directory 370 371 | Because the SQLite databases are designed to be shared, these are the 372 | shared database type. The shared database type is preferred; the legacy 373 | format is included for backward compatibility. 374 375 | By default, the tools (certutil, pk12util, modutil) assume that the given 376 | security databases follow the more common legacy type. Using the SQLite 377 | databases must be manually specified by using the sql: prefix with the 378 | given security directory. For example: 379 380 # pk12util -i /tmp/cert-files/users.p12 -d sql:/home/my/sharednssdb 381 382 | To set the shared database type as the default type for the tools, set the 383 | NSS_DEFAULT_DB_TYPE environment variable to sql: 384 385 export NSS_DEFAULT_DB_TYPE="sql" 386 387 | This line can be set added to the ~/.bashrc file to make the change 388 | permanent. 389 390 | Most applications do not use the shared database by default, but they can 391 | be configured to use them. For example, this how-to article covers how to 392 | configure Firefox and Thunderbird to use the new shared NSS databases: 393 394 o https://wiki.mozilla.org/NSS_Shared_DB_Howto 395 396 | For an engineering draft on the changes in the shared NSS databases, see 397 | the NSS project wiki: 398 399 o https://wiki.mozilla.org/NSS_Shared_DB 400 401 See Also 402 403 certutil (1) 404 405 modutil (1) 406 407 | The NSS wiki has information on the new database design and how to 408 | configure applications to use it. 409 410 o https://wiki.mozilla.org/NSS_Shared_DB_Howto 411 412 o https://wiki.mozilla.org/NSS_Shared_DB 413 414 Additional Resources 415 416 | For information about NSS and other tools related to NSS (like JSS), check 417 | out the NSS project wiki at 418 | [1]http://www.mozilla.org/projects/security/pki/nss/. The NSS site relates 419 | directly to NSS code changes and releases. 420 421 Mailing lists: https://lists.mozilla.org/listinfo/dev-tech-crypto 422 423 IRC: Freenode at #dogtag-pki 424 425 Authors 426 427 | The NSS tools were written and maintained by developers with Netscape, Red 428 | Hat, Sun, Oracle, Mozilla, and Google. 429 430 | Authors: Elio Maldonado <emaldona@redhat.com>, Deon Lackey 431 | <dlackey@redhat.com>. 432 433 License 434 435 | Licensed under the Mozilla Public License, v. 2.0. 436 | If a copy of the MPL was not distributed with this file, 437 | You can obtain one at https://mozilla.org/MPL/2.0/. 438 439 References 440 441 | 1. Mozilla NSS bug 836477 442 | https://bugzilla.mozilla.org/show_bug.cgi?id=836477