index.rst (12156B)
1 .. _mozilla_projects_nss_tools_nss_tools_pk12util: 2 3 NSS Tools pk12util 4 ================== 5 6 .. _using_the_pkcs_12_tool_(pk12util): 7 8 `Using the PKCS #12 Tool (pk12util) <#using_the_pkcs_12_tool_(pk12util)>`__ 9 --------------------------------------------------------------------------- 10 11 .. container:: 12 13 Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ 14 The PKCS #12 utility makes sharing of certificates among Enterprise server 3.x and any server 15 (Netscape products or non-Netscape products) that supports PKCS#12 possible. The tool allows you 16 to import certificates and keys from pkcs #12 files into NSS or export them and also list 17 certificates and keys in such files. 18 19 .. _availability_2: 20 21 ` <#availability_2>`__ Availability 22 ----------------------------------- 23 24 .. container:: 25 26 See the `release notes <../release_notes.html>`__ for the platforms this tool is available on. 27 28 `Synopsis <#synopsis>`__ 29 ------------------------ 30 31 .. container:: 32 33 **pk12util** ``-i p12File [-h tokenname] [-v] [common-options]`` 34 or 35 **pk12util** 36 ``-o p12File -n certname [-c keyCipher] [-C certCipher] [-m | --key_len keyLen] [-n | --cert_key_len certKeyLen] [common-options]`` 37 or 38 **pk12util** ``-l p12File [-h tokenname] [-r] [common-options]`` 39 where 40 **[common-options]** = 41 ``[-d dir] [-P dbprefix] [-k slotPasswordFile | -K slotPassword] [-w p12filePasswordFile | -W p12filePassword]`` 42 43 `Syntax <#syntax>`__ 44 -------------------- 45 46 .. container:: 47 48 To run the PKCS #12 Tool, type the command ``pk12util`` *option*\ ``[``\ *arguments*\ ``]`` where 49 *option* and *arguments* are combinations of the options and arguments listed in the following 50 section. Three of the options, -i, -o, and -l, should be considered commands of the pk12util 51 invocation. Each command takes several options. Options may take zero or more arguments. To see a 52 usage string, issue the pkcs12util command without any options. 53 54 .. _options_and_arguments: 55 56 `Options and Arguments <#options_and_arguments>`__ 57 -------------------------------------------------- 58 59 .. container:: 60 61 Options specify an action. Option arguments modify an action. The options and arguments for the 62 ``pk12util`` command are defined as follows: 63 64 +-------------------------------------------------+-------------------------------------------------+ 65 | **Options** | | 66 +-------------------------------------------------+-------------------------------------------------+ 67 | ``-i`` *p12file* | Import a certificate and private key from the | 68 | | p12file into the database. | 69 +-------------------------------------------------+-------------------------------------------------+ 70 | ``-o`` *p12file* | Export certificate and private key, specified | 71 | | by the -n option, from the database to the p12 | 72 | | file. | 73 +-------------------------------------------------+-------------------------------------------------+ 74 | ``-l`` *p12file* | List certificate and private key from the | 75 | | ``p12file`` file. | 76 +-------------------------------------------------+-------------------------------------------------+ 77 | **Arguments** | | 78 +-------------------------------------------------+-------------------------------------------------+ 79 | ``-n`` *certname* | Specify the nickname of the cert and private | 80 | | key to export. | 81 +-------------------------------------------------+-------------------------------------------------+ 82 | ``-d`` *dir* | Specify the database directory into which to | 83 | | import to or export from certificates and keys. | 84 | | If not specified the directory defaults to | 85 | | $HOME/.netscape (when $HOME exists in the | 86 | | environment), or to ./.netscape (when $HOME | 87 | | does not exist in the environment). | 88 +-------------------------------------------------+-------------------------------------------------+ 89 | ``-P`` *prefix* | Specify the prefix used on the ``cert8.db`` and | 90 | | ``key3.db`` files (for example, ``my_cert8.db`` | 91 | | and ``my_key3.db``). This option is provided as | 92 | | a special case. Changing the names of the | 93 | | certificate and key databases is not | 94 | | recommended. | 95 +-------------------------------------------------+-------------------------------------------------+ 96 | ``-h`` *tokenname* | Specify the name of the token to import into or | 97 | | export from | 98 +-------------------------------------------------+-------------------------------------------------+ 99 | ``-v`` | Enable debug logging when importing | 100 +-------------------------------------------------+-------------------------------------------------+ 101 | ``-k`` *slotPasswordFile* | Specify the text file containing the slot's | 102 | | password | 103 +-------------------------------------------------+-------------------------------------------------+ 104 | ``-K`` *slotPassword* | Specify a slot's password | 105 +-------------------------------------------------+-------------------------------------------------+ 106 | ``-w`` *p12filePasswordFile* | Specify the text file containing the pkcs 12 | 107 | | file's password | 108 +-------------------------------------------------+-------------------------------------------------+ 109 | ``-W`` *p12filePassword* | Specify the pkcs 12 file's password | 110 +-------------------------------------------------+-------------------------------------------------+ 111 | ``-c`` *key-cipher* | Specify the key encryption algorithm | 112 +-------------------------------------------------+-------------------------------------------------+ 113 | ``-C`` *certCipher* | Specify the PFX encryption algorithm | 114 +-------------------------------------------------+-------------------------------------------------+ 115 | ``-m | --key_len`` * | Specify the desired length of the symmetric key | 116 | keyLen* | to be used to encrypt the private key | 117 +-------------------------------------------------+-------------------------------------------------+ 118 | ``-n | --cert_key_len`` * | Specify the desired length of the symmetric key | 119 | certLeyLen* | to be used to encrypt the top level protocol | 120 | | data unit | 121 +-------------------------------------------------+-------------------------------------------------+ 122 123 +---+ 124 | | 125 +---+ 126 127 .. _password_based_encryption: 128 129 ` <#password_based_encryption>`__ Password Based Encryption 130 ----------------------------------------------------------- 131 132 .. container:: 133 134 PKCS #12 provides for not only the protection of the private keys but also the certificate and 135 meta-data associated with the keys. Password based encryption is used to protect private keys on 136 export to a PKCS #12 file and also the entire package when allowed. If no algorithm is specified, 137 the tool defaults to using "PKCS12 V2 PBE With SHA1 And 3KEY Triple DES-cbc" for private key 138 encryption. For historical export control reasons "PKCS12 V2 PBE With SHA1 And 40 Bit RC4" is the 139 default for the overall package encryption when not in FIPS mode and no package encryption when 140 in FIPS mode. The private key is always protected with strong encryption by default. A list of 141 ciphers follows. 142 143 - symmetric CBC ciphers for PKCS #5 V2: 144 145 - "DES_CBC" 146 - "RC2-CBC" 147 - "RC5-CBCPad" 148 - "DES-EDE3-CBC" 149 --- default for key encryption 150 - "AES-128-CBC" 151 - "AES-192-CBC" 152 - "AES-256-CBC" 153 - "CAMELLIA-128-CBC" 154 - "CAMELLIA-192-CBC" 155 - "CAMELLIA-256-CBC" 156 157 - PKCS #12 PBE Ciphers: 158 159 - "PKCS #12 PBE With Sha1 and 128 Bit RC4" 160 - "PKCS #12 PBE With Sha1 and 40 Bit RC4" 161 - "PKCS #12 PBE With Sha1 and Triple DES CBC" 162 - "PKCS #12 PBE With Sha1 and 128 Bit RC2 CBC" 163 - "PKCS #12 PBE With Sha1 and 40 Bit RC2 CBC" 164 - "PKCS12 V2 PBE With SHA1 And 128 Bit RC4" 165 - "PKCS12 V2 PBE With SHA1 And 40 Bit RC4" 166 --- default for PFX encryption in non-fips mode, no encryption on fips mode 167 - "PKCS12 V2 PBE With SHA1 And 3KEY Triple DES-cbc" 168 - "PKCS12 V2 PBE With SHA1 And 2KEY Triple DES-cbc" 169 - "PKCS12 V2 PBE With SHA1 And 128 Bit RC2 CBC" 170 - "PKCS12 V2 PBE With SHA1 And 40 Bit RC2 CBC" 171 172 - PKCS #5 PBE Ciphers: 173 174 - "PKCS #5 Password Based Encryption with MD2 and DES CBC" 175 - "PKCS #5 Password Based Encryption with MD5 and DES CBC" 176 - "PKCS #5 Password Based Encryption with SHA1 and DES CBC" 177 178 It should be noted that the crypto provider may be the softtoken module or an external hardware 179 module. It may be the case that the cryptographic module does not support the requested algorithm 180 and a best fit will be selected, likely to be the default. If no suitable replacement for the 181 desired algorithm can be found a "no security module can perform the requested operation" will 182 appear on the error message. 183 184 .. _error_codes: 185 186 ` <#error_codes>`__ Error Codes 187 ------------------------------- 188 189 .. container:: 190 191 **pk12util** can return the following values: 192 | **0** - No error 193 | **1** - User Cancelled 194 | **2** - Usage error 195 | **6** - NLS init error 196 | **8** - Certificate DB open error 197 | **9** - Key DB open error 198 | **10** - File initialization error 199 | **11** - Unicode conversion error 200 | **12** - Temporary file creation error 201 | **13** - PKCS11 get slot error 202 | **14** - PKCS12 decoder start error 203 | **15** - error read from import file 204 | **16** - pkcs12 decode error 205 | **17** - pkcs12 decoder verify error 206 | **18** - pkcs12 decoder validate bags error 207 | **19** - pkcs12 decoder import bags error 208 | **20** - key db conversion version 3 to version 2 error 209 | **21** - cert db conversion version 7 to version 5 error 210 | **22** - cert and key dbs patch error 211 | **23** - get default cert db error 212 | **24** - find cert by nickname error 213 | **25** - create export context error 214 | **26** - PKCS12 add password itegrity error 215 | **27** - cert and key Safes creation error 216 | **28** - PKCS12 add cert and key error 217 | **29** - PKCS12 encode error