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