pkcs12.pod revision 285830
11541Srgrimes 21541Srgrimes=pod 31541Srgrimes 41541Srgrimes=head1 NAME 51541Srgrimes 61541Srgrimespkcs12 - PKCS#12 file utility 71541Srgrimes 81541Srgrimes=head1 SYNOPSIS 91541Srgrimes 101541SrgrimesB<openssl> B<pkcs12> 111541Srgrimes[B<-export>] 121541Srgrimes[B<-chain>] 131541Srgrimes[B<-inkey filename>] 141541Srgrimes[B<-certfile filename>] 151541Srgrimes[B<-name name>] 161541Srgrimes[B<-caname name>] 171541Srgrimes[B<-in filename>] 181541Srgrimes[B<-out filename>] 191541Srgrimes[B<-noout>] 201541Srgrimes[B<-nomacver>] 211541Srgrimes[B<-nocerts>] 221541Srgrimes[B<-clcerts>] 231541Srgrimes[B<-cacerts>] 241541Srgrimes[B<-nokeys>] 251541Srgrimes[B<-info>] 261541Srgrimes[B<-des | -des3 | -idea | -aes128 | -aes192 | -aes256 | -camellia128 | -camellia192 | -camellia256 | -nodes>] 271541Srgrimes[B<-noiter>] 281541Srgrimes[B<-maciter | -nomaciter | -nomac>] 291541Srgrimes[B<-twopass>] 301541Srgrimes[B<-descert>] 311541Srgrimes[B<-certpbe cipher>] 321541Srgrimes[B<-keypbe cipher>] 3322521Sdyson[B<-macalg digest>] 3450477Speter[B<-keyex>] 351541Srgrimes[B<-keysig>] 3622521Sdyson[B<-password arg>] 3722521Sdyson[B<-passin arg>] 3822521Sdyson[B<-passout arg>] 3922521Sdyson[B<-rand file(s)>] 4022521Sdyson[B<-CAfile file>] 4122521Sdyson[B<-CApath dir>] 4222521Sdyson[B<-CSP name>] 4322521Sdyson 4422521Sdyson=head1 DESCRIPTION 4522521Sdyson 4622521SdysonThe B<pkcs12> command allows PKCS#12 files (sometimes referred to as 4745058SeivindPFX files) to be created and parsed. PKCS#12 files are used by several 4822521Sdysonprograms including Netscape, MSIE and MS Outlook. 4922521Sdyson 5022521Sdyson=head1 COMMAND OPTIONS 5122521Sdyson 5222521SdysonThere are a lot of options the meaning of some depends of whether a PKCS#12 file 5322521Sdysonis being created or parsed. By default a PKCS#12 file is parsed. A PKCS#12 5451679Seivindfile can be created by using the B<-export> option (see below). 5551679Seivind 5651679Seivind=head1 PARSING OPTIONS 5751679Seivind 5851679Seivind=over 4 5951679Seivind 6051679Seivind=item B<-in filename> 6122521Sdyson 6222521SdysonThis specifies filename of the PKCS#12 file to be parsed. Standard input is used 6322521Sdysonby default. 6422521Sdyson 6522521Sdyson=item B<-out filename> 6622521Sdyson 6722521SdysonThe filename to write certificates and private keys to, standard output by 681541Srgrimesdefault. They are all written in PEM format. 691541Srgrimes 701541Srgrimes=item B<-passin arg> 711541Srgrimes 721541Srgrimesthe PKCS#12 file (i.e. input file) password source. For more information about 731541Srgrimesthe format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in 7422521SdysonL<openssl(1)|openssl(1)>. 7528732Sphk 7628732Sphk=item B<-passout arg> 7728732Sphk 7828732Sphkpass phrase source to encrypt any outputted private keys with. For more 7928732Sphkinformation about the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section 8028732Sphkin L<openssl(1)|openssl(1)>. 8128732Sphk 8228732Sphk=item B<-password arg> 8328732Sphk 8428732SphkWith -export, -password is equivalent to -passout. 8528732SphkOtherwise, -password is equivalent to -passin. 8628732Sphk 8735823Smsmith=item B<-noout> 8822521Sdyson 8922521Sdysonthis option inhibits output of the keys and certificates to the output file 901541Srgrimesversion of the PKCS#12 file. 9135823Smsmith 921541Srgrimes=item B<-clcerts> 931541Srgrimes 941541Srgrimesonly output client certificates (not CA certificates). 951541Srgrimes 961541Srgrimes=item B<-cacerts> 9722521Sdyson 9822521Sdysononly output CA certificates (not client certificates). 9922521Sdyson 10022521Sdyson=item B<-nocerts> 10135823Smsmith 10222521Sdysonno certificates at all will be output. 10322521Sdyson 10422521Sdyson=item B<-nokeys> 10522521Sdyson 10622521Sdysonno private keys will be output. 10735823Smsmith 10822521Sdyson=item B<-info> 10922521Sdyson 1101541Srgrimesoutput additional information about the PKCS#12 file structure, algorithms used and 11135823Smsmithiteration counts. 1121541Srgrimes 1131541Srgrimes=item B<-des> 1141541Srgrimes 1151541Srgrimesuse DES to encrypt private keys before outputting. 1161541Srgrimes 11722521Sdyson=item B<-des3> 11822521Sdyson 11922521Sdysonuse triple DES to encrypt private keys before outputting, this is the default. 1201541Srgrimes 1211541Srgrimes=item B<-idea> 1221541Srgrimes 1231541Srgrimesuse IDEA to encrypt private keys before outputting. 1241541Srgrimes 1251541Srgrimes=item B<-aes128>, B<-aes192>, B<-aes256> 1261541Srgrimes 12722521Sdysonuse AES to encrypt private keys before outputting. 12822521Sdyson 12922521Sdyson=item B<-camellia128>, B<-camellia192>, B<-camellia256> 1301541Srgrimes 1311541Srgrimesuse Camellia to encrypt private keys before outputting. 1321541Srgrimes 1331541Srgrimes=item B<-nodes> 1341541Srgrimes 1351541Srgrimesdon't encrypt the private keys at all. 1361541Srgrimes 13722521Sdyson=item B<-nomacver> 13822521Sdyson 13922521Sdysondon't attempt to verify the integrity MAC before reading the file. 1401541Srgrimes 1411541Srgrimes=item B<-twopass> 1421541Srgrimes 1431541Srgrimesprompt for separate integrity and encryption passwords: most software 1441541Srgrimesalways assumes these are the same so this option will render such 1451541SrgrimesPKCS#12 files unreadable. 1461541Srgrimes 14722521Sdyson=back 14822521Sdyson 14922521Sdyson=head1 FILE CREATION OPTIONS 1501541Srgrimes 1511541Srgrimes=over 4 1521541Srgrimes 1531541Srgrimes=item B<-export> 1541541Srgrimes 1551541SrgrimesThis option specifies that a PKCS#12 file will be created rather than 1561541Srgrimesparsed. 15722521Sdyson 15822521Sdyson=item B<-out filename> 15922521Sdyson 1601541SrgrimesThis specifies filename to write the PKCS#12 file to. Standard output is used 1611541Srgrimesby default. 1621541Srgrimes 1631541Srgrimes=item B<-in filename> 1641541Srgrimes 1651541SrgrimesThe filename to read certificates and private keys from, standard input by 1661541Srgrimesdefault. They must all be in PEM format. The order doesn't matter but one 16722521Sdysonprivate key and its corresponding certificate should be present. If additional 16822521Sdysoncertificates are present they will also be included in the PKCS#12 file. 16922521Sdyson 1701541Srgrimes=item B<-inkey filename> 1711541Srgrimes 1721541Srgrimesfile to read private key from. If not present then a private key must be present 1731541Srgrimesin the input file. 1741541Srgrimes 1751541Srgrimes=item B<-name friendlyname> 1761541Srgrimes 17722521SdysonThis specifies the "friendly name" for the certificate and private key. This 17822521Sdysonname is typically displayed in list boxes by software importing the file. 17922521Sdyson 1801541Srgrimes=item B<-certfile filename> 1811541Srgrimes 1821541SrgrimesA filename to read additional certificates from. 1831541Srgrimes 1841541Srgrimes=item B<-caname friendlyname> 1851541Srgrimes 1861541SrgrimesThis specifies the "friendly name" for other certificates. This option may be 18722521Sdysonused multiple times to specify names for all certificates in the order they 18822521Sdysonappear. Netscape ignores friendly names on other certificates whereas MSIE 18922521Sdysondisplays them. 19022521Sdyson 19122521Sdyson=item B<-pass arg>, B<-passout arg> 19222521Sdyson 19322521Sdysonthe PKCS#12 file (i.e. output file) password source. For more information about 19422521Sdysonthe format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in 19522521SdysonL<openssl(1)|openssl(1)>. 19622521Sdyson 19722521Sdyson=item B<-passin password> 19822521Sdyson 19922521Sdysonpass phrase source to decrypt any input private keys with. For more information 2001541Srgrimesabout the format of B<arg> see the B<PASS PHRASE ARGUMENTS> section in 2011541SrgrimesL<openssl(1)|openssl(1)>. 20222521Sdyson 2031541Srgrimes=item B<-chain> 2041541Srgrimes 2051541Srgrimesif this option is present then an attempt is made to include the entire 2061541Srgrimescertificate chain of the user certificate. The standard CA store is used 2071541Srgrimesfor this search. If the search fails it is considered a fatal error. 2081541Srgrimes 20922521Sdyson=item B<-descert> 21029353Speter 21122521Sdysonencrypt the certificate using triple DES, this may render the PKCS#12 21229353Speterfile unreadable by some "export grade" software. By default the private 2131541Srgrimeskey is encrypted using triple DES and the certificate using 40 bit RC2. 21429353Speter 2151541Srgrimes=item B<-keypbe alg>, B<-certpbe alg> 2161541Srgrimes 2171541Srgrimesthese options allow the algorithm used to encrypt the private key and 2181541Srgrimescertificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name 21922521Sdysoncan be used (see B<NOTES> section for more information). If a a cipher name 22022521Sdyson(as output by the B<list-cipher-algorithms> command is specified then it 22122521Sdysonis used with PKCS#5 v2.0. For interoperability reasons it is advisable to only 22222521Sdysonuse PKCS#12 algorithms. 22322521Sdyson 22422521Sdyson=item B<-keyex|-keysig> 22522521Sdyson 22622521Sdysonspecifies that the private key is to be used for key exchange or just signing. 22722521SdysonThis option is only interpreted by MSIE and similar MS software. Normally 22822521Sdyson"export grade" software will only allow 512 bit RSA keys to be used for 22922521Sdysonencryption purposes but arbitrary length keys for signing. The B<-keysig> 2301541Srgrimesoption marks the key for signing only. Signing only keys can be used for 2311541SrgrimesS/MIME signing, authenticode (ActiveX control signing) and SSL client 2321541Srgrimesauthentication, however due to a bug only MSIE 5.0 and later support 2331541Srgrimesthe use of signing only keys for SSL client authentication. 2341541Srgrimes 2351541Srgrimes=item B<-macalg digest> 2361541Srgrimes 23722521Sdysonspecify the MAC digest algorithm. If not included them SHA1 will be used. 23822521Sdyson 23922521Sdyson=item B<-nomaciter>, B<-noiter> 2401541Srgrimes 2411541Srgrimesthese options affect the iteration counts on the MAC and key algorithms. 2421541SrgrimesUnless you wish to produce files compatible with MSIE 4.0 you should leave 2431541Srgrimesthese options alone. 2441541Srgrimes 2451541SrgrimesTo discourage attacks by using large dictionaries of common passwords the 2461541Srgrimesalgorithm that derives keys from passwords can have an iteration count applied 24722521Sdysonto it: this causes a certain part of the algorithm to be repeated and slows it 24835823Smsmithdown. The MAC is used to check the file integrity but since it will normally 24935823Smsmithhave the same password as the keys and certificates it could also be attacked. 25022521SdysonBy default both MAC and encryption iteration counts are set to 2048, using 2511541Srgrimesthese options the MAC and encryption iteration counts can be set to 1, since 25235823Smsmiththis reduces the file security you should not use these options unless you 25335823Smsmithreally have to. Most software supports both MAC and key iteration counts. 2541541SrgrimesMSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> 2551541Srgrimesoption. 2561541Srgrimes 25722521Sdyson=item B<-maciter> 25835823Smsmith 25922521SdysonThis option is included for compatibility with previous versions, it used 26022521Sdysonto be needed to use MAC iterations counts but they are now used by default. 2619842Sdg 26235823Smsmith=item B<-nomac> 2639842Sdg 2649842Sdgdon't attempt to provide the MAC integrity. 2659842Sdg 2661541Srgrimes=item B<-rand file(s)> 26722521Sdyson 26822521Sdysona file or files containing random data used to seed the random number 26922521Sdysongenerator, or an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 27022521SdysonMultiple files can be specified separated by a OS-dependent character. 27122521SdysonThe separator is B<;> for MS-Windows, B<,> for OpenVMS, and B<:> for 27222521Sdysonall others. 2731541Srgrimes 2741541Srgrimes=item B<-CAfile file> 2751541Srgrimes 2761541SrgrimesCA storage as a file. 2771541Srgrimes 2781541Srgrimes=item B<-CApath dir> 2791541Srgrimes 2801541SrgrimesCA storage as a directory. This directory must be a standard certificate 2811541Srgrimesdirectory: that is a hash of each subject name (using B<x509 -hash>) should be 28222521Sdysonlinked to each certificate. 28335823Smsmith 28422521Sdyson=item B<-CSP name> 28522521Sdyson 2861541Srgrimeswrite B<name> as a Microsoft CSP name. 28735823Smsmith 2881541Srgrimes=back 2891541Srgrimes 2901541Srgrimes=head1 NOTES 2911541Srgrimes 2921541SrgrimesAlthough there are a large number of options most of them are very rarely 29322521Sdysonused. For PKCS#12 file parsing only B<-in> and B<-out> need to be used 29435823Smsmithfor PKCS#12 file creation B<-export> and B<-name> are also used. 29535823Smsmith 29622521SdysonIf none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present 2971541Srgrimesthen all certificates will be output in the order they appear in the input 29835823SmsmithPKCS#12 files. There is no guarantee that the first certificate present is 29935823Smsmiththe one corresponding to the private key. Certain software which requires 3001541Srgrimesa private key and certificate and assumes the first certificate in the 3011541Srgrimesfile is the one corresponding to the private key: this may not always 3021541Srgrimesbe the case. Using the B<-clcerts> option will solve this problem by only 30322521Sdysonoutputting the certificate corresponding to the private key. If the CA 30435823Smsmithcertificates are required then they can be output to a separate file using 30522521Sdysonthe B<-nokeys -cacerts> options to just output CA certificates. 30622521Sdyson 30722521SdysonThe B<-keypbe> and B<-certpbe> algorithms allow the precise encryption 30822521Sdysonalgorithms for private keys and certificates to be specified. Normally 30922521Sdysonthe defaults are fine but occasionally software can't handle triple DES 31022521Sdysonencrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can 3111541Srgrimesbe used to reduce the private key encryption to 40 bit RC2. A complete 31235823Smsmithdescription of all algorithms is contained in the B<pkcs8> manual page. 3131541Srgrimes 3141541Srgrimes=head1 EXAMPLES 3151541Srgrimes 3161541SrgrimesParse a PKCS#12 file and output it to a file: 3171541Srgrimes 3181541Srgrimes openssl pkcs12 -in file.p12 -out file.pem 31922521Sdyson 32022521SdysonOutput only client certificates to a file: 32122521Sdyson 3221541Srgrimes openssl pkcs12 -in file.p12 -clcerts -out file.pem 3231541Srgrimes 3241541SrgrimesDon't encrypt the private key: 3251541Srgrimes 3263167Sdfr openssl pkcs12 -in file.p12 -out file.pem -nodes 32722521Sdyson 32822521SdysonPrint some info about a PKCS#12 file: 3291541Srgrimes 3301541Srgrimes openssl pkcs12 -in file.p12 -info -noout 33122521Sdyson 33222521SdysonCreate a PKCS#12 file: 33322521Sdyson 3341541Srgrimes openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" 3351541Srgrimes 3361541SrgrimesInclude some extra certificates: 3371541Srgrimes 3381541Srgrimes openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \ 3391541Srgrimes -certfile othercerts.pem 34022521Sdyson 34122521Sdyson=head1 BUGS 34222521Sdyson 3431541SrgrimesSome would argue that the PKCS#12 standard is one big bug :-) 3441541Srgrimes 3451541SrgrimesVersions of OpenSSL before 0.9.6a had a bug in the PKCS#12 key generation 3461541Srgrimesroutines. Under rare circumstances this could produce a PKCS#12 file encrypted 3471541Srgrimeswith an invalid key. As a result some PKCS#12 files which triggered this bug 34822521Sdysonfrom other implementations (MSIE or Netscape) could not be decrypted 34922521Sdysonby OpenSSL and similarly OpenSSL could produce PKCS#12 files which could 35022521Sdysonnot be decrypted by other implementations. The chances of producing such 3511541Srgrimesa file are relatively small: less than 1 in 256. 3521541Srgrimes 35322521SdysonA side effect of fixing this bug is that any old invalidly encrypted PKCS#12 3541541Srgrimesfiles cannot no longer be parsed by the fixed version. Under such circumstances 3551541Srgrimesthe B<pkcs12> utility will report that the MAC is OK but fail with a decryption 35622521Sdysonerror when extracting private keys. 35722521Sdyson 35822521SdysonThis problem can be resolved by extracting the private keys and certificates 3591541Srgrimesfrom the PKCS#12 file using an older version of OpenSSL and recreating the PKCS#12 3601541Srgrimesfile from the keys and certificates using a newer version of OpenSSL. For example: 36122521Sdyson 3621541Srgrimes old-openssl -in bad.p12 -out keycerts.pem 3631541Srgrimes openssl -in keycerts.pem -export -name "My PKCS#12 file" -out fixed.p12 36422521Sdyson 36522521Sdyson=head1 SEE ALSO 36622521Sdyson 3671541SrgrimesL<pkcs8(1)|pkcs8(1)> 3681541Srgrimes 36922521Sdyson