1=pod 2{- OpenSSL::safe::output_do_not_edit_headers(); -} 3 4=head1 NAME 5 6openssl-pkcs12 - PKCS#12 file command 7 8=head1 SYNOPSIS 9 10B<openssl> B<pkcs12> 11[B<-help>] 12[B<-passin> I<arg>] 13[B<-passout> I<arg>] 14[B<-password> I<arg>] 15[B<-twopass>] 16[B<-in> I<filename>|I<uri>] 17[B<-out> I<filename>] 18[B<-nokeys>] 19[B<-nocerts>] 20[B<-noout>] 21[B<-legacy>] 22{- $OpenSSL::safe::opt_engine_synopsis -}{- $OpenSSL::safe::opt_provider_synopsis -} 23{- $OpenSSL::safe::opt_r_synopsis -} 24 25PKCS#12 input (parsing) options: 26[B<-info>] 27[B<-nomacver>] 28[B<-clcerts>] 29[B<-cacerts>] 30 31[B<-aes128>] 32[B<-aes192>] 33[B<-aes256>] 34[B<-aria128>] 35[B<-aria192>] 36[B<-aria256>] 37[B<-camellia128>] 38[B<-camellia192>] 39[B<-camellia256>] 40[B<-des>] 41[B<-des3>] 42[B<-idea>] 43[B<-noenc>] 44[B<-nodes>] 45 46PKCS#12 output (export) options: 47 48[B<-export>] 49[B<-inkey> I<filename>|I<uri>] 50[B<-certfile> I<filename>] 51[B<-passcerts> I<arg>] 52[B<-chain>] 53[B<-untrusted> I<filename>] 54{- $OpenSSL::safe::opt_trust_synopsis -} 55[B<-name> I<name>] 56[B<-caname> I<name>] 57[B<-CSP> I<name>] 58[B<-LMK>] 59[B<-keyex>] 60[B<-keysig>] 61[B<-keypbe> I<cipher>] 62[B<-certpbe> I<cipher>] 63[B<-descert>] 64[B<-macalg> I<digest>] 65[B<-iter> I<count>] 66[B<-noiter>] 67[B<-nomaciter>] 68[B<-maciter>] 69[B<-macsaltlen>] 70[B<-nomac>] 71 72=head1 DESCRIPTION 73 74This command allows PKCS#12 files (sometimes referred to as 75PFX files) to be created and parsed. PKCS#12 files are used by several 76programs including Netscape, MSIE and MS Outlook. 77 78=head1 OPTIONS 79 80There are a lot of options the meaning of some depends of whether a PKCS#12 file 81is being created or parsed. By default a PKCS#12 file is parsed. 82A PKCS#12 file can be created by using the B<-export> option (see below). 83The PKCS#12 export encryption and MAC options such as B<-certpbe> and B<-iter> 84and many further options such as B<-chain> are relevant only with B<-export>. 85Conversely, the options regarding encryption of private keys when outputting 86PKCS#12 input are relevant only when the B<-export> option is not given. 87 88The default encryption algorithm is AES-256-CBC with PBKDF2 for key derivation. 89 90When encountering problems loading legacy PKCS#12 files that involve, 91for example, RC2-40-CBC, 92try using the B<-legacy> option and, if needed, the B<-provider-path> option. 93 94=over 4 95 96=item B<-help> 97 98Print out a usage message. 99 100=item B<-passin> I<arg> 101 102The password source for the input, and for encrypting any private keys that 103are output. 104For more information about the format of B<arg> 105see L<openssl-passphrase-options(1)>. 106 107=item B<-passout> I<arg> 108 109The password source for output files. 110 111=item B<-password> I<arg> 112 113With B<-export>, B<-password> is equivalent to B<-passout>, 114otherwise it is equivalent to B<-passin>. 115 116=item B<-twopass> 117 118Prompt for separate integrity and encryption passwords: most software 119always assumes these are the same so this option will render such 120PKCS#12 files unreadable. Cannot be used in combination with the options 121B<-password>, B<-passin> if importing from PKCS#12, or B<-passout> if exporting. 122 123=item B<-nokeys> 124 125No private keys will be output. 126 127=item B<-nocerts> 128 129No certificates will be output. 130 131=item B<-noout> 132 133This option inhibits all credentials output, 134and so the input is just verified. 135 136=item B<-legacy> 137 138Use legacy mode of operation and automatically load the legacy provider. 139If OpenSSL is not installed system-wide, 140it is necessary to also use, for example, C<-provider-path ./providers> 141or to set the environment variable B<OPENSSL_MODULES> 142to point to the directory where the providers can be found. 143 144In the legacy mode, the default algorithm for certificate encryption 145is RC2_CBC or 3DES_CBC depending on whether the RC2 cipher is enabled 146in the build. The default algorithm for private key encryption is 3DES_CBC. 147If the legacy option is not specified, then the legacy provider is not loaded 148and the default encryption algorithm for both certificates and private keys is 149AES_256_CBC with PBKDF2 for key derivation. 150 151{- $OpenSSL::safe::opt_engine_item -} 152 153{- $OpenSSL::safe::opt_provider_item -} 154 155{- $OpenSSL::safe::opt_r_item -} 156 157=back 158 159=head2 PKCS#12 input (parsing) options 160 161=over 4 162 163=item B<-in> I<filename>|I<uri> 164 165This specifies the input filename or URI. 166Standard input is used by default. 167Without the B<-export> option this must be PKCS#12 file to be parsed. 168For use with the B<-export> option 169see the L</PKCS#12 output (export) options> section. 170 171=item B<-out> I<filename> 172 173The filename to write certificates and private keys to, standard output by 174default. They are all written in PEM format. 175 176=item B<-info> 177 178Output additional information about the PKCS#12 file structure, algorithms 179used and iteration counts. 180 181=item B<-nomacver> 182 183Don't attempt to verify the integrity MAC. 184 185=item B<-clcerts> 186 187Only output client certificates (not CA certificates). 188 189=item B<-cacerts> 190 191Only output CA certificates (not client certificates). 192 193=item B<-aes128>, B<-aes192>, B<-aes256> 194 195Use AES to encrypt private keys before outputting. 196 197=item B<-aria128>, B<-aria192>, B<-aria256> 198 199Use ARIA to encrypt private keys before outputting. 200 201=item B<-camellia128>, B<-camellia192>, B<-camellia256> 202 203Use Camellia to encrypt private keys before outputting. 204 205=item B<-des> 206 207Use DES to encrypt private keys before outputting. 208 209=item B<-des3> 210 211Use triple DES to encrypt private keys before outputting. 212 213=item B<-idea> 214 215Use IDEA to encrypt private keys before outputting. 216 217=item B<-noenc> 218 219Don't encrypt private keys at all. 220 221=item B<-nodes> 222 223This option is deprecated since OpenSSL 3.0; use B<-noenc> instead. 224 225=back 226 227=head2 PKCS#12 output (export) options 228 229=over 4 230 231=item B<-export> 232 233This option specifies that a PKCS#12 file will be created rather than 234parsed. 235 236=item B<-out> I<filename> 237 238This specifies filename to write the PKCS#12 file to. Standard output is used 239by default. 240 241=item B<-in> I<filename>|I<uri> 242 243This specifies the input filename or URI. 244Standard input is used by default. 245With the B<-export> option this is a file with certificates and a key, 246or a URI that refers to a key accessed via an engine. 247The order of credentials in a file doesn't matter but one private key and 248its corresponding certificate should be present. If additional 249certificates are present they will also be included in the PKCS#12 output file. 250 251=item B<-inkey> I<filename>|I<uri> 252 253The private key input for PKCS12 output. 254If this option is not specified then the input file (B<-in> argument) must 255contain a private key. 256If no engine is used, the argument is taken as a file. 257If the B<-engine> option is used or the URI has prefix C<org.openssl.engine:> 258then the rest of the URI is taken as key identifier for the given engine. 259 260=item B<-certfile> I<filename> 261 262An input file with extra certificates to be added to the PKCS#12 output 263if the B<-export> option is given. 264 265=item B<-passcerts> I<arg> 266 267The password source for certificate input such as B<-certfile> 268and B<-untrusted>. 269For more information about the format of B<arg> see 270L<openssl-passphrase-options(1)>. 271 272=item B<-chain> 273 274If this option is present then the certificate chain of the end entity 275certificate is built and included in the PKCS#12 output file. 276The end entity certificate is the first one read from the B<-in> file 277if no key is given, else the first certificate matching the given key. 278The standard CA trust store is used for chain building, 279as well as any untrusted CA certificates given with the B<-untrusted> option. 280 281=item B<-untrusted> I<filename> 282 283An input file of untrusted certificates that may be used 284for chain building, which is relevant only when a PKCS#12 file is created 285with the B<-export> option and the B<-chain> option is given as well. 286Any certificates that are actually part of the chain are added to the output. 287 288{- $OpenSSL::safe::opt_trust_item -} 289 290=item B<-name> I<friendlyname> 291 292This specifies the "friendly name" for the certificates and private key. This 293name is typically displayed in list boxes by software importing the file. 294 295=item B<-caname> I<friendlyname> 296 297This specifies the "friendly name" for other certificates. This option may be 298used multiple times to specify names for all certificates in the order they 299appear. Netscape ignores friendly names on other certificates whereas MSIE 300displays them. 301 302=item B<-CSP> I<name> 303 304Write I<name> as a Microsoft CSP name. 305The password source for the input, and for encrypting any private keys that 306are output. 307For more information about the format of B<arg> 308see L<openssl-passphrase-options(1)>. 309 310=item B<-LMK> 311 312Add the "Local Key Set" identifier to the attributes. 313 314=item B<-keyex>|B<-keysig> 315 316Specifies that the private key is to be used for key exchange or just signing. 317This option is only interpreted by MSIE and similar MS software. Normally 318"export grade" software will only allow 512 bit RSA keys to be used for 319encryption purposes but arbitrary length keys for signing. The B<-keysig> 320option marks the key for signing only. Signing only keys can be used for 321S/MIME signing, authenticode (ActiveX control signing) and SSL client 322authentication, however, due to a bug only MSIE 5.0 and later support 323the use of signing only keys for SSL client authentication. 324 325=item B<-keypbe> I<alg>, B<-certpbe> I<alg> 326 327These options allow the algorithm used to encrypt the private key and 328certificates to be selected. Any PKCS#5 v1.5 or PKCS#12 PBE algorithm name 329can be used (see L</NOTES> section for more information). If a cipher name 330(as output by C<openssl list -cipher-algorithms>) is specified then it 331is used with PKCS#5 v2.0. For interoperability reasons it is advisable to only 332use PKCS#12 algorithms. 333 334Special value C<NONE> disables encryption of the private key and certificates. 335 336=item B<-descert> 337 338Encrypt the certificates using triple DES. By default the private 339key and the certificates are encrypted using AES-256-CBC unless 340the '-legacy' option is used. If '-descert' is used with the '-legacy' 341then both, the private key and the certificates are encrypted using triple DES. 342 343=item B<-macalg> I<digest> 344 345Specify the MAC digest algorithm. If not included SHA256 will be used. 346 347=item B<-iter> I<count> 348 349This option specifies the iteration count for the encryption key and MAC. The 350default value is 2048. 351 352To discourage attacks by using large dictionaries of common passwords the 353algorithm that derives keys from passwords can have an iteration count applied 354to it: this causes a certain part of the algorithm to be repeated and slows it 355down. The MAC is used to check the file integrity but since it will normally 356have the same password as the keys and certificates it could also be attacked. 357 358=item B<-noiter>, B<-nomaciter> 359 360By default both encryption and MAC iteration counts are set to 2048, using 361these options the MAC and encryption iteration counts can be set to 1, since 362this reduces the file security you should not use these options unless you 363really have to. Most software supports both MAC and encryption iteration counts. 364MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> 365option. 366 367=item B<-maciter> 368 369This option is included for compatibility with previous versions, it used 370to be needed to use MAC iterations counts but they are now used by default. 371 372=item B<-macsaltlen> 373 374This option specifies the salt length in bytes for the MAC. The salt length 375should be at least 16 bytes as per NIST SP 800-132. The default value 376is 8 bytes for backwards compatibility. 377 378=item B<-nomac> 379 380Do not attempt to provide the MAC integrity. This can be useful with the FIPS 381provider as the PKCS12 MAC requires PKCS12KDF which is not an approved FIPS 382algorithm and cannot be supported by the FIPS provider. 383 384=back 385 386=head1 NOTES 387 388Although there are a large number of options most of them are very rarely 389used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used 390for PKCS#12 file creation B<-export> and B<-name> are also used. 391 392If none of the B<-clcerts>, B<-cacerts> or B<-nocerts> options are present 393then all certificates will be output in the order they appear in the input 394PKCS#12 files. There is no guarantee that the first certificate present is 395the one corresponding to the private key. 396Certain software which tries to get a private key and the corresponding 397certificate might assume that the first certificate in the file is the one 398corresponding to the private key, but that may not always be the case. 399Using the B<-clcerts> option will solve this problem by only 400outputting the certificate corresponding to the private key. If the CA 401certificates are required then they can be output to a separate file using 402the B<-nokeys> B<-cacerts> options to just output CA certificates. 403 404The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption 405algorithms for private keys and certificates to be specified. Normally 406the defaults are fine but occasionally software can't handle triple DES 407encrypted private keys, then the option B<-keypbe> I<PBE-SHA1-RC2-40> can 408be used to reduce the private key encryption to 40 bit RC2. A complete 409description of all algorithms is contained in L<openssl-pkcs8(1)>. 410 411Prior 1.1 release passwords containing non-ASCII characters were encoded 412in non-compliant manner, which limited interoperability, in first hand 413with Windows. But switching to standard-compliant password encoding 414poses problem accessing old data protected with broken encoding. For 415this reason even legacy encodings is attempted when reading the 416data. If you use PKCS#12 files in production application you are advised 417to convert the data, because implemented heuristic approach is not 418MT-safe, its sole goal is to facilitate the data upgrade with this 419command. 420 421=head1 EXAMPLES 422 423Parse a PKCS#12 file and output it to a PEM file: 424 425 openssl pkcs12 -in file.p12 -out file.pem 426 427Output only client certificates to a file: 428 429 openssl pkcs12 -in file.p12 -clcerts -out file.pem 430 431Don't encrypt the private key: 432 433 openssl pkcs12 -in file.p12 -out file.pem -noenc 434 435Print some info about a PKCS#12 file: 436 437 openssl pkcs12 -in file.p12 -info -noout 438 439Print some info about a PKCS#12 file in legacy mode: 440 441 openssl pkcs12 -in file.p12 -info -noout -legacy 442 443Create a PKCS#12 file from a PEM file that may contain a key and certificates: 444 445 openssl pkcs12 -export -in file.pem -out file.p12 -name "My PSE" 446 447Include some extra certificates: 448 449 openssl pkcs12 -export -in file.pem -out file.p12 -name "My PSE" \ 450 -certfile othercerts.pem 451 452Export a PKCS#12 file with data from a certificate PEM file and from a further 453PEM file containing a key, with default algorithms as in the legacy provider: 454 455 openssl pkcs12 -export -in cert.pem -inkey key.pem -out file.p12 -legacy 456 457=head1 SEE ALSO 458 459L<openssl(1)>, 460L<openssl-pkcs8(1)>, 461L<ossl_store-file(7)> 462 463=head1 HISTORY 464 465The B<-engine> option was deprecated in OpenSSL 3.0. 466The B<-nodes> option was deprecated in OpenSSL 3.0, too; use B<-noenc> instead. 467 468=head1 COPYRIGHT 469 470Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. 471 472Licensed under the Apache License 2.0 (the "License"). You may not use 473this file except in compliance with the License. You can obtain a copy 474in the file LICENSE in the source distribution or at 475L<https://www.openssl.org/source/license.html>. 476 477=cut 478