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