Add PKCS#12 manpage and use MAC iteration counts by default.

diff --git a/CHANGES b/CHANGES
index 09b277ecd013833e24fba5fd936297cdbf5d0600..18e0c28e7b04857e2e3a0ff0dcc2610596599a84 100644 (file)
--- a/CHANGES
+++ b/CHANGES
@@ -4,6 +4,12 @@
 
  Changes between 0.9.4 and 0.9.5  [xx XXX 1999]
 
 
  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]
 
   *) Honor the no-xxx Configure options when creating .DEF files.
      [Ulf Möller]
 

diff --git a/apps/pkcs12.c b/apps/pkcs12.c
index 65276f5229ee025cb746afc5f5b937e232424eb9..800e2a840633e0728373d2824a855100f9467daa 100644 (file)
--- 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 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;
     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, "-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]) {
                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 (file)
index 0000000..7b40f6c
--- /dev/null
+++ b/doc/man/pkcs12.pod
@@ -0,0 +1,286 @@
+
+=pod
+
+=head1 NAME
+
+pkcs12 - PKCS#12 file utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs12>
+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<pkcs12> 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<var>.
+
+=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<var>.
+
+=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<NOTES> 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<pkcs8> 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)
+