doc/man/pkcs12.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 pkcs12 - PKCS#12 file utility
   7
   8 =head1 SYNOPSIS
   9
  10 B<openssl> B<pkcs12>
  11 [B<-export>]
  12 [B<-chain>]
  13 [B<-inkey filename>]
  14 [B<-certfile filename>]
  15 [B<-name name>]
  16 [B<-caname name>]
  17 [B<-in filename>]
  18 [B<-out filename>]
  19 [B<-noout>]
  20 [B<-nomacver>]
  21 [B<-nocerts>]
  22 [B<-clcerts>]
  23 [B<-cacerts>]
  24 [B<-nokeys>]
  25 [B<-info>]
  26 [B<-des>]
  27 [B<-des3>]
  28 [B<-idea>]
  29 [B<-nodes>]
  30 [B<-noiter>]
  31 [B<-maciter>]
  32 [B<-twopass>]
  33 [B<-descert>]
  34 [B<-certpbe>]
  35 [B<-keypbe>]
  36 [B<-keyex>]
  37 [B<-keysig>]
  38 [B<-password password>]
  39 [B<-envpass var>]
  40
  41 =head1 DESCRIPTION
  42
  43 The B<pkcs12> command allows PKCS#12 files (sometimes referred to as
  44 PFX files) to be created and parsed. PKCS#12 files are used by several
  45 programs including Netscape, MSIE and MS Outlook.
  46
  47 =head1 COMMAND OPTIONS
  48
  49 There are a lot of options the meaning of some depends of whether a PKCS#12 file
  50 is being created or parsed. By default a PKCS#12 file is parsed a PKCS#12
  51 file can be created by using the B<-export> option (see below).
  52
  53 =head1 PARSING OPTIONS
  54
  55 =over 4
  56
  57 =item B<-in filename>
  58
  59 This specifies filename of the PKCS#12 file to be parsed. Standard input is used
  60 by default.
  61
  62 =item B<-out filename>
  63
  64 The filename to write certificates and private keys to, standard output by default.
  65 They are all written in PEM format.
  66
  67 =item B<-pass password>
  68
  69 the PKCS#12 file password. Since certain utilities like "ps" make the command line
  70 visible this option should be used with caution.
  71
  72 =item B<-envpass var>
  73
  74 read the PKCS#12 file password from the environment variable B<var>.
  75
  76 =item B<-noout>
  77
  78 this option inhibits output of the keys and certificates to the output file version
  79 of the PKCS#12 file.
  80
  81 =item B<-clcerts>
  82
  83 only output client certificates (not CA certificates).
  84
  85 =item B<-cacerts>
  86
  87 only output CA certificates (not client certificates).
  88
  89 =item B<-nocerts>
  90
  91 no certificates at all will be output.
  92
  93 =item B<-nokeys>
  94
  95 no private keys will be output.
  96
  97 =item B<-info>
  98
  99 output additional information about the PKCS#12 file structure, algorithms used and
 100 iteration counts.
 101
 102 =item B<-des>
 103
 104 use DES to encrypt private keys before outputting.
 105
 106 =item B<-des3>
 107
 108 use triple DES to encrypt private keys before outputting, this is the default.
 109
 110 =item B<-idea>
 111
 112 use IDEA to encrypt private keys before outputting.
 113
 114 =item B<-nodes>
 115
 116 don't encrypt the private keys at all.
 117
 118 =item B<-nomacver>
 119
 120 don't attempt to verify the integrity MAC before reading the file.
 121
 122 =item B<-twopass>
 123
 124 prompt for separate integrity and encryption passwords: most software
 125 always assumes these are the same so this option will render such
 126 PKCS#12 files unreadable.
 127
 128 =back
 129
 130 =head1 FILE CREATION OPTIONS
 131
 132 =over 4
 133
 134 =item B<-export>
 135
 136 This option specifies that a PKCS#12 file will be created rather than
 137 parsed.
 138
 139 =item B<-out filename>
 140
 141 This specifies filename to write the PKCS#12 file to. Standard output is used
 142 by default.
 143
 144 =item B<-in filename>
 145
 146 The filename to read certificates and private keys from, standard input by default.
 147 They must all be in PEM format. The order doesn't matter but one private key and
 148 its corresponding certificate should be present. If additional certificates are
 149 present they will also be included in the PKCS#12 file.
 150
 151 =item B<-inkey filename>
 152
 153 file to read private key from. If not present then a private key must be present
 154 in the input file.
 155
 156 =item B<-name friendlyname>
 157
 158 This specifies the "friendly name" for the certificate and private key. This name
 159 is typically displayed in list boxes by software importing the file.
 160
 161 =item B<-certfile filename>
 162
 163 A filename to read additional certificates from.
 164
 165 =item B<-caname friendlyname>
 166
 167 This specifies the "friendly name" for other certificates. This option may be
 168 used multiple times to specify names for all certificates in the order they
 169 appear. Netscape ignores friendly names on other certificates whereas MSIE
 170 displays them.
 171
 172 =item B<-pass password>
 173
 174 the PKCS#12 file password. Since certain utilities like "ps" make the command line
 175 visible this option should be used with caution.
 176
 177 =item B<-envpass var>
 178
 179 read the PKCS#12 file password from the environment variable B<var>.
 180
 181 =item B<-chain>
 182
 183 if this option is present then an attempt is made to include the entire
 184 certificate chain of the user certificate. The standard CA store is used
 185 for this search. If the search fails it is considered a fatal error.
 186
 187 =item B<-descert>
 188
 189 encrypt the certificate using triple DES, this may render the PKCS#12
 190 file unreadable by some "export grade" software. By default the private
 191 key is encrypted using triple DES and the certificate using 40 bit RC2.
 192
 193 =item B<-keypbe alg>, B<-certpbe alg>
 194
 195 these options allow the algorithm used to encrypt the private key and
 196 certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms
 197 can be selected it is advisable only to use PKCS#12 algorithms. See the list
 198 in the B<NOTES> section for more information.
 199
 200 =item B<-keyex|-keysig>
 201
 202 specifies that the private key is to be used for key exchange or just signing.
 203 This option is only interpreted by MSIE and similar MS software. Normally
 204 "export grade" software will only allow 512 bit RSA keys to be used for
 205 encryption purposes but arbitrary length keys for signing. The B<-keysig>
 206 option marks the key for signing only. Signing only keys can be used for
 207 S/MIME signing, authenticode (ActiveX control signing)  and SSL client
 208 authentication, however due to a bug only MSIE 5.0 and later support
 209 the use of signing only keys for SSL client authentication.
 210
 211 =item B<-nomaciter>, B<-noiter>
 212
 213 these options affect the iteration counts on the MAC and key algorithms.
 214 Unless you wish to produce files compatible with MSIE 4.0 you should leave
 215 these options alone.
 216
 217 To discourage attacks by using large dictionaries of common passwords the
 218 algorithm that derives keys from passwords can have an iteration count applied
 219 to it: this causes a certain part of the algorithm to be repeated and slows it
 220 down. The MAC is used to check the file integrity but since it will normally
 221 have the same password as the keys and certificates it could also be attacked.
 222 By default both MAC and encryption iteration counts are set to 2048, using
 223 these options the MAC and encryption iteration counts can be set to 1, since
 224 this reduces the file security you should not use these options unless you
 225 really have to. Most software supports both MAC and key iteration counts.
 226 MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter>
 227 option.
 228
 229 =item B<-maciter>
 230
 231 This option is included for compatibility with previous versions, it used
 232 to be needed to use MAC iterations counts but they are now used by default.
 233
 234 =back
 235
 236 =head1 NOTES
 237
 238 Although there are a large number of options most of them are very rarely
 239 used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used
 240 for PKCS#12 file creation B<-export> and B<-name> are also used.
 241
 242 The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption
 243 algorithms for private keys and certificates to be specified. Normally
 244 the defaults are fine but occasionally software can't handle triple DES
 245 encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can
 246 be used to reduce the private key encryption to 40 bit RC2. A complete
 247 description of all algorithms is contained in the B<pkcs8> manual page.
 248
 249 =head1 EXAMPLES
 250
 251 Parse a PKCS#12 file and output it to a file:
 252
 253  openssl pkcs12 -in file.p12 -out file.pem
 254
 255 Output only client certificates to a file:
 256
 257  openssl pkcs12 -in file.p12 -clcerts -out file.pem
 258
 259 Don't encrypt the private key:
 260
 261  openssl pkcs12 -in file.p12 -out file.pem -nodes
 262
 263 Print some info about a PKCS#12 file:
 264
 265  openssl pkcs12 -in file.p12 -info -noout
 266
 267 Create a PKCS#12 file:
 268
 269  openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate"
 270
 271 Include some extra certificates:
 272
 273  openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \
 274   -certfile othercerts.pem
 275
 276 =head1 BUGS
 277
 278 Some would argue that the PKCS#12 standard is one big bug :-)
 279
 280 Need password options for the PEM files: this will probably be fixed before
 281 release.
 282
 283 =head1 SEE ALSO
 284
 285 pkcs8(1)
 286