From dad666fbbeed2a0699ca682b96f26f490cee1a4c Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Sat, 8 Jan 2000 03:16:04 +0000 Subject: [PATCH] Add PKCS#12 manpage and use MAC iteration counts by default. --- CHANGES | 6 + apps/pkcs12.c | 4 +- doc/man/pkcs12.pod | 286 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 295 insertions(+), 1 deletion(-) create mode 100644 doc/man/pkcs12.pod diff --git a/CHANGES b/CHANGES index 09b277ecd0..18e0c28e7b 100644 --- a/CHANGES +++ b/CHANGES @@ -4,6 +4,12 @@ Changes between 0.9.4 and 0.9.5 [xx XXX 1999] + *) Add manpage for the pkcs12 command. Also change the default + behaviour so MAC iteration counts are used unless the new + -nomaciter option is used. This improves file security and + only older versions of MSIE (4.0 for example) need it. + [Steve Henson] + *) Honor the no-xxx Configure options when creating .DEF files. [Ulf Möller] diff --git a/apps/pkcs12.c b/apps/pkcs12.c index 65276f5229..800e2a8406 100644 --- a/apps/pkcs12.c +++ b/apps/pkcs12.c @@ -100,7 +100,7 @@ int MAIN(int argc, char **argv) int chain = 0; int badarg = 0; int iter = PKCS12_DEFAULT_ITER; - int maciter = 1; + int maciter = PKCS12_DEFAULT_ITER; int twopass = 0; int keytype = 0; int cert_pbe = NID_pbe_WithSHA1And40BitRC2_CBC; @@ -143,6 +143,8 @@ int MAIN(int argc, char **argv) else if (!strcmp (*args, "-noiter")) iter = 1; else if (!strcmp (*args, "-maciter")) maciter = PKCS12_DEFAULT_ITER; + else if (!strcmp (*args, "-nomaciter")) + maciter = 1; else if (!strcmp (*args, "-nodes")) enc=NULL; else if (!strcmp (*args, "-certpbe")) { if (args[1]) { diff --git a/doc/man/pkcs12.pod b/doc/man/pkcs12.pod new file mode 100644 index 0000000000..7b40f6cbc4 --- /dev/null +++ b/doc/man/pkcs12.pod @@ -0,0 +1,286 @@ + +=pod + +=head1 NAME + +pkcs12 - PKCS#12 file utility + +=head1 SYNOPSIS + +B B +B<-export> +B<-chain> +B<-inkey file> +B<-certfile f> +B<-name name> +B<-caname name> +B<-in infile> +B<-out outfile> +B<-noout> +B<-nomacver> +B<-nocerts> +B<-clcerts> +B<-cacerts> +B<-nokeys> +B<-info> +B<-des> +B<-des3> +B<-idea> +B<-nodes> +B<-noiter> +B<-maciter> +B<-twopass> +B<-descert> +B<-certpbe> +B<-keypbe> +B<-keyex> +B<-keysig> +B<-password pass> +B<-envpass pass> + +=head1 DESCRIPTION + +The B command allows PKCS#12 files (sometimes referred to as +PFX files) to be created and parsed. PKCS#12 files are used by several +software programs including Netscape, MSIE and MS Outlook. + +=head1 COMMAND OPTIONS + +There are a lot of options the meaning of some depends of whether a PKCS#12 file +is being created or parsed. By default a PKCS#12 file is parsed a PKCS#12 +file can be created by using the B<-export> option (see below). + +=head1 PARSING OPTIONS + +=over 4 + +=item B<-in filename> + +This specifies filename of the PKCS#12 file to be parsed. Standard input is used +by default. + +=item B<-out filename> + +The filename to write certificates and private keys to, standard output by default. +They are all written in PEM format. + +=item B<-pass password> + +the PKCS#12 file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpass var> + +read the PKCS#12 file password from the environment variable B. + +=item B<-noout> + +this option inhibits output of the keys and certificates to the output file version +of the PKCS#12 file. + +=item B<-clcerts> + +only output client certificates (not CA certificates). + +=item B<-cacerts> + +only output CA certificates (not client certificates). + +=item B<-nocerts> + +no certificates at all will be output. + +=item B<-nokeys> + +no private keys will be output. + +=item B<-info> + +output additional information about the PKCS#12 file structure, algorithms used and +iteration counts. + +=item B<-des> + +use DES to encrypt private keys before outputting. + +=item B<-des3> + +use triple DES to encrypt private keys before outputting, this is the default. + +=item B<-idea> + +use IDEA to encrypt private keys before outputting. + +=item B<-nodes> + +don't encrypt the private keys at all. + +=item B<-nomacver> + +don't attempt to verify the integrity MAC before reading the file. + +=item B<-twopass> + +prompt for separate integrity and encryption passwords: most software +always assumes these are the same so this option will render such +PKCS#12 files unreadable. + +=back + +=head1 FILE CREATION OPTIONS + +=over 4 + +=item B<-export> + +This option specifies that a PKCS#12 file will be created rather than +parsed. + +=item B<-out filename> + +This specifies filename to write the PKCS#12 file to. Standard output is used +by default. + +=item B<-in filename> + +The filename to read certificates and private keys from, standard input by default. +They must all be in PEM format. The order doesn't matter but one private key and +its corresponding certificate should be present. If additional certificates are +present they will also be included in the PKCS#12 file. + +=item B<-inkey filename> + +file to read private key from. If not present then a private key must be present +in the input file. + +=item B<-name friendlyname> + +This specifies the "friendly name" for the certificate and private key. This name +is typically displayed in list boxes by software importing the file. + +=item B<-certfile filename> + +A filename to read additional certificates from. + +=item B<-caname friendlyname> + +This specifies the "friendly name" for other certificates. This option may be +used multiple times to specify names for all certificates in the order they +appear. Netscape ignores friendly names on other certificates whereas MSIE +displays them. + +=item B<-pass password> + +the PKCS#12 file password. Since certain utilities like "ps" make the command line +visible this option should be used with caution. + +=item B<-envpass var> + +read the PKCS#12 file password from the environment variable B. + +=item B<-chain> + +if this option is present then an attempt is made to include the entire +certificate chain of the user certificate. The standard CA store is used +for this search. If the search fails it is considered a fatal error. + +=item B<-descert> + +encrypt the certificate using triple DES, this may render the PKCS#12 +file unreadable by some "export grade" software. By default the private +key is encrypted using triple DES and the certificate using 40 bit RC2. + +=item B<-keypbe alg>, B<-certpbe alg> + +these options allow the algorithm used to encrypt the private key and +certificates to be selected. Although any PKCS#5 v1.5 or PKCS#12 algorithms +can be selected it is advisable only to use PKCS#12 algorithms. See the list +in the B section for more information. + +=item B<-keyex|-keysig> + +specifies that the private key is to be used for key exchange or just signing. +This option is only interpreted by MSIE and similar MS software. Normally +"export grade" software will only allow 512 bit RSA keys to be used for +encryption purposes but arbitrary length keys for signing. The B<-keysig> +option marks the key for signing only. Signing only keys can be used for +S/MIME signing, authenticode (ActiveX control signing) and SSL client +authentication, however due to a bug only MSIE 5.0 and later support +the use of signing only keys for SSL client authentication. + +=item B<-nomaciter>, B<-noiter> + +these options affect the iteration counts on the MAC and key algorithms. +Unless you wish to produce files compatible with MSIE 4.0 you should leave +these options alone. + +To discourage attacks by using large dictionaries of common passwords the +algorithm that derives keys from passwords can have an iteration count applied +to it: this causes a certain part of the algorithm to be repeated and slows it +down. The MAC is used to check the file integrity but since it will normally +have the same password as the keys and certificates it could also be attacked. +By default both MAC and encryption iteration counts are set to 2048, using +these options the MAC and encryption iteration counts can be set to 1, since +this reduces the file security you should not use these options unless you +really have to. Most software supports both MAC and key iteration counts. +MSIE 4.0 doesn't support MAC iteration counts so it needs the B<-nomaciter> +option. + +=item B<-maciter> + +This option is included for compatibility with previous versions, it used +to be needed to use MAC iterations counts but they are now used by default. + +=back + +=head1 NOTES + +Although there are a large number of options most of them are very rarely +used. For PKCS#12 file parsing only B<-in> and B<-out> need to be used +for PKCS#12 file creation B<-export> and B<-name> are also used. + +The B<-keypbe> and B<-certpbe> algorithms allow the precise encryption +algorithms for private keys and certificates to be specified. Normally +the defaults are fine but occasionally software can't handle triple DES +encrypted private keys, then the option B<-keypbe PBE-SHA1-RC2-40> can +be used to reduce the private key encryption to 40 bit RC2. A complete +description of all algorithms is contained in the B manual page. + +=head1 EXAMPLES + +Parse a PKCS#12 file and output it to a file: + + openssl pkcs12 -in file.p12 -out file.pem + +Output only client certificates to a file: + + openssl pkcs12 -in file.p12 -clcerts -out file.pem + +Don't encrypt the private key: + + openssl pkcs12 -in file.p12 -out file.pem -nodes + +Print some info about a PKCS#12 file: + + openssl pkcs12 -in file.p12 -info -noout + +Create a PKCS#12 file: + + openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" + +Include some extra certificates: + + openssl pkcs12 -export -in file.pem -out file.p12 -name "My Certificate" \ + -certfile othercerts.pem + +=head1 BUGS + +Some would argue that the PKCS#12 standard is one big bug :-) + +Need password options for the PEM files: this will probably be fixed before +release. + +=head1 SEE ALSO + +pkcs8(1) + -- GitLab