doc/man1/openssl-pkcs12.pod.in

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