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