pkcs12.pod revision 59191
190792Sgshapiro 2261194Sgshapiro=pod 390792Sgshapiro 490792Sgshapiro=head1 NAME 590792Sgshapiro 690792Sgshapiropkcs12 - PKCS#12 file utility 790792Sgshapiro 890792Sgshapiro=head1 SYNOPSIS 990792Sgshapiro 1090792SgshapiroB<openssl> B<pkcs12> 1190792Sgshapiro[B<-export>] 12266527Sgshapiro[B<-chain>] 1390792Sgshapiro[B<-inkey filename>] 1490792Sgshapiro[B<-certfile filename>] 1590792Sgshapiro[B<-name name>] 1690792Sgshapiro[B<-caname name>] 1790792Sgshapiro[B<-in filename>] 1890792Sgshapiro[B<-out filename>] 1990792Sgshapiro[B<-noout>] 2090792Sgshapiro[B<-nomacver>] 2190792Sgshapiro[B<-nocerts>] 2290792Sgshapiro[B<-clcerts>] 2390792Sgshapiro[B<-cacerts>] 2490792Sgshapiro[B<-nokeys>] 2590792Sgshapiro[B<-info>] 2690792Sgshapiro[B<-des>] 2790792Sgshapiro[B<-des3>] 2890792Sgshapiro[B<-idea>] 2990792Sgshapiro[B<-nodes>] 3090792Sgshapiro[B<-noiter>] 3190792Sgshapiro[B<-maciter>] 3290792Sgshapiro[B<-twopass>] 3390792Sgshapiro[B<-descert>] 3490792Sgshapiro[B<-certpbe>] 3590792Sgshapiro[B<-keypbe>] 3690792Sgshapiro[B<-keyex>] 3790792Sgshapiro[B<-keysig>] 3890792Sgshapiro[B<-password arg>] 3990792Sgshapiro[B<-passin arg>] 4090792Sgshapiro[B<-passout arg>] 4190792Sgshapiro[B<-rand file(s)>] 4290792Sgshapiro 4390792Sgshapiro=head1 DESCRIPTION 4490792Sgshapiro 4590792SgshapiroThe B<pkcs12> command allows PKCS#12 files (sometimes referred to as 4690792SgshapiroPFX files) to be created and parsed. PKCS#12 files are used by several 4790792Sgshapiroprograms including Netscape, MSIE and MS Outlook. 4890792Sgshapiro 4990792Sgshapiro=head1 COMMAND OPTIONS 5090792Sgshapiro 5190792SgshapiroThere are a lot of options the meaning of some depends of whether a PKCS#12 file 5290792Sgshapirois being created or parsed. By default a PKCS#12 file is parsed a PKCS#12 5390792Sgshapirofile can be created by using the B<-export> option (see below). 5490792Sgshapiro 5590792Sgshapiro=head1 PARSING OPTIONS 5690792Sgshapiro 5790792Sgshapiro=over 4 5890792Sgshapiro 5990792Sgshapiro=item B<-in filename> 6090792Sgshapiro 6190792SgshapiroThis specifies filename of the PKCS#12 file to be parsed. Standard input is used 6290792Sgshapiroby default. 6390792Sgshapiro 6490792Sgshapiro=item B<-out filename> 6590792Sgshapiro 6690792SgshapiroThe filename to write certificates and private keys to, standard output by default. 6790792SgshapiroThey are all written in PEM format. 6890792Sgshapiro 6990792Sgshapiro=item B<-pass arg>, B<-passin arg> 7090792Sgshapiro 7190792Sgshapirothe PKCS#12 file (i.e. input file) password source. For more information about the 7290792Sgshapiroformat of B<arg> see the B<PASS PHRASE ARGUMENTS> section in 7390792SgshapiroL<openssl(1)|openssl(1)>. 7490792Sgshapiro 7590792Sgshapiro=item B<-passout arg> 7690792Sgshapiro 7790792Sgshapiropass phrase source to encrypt any outputed private keys with. For more information 7890792Sgshapiroabout the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in 7990792SgshapiroL<openssl(1)|openssl(1)>. 8090792Sgshapiro 8190792Sgshapiro=item B<-noout> 8290792Sgshapiro 8390792Sgshapirothis option inhibits output of the keys and certificates to the output file version 8490792Sgshapiroof the PKCS#12 file. 8590792Sgshapiro 8690792Sgshapiro=item B<-clcerts> 8790792Sgshapiro 8890792Sgshapiroonly output client certificates (not CA certificates). 8990792Sgshapiro 9090792Sgshapiro=item B<-cacerts> 9190792Sgshapiro 9290792Sgshapiroonly output CA certificates (not client certificates). 9390792Sgshapiro 9490792Sgshapiro=item B<-nocerts> 9590792Sgshapiro 9690792Sgshapirono certificates at all will be output. 9790792Sgshapiro 9890792Sgshapiro=item B<-nokeys> 9990792Sgshapiro 10090792Sgshapirono private keys will be output. 10190792Sgshapiro 10290792Sgshapiro=item B<-info> 10390792Sgshapiro 10490792Sgshapirooutput additional information about the PKCS#12 file structure, algorithms used and 10590792Sgshapiroiteration counts. 10690792Sgshapiro 10790792Sgshapiro=item B<-des> 10890792Sgshapiro 10990792Sgshapirouse DES to encrypt private keys before outputting. 11090792Sgshapiro 11190792Sgshapiro=item B<-des3> 11290792Sgshapiro 11390792Sgshapirouse triple DES to encrypt private keys before outputting, this is the default. 11490792Sgshapiro 11590792Sgshapiro=item B<-idea> 11690792Sgshapiro 11790792Sgshapirouse IDEA to encrypt private keys before outputting. 11890792Sgshapiro 11990792Sgshapiro=item B<-nodes> 12090792Sgshapiro 12190792Sgshapirodon't encrypt the private keys at all. 12290792Sgshapiro 12390792Sgshapiro=item B<-nomacver> 12490792Sgshapiro 12590792Sgshapirodon't attempt to verify the integrity MAC before reading the file. 12690792Sgshapiro 12790792Sgshapiro=item B<-twopass> 12890792Sgshapiro 12990792Sgshapiroprompt for separate integrity and encryption passwords: most software 130125820Sgshapiroalways assumes these are the same so this option will render such 13190792SgshapiroPKCS#12 files unreadable. 13290792Sgshapiro 13390792Sgshapiro=back 13490792Sgshapiro 13590792Sgshapiro=head1 FILE CREATION OPTIONS 13690792Sgshapiro 13790792Sgshapiro=over 4 13890792Sgshapiro 13990792Sgshapiro=item B<-export> 14090792Sgshapiro 14190792SgshapiroThis option specifies that a PKCS#12 file will be created rather than 14290792Sgshapiroparsed. 14390792Sgshapiro 14490792Sgshapiro=item B<-out filename> 14590792Sgshapiro 14690792SgshapiroThis specifies filename to write the PKCS#12 file to. Standard output is used 14790792Sgshapiroby default. 14890792Sgshapiro 14990792Sgshapiro=item B<-in filename> 15090792Sgshapiro 15190792SgshapiroThe filename to read certificates and private keys from, standard input by default. 15290792SgshapiroThey must all be in PEM format. The order doesn't matter but one private key and 15390792Sgshapiroits corresponding certificate should be present. If additional certificates are 15490792Sgshapiropresent they will also be included in the PKCS#12 file. 15590792Sgshapiro 15690792Sgshapiro=item B<-inkey filename> 15790792Sgshapiro 15890792Sgshapirofile to read private key from. If not present then a private key must be present 15990792Sgshapiroin the input file. 16090792Sgshapiro 16190792Sgshapiro=item B<-name friendlyname> 16290792Sgshapiro 16390792SgshapiroThis specifies the "friendly name" for the certificate and private key. This name 16490792Sgshapirois typically displayed in list boxes by software importing the file. 16590792Sgshapiro 166125820Sgshapiro=item B<-certfile filename> 16790792Sgshapiro 16890792SgshapiroA filename to read additional certificates from. 16990792Sgshapiro 17090792Sgshapiro=item B<-caname friendlyname> 17190792Sgshapiro 17290792SgshapiroThis specifies the "friendly name" for other certificates. This option may be 17390792Sgshapiroused multiple times to specify names for all certificates in the order they 17490792Sgshapiroappear. Netscape ignores friendly names on other certificates whereas MSIE 17590792Sgshapirodisplays them. 17690792Sgshapiro 17790792Sgshapiro=item B<-pass arg>, B<-passout arg> 17890792Sgshapiro 17990792Sgshapirothe PKCS#12 file (i.e. output file) password source. For more information about 18090792Sgshapirothe format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in 18190792SgshapiroL<openssl(1)|openssl(1)>. 18290792Sgshapiro 18390792Sgshapiro=item B<-passin password> 18490792Sgshapiro 18590792Sgshapiropass phrase source to decrypt any input private keys with. For more information 18690792Sgshapiroabout the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in 18790792SgshapiroL<openssl(1)|openssl(1)>. 188 189=item B<-chain> 190 191if this option is present then an attempt is made to include the entire 192certificate chain of the user certificate. The standard CA store is used 193for this search. If the search fails it is considered a fatal error. 194 195=item B<-descert> 196 197encrypt the certificate using triple DES, this may render the PKCS#12 198file unreadable by some "export grade" software. By default the private 199key is encrypted using triple DES and the certificate using 40 bit RC2. 200 201=item B<-keypbe alg>, B<-certpbe alg> 202 203these options allow the algorithm used to encrypt the private key and 204certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms 205can be selected it is advisable only to use PKCS#12 algorithms. See the list 206in the B<NOTES> section for more information. 207 208=item B<-keyex|-keysig> 209 210specifies that the private key is to be used for key exchange or just signing. 211This option is only interpreted by MSIE and similar MS software. Normally 212"export grade" software will only allow 512 bit RSA keys to be used for 213encryption purposes but arbitrary length keys for signing. The B<-keysig> 214option marks the key for signing only. Signing only keys can be used for 215S/MIME signing, authenticode (ActiveX control signing) and SSL client 216authentication, however due to a bug only MSIE 5.0 and later support 217the use of signing only keys for SSL client authentication. 218 219=item B<-nomaciter>, B<-noiter> 220 221these options affect the iteration counts on the MAC and key algorithms. 222Unless you wish to produce files compatible with MSIE 4.0 you should leave 223these options alone. 224 225To discourage attacks by using large dictionaries of common passwords the 226algorithm that derives keys from passwords can have an iteration count applied 227to it: this causes a certain part of the algorithm to be repeated and slows it 228down. The MAC is used to check the file integrity but since it will normally 229have the same password as the keys and certificates it could also be attacked. 230By default both MAC and encryption iteration counts are set to 2048, using 231these options the MAC and encryption iteration counts can be set to 1, since 232this reduces the file security you should not use these options unless you 233really have to. Most software supports both MAC and key iteration counts. 234MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> 235option. 236 237=item B<-maciter> 238 239This option is included for compatibility with previous versions, it used 240to be needed to use MAC iterations counts but they are now used by default. 241 242=item B<-rand file(s)> 243 244a file or files containing random data used to seed the random number 245generator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 246Multiple files can be specified separated by a OS-dependent character. 247The separator is B<;> for MS-Windows, B<,> for OpenVSM, and B<:> for 248all others. 249 250=back 251 252=head1 NOTES 253 254Although there are a large number of options most of them are very rarely 255used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used 256for PKCS#12 file creation B<-export> and B<-name> are also used. 257 258If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present 259then all certificates will be output in the order they appear in the input 260PKCS#12 files. There is no guarantee that the first certificate present is 261the one corresponding to the private key. Certain software which requires 262a private key and certificate and assumes the first certificate in the 263file is the one corresponding to the private key: this may not always 264be the case. Using the B<-clcerts> option will solve this problem by only 265outputing the certificate corresponding to the private key. If the CA 266certificates are required then they can be output to a separate file using 267the B<-nokeys -cacerts> options to just output CA certificates. 268 269The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption 270algorithms for private keys and certificates to be specified. Normally 271the defaults are fine but occasionally software can't handle triple DES 272encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can 273be used to reduce the private key encryption to 40 bit RC2. A complete 274description of all algorithms is contained in the B<pkcs8> manual page. 275 276=head1 EXAMPLES 277 278Parse a PKCS#12 file and output it to a file: 279 280 openssl pkcs12 -in file.p12 -out file.pem 281 282Output only client certificates to a file: 283 284 openssl pkcs12 -in file.p12 -clcerts -out file.pem 285 286Don't encrypt the private key: 287 288 openssl pkcs12 -in file.p12 -out file.pem -nodes 289 290Print some info about a PKCS#12 file: 291 292 openssl pkcs12 -in file.p12 -info -noout 293 294Create a PKCS#12 file: 295 296 openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" 297 298Include some extra certificates: 299 300 openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \ 301 -certfile othercerts.pem 302 303=head1 BUGS 304 305Some would argue that the PKCS#12 standard is one big bug :-) 306 307=head1 SEE ALSO 308 309L<pkcs8(1)|pkcs8(1)> 310 311