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