Change the 'man' directory to 'apps'. Yes I wish cvs

could rename too :-(

27 files changed, 5145 insertions, 0 deletions

diff --git a/doc/apps/asn1parse.pod b/doc/apps/asn1parse.pod
new file mode 100644
index 0000000000..e76e9813ab
--- /dev/null
+++ b/doc/apps/asn1parse.pod
@@ -0,0 +1,129 @@
+=pod
+
+=head1 NAME
+
+asn1parse - ASN.1 parsing tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<asn1parse>
+[B<-inform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-offset number>]
+[B<-length number>]
+[B<-i>]
+[B<-oid filename>]
+[B<-strparse offset>]
+
+=head1 DESCRIPTION
+
+The B<asn1parse> command is a diagnostic utility that can parse ASN.1
+structures. It can also be used to extract data from ASN.1 formatted data.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-inform> B<DER|PEM>
+
+the input format. B<DER> is binary format and B<PEM> (the default) is base64
+encoded.
+
+=item B<-in filename>
+
+the input file, default is standard input
+
+=item B<-out filename>
+
+output file to place the DER encoded data into. If this
+option is not present then no data will be output. This is most useful when
+combined with the B<-strparse> option.
+
+=item B<-noout>
+
+don't output the parsed version of the input file.
+
+=item B<-offset number>
+
+starting offset to begin parsing, default is start of file.
+
+=item B<-length number>
+
+number of bytes to parse, default is until end of file.
+
+=item B<-i>
+
+indents the output according to the "depth" of the structures.
+
+=item B<-oid filename>
+
+a file containing additional OBJECT IDENTIFIERs (OIDs). The format of this
+file is described in the NOTES section below.
+
+=item B<-strparse offset>
+
+parse the contents octets of the ASN.1 object starting at B<offset>. This
+option can be used multiple times to "drill down" into a nested structure.
+
+
+=back
+
+=head2 OUTPUT
+
+The output will typically contain lines like this:
+
+  0:d=0  hl=4 l= 681 cons: SEQUENCE          
+
+.....
+
+  229:d=3  hl=3 l= 141 prim: BIT STRING        
+  373:d=2  hl=3 l= 162 cons: cont [ 3 ]        
+  376:d=3  hl=3 l= 159 cons: SEQUENCE          
+  379:d=4  hl=2 l=  29 cons: SEQUENCE          
+  381:d=5  hl=2 l=   3 prim: OBJECT            :X509v3 Subject Key Identifier
+  386:d=5  hl=2 l=  22 prim: OCTET STRING      
+  410:d=4  hl=2 l= 112 cons: SEQUENCE          
+  412:d=5  hl=2 l=   3 prim: OBJECT            :X509v3 Authority Key Identifier
+  417:d=5  hl=2 l= 105 prim: OCTET STRING      
+  524:d=4  hl=2 l=  12 cons: SEQUENCE          
+
+.....
+
+This example is part of a self signed certificate. Each line starts with the
+offset in decimal. B<d=XX> specifies the current depth. The depth is increased
+within the scope of any SET or SEQUENCE. B<hl=XX> gives the header length
+(tag and length octets) of the current type. B<l=XX> gives the length of
+the contents octets.
+
+The B<-i> option can be used to make the output more readable.
+
+Some knowledge of the ASN.1 structure is needed to interpret the output. 
+
+In this example the BIT STRING at offset 229 is the certificate public key.
+The contents octets of this will contain the public key information. This can
+be examined using the option B<-strparse 229> to yield:
+
+    0:d=0  hl=3 l= 137 cons: SEQUENCE          
+    3:d=1  hl=3 l= 129 prim: INTEGER           :E5D21E1F5C8D208EA7A2166C7FAF9F6BDF2059669C60876DDB70840F1A5AAFA59699FE471F379F1DD6A487E7D5409AB6A88D4A9746E24B91D8CF55DB3521015460C8EDE44EE8A4189F7A7BE77D6CD3A9AF2696F486855CF58BF0EDF2B4068058C7A947F52548DDF7E15E96B385F86422BEA9064A3EE9E1158A56E4A6F47E5897
+  135:d=1  hl=2 l=   3 prim: INTEGER           :010001
+
+=head1 NOTES
+
+If an OID is not part of OpenSSL's internal table it will be represented in
+numerical form (for example 1.2.3.4). The file passed to the B<-oid> option 
+allows additional OIDs to be included. Each line consists of three columns,
+the first column is the OID in numerical format and should be followed by white
+space. The second column is the "short name" which is a single word followed
+by white space. The final column is the rest of the line and is the
+"long name". B<asn1parse> displays the long name. Example:
+
+C<1.2.3.4	shortName	A long name>
+
+=head1 BUGS
+
+There should be options to change the format of input lines. The output of some
+ASN.1 types is not well handled (if at all).
+
+=cut
diff --git a/doc/apps/ca.pod b/doc/apps/ca.pod
new file mode 100644
index 0000000000..999622b570
--- /dev/null
+++ b/doc/apps/ca.pod
@@ -0,0 +1,472 @@
+
+=pod
+
+=head1 NAME
+
+ca - sample minimal CA application
+
+=head1 SYNOPSIS
+
+B<openssl> B<ca>
+[B<-verbose>]
+[B<-config filename>]
+[B<-name section>]
+[B<-gencrl>]
+[B<-revoke file>]
+[B<-crldays days>]
+[B<-crlhours hours>]
+[B<-crlexts section>]
+[B<-startdate date>]
+[B<-enddate date>]
+[B<-days arg>]
+[B<-md arg>]
+[B<-policy arg>]
+[B<-keyfile arg>]
+[B<-key arg>]
+[B<-cert file>]
+[B<-in file>]
+[B<-out file>]
+[B<-outdir dir>]
+[B<-infiles>]
+[B<-spkac file>]
+[B<-ss_cert file>]
+[B<-preserveDN>]
+[B<-batch>]
+[B<-msie_hack>]
+[B<-extensions section>]
+
+=head1 DESCRIPTION
+
+The B<ca> command is a minimal CA application. It can be used
+to sign certificate requests in a variety of forms and generate
+CRLs it also maintains a text database of issued certificates
+and their status.
+
+The options descriptions will be divided into each purpose.
+
+=head1 CA OPTIONS
+
+=over 4
+
+=item B<-config filename>
+
+specifies the configuration file to use.
+
+=item B<-in filename>
+
+an input filename containing a single certificate request to be
+signed by the CA.
+
+=item B<-ss_cert filename>
+
+a single self signed certificate to be signed by the CA.
+
+=item B<-spkac filename>
+
+a file containing a single Netscape signed public key and challenge
+and additional field values to be signed by the CA. See the B<NOTES>
+section for information on the required format.
+
+=item B<-infiles>
+
+if present this should be the last option, all subsequent arguments
+are assumed to the the names of files containing certificate requests. 
+
+=item B<-out filename>
+
+the output file to output certificates to. The default is standard
+output. The certificate details will also be printed out to this
+file.
+
+=item B<-outdir directory>
+
+the directory to output certificates to. The certificate will be
+written to a filename consisting of the serial number in hex with
+".pem" appended.
+
+=item B<-cert>
+
+the CA certificate file.
+
+=item B<-keyfile filename>
+
+the private key to sign requests with.
+
+=item B<-key password>
+
+the password used to encrypt the private key. Since on some
+systems the command line arguments are visible (e.g. Unix with
+the 'ps' utility) this option should be used with caution.
+
+=item B<-verbose>
+
+this prints extra details about the operations being performed.
+
+=item B<-startdate date>
+
+this allows the start date to be explicitly set. The format of the
+date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
+
+=item B<-enddate date>
+
+this allows the expiry date to be explicitly set. The format of the
+date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
+
+=item B<-days arg>
+
+the number of days to certify the certificate for.
+
+=item B<-md alg>
+
+the message digest to use. Possible values include md5, sha1 and mdc2.
+This option also applies to CRLs.
+
+=item B<-policy arg>
+
+this option defines the CA "policy" to use. This is a section in
+the configuration file which decides which fields should be mandatory
+or match the CA certificate. Check out the B<POLICY FORMAT> section
+for more information.
+
+=item B<-msie_hack>
+
+this is a legacy option to make B<ca> work with very old versions of
+the IE certificate enrollment control "certenr3". It used UniversalStrings
+for almost everything. Since the old control has various security bugs
+its use is strongly discouraged. The newer control "Xenroll" does not
+need this option.
+
+=item B<-preserveDN>
+
+Normally the DN order of a certificate is the same as the order of the
+fields in the relevant policy section. When this option is set the order 
+is the same as the request. This is largely for compatibility with the
+older IE enrollment control which would only accept certificates if their
+DNs match the order of the request. This is not needed for Xenroll.
+
+=item B<-batch>
+
+this sets the batch mode. In this mode no questions will be asked
+and all certificates will be certified automatically.
+
+=item B<-extensions section>
+
+the section of the configuration file containing certificate extensions
+to be added when a certificate is issued. If no extension section is
+present then a V1 certificate is created. If the extension section
+is present (even if it is empty) then a V3 certificate is created.
+
+=back
+
+=head1 CRL OPTIONS
+
+=over 4
+
+=item B<-gencrl>
+
+this option generates a CRL based on information in the index file.
+
+=item B<-crldays num>
+
+the number of days before the next CRL is due. That is the days from
+now to place in the CRL nextUpdate field.
+
+=item B<-crlhours num>
+
+the number of hours before the next CRL is due.
+
+=item B<-revoke filename>
+
+a filename containing a certificate to revoke.
+
+=item B<-crlexts section>
+
+the section of the configuration file containing CRL extensions to
+include. If no CRL extension section is present then a V1 CRL is
+created, if the CRL extension section is present (even if it is
+empty) then a V2 CRL is created. The CRL extensions specified are
+CRL extensions and B<not> CRL entry extensions.  It should be noted
+that some software (for example Netscape) can't handle V2 CRLs. 
+
+=back
+
+=head1 CONFIGURATION FILE OPTIONS
+
+The options for B<ca> are contained in the B<ca> section of the
+configuration file. Many of these are identical to command line
+options. Where the option is present in the configuration file
+and the command line the command line value is used. Where an
+option is described as mandatory then it must be present in
+the configuration file or the command line equivalent (if
+any) used.
+
+=over 4
+
+=item B<oid_file>
+
+This specifies a file containing additional B<OBJECT IDENTIFIERS>.
+Each line of the file should consist of the numerical form of the
+object identifier followed by white space then the short name followed
+by white space and finally the long name. 
+
+=item B<oid_section>
+
+This specifies a section in the configuration file containing extra
+object identifiers. Each line should consist of the short name of the
+object identifier followed by B<=> and the numerical form. The short
+and long names are the same when this option is used.
+
+=item B<new_certs_dir>
+
+the same as the B<-outdir> command line option. It specifies
+the directory where new certificates will be placed. Mandatory.
+
+=item B<certificate>
+
+the same as B<-cert>. It gives the file containing the CA
+certificate. Mandatory.
+
+=item B<private_key>
+
+same as the B<-keyfile> option. The file containing the
+CA private key. Mandatory.
+
+=item B<RANDFILE>
+
+a file used to read and write random number seed information.
+
+=item B<default_days>
+
+the same as the B<-days> option. The number of days to certify
+a certificate for. 
+
+=item B<default_startdate>
+
+the same as the B<-startdate> option. The start date to certify
+a certificate for. If not set the current time is used.
+
+=item B<default_enddate>
+
+the same as the B<-enddate> option. Either this option or
+B<default_days> (or the command line equivalents) must be
+present.
+
+=item B<default_crl_hours default_crl_days>
+
+the same as the B<-crlhours> and the B<-crldays> options. These
+will only be used if neither command line option is present. At
+least one of these must be present to generate a CRL.
+
+=item B<default_md>
+
+the same as the B<-md> option. The message digest to use. Mandatory.
+
+=item B<database>
+
+the text database file to use. Mandatory. This file must be present
+though initially it will be empty.
+
+=item B<serialfile>
+
+a text file containing the next serial number to use in hex. Mandatory.
+This file must be present and contain a valid serial number.
+
+=item B<x509_extensions>
+
+the same as B<-extensions>.
+
+=item B<crl_extensions>
+
+the same as B<-crlexts>.
+
+=item B<preserve>
+
+the same as B<-preserveDN>
+
+=item B<msie_hack>
+
+the same as B<-msie_hack>
+
+=item B<policy>
+
+the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
+for more information.
+
+=back
+
+=head1 POLICY FORMAT
+
+The policy section consists of a set of variables corresponding to
+certificate DN fields. If the value is "match" then the field value
+must match the same field in the CA certificate. If the value is
+"supplied" then it must be present. If the value is "optional" then
+it may be present. Any fields not mentioned in the policy section
+are silently deleted, unless the B<-preserveDN> option is set but
+this can be regarded more of a quirk than intended behaviour.
+
+=head1 SPKAC FORMAT
+
+The input to the B<-spkac> command line option is a Netscape
+signed public key and challenge. This will usually come from
+the B<KEYGEN> tag in an HTML form to create a new private key. 
+It is however possible to create SPKACs using the B<spkac> utility.
+
+The file should contain the variable SPKAC set to the value of
+the SPKAC and also the required DN components as name value pairs.
+If you need to include the same component twice then it can be
+preceded by a number and a '.'.
+
+=head1 EXAMPLES
+
+Note: these examples assume that the B<ca> directory structure is
+already set up and the relevant files already exist. This usually
+involves creating a CA certificate and private key with B<req>, a
+serial number file and an empty index file and placing them in
+the relevant directories.
+
+To use the sample configuration file below the directories demoCA,
+demoCA/private and demoCA/newcerts would be created. The CA
+certificate would be copied to demoCA/cacert.pem and its private
+key to demoCA/private/cakey.pem. A file demoCA/serial would be
+created containing for example "01" and the empty index file
+demoCA/index.txt.
+
+
+Sign a certificate request:
+
+openssl ca -in req.pem -out newcert.pem
+
+Generate a CRL
+
+openssl ca -gencrl -out crl.pem
+
+Sign several requests:
+
+openssl ca -infiles req1.pem req2.pem req3.pem
+
+Certify a Netscape SPKAC:
+
+openssl ca -spkac spkac.txt
+
+A sample SPKAC file (the SPKAC line has been truncated for clarity):
+
+ SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
+ CN=Steve Test
+ emailAddress=steve@openssl.org
+ 0.OU=OpenSSL Group
+ 1.OU=Another Group
+
+A sample configuration file with the relevant sections for B<ca>:
+
+ [ ca ]
+ default_ca      = CA_default            # The default ca section
+ 
+ [ CA_default ]
+
+ dir            = ./demoCA              # top dir
+ database       = $dir/index.txt        # index file.
+ new_certs_dir	= $dir/newcerts         # new certs dir
+ 
+ certificate    = $dir/cacert.pem       # The CA cert
+ serial         = $dir/serial           # serial no file
+ private_key    = $dir/private/cakey.pem# CA private key
+ RANDFILE       = $dir/private/.rand    # random number file
+ 
+ default_days   = 365                   # how long to certify for
+ default_crl_days= 30                   # how long before next CRL
+ default_md     = md5                   # md to use
+
+ policy         = policy_any            # default policy
+
+ [ policy_any ]
+ countryName            = supplied
+ stateOrProvinceName    = optional
+ organizationName       = optional
+ organizationalUnitName = optional
+ commonName             = supplied
+ emailAddress           = optional
+
+=head1 WARNINGS
+
+The B<ca> command is quirky and at times downright unfriendly.
+
+The B<ca> utility was originally meant as an example of how to do things
+in a CA. It was not supposed be be used as a full blown CA itself:
+nevertheless some people are using it for this purpose.
+
+The B<ca> command is effectively a single user command: no locking is
+done on the various files and attempts to run more than one B<ca> command
+on the same database can have unpredictable results.
+
+=head1 FILES
+
+Note: the location of all files can change either by compile time options,
+configuration file entries, environment variables or command line options.
+The values below reflect the default values.
+
+ /usr/local/ssl/lib/openssl.cnf - master configuration file
+ ./demoCA                       - main CA directory
+ ./demoCA/cacert.pem            - CA certificate
+ ./demoCA/private/cakey.pem     - CA private key
+ ./demoCA/serial                - CA serial number file
+ ./demoCA/serial.old            - CA serial number backup file
+ ./demoCA/index.txt             - CA text database file
+ ./demoCA/index.txt.old         - CA text database backup file
+ ./demoCA/certs                 - certificate output file
+ ./demoCA/.rnd                  - CA random seed information
+
+=head1 ENVIRONMENT VARIABLES
+
+B<OPENSSL_CONF> reflects the location of master configuration file it can
+be overridden by the B<-config> command line option.
+
+=head1 RESTRICTIONS
+
+The text database index file is a critical part of the process and 
+if corrupted it can be difficult to fix. It is theoretically possible
+to rebuild the index file from all the issued certificates and a current
+CRL: however there is no option to do this.
+
+CRL entry extensions cannot currently be created: only CRL extensions
+can be added.
+
+V2 CRL features like delta CRL support and CRL numbers are not currently
+supported.
+
+Although several requests can be input and handled at once it is only
+possible to include one SPKAC or self signed certificate.
+
+=head1 BUGS
+
+The use of an in memory text database can cause problems when large
+numbers of certificates are present because, as the name implies
+the database has to be kept in memory.
+
+Certificate request extensions are ignored: some kind of "policy" should
+be included to use certain static extensions and certain extensions
+from the request.
+
+It is not possible to certify two certificates with the same DN: this
+is a side effect of how the text database is indexed and it cannot easily
+be fixed without introducing other problems. Some S/MIME clients can use
+two certificates with the same DN for separate signing and encryption
+keys.
+
+The B<ca> command really needs rewriting or the required functionality
+exposed at either a command or interface level so a more friendly utility
+(perl script or GUI) can handle things properly. The scripts B<CA.sh> and
+B<CA.pl> help a little but not very much.
+
+Any fields in a request that are not present in a policy are silently
+deleted. This does not happen if the B<-preserveDN> option is used but
+the extra fields are not displayed when the user is asked to certify
+a request. The behaviour should be more friendly and configurable.
+
+Cancelling some commands by refusing to certify a certificate can
+create an empty file.
+
+=head1 SEE ALSO
+
+req(1), spkac(1), x509(1), CA.pl(1), config(5)
+
+=cut
diff --git a/doc/apps/config.pod b/doc/apps/config.pod
new file mode 100644
index 0000000000..a5974d945a
--- /dev/null
+++ b/doc/apps/config.pod
@@ -0,0 +1,138 @@
+
+=pod
+
+=head1 NAME
+
+config - OpenSSL CONF library configuration files
+
+=head1 DESCRIPTION
+
+The OpenSSL CONF library can be used to read configuration files.
+It is used for the OpenSSL master configuration file B<openssl.cnf>
+and in a few other places like B<SPKAC> files and certificate extension
+files for the B<x509> utility.
+
+A configuration file is divided into a number of sections. Each section
+starts with a line B<[ section_name ]> and ends when a new section is
+started or end of file is reached. A section name can consist of
+alphanumeric characters and underscores.
+
+The first section of a configuration file is special and is referred
+to as the B<default> section this is usually unnamed and is from the
+start of file until the first named section. When a name is being looked up
+it is first looked up in a named section (if any) and then the
+default section.
+
+The environment is mapped onto a section called B<ENV>.
+
+Comments can be included by preceding them with the B<#> character
+
+Each section in a configuration file consists of a number of name and
+value pairs of the form B<name=value>
+
+The B<name> string can contain any alphanumeric characters as well as
+a few punctuation symbols such as B<.> B<,> B<;> and B<_>.
+
+The B<value> string consists of the string following the B<=> character
+until end of line with any leading and trailing white space removed.
+
+The value string undergoes variable expansion. This can be done by
+including the form B<$var> or B<${var}>: this will substitute the value
+of the named variable in the current section. It is also possible to
+substitute a value from another section using the syntax B<$section::name>
+or B<${section::name}>. By using the form B<$ENV::name> environment
+variables can be substituted. It is also possible to assign values to
+environment variables by using the name B<ENV::name>, this will work
+if the program looks up environment variables using the B<CONF> library
+instead of calling B<getenv()> directly.
+
+It is possible to escape certain characters by using any kind of quote
+or the B<\> character. By making the last character of a line a B<\>
+a B<value> string can be spread across multiple lines. In addition
+the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognised.
+
+=head1 NOTES
+
+If a configuration file attempts to expand a variable that doesn't exist
+then an error is flagged and the file will not load. This can happen
+if an attempt is made to expand an environment variable that doesn't
+exist. For example the default OpenSSL master configuration file used
+the value of B<HOME> which may not be defined on non Unix systems.
+
+This can be worked around by including a B<default> section to provide
+a default value: then if the environment lookup fails the default value
+will be used instead. For this to work properly the default value must
+be defined earlier in the configuration file than the expansion. See
+the B<EXAMPLES> section for an example of how to do this.
+
+If the same variable exists in the same section then all but the last
+value will be silently ignored. In certain circumstances such as with
+DNs the same field may occur multiple times. This is usually worked
+around by ignoring any characters before an initial B<.> e.g.
+
+ 1.OU="My first OU"
+ 2.OU="My Second OU"
+
+=head1 EXAMPLES
+
+Here is a sample configuration file using some of the features
+mentioned above.
+
+ # This is the default section.
+ 
+ HOME=/temp
+ RANDFILE= ${ENV::HOME}/.rnd
+ configdir=$ENV::HOME/config
+
+ [ section_one ]
+
+ # We are now in section one.
+
+ # Quotes permit leading and trailing whitespace
+ any = " any variable name "
+
+ other = A string that can \
+ cover several lines \
+ by including \\ characters
+
+ message = Hello World\n
+
+ [ section_two ]
+
+ greeting = $section_one::message
+
+This next example shows how to expand environment variables safely.
+
+Suppose you want a variable called B<tmpfile> to refer to a
+temporary filename. The directory it is placed in can determined by
+the the B<TEMP> or B<TMP> environment variables but they may not be
+set to any value at all. If you just include the environment variable
+names and the variable doesn't exist then this will cause an error when
+an attempt is made to load the configuration file. By making use of the
+default section both values can be looked up with B<TEMP> taking 
+priority and B</tmp> used if neither is defined:
+
+ TMP=/tmp
+ # The above value is used if TMP isn't in the environment
+ TEMP=$ENV::TMP
+ # The above value is used if TEMP isn't in the environment
+ tmpfile=${ENV::TEMP}/tmp.filename
+
+=head1 BUGS
+
+Currently there is no way to include characters using the octal B<\nnn>
+form. Strings are all null terminated so nulls cannot form part of
+the value.
+
+The escaping isn't quite right: if you want to use sequences like B<\n>
+you can't use any quote escaping on the same line.
+
+Files are loaded in a single pass. This means that an variable expansion
+will only work if the variables referenced are defined earlier in the
+file.
+
+=head1 SEE ALSO
+
+x509(1), req(1), ca(1)
+
+=cut
diff --git a/doc/apps/crl.pod b/doc/apps/crl.pod
new file mode 100644
index 0000000000..8b19592c85
--- /dev/null
+++ b/doc/apps/crl.pod
@@ -0,0 +1,110 @@
+=pod
+
+=head1 NAME
+
+crl - CRL utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<crl>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-text>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-hash>]
+[B<-issuer>]
+[B<-lastupdate>]
+[B<-nextupdate>]
+[B<-CAfile file>]
+[B<-CApath dir>]
+
+=head1 DESCRIPTION
+
+The B<crl> command processes CRL files in DER or PEM format.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. B<DER> format is DER encoded CRL
+structure. B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-text>
+
+print out the CRL in text form.
+
+=item B<-noout>
+
+don't output the encoded version of the CRL.
+
+=item B<-hash>
+
+output a hash of the issuer name. This can be use to lookup CRLs in
+a directory by issuer name.
+
+=item B<-issuer>
+
+output the issuer name.
+
+=item B<-lastupdate>
+
+output the lastUpdate field.
+
+=item B<-nextupdate>
+
+output the nextUpdate field.
+
+=item B<-CAfile file>
+
+verify the signature on a CRL by looking up the issuing certificate in
+B<file>
+
+=item B<-CApath dir>
+
+verify the signature on a CRL by looking up the issuing certificate in
+B<dir>. This directory must be a standard certificate directory: that
+is a hash of each subject name (using B<x509 -hash>) should be linked
+to each certificate.
+
+=back
+
+=head1 EXAMPLES
+
+Convert a CRL file from PEM to DER:
+
+ openssl crl -in crl.pem -outform DER -out crl.der
+
+Output the text form of a DER encoded certificate:
+
+ openssl crl -in crl.der -text -noout
+
+=head1 BUGS
+
+Ideally it should be possible to create a CRL using appropriate options
+and files too.
+
+=head1 SEE ALSO
+
+crl2pkcs7(1), ca(1), x509(1)
+
+=cut
diff --git a/doc/apps/crl2pkcs7.pod b/doc/apps/crl2pkcs7.pod
new file mode 100644
index 0000000000..ad749ed0c3
--- /dev/null
+++ b/doc/apps/crl2pkcs7.pod
@@ -0,0 +1,90 @@
+=pod
+
+=head1 NAME
+
+crl2pkcs7 - Create a PKCS#7 structure from a CRL and certificates.
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs7>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-print_certs>]
+
+=head1 DESCRIPTION
+
+The B<crl2pkcs7> command takes an optional CRL and one or more
+certificates and converts them into a PKCS#7 degenerate "certificates
+only" structure.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the CRL input format. B<DER> format is DER encoded CRL
+structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the PKCS#7 structure output format. B<DER> format is DER
+encoded PKCS#7 structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-in filename>
+
+This specifies the input filename to read a CRL from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write the PKCS#7 structure to or standard
+output by default.
+
+=item B<-certfile filename>
+
+specifies a filename containing one or more certificates in B<PEM> format.
+All certificates in the file will be added to the PKCS#7 structure. This
+option can be used more than once to read certificates form multiple
+files.
+
+=item B<-nocrl>
+
+normally a CRL is included in the output file. With this option no CRL is
+included in the output file and a CRL is not read from the input file.
+
+=back
+
+=head1 EXAMPLES
+
+Create a PKCS#7 structure from a certificate and CRL:
+
+ openssl crl2pkcs7 -in crl.pem -certfile cert.pem -out p7.pem
+
+Creates a PKCS#7 structure in DER format with no CRL from several
+different certificates:
+
+ openssl crl2pkcs7 -nocrl -certfile newcert.pem 
+	-certfile demoCA/cacert.pem -outform DER -out p7.der
+
+=head1 NOTES
+
+The output file is a PKCS#7 signed data structure containing no signers and
+just certificates and an optional CRL.
+
+This utility can be used to send certificates and CAs to Netscape as part of
+the certificate enrollment process. This involves sending the DER encoded output
+as MIME type application/x-x509-user-cert.
+
+The B<PEM> encoded form with the header and footer lines removed can be used to
+install user certificates and CAs in MSIE using the Xenroll control.
+
+=head1 SEE ALSO
+
+pkcs7(1)
+
+=cut
diff --git a/doc/apps/dgst.pod b/doc/apps/dgst.pod
new file mode 100644
index 0000000000..cbf2cc529a
--- /dev/null
+++ b/doc/apps/dgst.pod
@@ -0,0 +1,49 @@
+=pod
+
+=head1 NAME
+
+dgst, md5, md2, sha1, sha, mdc2, ripemd160 - message digests
+
+=head1 SYNOPSIS
+
+[B<dgst>]
+[B<-md5|-md2|-sha1|-sha|mdc2|-ripemd160>]
+[B<-c>]
+[B<-d>]
+[B<file...>]
+
+[B<md5|md2|sha1|sha|mdc2|ripemd160>]
+[B<-c>]
+[B<-d>]
+[B<file...>]
+
+=head1 DESCRIPTION
+
+The digest functions print out the message digest of a supplied file or files
+in hexadecimal form.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-c>
+
+print out the digest in two digit groups separated by colons.
+
+=item B<-d>
+
+print out BIO debugging information.
+
+=item B<file...>
+
+file or files to digest. If no files are specified then standard input is
+used.
+
+=back
+
+=head1 NOTES
+
+The digest of choice for all new applications is SHA1. Other digests are
+however still widely used.
+
+=cut
diff --git a/doc/apps/dh.pod b/doc/apps/dh.pod
new file mode 100644
index 0000000000..99b307368f
--- /dev/null
+++ b/doc/apps/dh.pod
@@ -0,0 +1,87 @@
+=pod
+
+=head1 NAME
+
+dh - DH parameter manipulation and generation
+
+=head1 SYNOPSIS
+
+B<openssl dh>
+[B<-inform DER|PEM>]
+[B<-outform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-text>]
+[B<-C>]
+
+=head1 DESCRIPTION
+
+This command is used to manipulate DH parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#3 DHparameter structure. The PEM form is the
+default format: it consists of the B<DER> format base64 encoded with
+additional header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified.
+
+=item B<-out filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output filename should B<not> be the same
+as the input filename.
+
+=item B<-noout>
+
+this option inhibits the output of the encoded version of the parameters.
+
+=item B<-text>
+
+this option prints out the DH parameters in human readable form.
+
+=item B<-C>
+
+this option converts the parameters into C code. The parameters can then
+be loaded by calling the B<get_dhXXX()> function.
+
+=back
+
+=head1 NOTES
+
+PEM format DH parameters use the header and footer lines:
+
+ -----BEGIN DH PARAMETERS-----
+ -----END DH PARAMETERS-----
+
+OpenSSL currently only supports the older PKCS#3 DH, not the newer X9.42
+DH.
+
+This program manipulates DH parameters not keys.
+
+=head1 BUGS
+
+This program is badly named: the B<rsa> and B<dsa> programs manipulate keys
+and not parameters.
+
+There should be a way to generate and manipulate DH keys.
+
+=head1 SEE ALSO
+
+dsaparam(1)
+
+=cut
diff --git a/doc/apps/dsa.pod b/doc/apps/dsa.pod
new file mode 100644
index 0000000000..1235e5598b
--- /dev/null
+++ b/doc/apps/dsa.pod
@@ -0,0 +1,154 @@
+=pod
+
+=head1 NAME
+
+dsa - DSA key processing
+
+=head1 SYNOPSIS
+
+B<openssl> B<dsa>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin password>]
+[B<-envpassin var>]
+[B<-out filename>]
+[B<-passout password>]
+[B<-envpassout var>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-text>]
+[B<-noout>]
+[B<-modulus>]
+[B<-pubin>]
+[B<-pubout>]
+
+=head1 DESCRIPTION
+
+The B<dsa> command processes DSA keys. They can be converted between various
+forms and their components printed out. B<Note> This command uses the
+traditional SSLeay compatible format for private key encryption: newer
+applications should use the more secure PKCS#8 format using the B<pkcs8>
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option with a private key uses
+an ASN1 DER encoded form of an ASN.1 SEQUENCE consisting of the values of
+version (currently zero), p, q, g, the public and private key components
+respectively as ASN.1 INTEGERs. When used with a public key it uses a
+SubjectPublicKeyInfo structure: it is an error if the key is not DSA.
+
+The B<PEM> form is the default format: it consists of the B<DER> format base64
+encoded with additional header and footer lines. In the case of a private key
+PKCS#8 format is also accepted.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin password>
+
+the input file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassin var>
+
+read the input file password from the environment variable B<var>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+is not specified. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout password>
+
+the output file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassout var>
+
+read the output file password from the environment variable B<var>.
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, or the 
+IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
+If none of these options is specified the key is written in plain text. This
+means that using the B<rsa> utility to read in an encrypted key with no
+encryption option can be used to remove the pass phrase from a key, or by
+setting the encryption options it can be use to add or change the pass phrase.
+These options can only be used with PEM format output files.
+
+=item B<-text>
+
+prints out the public, private key components and parameters.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the key.
+
+=item B<-modulus>
+
+this option prints out the value of the public key component of the key.
+
+=item B<-pubin>
+
+by default a private key is input file with this option a public key is input
+instead.
+
+=item B<-pubout>
+
+by default a private key is output. With this option a public
+key will be output instead. This option is automatically set if the input is
+a public key.
+
+=back
+
+=head1 NOTES
+
+The PEM private key format uses the header and footer lines:
+
+ -----BEGIN DSA PRIVATE KEY-----
+ -----END DSA PRIVATE KEY-----
+
+=head1 EXAMPLES
+
+To remove the pass phrase on a DSA private key:
+
+C<openssl dsa -in key.pem -out keyout.pem>
+
+To encrypt a private key using triple DES:
+
+C<openssl dsa -in key.pem -des3 -out keyout.pem>
+
+To convert a private key from PEM to DER format: 
+
+C<openssl dsa -in key.pem -outform DER -out keyout.der>
+
+To print out the components of a private key to standard output:
+
+C<openssl dsa -in key.pem -text -noout>
+
+To just output the public part of a private key:
+
+C<openssl dsa -in key.pem -pubout -out pubkey.pem>
+
+=head1 SEE ALSO
+
+dsaparam(1), gendsa(1), rsa(1), genrsa(1)
+
+=cut
diff --git a/doc/apps/dsaparam.pod b/doc/apps/dsaparam.pod
new file mode 100644
index 0000000000..f5f3f317bd
--- /dev/null
+++ b/doc/apps/dsaparam.pod
@@ -0,0 +1,100 @@
+=pod
+
+=head1 NAME
+
+dsaparam - DSA parameter manipulation and generation
+
+=head1 SYNOPSIS
+
+B<openssl dsaparam>
+[B<-inform DER|PEM>]
+[B<-outform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-noout>]
+[B<-text>]
+[B<-C>]
+[B<-rand file(s)>]
+[B<-genkey>]
+[B<numbits>]
+
+=head1 DESCRIPTION
+
+This command is used to manipulate or generate DSA parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with RFC2459 (PKIX) DSS-Parms that is a SEQUENCE consisting
+of p, q and g respectively. The PEM form is the default format: it consists
+of the B<DER> format base64 encoded with additional header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read parameters from or standard input if
+this option is not specified. If the B<numbits> parameter is included then
+this option will be ignored.
+
+=item B<-out filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output filename should B<not> be the same
+as the input filename.
+
+=item B<-noout>
+
+this option inhibits the output of the encoded version of the parameters.
+
+=item B<-text>
+
+this option prints out the DSA parameters in human readable form.
+
+=item B<-C>
+
+this option converts the parameters into C code. The parameters can then
+be loaded by calling the B<get_dsaXXX()> function.
+
+=item B<-genkey>
+
+this option will generate a DSA either using the specified or generated
+parameters.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator. Multiple files can be specified separated by a OS-dependent
+character.  For MS-Windows, the separator is B<;>.  For OpenVMS, it's
+B<,>.  For all others, it's B<:>.
+
+=item B<numbits>
+
+this option specifies that a parameter set should be generated of size
+B<numbits>. It must be the last option. If this option is included then
+the input file (if any) is ignored.
+
+=back
+
+=head1 NOTES
+
+PEM format DSA parameters use the header and footer lines:
+
+ -----BEGIN DSA PARAMETERS-----
+ -----END DSA PARAMETERS-----
+
+DSA parameter generation is a slow process and as a result the same set of
+DSA parameters is often used to generate several distinct keys.
+
+=head1 SEE ALSO
+
+gendsa(1), dsa(1), genrsa(1), rsa(1)
+
+=cut
diff --git a/doc/apps/enc.pod b/doc/apps/enc.pod
new file mode 100644
index 0000000000..349fca00f8
--- /dev/null
+++ b/doc/apps/enc.pod
@@ -0,0 +1,248 @@
+=pod
+
+=head1 NAME
+
+enc - symmetric cipher routines
+
+=head1 SYNOPSIS
+
+B<openssl enc -ciphername>
+[B<-in filename>]
+[B<-out filename>]
+[B<-e>]
+[B<-d>]
+[B<-a>]
+[B<-A>]
+[B<-k password>]
+[B<-kfile filename>]
+[B<-K key>]
+[B<-iv IV>]
+[B<-p>]
+[B<-P>]
+[B<-bufsize number>]
+[B<-debug>]
+
+=head1 DESCRIPTION
+
+The symmetric cipher commands allow data to be encrypted or decrypted
+using various block and stream ciphers using keys based on passwords
+or explicitly provided. Base64 encoding or decoding can also be performed
+either by itself or in addition to the encryption or decryption.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-in filename>
+
+the input filename, standard input by default.
+
+=item B<-out filename>
+
+the output filename, standard output by default.
+
+=item B<-salt>
+
+use a salt in the key derivation routines. This option should B<ALWAYS>
+be used unless compatibility with previous versions of OpenSSL or SSLeay
+is required. This option is only present on OpenSSL versions 0.9.5 or
+above.
+
+=item B<-nosalt>
+
+don't use a salt in the key derivation routines. This is the default for
+compatibility with previous versions of OpenSSL and SSLeay.
+
+=item B<-e>
+
+encrypt the input data: this is the default.
+
+=item B<-d>
+
+decrypt the input data.
+
+=item B<-a>
+
+base64 process the data. This means that if encryption is taking place
+the data is base64 encoded after encryption. If decryption is set then
+the input data is base64 decoded before being decrypted.
+
+=item B<-A>
+
+if the B<-a> option is set then base64 process the data on one line.
+
+=item B<-k password>
+
+the password to derive the key from.
+
+=item B<-kfile filename>
+
+read the password to derive the key from the first line of B<filename>
+
+=item B<-S salt>
+
+the actual salt to use: this must be represented as a string comprised only
+of hex digits.
+
+=item B<-K key>
+
+the actual key to use: this must be represented as a string comprised only
+of hex digits.
+
+=item B<-iv IV>
+
+the actual IV to use: this must be represented as a string comprised only
+of hex digits.
+
+=item B<-p>
+
+print out the key and IV used.
+
+=item B<-P>
+
+print out the key and IV used then immediately exit: don't do any encryption
+or decryption.
+
+=item B<-bufsize number>
+
+set the buffer size for I/O
+
+=item B<-debug>
+
+debug the BIOs used for I/O.
+
+=back
+
+=head1 NOTES
+
+The program can be called either as B<openssl ciphername> or
+B<openssl enc -ciphername>.
+
+A password will be prompted for to derive the key and IV if necessary.
+
+The B<-salt> option should B<ALWAYS> be used if the key is being derived
+from a password unless you want compatibility with previous versions of
+OpenSSL and SSLeay.
+
+Without the B<-salt> option it is possible to perform efficient dictionary
+attacks on the password and to attack stream cipher encrypted data. The reason
+for this is that without the salt the same password always generates the same
+encryption key. When the salt is being used the first eight bytes of the
+encrypted data are reserved for the salt: it is generated at random when
+encrypting a file and read from the encrypted file when it is decrypted.
+
+Some of the ciphers do not have large keys and others have security
+implications if not used correctly. A beginner is advised to just use
+a strong block cipher in CBC mode such as bf or des3.
+
+All the block ciphers use PKCS#5 padding also known as standard block
+padding: this allows a rudimentary integrity or password check to be
+performed. However since the chance of random data passing the test is
+better than 1 in 256 it isn't a very good test.
+
+All RC2 ciphers have the same key and effective key length.
+
+Blowfish and RC5 algorithms use a 128 bit key.
+
+=head1 SUPPORTED CIPHERS
+
+ base64             Base 64
+
+ bf-cbc             Blowfish in CBC mode
+ bf                 Alias for bf-cbc
+ bf-cfb             Blowfish in CFB mode
+ bf-ecb             Blowfish in ECB mode
+ bf-ofb             Blowfish in OFB mode
+
+ cast-cbc           CAST in CBC mode
+ cast               Alias for cast-cbc
+ cast5-cbc          CAST5 in CBC mode
+ cast5-cfb          CAST5 in CFB mode
+ cast5-ecb          CAST5 in ECB mode
+ cast5-ofb          CAST5 in OFB mode
+
+ des-cbc            DES in CBC mode
+ des                Alias for des-cbc
+ des-cfb            DES in CBC mode
+ des-ofb            DES in OFB mode
+ des-ecb            DES in ECB mode
+
+ des-ede-cbc        Two key triple DES EDE in CBC mode
+ des-ede            Alias for des-ede
+ des-ede-cfb        Two key triple DES EDE in CFB mode
+ des-ede-ofb        Two key triple DES EDE in OFB mode
+
+ des-ede3-cbc       Three key triple DES EDE in CBC mode
+ des-ede3           Alias for des-ede3-cbc
+ des3               Alias for des-ede3-cbc
+ des-ede3-cfb       Three key triple DES EDE CFB mode
+ des-ede3-ofb       Three key triple DES EDE in OFB mode
+
+ desx               DESX algorithm.
+
+ idea-cbc           IDEA algorithm in CBC mode
+ idea               same as idea-cbc
+ idea-cfb           IDEA in CFB mode
+ idea-ecb           IDEA in ECB mode
+ idea-ofb           IDEA in OFB mode
+
+ rc2-cbc            128 bit RC2 in CBC mode
+ rc2                Alias for rc2-cbc
+ rc2-cfb            128 bit RC2 in CBC mode
+ rc2-ecb            128 bit RC2 in CBC mode
+ rc2-ofb            128 bit RC2 in CBC mode
+ rc2-64-cbc         64 bit RC2 in CBC mode
+ rc2-40-cbc         40 bit RC2 in CBC mode
+
+ rc4                128 bit RC4
+ rc4-64             64 bit RC4
+ rc4-40             40 bit RC4
+
+ rc5-cbc            RC5 cipher in CBC mode
+ rc5                Alias for rc5-cbc
+ rc5-cfb            RC5 cipher in CBC mode
+ rc5-ecb            RC5 cipher in CBC mode
+ rc5-ofb            RC5 cipher in CBC mode
+
+=head1 EXAMPLES
+
+Just base64 encode a binary file:
+
+ openssl base64 -in file.bin -out file.b64
+
+Decode the same file
+
+ openssl base64 -d -in file.b64 -out file.bin 
+
+Encrypt a file using triple DES in CBC mode using a prompted password:
+
+ openssl des3 -salt -in file.txt -out file.des3 
+
+Decrypt a file using a supplied password:
+
+ openssl des3 -d -salt -in file.des3 -out file.txt -k mypassword
+
+Encrypt a file then base64 encode it (so it can be sent via mail for example)
+using Blowfish in CBC mode:
+
+ openssl bf -a -salt -in file.txt -out file.bf
+
+Base64 decode a file then decrypt it:
+
+ openssl bf -d -salt -a -in file.bf -out file.txt
+
+Decrypt some data using a supplied 40 bit RC4 key:
+
+ openssl rc4-40 -in file.rc4 -out file.txt -K 0102030405
+
+=head1 BUGS
+
+The B<-A> option when used with large files doesn't work properly.
+
+There should be an option to allow an iteration count to be included.
+
+Like the EVP library the B<enc> program only supports a fixed number of
+algorithms with certain parameters. So if, for example, you want to use RC2
+with a 76 bit key or RC4 with an 84 bit key you can't use this program.
+
+=cut
diff --git a/doc/apps/gendh.pod b/doc/apps/gendh.pod
new file mode 100644
index 0000000000..8262622a3d
--- /dev/null
+++ b/doc/apps/gendh.pod
@@ -0,0 +1,74 @@
+=pod
+
+=head1 NAME
+
+gendh - DH parameter generation
+
+=head1 SYNOPSIS
+
+B<openssl gendh>
+[B<-out filename>]
+[B<-2>]
+[B<-5>]
+[B<-rand file(s)>]
+[numbits]
+
+=head1 DESCRIPTION
+
+This command is used to generate DH parameter files.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-out filename>
+
+This specifies the output filename parameters to. Standard output is used
+if this option is not present. The output format is a base64 encoded form of
+a PKCS#5 DHParameter structure. 
+
+=item B<-2>, B<-5>
+
+The generator to use, either 2 or 5. 2 is the default.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator. Multiple files can be specified separated by a OS-dependent
+character.  For MS-Windows, the separator is B<;>.  For OpenVMS, it's
+B<,>.  For all others, it's B<:>.
+
+=item B<numbits>
+
+this option specifies that a parameter set should be generated of size
+B<numbits>. It must be the last option. If not present then a value of 512
+is used.
+
+=back
+
+=head1 NOTES
+
+PEM format DH parameters use the header and footer lines:
+
+ -----BEGIN DH PARAMETERS-----
+ -----END DH PARAMETERS-----
+
+DH parameter generation is a slow process and as a result the same set of
+DH parameters is often reused.
+
+OpenSSL currently uses PKCS#3 DH not the more recent X9.42 DH.
+
+This program creates DH parameters only, not DH keys.
+
+=head1 BUGS
+
+The program is badly named. The programs B<gendsa> and B<genrsa> generate
+actual keys and not parameters.
+
+There should be a way to generate and manipulate DH keys.
+
+=head1 SEE ALSO
+
+dsaparam(1)
+
+=cut
diff --git a/doc/apps/gendsa.pod b/doc/apps/gendsa.pod
new file mode 100644
index 0000000000..a23e755fa8
--- /dev/null
+++ b/doc/apps/gendsa.pod
@@ -0,0 +1,56 @@
+=pod
+
+=head1 NAME
+
+gendsa - generate a DSA private key from a set of parameters
+
+=head1 SYNOPSIS
+
+B<openssl> B<gendsa>
+[B<-out filename>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-rand file(s)>]
+[B<paramfile>]
+
+=head1 DESCRIPTION
+
+The B<gendsa> command generates a DSA private key from a DSA parameter file
+(which will be typically generated by the B<openssl dsaparam> command).
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, or the 
+IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
+If none of these options is specified no encryption is used.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator. Multiple files can be specified separated by a OS-dependent
+character.  For MS-Windows, the separator is B<;>.  For OpenVMS, it's
+B<,>.  For all others, it's B<:>.
+
+=item B<paramfile>
+
+This option specifies the DSA parameter file to use. The parameters in this
+file determine the size of the private key. DSA parameters can be generated
+and examined using the B<openssl dsaparam> command.
+
+=back
+
+=head1 NOTES
+
+DSA key generation is little more than random number generation so it is
+much quicker that RSA key generation for example.
+
+=head1 SEE ALSO
+
+dsaparam(1), dsa(1), genrsa(1), rsa(1)
+
+=cut
diff --git a/doc/apps/genrsa.pod b/doc/apps/genrsa.pod
new file mode 100644
index 0000000000..b224bd1fc8
--- /dev/null
+++ b/doc/apps/genrsa.pod
@@ -0,0 +1,72 @@
+=pod
+
+=head1 NAME
+
+genrsa - generate an RSA private key
+
+
+=head1 SYNOPSIS
+
+B<openssl> B<genrsa>
+[B<-out filename>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-f4>]
+[B<-3>]
+[B<-rand file(s)>]
+[B<numbits>]
+
+=head1 DESCRIPTION
+
+The B<genrsa> command generates an RSA private key.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, or the 
+IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
+If none of these options is specified no encryption is used.
+
+=item B<-F4|-3>
+
+the public exponent to use, either 65537 or 3. The default is 65537.
+
+=item B<-rand file(s)>
+
+a file or files containing random data used to seed the random number
+generator. Multiple files can be specified separated by a OS-dependent
+character.  For MS-Windows, the separator is B<;>.  For OpenVMS, it's
+B<,>.  For all others, it's B<:>.
+
+=item B<numbits>
+
+the size of the private key to generate in bits. This must be the last option
+specified. The default is 512.
+
+=back
+
+=head1 NOTES
+
+RSA private key generation essentially involves the generation of two prime
+numbers. When generating a private key various symbols will be output to
+indicate the progress of the generation. A B<.> represents each number tested.
+A B<+> means a number has passed a single primality test. A newline means that
+the number has passed all the prime tests (currently set to 5 single tests).
+
+Because key generation is a random process the time taken to generate a key
+may vary somewhat.
+
+=head1 BUGS
+
+A quirk of the prime generation algorithm is that it cannot generate small
+primes. Therefore the number of bits should not be less that 64. For typical
+private keys this will not matter because for security reasons they will
+be much larger (typically 1024 bits).
+
+=head1 SEE ALSO
+
+gendsa(1)
diff --git a/doc/apps/nseq.pod b/doc/apps/nseq.pod
new file mode 100644
index 0000000000..989c3108fb
--- /dev/null
+++ b/doc/apps/nseq.pod
@@ -0,0 +1,70 @@
+=pod
+
+=head1 NAME
+
+nseq - create or examine a netscape certificate sequence
+
+=head1 SYNOPSIS
+
+B<openssl> B<nseq>
+[B<-in filename>]
+[B<-out filename>]
+[B<-toseq>]
+
+=head1 DESCRIPTION
+
+The B<nseq> command takes a file containing a Netscape certificate
+sequence and prints out the certificates contained in it or takes a
+file of certificates and converts it into a Netscape certificate
+sequence.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-in filename>
+
+This specifies the input filename to read or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename or standard output by default.
+
+=item B<-toseq>
+
+normally a Netscape certificate sequence will be input and the output
+is the certificates contained in it. With the B<-toseq> option the
+situation is reversed: a Netscape certificate sequence is created from
+a file of certificates.
+
+=back
+
+=head1 EXAMPLES
+
+Output the certificates in a Netscape certificate sequence
+
+ openssl nseq -in nseq.pem -out certs.pem
+
+Create a Netscape certificate sequence
+
+ openssl nseq -in certs.pem -toseq -out nseq.pem
+
+=head1 NOTES
+
+The B<PEM> encoded form uses the same headers and footers as a certificate:
+
+ -----BEGIN CERTIFICATE-----
+ -----END CERTIFICATE-----
+
+A Netscape certificate sequence is a Netscape specific form that can be sent
+to browsers as an alternative to the standard PKCS#7 format when several
+certificates are sent to the browser: for example during certificate enrollment.
+It is used by Netscape certificate server for example.
+
+=head1 BUGS
+
+This program needs a few more options: like allowing DER or PEM input and
+output files and allowing multiple certificate files to be used.
+
+=cut
diff --git a/doc/apps/openssl.pod b/doc/apps/openssl.pod
new file mode 100644
index 0000000000..f5ce14ca2f
--- /dev/null
+++ b/doc/apps/openssl.pod
@@ -0,0 +1,240 @@
+
+=pod
+
+=head1 NAME
+
+openssl - OpenSSL command line tool
+
+=head1 SYNOPSIS
+
+B<openssl>
+I<command>
+[ I<command_opts> ]
+[ I<command_args> ]
+
+=head1 DESCRIPTION
+
+OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL
+v2/v3) and Transport Layer Security (TLS v1) network protocols and related
+cryptography standards required by them.
+
+The B<openssl> program is a command line tool for using the various
+cryptography functions of OpenSSL's B<crypto> library from the shell. 
+It can be used for 
+
+ o  Creation of RSA, DH and DSA key parameters
+ o  Creation of X.509 certificates, CSRs and CRLs 
+ o  Calculation of Message Digests
+ o  Encryption and Decryption with Ciphers
+ o  SSL/TLS Client and Server Tests
+
+=head1 COMMAND SUMMARY
+
+The B<openssl> program provides a rich variety of commands (I<command> in the
+SYNOPSIS above), each of which often has a wealth of options and arguments
+(I<command_opts> and I<command_args> in the SYNOPSIS).
+
+=head2 STANDARD COMMANDS
+
+=over 10
+
+=item B<asn1parse> 
+
+Parse an ASN.1 sequence.
+
+=item B<ca>
+
+Certificate Authority (CA) Management.  
+
+=item B<ciphers>
+
+Cipher Suite Description Determination.
+
+=item B<crl>
+
+Certificate Revocation List (CRL) Management.
+
+=item B<crl2pkcs7>      
+
+CRL to PKCS#7 Conversion.
+
+=item B<dgst>
+
+Message Digest Calculation.
+
+=item B<dh>
+
+Diffie-Hellman Data Management.
+
+=item B<dsa>
+
+DSA Data Management.
+
+=item B<dsaparam>
+
+DSA Parameter Generation.
+
+=item B<enc>            
+
+Encoding with Ciphers.
+
+=item B<errstr>
+
+Error Number to Error String Conversion.
+
+=item B<gendh>
+
+Generation of Diffie-Hellman Parameters.
+
+=item B<gendsa>
+
+Generation of DSA Parameters.
+
+=item B<genrsa>
+
+Generation of RSA Parameters.
+
+=item B<pkcs7>
+
+PKCS#7 Data Management.
+
+=item B<req>
+
+X.509 Certificate Signing Request (CSR) Management.
+
+=item B<rsa>
+
+RSA Data Management.
+
+=item B<s_client>
+
+This implements a generic SSL/TLS client which can establish a transparent
+connection to a remote server speaking SSL/TLS. It's intended for testing
+purposes only and provides only rudimentary interface functionality but
+internally uses mostly all functionality of the OpenSSL B<ssl> library.
+
+=item B<s_server>
+
+This implements a generic SSL/TLS server which accepts connections from remote
+clients speaking SSL/TLS. It's intended for testing purposes only and provides
+only rudimentary interface functionality but internally uses mostly all
+functionality of the OpenSSL B<ssl> library.  It provides both an own command
+line oriented protocol for testing SSL functions and a simple HTTP response
+facility to emulate an SSL/TLS-aware webserver.
+
+=item B<s_time>        
+
+SSL Connection Timer.
+
+=item B<sess_id>
+
+SSL Session Data Management.
+
+=item B<speed>
+
+Algorithm Speed Measurement.
+
+=item B<verify>
+
+X.509 Certificate Verification.
+
+=item B<version>
+
+OpenSSL Version Information.
+
+=item B<x509>           
+
+X.509 Certificate Data Management.
+
+=back
+
+=head2 MESSAGE DIGEST COMMANDS
+
+=over 10
+
+=item B<md2>
+
+MD2 Digest
+
+=item B<md5>
+
+MD5 Digest
+
+=item B<mdc2>
+
+MDC2 Digest
+
+=item B<rmd160>
+
+RMD-160 Digest
+
+=item B<sha>            
+
+SHA Digest
+
+=item B<sha1>           
+
+SHA-1 Digest
+
+=back
+
+=head2 ENCODING AND CIPHER COMMANDS
+
+=over 10
+
+=item B<base64>
+
+Base64 Encoding
+
+=item B<bf bf-cbc bf-cfb bf-ecb bf-ofb>
+
+Blowfish Cipher
+
+=item B<cast cast-cbc>
+
+CAST Cipher
+
+=item B<cast5-cbc cast5-cfb cast5-ecb cast5-ofb>
+
+CAST5 Cipher
+
+=item B<des des-cbc des-cfb des-ecb des-ede des-ede-cbc des-ede-cfb des-ede-ofb des-ofb>
+
+DES Cipher
+
+=item B<des3 desx des-ede3 des-ede3-cbc des-ede3-cfb des-ede3-ofb>
+
+Triple-DES Cipher
+
+=item B<idea idea-cbc idea-cfb idea-ecb idea-ofb>
+
+IDEA Cipher
+
+=item B<rc2 rc2-cbc rc2-cfb rc2-ecb rc2-ofb>
+
+RC2 Cipher
+
+=item B<rc4>
+
+RC4 Cipher
+
+=item B<rc5 rc5-cbc rc5-cfb rc5-ecb rc5-ofb>
+
+RC5 Cipher
+
+=back
+
+=head1 SEE ALSO
+
+asn1parse(1), ca(1), config(1), crl(1), crl2pkcs7(1), dgst(1), dh(1),
+dsa(1), dsaparam(1), enc(1), gendh(1), gendsa(1), genrsa(1), nseq(1),
+openssl(1), pkcs12(1), pkcs7(1), pkcs8(1), req(1), rsa(1), s_client(1),
+s_server(1), smime(1), spkac(1), verify(1), version(1), x509(1),
+crypto(3), ssl(3)
+
+=head1 HISTORY
+
+The openssl(1) document appeared in OpenSSL 0.9.2
+
+=cut
+
diff --git a/doc/apps/pkcs12.pod b/doc/apps/pkcs12.pod
new file mode 100644
index 0000000000..14982096c1
--- /dev/null
+++ b/doc/apps/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 filename>]
+[B<-certfile filename>]
+[B<-name name>]
+[B<-caname name>]
+[B<-in filename>]
+[B<-out filename>]
+[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 password>]
+[B<-envpass var>]
+
+=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
+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)
+
diff --git a/doc/apps/pkcs7.pod b/doc/apps/pkcs7.pod
new file mode 100644
index 0000000000..0514c5d667
--- /dev/null
+++ b/doc/apps/pkcs7.pod
@@ -0,0 +1,85 @@
+=pod
+
+=head1 NAME
+
+pkcs7 - PKCS#7 utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs7>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-print_certs>]
+[B<-text>]
+[B<-noout>]
+
+=head1 DESCRIPTION
+
+The B<pkcs7> command processes PKCS#7 files in DER or PEM format.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. B<DER> format is DER encoded PKCS#7
+v1.5 structure.B<PEM> (the default) is a base64 encoded version of
+the DER form with header and footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-print_certs>
+
+prints out any certificates or CRLs contained in the file. They are
+preceded by their subject and issuer names in one line format.
+
+=item B<-text>
+
+prints out certificates details in full rather than just subject and
+issuer names.
+
+=item B<-noout>
+
+don't output the encoded version of the PKCS#7 structure (or certificates
+is B<-print_certs> is set).
+
+=back
+
+=head1 EXAMPLES
+
+Convert a PKCS#7 file from PEM to DER:
+
+ openssl pkcs7 -in file.pem -outform DER -out file.der
+
+Output all certificates in a file:
+
+ openssl pkcs7 -in file.pem -print_certs -out certs.pem
+
+=head1 RESTRICTIONS
+
+There is no option to print out all the fields of a PKCS#7 file.
+
+This PKCS#7 routines only understand PKCS#7 v 1.5 as specified in RFC2315 they 
+cannot currently parse, for example, the new CMS as described in RFC2630.
+
+=head1 SEE ALSO
+
+crl2pkcs7(1)
+
+=cut
diff --git a/doc/apps/pkcs8.pod b/doc/apps/pkcs8.pod
new file mode 100644
index 0000000000..171b58b4b8
--- /dev/null
+++ b/doc/apps/pkcs8.pod
@@ -0,0 +1,224 @@
+=pod
+
+=head1 NAME
+
+pkcs8 - PKCS#8 format private key conversion tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<pkcs8>
+[B<-topk8>]
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin password>]
+[B<-envpassin var>]
+[B<-out filename>]
+[B<-passout password>]
+[B<-envpassout var>]
+[B<-noiter>]
+[B<-nocrypt>]
+[B<-nooct>]
+[B<-v2 alg>]
+[B<-v1 alg>]
+
+=head1 DESCRIPTION
+
+The B<pkcs8> command processes private keys in PKCS#8 format. It can handle
+both unencrypted PKCS#8 PrivateKeyInfo format and EncryptedPrivateKeyInfo
+format with a variety of PKCS#5 (v1.5 and v2.0) and PKCS#12 algorithms.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-topk8>
+
+Normally a PKCS#8 private key is expected on input and a traditional format
+private key will be written. With the B<-topk8> option the situation is
+reversed: it reads a traditional format private key and writes a PKCS#8
+format key.
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. If a PKCS#8 format key is expected on input
+then either a B<DER> or B<PEM> encoded version of a PKCS#8 key will be
+expected. Otherwise the B<DER> or B<PEM> format of the traditional format
+private key is used.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin password>
+
+the input file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassin var>
+
+read the input file password from the environment variable B<var>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+default. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout password>
+
+the output file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassout var>
+
+read the output file password from the environment variable B<var>.
+
+=item B<-nocrypt>
+
+PKCS#8 keys generated or input are normally PKCS#8 EncryptedPrivateKeyInfo
+structures using an appropriate password based encryption algorithm. With
+this option an unencrypted PrivateKeyInfo structure is expected or output.
+This option does not encrypt private keys at all and should only be used
+when absolutely necessary. Certain software such as some versions of Java
+code signing software used unencrypted private keys.
+
+=item B<-nooct>
+
+This option generates private keys in a broken format that some software
+uses. Specifically the private key should be enclosed in a OCTET STRING
+but some software just includes the structure itself without the
+surrounding OCTET STRING.
+
+=item B<-v2 alg>
+
+This option enables the use of PKCS#5 v2.0 algorithms. Normally PKCS#8
+private keys are encrypted with the password based encryption algorithm
+called B<pbeWithMD5AndDES-CBC> this uses 56 bit DES encryption but it
+was the strongest encryption algorithm supported in PKCS#5 v1.5. Using 
+the B<-v2> option PKCS#5 v2.0 algorithms are used which can use any
+encryption algorithm such as 168 bit triple DES or 128 bit RC2 however
+not many implementations support PKCS#5 v2.0 yet. If you are just using
+private keys with OpenSSL then this doesn't matter.
+
+The B<alg> argument is the encryption algorithm to use, valid values include
+B<des>, B<des3> and B<rc2>. It is recommended that B<des3> is used.
+
+=item B<-v1 alg>
+
+This option specifies a PKCS#5 v1.5 or PKCS#12 algorithm to use. A complete
+list of possible algorithms is included below.
+
+=back
+
+=head1 NOTES
+
+The encrypted form of a PEM encode PKCS#8 files uses the following
+headers and footers:
+
+ -----BEGIN ENCRYPTED PRIVATE KEY-----
+ -----END ENCRYPTED PRIVATE KEY-----
+
+The unencrypted form uses:
+
+ -----BEGIN PRIVATE KEY-----
+ -----END PRIVATE KEY-----
+
+Private keys encrypted using PKCS#5 v2.0 algorithms and high iteration
+counts are more secure that those encrypted using the traditional
+SSLeay compatible formats. So if additional security is considered
+important the keys should be converted.
+
+The default encryption is only 56 bits because this is the encryption
+that most current implementations of PKCS#8 will support.
+
+Some software may use PKCS#12 password based encryption algorithms
+with PKCS#8 format private keys: these are handled automatically
+but there is no option to produce them.
+
+It is possible to write out DER encoded encrypted private keys in
+PKCS#8 format because the encryption details are included at an ASN1
+level whereas the traditional format includes them at a PEM level.
+
+=head1 PKCS#5 v1.5 and PKCS#12 algorithms.
+
+Various algorithms can be used with the B<-v1> command line option,
+including PKCS#5 v1.5 and PKCS#12. These are described in more detail
+below.
+
+=over 4
+
+=item B<PBE-MD2-DES PBE-MD5-DES>
+
+These algorithms were included in the original PKCS#5 v1.5 specification.
+They only offer 56 bits of protection since they both use DES.
+
+=item B<PBE-SHA1-RC2-64 PBE-MD2-RC2-64 PBE-MD5-RC2-64 PBE-SHA1-DES>
+
+These algorithms are not mentioned in the original PKCS#5 v1.5 specification
+but they use the same key derivation algorithm and are supported by some
+software. They are mentioned in PKCS#5 v2.0. They use either 64 bit RC2 or
+56 bit DES.
+
+=item B<PBE-SHA1-RC4-128 PBE-SHA1-RC4-40 PBE-SHA1-3DES PBE-SHA1-2DES PBE-SHA1-RC2-128 PBE-SHA1-RC2-40>
+
+These algorithms use the PKCS#12 password based encryption algorithm and
+allow strong encryption algorithms like triple DES or 128 bit RC2 to be used.
+
+=back
+
+=head1 EXAMPLES
+
+Convert a private from traditional to PKCS#5 v2.0 format using triple
+DES:
+
+ openssl pkcs8 -in key.pem -topk8 -v2 des3 -out enckey.pem
+
+Convert a private key to PKCS#8 using a PKCS#5 1.5 compatible algorithm
+(DES):
+
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem
+
+Convert a private key to PKCS#8 using a PKCS#12 compatible algorithm
+(3DES):
+
+ openssl pkcs8 -in key.pem -topk8 -out enckey.pem -v1 PBE-SHA1-3DES
+
+Read a DER unencrypted PKCS#8 format private key:
+
+ openssl pkcs8 -inform DER -nocrypt -in key.der -out key.pem
+
+Convert a private key from any PKCS#8 format to traditional format:
+
+ openssl pkcs8 -in pk8.pem -out key.pem
+
+=head1 STANDARDS
+
+Test vectors from this implementation were posted to the pkcs-tng mailing
+list using triple DES, DES and RC2 with high iteration counts, several
+people confirmed that they could decrypt the private keys produced and
+Therefore it can be assumed that the PKCS#5 v2.0 implementation is
+reasonably accurate at least as far as these algorithms are concerned.
+
+=head1 BUGS
+
+There should be an option that prints out the encryption algorithm
+in use and other details such as the iteration count.
+
+PKCS#8 using triple DES and PKCS#5 v2.0 should be the default private
+key format for OpenSSL: for compatibility several of the utilities use
+the old format at present.
+
+=head1 SEE ALSO
+
+dsa(1), rsa(1), genrsa(1), gendsa(1)
+
+=cut
diff --git a/doc/apps/req.pod b/doc/apps/req.pod
new file mode 100644
index 0000000000..e836f187ac
--- /dev/null
+++ b/doc/apps/req.pod
@@ -0,0 +1,530 @@
+
+=pod
+
+=head1 NAME
+
+req - PKCS#10 certificate and certificate generating utility.
+
+=head1 SYNOPSIS
+
+B<openssl> B<req>
+[B<-inform PEM|DER>]
+[B<-outform PEM|DER>]
+[B<-in filename>]
+[B<-passin password>]
+[B<-envpassin var>]
+[B<-out filename>]
+[B<-passout password>]
+[B<-envpassout var>]
+[B<-text>]
+[B<-noout>]
+[B<-verify>]
+[B<-modulus>]
+[B<-new>]
+[B<-newkey rsa:bits>]
+[B<-newkey dsa:file>]
+[B<-nodes>]
+[B<-key filename>]
+[B<-keyform PEM|DER>]
+[B<-keyout filename>]
+[B<-[md5|sha1|md2|mdc2]>]
+[B<-config filename>]
+[B<-x509>]
+[B<-days n>]
+[B<-noasn1-kludge>]
+[B<-extensions section>]
+[B<-reqexts section>]
+
+=head1 DESCRIPTION
+
+The B<req> command primarily creates and processes certificate requests
+in PKCS#10 format. It can additionally create self signed certificates
+for use as root CAs for example.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#10. The B<PEM> form is the default format: it
+consists of the B<DER> format base64 encoded with additional header and
+footer lines.
+
+=item B<-outform DER|PEM>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a request from or standard input
+if this option is not specified. A request is only read if the creation
+options (B<-new> and B<-newkey>) are not specified.
+
+=item B<-passin password>
+
+the input file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassin var>
+
+read the input file password from the environment variable B<var>.
+
+=item B<-out filename>
+
+This specifies the output filename to write to or standard output by
+default.
+
+=item B<-passout password>
+
+the output file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassout var>
+
+read the output file password from the environment variable B<var>.
+
+=item B<-text>
+
+prints out the certificate request in text form.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the request.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the public key
+contained in the request.
+
+=item B<-verify>
+
+verifies the signature on the request.
+
+=item B<-new>
+
+this option generates a new certificate request. It will prompt
+the user for the relevant field values. The actual fields
+prompted for and their maximum and minimum sizes are specified
+in the configuration file and any requested extensions.
+
+If the B<-key> option is not used it will generate a new RSA private
+key using information specified in the configuration file.
+
+=item B<-newkey arg>
+
+this option creates a new certificate request and a new private
+key. The argument takes one of two forms. B<rsa:nbits>, where
+B<nbits> is the number of bits, generates an RSA key B<nbits>
+in size. B<dsa:filename> generates a DSA key using the parameters
+in the file B<filename>.
+
+=item B<-key filename>
+
+This specifies the file to read the private key from. It also
+accepts PKCS#8 format private keys for PEM format files.
+
+=item B<-keyform PEM|DER>
+
+the format of the private key file specified in the B<-key>
+argument. PEM is the default.
+
+=item B<-keyout filename>
+
+this gives the filename to write the newly created private key to.
+If this option is not specified then the filename present in the
+configuration file is used.
+
+=item B<-nodes>
+
+if this option is specified then if a private key is created it
+will not be encrypted.
+
+=item B<-[md5|sha1|md2|mdc2]>
+
+this specifies the message digest to sign the request with. This
+overrides the digest algorithm specified in the configuration file.
+This option is ignored for DSA requests: they always use SHA1.
+
+=item B<-config filename>
+
+this allows an alternative configuration file to be specified,
+this overrides the compile time filename or any specified in
+the B<OPENSSL_CONF> environment variable.
+
+=item B<-x509>
+
+this option outputs a self signed certificate instead of a certificate
+request. This is typically used to generate a test certificate or
+a self signed root CA. The extensions added to the certificate
+(if any) are specified in the configuration file.
+
+=item B<-days n>
+
+when the B<-x509> option is being used this specifies the number of
+days to certify the certificate for. The default is 30 days.
+
+=item B<-extensions section>
+=item B<-reqexts section>
+
+these options specify alternative sections to include certificate
+extensions (if the B<-x509> option is present) or certificate
+request extensions. This allows several different sections to
+be used in the same configuration file to specify requests for
+a variety of purposes.
+
+=item B<-asn1-kludge>
+
+by default the B<req> command outputs certificate requests containing
+no attributes in the correct PKCS#10 format. However certain CAs will only
+accept requests containing no attributes in an invalid form: this
+option produces this invalid format.
+
+More precisely the B<Attributes> in a PKCS#10 certificate request
+are defined as a B<SET OF Attribute>. They are B<not OPTIONAL> so
+if no attributes are present then they should be encoded as an
+empty B<SET OF>. The invalid form does not include the empty
+B<SET OF> whereas the correct form does.
+
+It should be noted that very few CAs still require the use of this option.
+
+=back
+
+=head1 CONFIGURATION FILE FORMAT
+
+The configuration options are specified in the B<req> section of
+the configuration file. As with all configuration files if no
+value is specified in the specific section (i.e. B<req>) then
+the initial unnamed or B<default> section is searched too.
+
+The options available are described in detail below.
+
+=over 4
+
+=item B<input_password output_password>
+
+The passwords for the input private key file (if present) and
+the output private key file (if one will be created). The
+command line options B<passin>, B<envpassin>, B<passout> and
+B<envpassout> override the configuration file values.
+
+=item B<default_bits>
+
+This specifies the default key size in bits. If not specified then
+512 is used. It is used if the B<-new> option is used. It can be
+overridden by using the B<-newkey> option.
+
+=item B<default_keyfile>
+
+This is the default filename to write a private key to. If not
+specified the key is written to standard output. This can be
+overridden by the B<-keyout> option.
+
+=item B<oid_file>
+
+This specifies a file containing additional B<OBJECT IDENTIFIERS>.
+Each line of the file should consist of the numerical form of the
+object identifier followed by white space then the short name followed
+by white space and finally the long name. 
+
+=item B<oid_section>
+
+This specifies a section in the configuration file containing extra
+object identifiers. Each line should consist of the short name of the
+object identifier followed by B<=> and the numerical form. The short
+and long names are the same when this option is used.
+
+=item B<RANDFILE>
+
+This specifies a filename in which random number seed information is
+placed and read from. It is used for private key generation.
+
+=item B<encrypt_key>
+
+If this is set to B<no> then if a private key is generated it is
+B<not> encrypted. This is equivalent to the B<-nodes> command line
+option. For compatibility B<encrypt_rsa_key> is an equivalent option.
+
+=item B<default_md>
+
+This option specifies the digest algorithm to use. Possible values
+include B<md5 sha1 mdc2>. If not present then MD5 is used. This
+option can be overridden on the command line.
+
+=item B<string_mask>
+
+This option masks out the use of certain string types in certain
+fields. Most users will not need to change this option.
+
+It can be set to several values B<default> which is also the default
+option uses PrintableStrings, T61Strings and BMPStrings if the 
+B<pkix> value is used then only PrintableStrings and BMPStrings will
+be used. This follows the PKIX recommendation in RFC2459. If the
+B<utf8only> option is used then only UTF8Strings will be used: this
+is the PKIX recommendation in RFC2459 after 2003. Finally the B<nombstr>
+option just uses PrintableStrings and T61Strings: certain software has
+problems with BMPStrings and UTF8Strings: in particular Netscape.
+
+=item B<req_extensions>
+
+this specifies the configuration file section containing a list of
+extensions to add to the certificate request. It can be overridden
+by the B<-reqexts> command line switch.
+
+=item B<x509_extensions>
+
+this specifies the configuration file section containing a list of
+extensions to add to certificate generated when the B<-x509> switch
+is used. It can be overridden by the B<-extensions> command line switch.
+
+=item B<prompt>
+
+if set to the value B<no> this disables prompting of certificate fields
+and just takes values from the config file directly. It also changes the
+expected format of the B<distinguished_name> and B<attributes> sections.
+
+=item B<attributes>
+
+this specifies the section containing any request attributes: its format
+is the same as B<distinguished_name>. Typically these may contain the
+challengePassword or unstructuredName types. They are currently ignored
+by OpenSSL's request signing utilities but some CAs might want them.
+
+=item B<distinguished_name>
+
+This specifies the section containing the distinguished name fields to
+prompt for when generating a certificate or certificate request. The format
+is described in the next section.
+
+=back
+
+=head1 DISTINGUISHED NAME AND ATTRIBUTE SECTION FORMAT
+
+There are two separate formats for the distinguished name and attribute
+sections. If the B<prompt> option is set to B<no> then these sections
+just consist of field names and values: for example,
+
+ CN=My Name
+ OU=My Organization
+ emailAddress=someone@somehere.org
+
+This allows external programs (e.g. GUI based) to generate a template file
+with all the field names and values and just pass it to B<req>. An example
+of this kind of configuration files is contained in the B<EXAMPLES> section.
+
+Alternatively if the B<prompt> option is absent or not set to B<no> the the
+file contains field prompting information. It consists of lines of the form:
+
+ fieldName="prompt"
+ fieldName_default="default field value"
+ fieldName_min= 2
+ fieldName_max= 4
+
+"fieldName" is the field name being used, for example commonName (or CN).
+The "prompt" string is used to ask the user to enter the relevant
+details. If the user enters nothing then the default value is used if no
+default value is present then the field is omitted. A field can
+still be omitted if a default value is present if the user just
+enters the '.' character.
+
+The number of characters entered must be between the fieldName_min and
+fieldName_max limits: there may be additional restrictions based
+on the field being used (for example countryName can only ever be
+two characters long and must fit in a PrintableString).
+
+Some fields (such as organizationName) can be used more than once
+in a DN. This presents a problem because configuration files will
+not recognize the same name occurring twice. To avoid this problem
+if the fieldName contains an some characters followed by a full stop
+they will be ignored. So for example a second organizationName can
+be input by calling it "1.organizationName".
+
+The actual permitted field names are any object identifier short or
+long names. These are compiled into OpenSSL and include the usual
+values such as commonName, countryName, localityName, organizationName,
+organizationUnitName, stateOrPrivinceName. Additionally emailAddress
+is include as well as name, surname, givenName initials and dnQualifier
+are supported.
+
+Additional object identifiers can be defined with the B<oid_file> or
+B<oid_section> options in the configuration file. Any additional fields
+will be treated as though they were a DirectoryString.
+
+
+=head1 EXAMPLES
+
+Examine and verify certificate request:
+
+ openssl req -in req.pem -text -verify -noout
+
+Create a private key and then generate a certificate request from it:
+
+ openssl genrsa -out key.pem 1024
+ openssl req -new -key key.pem -out req.pem
+
+The same but just using req:
+
+ openssl req -newkey rsa:1024 -keyout key.pem -out req.pem
+
+Generate a self signed root certificate:
+
+ openssl req -x509 -newkey rsa:1024 -keyout key.pem -out req.pem
+
+Example of a file pointed to by the B<oid_file> option:
+
+ 1.2.3.4	shortName	A longer Name
+ 1.2.3.6	otherName	Other longer Name
+
+Example of a section pointed to by B<oid_section> making use of variable
+expansion:
+
+ testoid1=1.2.3.5
+ testoid2=${testoid1}.6
+
+Sample configuration file prompting for field values:
+
+ [ req ]
+ default_bits		= 1024
+ default_keyfile 	= privkey.pem
+ distinguished_name	= req_distinguished_name
+ attributes		= req_attributes
+ x509_extensions	= v3_ca
+
+ dirstring_type = nobmp
+
+ [ req_distinguished_name ]
+ countryName			= Country Name (2 letter code)
+ countryName_default		= AU
+ countryName_min		= 2
+ countryName_max		= 2
+
+ localityName			= Locality Name (eg, city)
+
+ organizationalUnitName		= Organizational Unit Name (eg, section)
+
+ commonName			= Common Name (eg, YOUR name)
+ commonName_max			= 64
+
+ emailAddress			= Email Address
+ emailAddress_max		= 40
+
+ [ req_attributes ]
+ challengePassword		= A challenge password
+ challengePassword_min		= 4
+ challengePassword_max		= 20
+
+ [ v3_ca ]
+
+ subjectKeyIdentifier=hash
+ authorityKeyIdentifier=keyid:always,issuer:always
+ basicConstraints = CA:true
+
+Sample configuration containing all field values:
+
+
+ RANDFILE		= $ENV::HOME/.rnd
+
+ [ req ]
+ default_bits		= 1024
+ default_keyfile 	= keyfile.pem
+ distinguished_name	= req_distinguished_name
+ attributes		= req_attributes
+ prompt			= no
+ output_password	= mypass
+
+ [ req_distinguished_name ]
+ C			= GB
+ ST			= Test State or Province
+ L			= Test Locality
+ O			= Organization Name
+ OU			= Organizational Unit Name
+ CN			= Common Name
+ emailAddress		= test@email.address
+
+ [ req_attributes ]
+ challengePassword		= A challenge password
+
+
+=head1 NOTES
+
+The header and footer lines in the B<PEM> format are respectively:
+
+ -----BEGIN CERTIFICATE REQUEST----
+ -----END CERTIFICATE REQUEST----
+
+some software (some versions of Netscape certificate server) instead needs:
+
+ -----BEGIN NEW CERTIFICATE REQUEST----
+ -----END NEW CERTIFICATE REQUEST----
+
+but is otherwise compatible. Either form is accepted on input.
+
+The certificate requests generated by B<Xenroll> with MSIE have extensions
+added. It includes the B<keyUsage> extension which determines the type of
+key (signature only or general purpose) and any additional OIDs entered
+by the script in an extendedKeyUsage extension.
+
+=head1 DIAGNOSTICS
+
+The following messages are frequently asked about:
+
+	Using configuration from /some/path/openssl.cnf
+	Unable to load config info
+
+This is followed some time later by...
+
+	unable to find 'distinguished_name' in config
+	problems making Certificate Request
+
+The first error message is the clue: it can't find the configuration
+file! Certain operations (like examining a certificate request) don't
+need a configuration file so its use isn't enforced. Generation of
+certificates or requests however does need a configuration file. This
+could be regarded as a bug.
+
+Another puzzling message is this:
+
+        Attributes:
+            a0:00
+
+this is displayed when no attributes are present and the request includes
+the correct empty B<SET OF> structure (the DER encoding of which is 0xa0
+0x00). If you just see:
+
+        Attributes:
+
+then the B<SET OF> is missing and the encoding is technically invalid (but
+it is tolerated). See the description of the command line option B<-asn1-kludge>
+for more information.
+
+=head1 ENVIRONMENT VARIABLES
+
+The variable B<OPENSSL_CONF> if defined allows an alternative configuration
+file location to be specified, it will be overridden by the B<-config> command
+line switch if it is present. For compatibility reasons the B<SSLEAY_CONF>
+environment variable serves the same purpose but its use is discouraged.
+
+=head1 BUGS
+
+OpenSSL's handling of T61Strings (aka TeletexStrings) is broken: it effectively
+treats them as ISO-8859-1 (Latin 1), Netscape and MSIE have similar behaviour.
+This can cause problems if you need characters that aren't available in
+PrintableStrings and you don't want to or can't use BMPStrings.
+
+As a consequence of the T61String handling the only correct way to represent
+accented characters in OpenSSL is to use a BMPString: unfortunately Netscape
+currently chokes on these. If you have to use accented characters with Netscape
+and MSIE then you currently need to use the invalid T61String form.
+
+The current prompting is not very friendly. It doesn't allow you to confirm what
+you've just entered. Other things like extensions in certificate requests are
+statically defined in the configuration file. Some of these: like an email
+address in subjectAltName should be input by the user.
+
+=head1 SEE ALSO
+
+x509(1), ca(1), genrsa(1), gendsa(1), config(5)
+
+=cut
diff --git a/doc/apps/rsa.pod b/doc/apps/rsa.pod
new file mode 100644
index 0000000000..05c64eb470
--- /dev/null
+++ b/doc/apps/rsa.pod
@@ -0,0 +1,160 @@
+
+=pod
+
+=head1 NAME
+
+rsa - RSA key processing tool
+
+=head1 SYNOPSIS
+
+B<openssl> B<rsa>
+[B<-inform PEM|NET|DER>]
+[B<-outform PEM|NET|DER>]
+[B<-in filename>]
+[B<-passin password>]
+[B<-envpassin var>]
+[B<-out filename>]
+[B<-passout password>]
+[B<-envpassout var>]
+[B<-des>]
+[B<-des3>]
+[B<-idea>]
+[B<-text>]
+[B<-noout>]
+[B<-modulus>]
+[B<-check>]
+[B<-pubin>]
+[B<-pubout>]
+
+=head1 DESCRIPTION
+
+The B<rsa> command processes RSA keys. They can be converted between various
+forms and their components printed out. B<Note> this command uses the
+traditional SSLeay compatible format for private key encryption: newer
+applications should use the more secure PKCS#8 format using the B<pkcs8>
+utility.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-inform DER|NET|PEM>
+
+This specifies the input format. The B<DER> option uses an ASN1 DER encoded
+form compatible with the PKCS#1 RSAPrivateKey or SubjectPublicKeyInfo format.
+The B<PEM> form is the default format: it consists of the B<DER> format base64
+encoded with additional header and footer lines. On input PKCS#8 format private
+keys are also accepted. The B<NET> form is a format compatible with older Netscape
+servers and MS IIS, this uses unsalted RC4 for its encryption. It is not very
+secure and so should only be used when necessary.
+
+=item B<-outform DER|NET|PEM>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a key from or standard input if this
+option is not specified. If the key is encrypted a pass phrase will be
+prompted for.
+
+=item B<-passin password>
+
+the input file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassin var>
+
+read the input file password from the environment variable B<var>.
+
+=item B<-out filename>
+
+This specifies the output filename to write a key to or standard output by
+is not specified. If any encryption options are set then a pass phrase will be
+prompted for. The output filename should B<not> be the same as the input
+filename.
+
+=item B<-passout password>
+
+the output file password. Since certain utilities like "ps" make the command line
+visible this option should be used with caution.
+
+=item B<-envpassout var>
+
+read the output file password from the environment variable B<var>.
+
+=item B<-des|-des3|-idea>
+
+These options encrypt the private key with the DES, triple DES, or the 
+IDEA ciphers respectively before outputting it. A pass phrase is prompted for.
+If none of these options is specified the key is written in plain text. This
+means that using the B<rsa> utility to read in an encrypted key with no
+encryption option can be used to remove the pass phrase from a key, or by
+setting the encryption options it can be use to add or change the pass phrase.
+These options can only be used with PEM format output files.
+
+=item B<-text>
+
+prints out the various public or private key components in
+plain text in addition to the encoded version. 
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the key.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the key.
+
+=item B<-check>
+
+this option checks the consistency of an RSA private key.
+
+=item B<-pubin>
+
+by default a private key is input file with this option a public key is input
+instead.
+
+=item B<-pubout>
+
+by default a private key is output with this option a public
+key will be output instead. This option is automatically set if the input is
+a public key.
+
+=back
+
+=head1 NOTES
+
+The PEM private key format uses the header and footer lines:
+
+ -----BEGIN RSA PRIVATE KEY-----
+ -----END RSA PRIVATE KEY-----
+
+=head1 EXAMPLES
+
+To remove the pass phrase on an RSA private key:
+
+C<openssl rsa -in key.pem -out keyout.pem>
+
+To encrypt a private key using triple DES:
+
+C<openssl rsa -in key.pem -des3 -out keyout.pem>
+
+To convert a private key from PEM to DER format: 
+
+C<openssl rsa -in key.pem -outform DER -out keyout.der>
+
+To print out the components of a private key to standard output:
+
+C<openssl rsa -in key.pem -text -noout>
+
+To just output the public part of a private key:
+
+C<openssl rsa -in key.pem -pubout -out pubkey.pem>
+
+=head1 SEE ALSO
+
+pkcs8(1), dsa(1), genrsa(1), gendsa(1)
+
+=cut
diff --git a/doc/apps/s_client.pod b/doc/apps/s_client.pod
new file mode 100644
index 0000000000..cd9093eaba
--- /dev/null
+++ b/doc/apps/s_client.pod
@@ -0,0 +1,211 @@
+
+=pod
+
+=head1 NAME
+
+s_client - SSL/TLS client program
+
+=head1 SYNOPSIS
+
+B<openssl> B<s_client>
+[B<-connect> host:port>]
+[B<-verify depth>]
+[B<-cert filename>]
+[B<-key filename>]
+[B<-CApath directory>]
+[B<-CAfile filename>]
+[B<-reconnect>]
+[B<-pause>]
+[B<-showcerts>]
+[B<-debug>]
+[B<-nbio_test>]
+[B<-state>]
+[B<-nbio>]
+[B<-crlf>]
+[B<-quiet>]
+[B<-ssl2>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<-no_ssl2>]
+[B<-no_ssl3>]
+[B<-no_tls1>]
+[B<-bugs>]
+[B<-cipher cipherlist>]
+
+=head1 DESCRIPTION
+
+The B<s_client> command implements a generic SSL/TLS client which connects
+to a remote host using SSL/TLS. It is a I<very> useful diagnostic tool for
+SSL servers.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-connect host:port>
+
+This specifies the host and optional port to connect to. If not specified
+then an attempt is made to connect to the local host on port 4433.
+
+=item B<-cert certname>
+
+The certificate to use, if one is requested by the server. The default is
+not to use a certificate.
+
+=item B<-key keyfile>
+
+The private key to use. If not specified then the certificate file will
+be used.
+
+=item B<-verify depth>
+
+The verify depth to use. This specifies the maximum length of the
+server certificate chain and turns on server certificate verification.
+Currently the verify operation continues after errors so all the problems
+with a certificate chain can be seen. As a side effect the connection
+will never fail due to a server certificate verify failure.
+
+=item B<-CApath directory>
+
+The directory to use for server certificate verification. This directory
+must be in "hash format", see B<verify> for more information. These are
+also used when building the client certificate chain.
+
+=item B<-CAfile file>
+
+A file containing trusted certificates to use during server authentication
+and to use when attempting to build the client certificate chain.
+
+=item B<-reconnect>
+
+reconnects to the same server 5 times using the same session ID, this can
+be used as a test that session caching is working.
+
+=item B<-pause>
+
+pauses 1 second between each read and write call.
+
+=item B<-showcerts>
+
+display the whole server certificate chain: normally only the server
+certificate itself is displayed.
+
+=item B<-prexit>
+
+print session information when the program exits. This will always attempt
+to print out information even if the connection fails. Normally information
+will only be printed out once if the connection succeeds. This option is useful
+because the cipher in use may be renegotiated or the connection may fail
+because a client certificate is required or is requested only after an
+attempt is made to access a certain URL. Note: the output produced by this
+option is not always accurate because a connection might never have been
+established.
+
+=item B<-state>
+
+prints out the SSL session states.
+
+=item B<-debug>
+
+print extensive debugging information including a hex dump of all traffic.
+
+=item B<-nbio_test>
+
+tests non blocking I/O
+
+=item B<-nbio>
+
+turns on non blocking I/O
+
+=item B<-crlf>
+
+this option translated a line feed from the terminal into CR+LF as required
+by some servers.
+
+=item B<-quiet>
+
+inhibit printing of session and certificate information.
+
+=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>
+
+these options disable the use of certain SSL or TLS protocols. By default
+the initial handshake uses a method which should be compatible with all
+servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
+
+Unfortunately there are a lot of ancient and broken servers in use which
+cannot handle this technique and will fail to connect. Some servers only
+work if TLS is turned off with the B<-no_tls> option others will only
+support SSL v2 and may need the B<-ssl2> option.
+
+=item B<-bugs>
+
+there are several known bug in SSL and TLS implementations. Adding this
+option enables various workarounds.
+
+=item B<-cipher cipherlist>
+
+this allows the cipher list sent by the client to be modified. See the
+B<ciphers> command for more information.
+
+=back
+
+=head1 CONNECTED COMMANDS
+
+If a connection is established with an SSL server then any data received
+from the server is displayed and any key presses will be sent to the
+server. If the line begins with an B<R> then the session will be
+renegotiated. If the line begins with a B<Q> the connection will be closed
+down.
+
+=head1 NOTES
+
+B<s_client> can be used to debug SSL servers. To connect to an SSL HTTP
+server the command:
+
+ openssl s_client -connect servername:443
+
+would typically be used (https uses port 443). If the connection succeeds
+then an HTTP command can be given such as "GET /" to retrieve a web page.
+
+If the handshake fails then there are several possible causes, if it is
+nothing obvious like no client certificate then the B<-bugs>, B<-ssl2>,
+B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1> can be tried
+in case it is a buggy server. In particular you should play with these
+options B<before> submitting a bug report to an OpenSSL mailing list.
+
+A frequent problem when attempting to get client certificates working
+is that a web client complains it has no certificates or gives an empty
+list to choose from. This is normally because the server is not sending
+the clients certificate authority in its "acceptable CA list" when it
+requests a certificate. By using B<s_client> the CA list can be viewed
+and checked. However some servers only request client authentication
+after a specific URL is requested. To obtain the list in this case it
+is necessary to use the B<-prexit> command and send an HTTP request
+for an appropriate page.
+
+If a certificate is specified on the command line using the B<-cert>
+option it will not be used unless the server specifically requests
+a client certificate. Therefor merely including a client certificate
+on the command line is no guarantee that the certificate works.
+
+If there are problems verifying a server certificate then the
+B<-showcerts> option can be used to show the whole chain.
+
+=head1 BUGS
+
+Because this program has a lot of options and also because some of
+the techniques used are rather old, the C source of s_client is rather
+hard to read and not a model of how things should be done. A typical
+SSL client program would be much simpler.
+
+The B<-verify> option should really exit if the server verification
+fails.
+
+The B<-prexit> option is a bit of a hack. We should really report
+information whenever a session is renegotiated.
+
+=head1 SEE ALSO
+
+sess_id(1), s_server(1), ciphers(1)
+
+=cut
diff --git a/doc/apps/s_server.pod b/doc/apps/s_server.pod
new file mode 100644
index 0000000000..5b6a20221d
--- /dev/null
+++ b/doc/apps/s_server.pod
@@ -0,0 +1,262 @@
+
+=pod
+
+=head1 NAME
+
+s_server - SSL/TLS server program
+
+=head1 SYNOPSIS
+
+B<openssl> B<s_client>
+[B<-accept port>]
+[B<-context id>]
+[B<-verify depth>]
+[B<-Verify depth>]
+[B<-cert filename>]
+[B<-key keyfile>]
+[B<-dcert filename>]
+[B<-dkey keyfile>]
+[B<-dhparam filename>]
+[B<-nbio>]
+[B<-nbio_test>]
+[B<-crlf>]
+[B<-debug>]
+[B<-state>]
+[B<-CApath directory>]
+[B<-CAfile filename>]
+[B<-nocert>]
+[B<-cipher cipherlist>]
+[B<-quiet>]
+[B<-no_tmp_rsa>]
+[B<-ssl2>]
+[B<-ssl3>]
+[B<-tls1>]
+[B<-no_ssl2>]
+[B<-no_ssl3>]
+[B<-no_tls1>]
+[B<-no_dhe>]
+[B<-bugs>]
+[B<-hack>]
+[B<-www>]
+[B<-WWW>]
+
+=head1 DESCRIPTION
+
+The B<s_server> command implements a generic SSL/TLS server which listens
+for connections on a given port using SSL/TLS.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-accept port>
+
+the TCP port to listen on for connections. If not specified 4433 is used.
+
+=item B<-context id>
+
+sets the SSL context id. If a client certificate is being requested then
+this option must be set. It can be given any string value.
+
+=item B<-cert certname>
+
+The certificate to use, most servers cipher suites require the use of a
+certificate and some require a certificate with a certain public key type:
+for example the DSS cipher suites require a certificate containing a DSS
+(DSA) key. If not specified then the filename "server.pem" will be used.
+
+=item B<-key keyfile>
+
+The private key to use. If not specified then the certificate file will
+be used.
+
+=item B<-dcert filename>, B<-dkey keyname>
+
+specify an additional certificate and private key, these behave in the
+same manner as the B<-cert> and B<-key> options except there is no default
+if they are not specified (no additional certificate and key is used). As
+noted above some cipher suites require a certificate containing a key of
+a certain type. Some cipher suites need a certificate carrying an RSA key
+and some a DSS (DSA) key. By using RSA and DSS certificates and keys
+a server can support clients which only support RSA or DSS cipher suites
+by using an appropriate certificate.
+
+=item B<-nocert>
+
+if this option is set then no certificate is used. This restricts the
+cipher suites available to the anonymous ones (currently just anonymous
+DH).
+
+=item B<-dhparam filename>
+
+the DH parameter file to use. The ephemeral DH cipher suites generate keys
+using a set of DH parameters. If not specified then an attempt is made to
+load the parameters from the server certificate file. If this fails then
+a static set of parameters hard coded into the s_server program will be used.
+
+=item B<-nodhe>
+
+if this option is set then no DH parameters will be loaded effectively
+disabling the ephemeral DH cipher suites.
+
+=item B<-no_tmp_rsa>
+
+certain export cipher suites sometimes use a temporary RSA key, this option
+disables temporary RSA key generation.
+
+=item B<-verify depth>, B<-Verify depth>
+
+The verify depth to use. This specifies the maximum length of the
+client certificate chain and makes the server request a certificate from
+the client. With the B<-verify> option a certificate is requested but the
+client does not have to send one, with the B<-Verify> option the client
+must supply a certificate or an error occurs.
+
+=item B<-CApath directory>
+
+The directory to use for client certificate verification. This directory
+must be in "hash format", see B<verify> for more information. These are
+also used when building the server certificate chain.
+
+=item B<-CAfile file>
+
+A file containing trusted certificates to use during client authentication
+and to use when attempting to build the server certificate chain. The list
+is also used in the list of acceptable client CAs passed to the client when
+a certificate is requested.
+
+=item B<-state>
+
+prints out the SSL session states.
+
+=item B<-debug>
+
+print extensive debugging information including a hex dump of all traffic.
+
+=item B<-nbio_test>
+
+tests non blocking I/O
+
+=item B<-nbio>
+
+turns on non blocking I/O
+
+=item B<-crlf>
+
+this option translated a line feed from the terminal into CR+LF.
+
+=item B<-quiet>
+
+inhibit printing of session and certificate information.
+
+=item B<-ssl2>, B<-ssl3>, B<-tls1>, B<-no_ssl2>, B<-no_ssl3>, B<-no_tls1>
+
+these options disable the use of certain SSL or TLS protocols. By default
+the initial handshake uses a method which should be compatible with all
+servers and permit them to use SSL v3, SSL v2 or TLS as appropriate.
+
+=item B<-bugs>
+
+there are several known bug in SSL and TLS implementations. Adding this
+option enables various workarounds.
+
+=item B<-hack>
+
+this option enables a further workaround for some some early Netscape
+SSL code (?).
+
+=item B<-cipher cipherlist>
+
+this allows the cipher list sent by the client to be modified. See the
+B<ciphers> command for more information.
+
+=item B<-www>
+
+sends a status message back to the client when it connects. This includes
+lots of information about the ciphers used and various session parameters.
+The output is in HTML format so this option will normally be used with a
+web browser.
+
+=item B<-WWW>
+
+emulates a simple web server. Pages will be resolved relative to the
+current directory, for example if the URL https://myhost/page.html is
+requested the file ./page.html will be loaded.
+
+=back
+
+=head1 CONNECTED COMMANDS
+
+If a connection request is established with an SSL client and neither the
+B<-www> nor the B<-WWW> option has been used then normally any data received
+from the client is displayed and any key presses will be sent to the client. 
+
+Certain single letter commands are also recognised which perform special
+operations: these are listed below.
+
+=over 4
+
+=item B<q>
+
+end the current SSL connection but still accept new connections.
+
+=item B<Q>
+
+end the current SSL connection and exit.
+
+=item B<r>
+
+renegotiate the SSL session.
+
+=item B<R>
+
+renegotiate the SSL session and request a client certificate.
+
+=item B<P>
+
+send some plain text down the underlying TCP connection: this should
+cause the client to disconnect due to a protocol violation.
+
+=item B<S>
+
+print out some session cache status information.
+
+=back
+
+=head1 NOTES
+
+B<s_server> can be used to debug SSL clients. To accept connections from
+a web browser the command:
+
+ openssl s_server -accept 443 -www
+
+can be used for example.
+
+Most web browsers (in particular Netscape and MSIE) only support RSA cipher
+suites, so they cannot connect to servers which don't use a certificate
+carrying an RSA key or a version of OpenSSL with RSA disabled.
+
+Although specifying an empty list of CAs when requesting a client certificate
+is strictly speaking a protocol violation, some SSL clients interpret this to
+mean any CA is acceptable. This is useful for debugging purposes.
+
+The session parameters can printed out using the B<sess_id> program.
+
+=head1 BUGS
+
+Because this program has a lot of options and also because some of
+the techniques used are rather old, the C source of s_server is rather
+hard to read and not a model of how things should be done. A typical
+SSL server program would be much simpler.
+
+The output of common ciphers is wrong: it just gives the list of ciphers that
+OpenSSL recognizes and the client supports.
+
+There should be a way for the B<s_server> program to print out details of any
+unknown cipher suites a client says it supports.
+
+=head1 SEE ALSO
+
+sess_id(1), s_client(1), ciphers(1)
+
+=cut
diff --git a/doc/apps/smime.pod b/doc/apps/smime.pod
new file mode 100644
index 0000000000..d0da967083
--- /dev/null
+++ b/doc/apps/smime.pod
@@ -0,0 +1,313 @@
+=pod
+
+=head1 NAME
+
+smime - S/MIME utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<smime>
+[B<-encrypt>]
+[B<-decrypt>]
+[B<-sign>]
+[B<-verify>]
+[B<-pk7out>]
+[B<-des>]
+[B<-des3>]
+[B<-rc2-40>]
+[B<-rc2-64>]
+[B<-rc2-128>]
+[B<-in file>]
+[B<-certfile file>]
+[B<-signer file>]
+[B<-recip  file>]
+[B<-in file>]
+[B<-inkey file>]
+[B<-out file>]
+[B<-to addr>]
+[B<-from ad>]
+[B<-subject s>]
+[B<-text>]
+[cert.pem]...
+
+=head1 DESCRIPTION
+
+The B<smime> command handles S/MIME mail. It can encrypt, decrypt, sign and
+verify S/MIME messages.
+
+=head1 COMMAND OPTIONS
+
+There are five operation options that set the type of operation to be performed.
+The meaning of the other options varies according to the operation type.
+
+=over 4
+
+=item B<-encrypt>
+
+encrypt mail for the given recipient certificates. Input file is the message
+to be encrypted. The output file is the encrypted mail in MIME format.
+
+=item B<-decrypt>
+
+decrypt mail using the supplied certificate and private key. Expects an
+encrypted mail message in MIME format for the input file. The decrypted mail
+is written to the output file.
+
+=item B<-sign>
+
+sign mail using the supplied certificate and private key. Input file is
+the message to be signed. The signed message in MIME format is written
+to the output file.
+
+=item B<-verify>
+
+verify signed mail. Expects a signed mail message on input and outputs
+the signed data. Both clear text and opaque signing is supported.
+
+=item B<-pk7out>
+
+takes an input message and writes out a PEM encoded PKCS#7 structure.
+
+=item B<-in filename>
+
+the input message to be encrypted or signed or the MIME message to
+be decrypted or verified.
+
+=item B<-out filename>
+
+the message text that has been decrypted or verified or the output MIME
+format message that has been signed or verified.
+
+=item B<-text>
+
+this option adds plain text (text/plain) MIME headers to the supplied
+message if encrypting or signing. If decrypting or verifying it strips
+off text headers: if the decrypted or verified message is not of MIME 
+type text/plain then an error occurs.
+
+=item B<-CAfile file>
+
+a file containing trusted CA certificates, only used with B<-verify>.
+
+=item B<-CApath dir>
+
+a directory containing trusted CA certificates, only used with
+B<-verify>. This directory must be a standard certificate directory: that
+is a hash of each subject name (using B<x509 -hash>) should be linked
+to each certificate.
+
+=item B<-des -des3 -rc2-40 -rc2-64 -rc2-128>
+
+the encryption algorithm to use. DES (56 bits), triple DES (168 bits)
+or 40, 64 or 128 bit RC2 respectively if not specified 40 bit RC2 is
+used. Only used with B<-encrypt>.
+
+=item B<-nointern>
+
+when verifying a message normally certificates (if any) included in
+the message are searched for the signing certificate. With this option
+only the certificates specified in the B<-certfile> option are used.
+The supplied certificates can still be used as untrusted CAs however.
+
+=item B<-noverify>
+
+do not verify the signers certificate of a signed message.
+
+=item B<-nochain>
+
+do not do chain verification of signers certificates: that is don't
+use the certificates in the signed message as untrusted CAs.
+
+=item B<-nosigs>
+
+don't try to verify the signatures on the message.
+
+=item B<-nocerts>
+
+when signing a message the signer's certificate is normally included
+with this option it is excluded. This will reduce the size of the
+signed message but the verifier must have a copy of the signers certificate
+available locally (passed using the B<-certfile> option for example).
+
+=item B<-noattr>
+
+normally when a message is signed a set of attributes are included which
+include the signing time and supported symmetric algorithms. With this
+option they are not included.
+
+=item B<-binary>
+
+normally the input message is converted to "canonical" format which is
+effectively using CR and LF as end of line: as required by the S/MIME
+specification. When this option is present no translation occurs. This
+is useful when handling binary data which may not be in MIME format.
+
+=item B<-nodetach>
+
+when signing a message use opaque signing: this form is more resistant
+to translation by mail relays but it cannot be read by mail agents that
+do not support S/MIME.  Without this option cleartext signing with
+the MIME type multipart/signed is used.
+
+=item B<-certfile file>
+
+allows additional certificates to be specified. When signing these will
+be included with the message. When verifying these will be searched for
+the signers certificates. The certificates should be in PEM format.
+
+=item B<-signer file>
+
+the signers certificate when signing a message. If a message is
+being verified then the signers certificates will be written to this
+file if the verification was successful.
+
+=item B<-recip file>
+
+the recipients certificate when decrypting a message. This certificate
+must match one of the recipients of the message or an error occurs.
+
+=item B<-inkey file>
+
+the private key to use when signing or decrypting. This must match the
+corresponding certificate. If this option is not specified then the
+private key must be included in the certificate file specified with
+the B<-recip> or B<-signer> file.
+
+=item B<cert.pem...>
+
+one or more certificates of message recipients: used when encrypting
+a message. 
+
+=item B<-to, -from, -subject>
+
+the relevant mail headers. These are included outside the signed
+portion of a message so they may be included manually. If signing
+then many S/MIME mail clients check the signers certificate's email
+address matches that specified in the From: address.
+
+=back
+
+=head1 NOTES
+
+The MIME message must be sent without any blank lines between the
+headers and the output. Some mail programs will automatically add
+a blank line. Piping the mail directly to sendmail is one way to
+achieve the correct format.
+
+The supplied message to be signed or encrypted must include the
+necessary MIME headers: or many S/MIME clients wont display it
+properly (if at all). You can use the B<-text> option to automatically
+add plain text headers.
+
+A "signed and encrypted" message is one where a signed message is
+then encrypted. This can be produced by encrypting an already signed
+message: see the examples section.
+
+This version of the program only allows one signer per message but it
+will verify multiple signers on received messages. Some S/MIME clients
+choke if a message contains multiple signers. It is possible to sign
+messages "in parallel" by signing an already signed message.
+
+The options B<-encrypt> and B<-decrypt> reflect common usage in S/MIME
+clients. Strictly speaking these process PKCS#7 enveloped data: PKCS#7
+encrypted data is used for other purposes.
+
+=head1 EXIT CODES
+
+=over 4
+
+=item 0
+
+the operation was completely successfully.
+
+=item 1 
+
+an error occurred parsing the command options.
+
+=item 2
+
+one of the input files could not be read.
+
+=item 3
+
+an error occurred creating the PKCS#7 file or when reading the MIME
+message.
+
+=item 4
+
+an error occurred decrypting or verifying the message.
+
+=item 5
+
+the message was verified correctly but an error occurred writing out
+the signers certificates.
+
+=back
+
+=head1 EXAMPLES
+
+Create a cleartext signed message:
+
+ openssl smime -sign -in message.txt -text -out mail.msg
+           -signer mycert.pem
+
+Create and opaque signed message
+
+ openssl smime -sign -in message.txt -text -out mail.msg -nodetach
+           -signer mycert.pem
+
+Create a signed message, include some additional certificates and
+read the private key from another file:
+
+ openssl smime -sign -in in.txt -text -out mail.msg
+           -signer mycert.pem -inkey mykey.pem -certfile mycerts.pem
+
+Send a signed message under Unix directly to sendmail, including headers:
+
+ openssl smime -sign -in in.txt -text -signer mycert.pem -from steve@openssl.org
+  -to someone@somewhere -subject "Signed message" | sendmail someone@somewhere
+
+Verify a message and extract the signer's certificate if successful:
+
+ openssl smime -verify -in mail.msg -signer user.pem -out signedtext.txt
+
+Send encrypted mail using triple DES:
+
+ openssl smime -encrypt -in in.txt -from steve@openssl.org -to someone@somewhere
+   -subject "Encrypted message" -des3 user.pem -out mail.msg
+
+Sign and encrypt mail:
+
+ openssl smime -sign -in ml.txt -signer my.pem -text | openssl -encrypt -out mail.msg 
+  -from steve@openssl.org -to someone@somewhere -subject "Signed and Encrypted message"
+  -des3 user.pem
+
+Note: the encryption command does not include the B<-text> option because the message
+being encrypted already has MIME headers.
+
+Decrypt mail:
+
+ openssl smime -decrypt -in mail.msg -recip mycert.pem -inkey key.pem
+
+=head1 BUGS
+
+The MIME parser isn't very clever: it seems to handle most messages that I've thrown
+at it but it may choke on others.
+
+The code currently will only write out the signer's certificate to a file: if the
+signer has a separate encryption certificate this must be manually extracted. There
+should be some heuristic that determines the correct encryption certificate.
+
+Ideally a database should be maintained of a certificates for each email address.
+
+The code doesn't currently take note of the permitted symmetric encryption
+algorithms as supplied in the SMIMECapabilities signed attribute. this means the
+user has to manually include the correct encryption algorithm. It should store
+the list of permitted ciphers in a database and only use those.
+
+No revocation checking is done on the signer's certificate.
+
+The current code can only handle S/MIME v2 messages, the more complex S/MIME v3
+structures may cause parsing errors.
+
+=cut
diff --git a/doc/apps/spkac.pod b/doc/apps/spkac.pod
new file mode 100644
index 0000000000..75d58e772b
--- /dev/null
+++ b/doc/apps/spkac.pod
@@ -0,0 +1,115 @@
+=pod
+
+=head1 NAME
+
+spkac - SPKAC printing and generating utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<spkac>
+[B<-in filename>]
+[B<-out filename>]
+[B<-key keyfile>]
+[B<-challenge string>]
+[B<-spkac spkacname>]
+[B<-spksect section>]
+[B<-noout>]
+[B<-verify>]
+
+
+=head1 DESCRIPTION
+
+The B<spkac> command processes Netscape signed public key and challenge
+(SPKAC) files. It can print out their contents, verify the signature and
+produce its own SPKACs from a supplied private key.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-in filename>
+
+This specifies the input filename to read from or standard input if this
+option is not specified. Ignored if the B<-key> option is used.
+
+=item B<-out filename>
+
+specifies the output filename to write to or standard output by
+default.
+
+=item B<-key keyfile>
+
+create an SPKAC file using the private key in B<keyfile>. The
+B<-in>, B<-noout>, B<-spksect> and B<-verify> options are ignored if
+present.
+
+=item B<-challenge string>
+
+specifies the challenge string if an SPKAC is being created.
+
+=item B<-spkac spkacname>
+
+allows an alternative name form the variable containing the
+SPKAC. The default is "SPKAC". This option affects both
+generated and input SPKAC files.
+
+=item B<-spksect section>
+
+allows an alternative name form the section containing the
+SPKAC. The default is the default section.
+
+=item B<-noout>
+
+don't output the text version of the SPKAC (not used if an
+SPKAC is being created).
+
+=item B<-verify>
+
+verifies the digital signature on the supplied SPKAC.
+
+
+=back
+
+=head1 EXAMPLES
+
+Print out the contents of an SPKAC:
+
+ openssl spkac -in spkac.cnf
+
+Verify the signature of an SPKAC:
+
+ openssl spkac -in spkac.cnf -noout -verify
+
+Create an SPKAC using the challenge string "hello":
+
+ openssl spkac -key key.pem -challenge hello -out spkac.cnf
+
+Example of an SPKAC, (long lines split up for clarity):
+
+ SPKAC=MIG5MGUwXDANBgkqhkiG9w0BAQEFAANLADBIAkEA1cCoq2Wa3Ixs47uI7F\
+ PVwHVIPDx5yso105Y6zpozam135a8R0CpoRvkkigIyXfcCjiVi5oWk+6FfPaD03u\
+ PFoQIDAQABFgVoZWxsbzANBgkqhkiG9w0BAQQFAANBAFpQtY/FojdwkJh1bEIYuc\
+ 2EeM2KHTWPEepWYeawvHD0gQ3DngSC75YCWnnDdq+NQ3F+X4deMx9AaEglZtULwV\
+ 4=
+
+=head1 NOTES
+
+A created SPKAC with suitable DN components appended can be fed into
+the B<ca> utility.
+
+SPKACs are typically generated by Netscape when a form is submitted
+containing the B<KEYGEN> tag as part of the certificate enrollment
+process.
+
+The challenge string permits a primitive form of proof of possession
+of private key. By checking the SPKAC signature and a random challenge
+string some guarantee is given that the user knows the private key
+corresponding to the public key being certified. This is important in
+some applications. Without this it is possible for a previous SPKAC
+to be used in a "replay attack".
+
+=head1 SEE ALSO
+
+ca(1)
+
+=cut
diff --git a/doc/apps/verify.pod b/doc/apps/verify.pod
new file mode 100644
index 0000000000..2ff261e29a
--- /dev/null
+++ b/doc/apps/verify.pod
@@ -0,0 +1,273 @@
+=pod
+
+=head1 NAME
+
+pkcs7 - PKCS#7 utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<verify>
+[B<-CApath directory>]
+[B<-CAfile file>]
+[B<-purpose purpose>]
+[B<-untrusted file>]
+[B<-help>]
+[B<-verbose>]
+[B<->]
+[certificates]
+
+
+=head1 DESCRIPTION
+
+The B<verify> command verifies certificate chains.
+
+=head1 COMMAND OPTIONS
+
+=over 4
+
+=item B<-CApath directory>
+
+A directory of trusted certificates. The certificates should have names
+of the form: hash.0 or have symbolic links to them of this
+form ("hash" is the hashed certificate subject name: see the B<-hash> option
+of the B<x509> utility). Under Unix the B<c_rehash> script will automatically
+create symbolic links to a directory of certificates.
+
+=item B<-CAfile file>
+
+A file of trusted certificates. The file should contain multiple certificates
+in PEM format concatenated together.
+
+=item B<-untrusted file>
+
+A file of untrusted certificates. The file should contain multiple certificates
+
+=item B<-purpose purpose>
+
+the intended use for the certificate. Without this option no chain verification
+will be done. Currently accepted uses are B<sslclient>, B<sslserver>,
+B<nssslserver>, B<smimesign>, B<smimeencrypt>. See the B<VERIFY OPERATION>
+section for more information.
+
+=item B<-help>
+
+prints out a usage message.
+
+=item B<-verbose>
+
+print extra information about the operations being performed.
+
+=item B<->
+
+marks the last option. All arguments following this are assumed to be
+certificate files. This is useful if the first certificate filename begins
+with a B<->.
+
+=item B<certificates>
+
+one or more certificates to verify. If no certificate filenames are included
+then an attempt is made to read a certificate from standard input. They should
+all be in PEM format.
+
+
+=back
+
+=head1 VERIFY OPERATION
+
+The B<verify> program uses the same functions as the internal SSL and S/MIME
+verification, therefore this description applies to these verify operations
+too.
+
+There is one crucial difference between the verify operations performed
+by the B<verify> program: wherever possible an attempt is made to continue
+after an error whereas normally the verify operation would halt on the
+first error. This allows all the problems with a certificate chain to be
+determined.
+
+The verify operation consists of a number of separate steps.
+
+Firstly a certificate chain is built up starting from the supplied certificate
+and ending in the root CA. It is an error if the whole chain cannot be built
+up. The chain is built up by looking up a certificate whose subject name
+matches the issuer name of the current certificate. If a certificate is found
+whose subject and issuer names are identical it is assumed to be the root CA.
+The lookup first looks in the list of untrusted certificates and if no match
+is found the remaining lookups are from the trusted certificates. The root CA
+is always looked up in the trusted certificate list: if the certificate to
+verify is a root certificate then an exact match must be found in the trusted
+list.
+
+The second operation is to check every untrusted certificate's extensions for
+consistency with the supplied purpose. If the B<-purpose> option is not included
+then no checks are done. The supplied or "leaf" certificate must have extensions
+compatible with the supplied purpose and all other certificates must also be valid
+CA certificates. The precise extensions required are described in more detail in
+the B<CERTIFICATE EXTENSIONS> section of the B<x509> utility.
+
+The third operation is to check the trust settings on the root CA. The root
+CA should be trusted for the supplied purpose. For compatibility with previous
+versions of SSLeay and OpenSSL a certificate with no trust settings is considered
+to be valid for all purposes. 
+
+The final operation is to check the validity of the certificate chain. The validity
+period is checked against the current system time and the notBefore and notAfter
+dates in the certificate. The certificate signatures are also checked at this
+point.
+
+If all operations complete successfully then certificate is considered valid. If
+any operation fails then the certificate is not valid.
+
+=head1 DIAGNOSTICS
+
+When a verify operation fails the output messages can be somewhat cryptic. The
+general form of the error message is:
+
+ server.pem: /C=AU/ST=Queensland/O=CryptSoft Pty Ltd/CN=Test CA (1024 bit)
+ error 24 at 1 depth lookup:invalid CA certificate
+
+The first line contains the name of the certificate being verified followed by
+the subject name of the certificate. The second line contains the error number
+and the depth. The depth is number of the certificate being verified when a
+problem was detected starting with zero for the certificate being verified itself
+then 1 for the CA that signed the certificate and so on. Finally a text version
+of the error number is presented.
+
+An exhaustive list of the error codes and messages is shown below, this also
+includes the name of the error code as defined in the header file x509_vfy.h
+Some of the error codes are defined but never returned: these are described
+as "unused".
+
+=over 4
+
+=item B<0 X509_V_OK: ok>
+
+the operation was successful.
+
+=item B<2 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT: unable to get issuer certificate>
+
+the issuer certificate could not be found: this occurs if the issuer certificate
+of an untrusted certificate cannot be found.
+
+=item B<3 X509_V_ERR_UNABLE_TO_GET_CRL unable to get certificate CRL>
+
+the CRL of a certificate could not be found. Unused.
+
+=item B<4 X509_V_ERR_UNABLE_TO_DECRYPT_CERT_SIGNATURE: unable to decrypt certificate's signature>
+
+the certificate signature could not be decrypted. This means that the actual signature value
+could not be determined rather than it not matching the expected value, this is only
+meaningful for RSA keys.
+
+=item B<5 X509_V_ERR_UNABLE_TO_DECRYPT_CRL_SIGNATURE: unable to decrypt CRL's signature>
+
+the CRL signature could not be decrypted: this means that the actual signature value
+could not be determined rather than it not matching the expected value. Unused.
+
+=item B<6 X509_V_ERR_UNABLE_TO_DECODE_ISSUER_PUBLIC_KEY: unable to decode issuer public key>
+
+the public key in the certificate SubjectPublicKeyInfo could not be read.
+
+=item B<7 X509_V_ERR_CERT_SIGNATURE_FAILURE: certificate signature failure>
+
+the signature of the certificate is invalid.
+
+=item B<8 X509_V_ERR_CRL_SIGNATURE_FAILURE: CRL signature failure>
+
+the signature of the certificate is invalid. Unused.
+
+=item B<9 X509_V_ERR_CERT_NOT_YET_VALID: certificate is not yet valid>
+
+the certificate is not yet valid: the notBefore date is after the current time.
+
+=item B<10 X509_V_ERR_CRL_NOT_YET_VALID: CRL is not yet valid>
+
+the CRL is not yet valid. Unused.
+
+=item B<11 X509_V_ERR_CERT_HAS_EXPIRED: Certificate has expired>
+
+the certificate has expired: that is the notAfter date is before the current time.
+
+=item B<12 X509_V_ERR_CRL_HAS_EXPIRED: CRL has expired>
+
+the CRL has expired. Unused.
+
+=item B<13 X509_V_ERR_ERROR_IN_CERT_NOT_BEFORE_FIELD: format error in certificate's notBefore field>
+
+the certificate notBefore field contains an invalid time.
+
+=item B<14 X509_V_ERR_ERROR_IN_CERT_NOT_AFTER_FIELD: format error in certificate's notAfter field>
+
+the certificate notAfter field contains an invalid time.
+
+=item B<15 X509_V_ERR_ERROR_IN_CRL_LAST_UPDATE_FIELD: format error in CRL's lastUpdate field>
+
+the CRL lastUpdate field contains an invalid time. Unused.
+
+=item B<16 X509_V_ERR_ERROR_IN_CRL_NEXT_UPDATE_FIELD: format error in CRL's nextUpdate field>
+
+the CRL nextUpdate field contains an invalid time. Unused.
+
+=item B<17 X509_V_ERR_OUT_OF_MEM: out of memory>
+
+an error occurred trying to allocate memory. This should never happen.
+
+=item B<18 X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT: self signed certificate>
+
+the passed certificate is self signed and the same certificate cannot be found in the list of
+trusted certificates.
+
+=item B<19 X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN: self signed certificate in certificate chain>
+
+the certificate chain could be built up using the untrusted certificates but the root could not
+be found locally.
+
+=item B<20 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY: unable to get local issuer certificate>
+
+the issuer certificate of a locally looked up certificate could not be found. This normally means
+the list of trusted certificates is not complete.
+
+=item B<21 X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE: unable to verify the first certificate>
+
+no signatures could be verified because the chain contains only one certificate and it is not
+self signed.
+
+=item B<22 X509_V_ERR_CERT_CHAIN_TOO_LONG: certificate chain too long>
+
+the certificate chain length is greater than the supplied maximum depth. Unused.
+
+=item B<23 X509_V_ERR_CERT_REVOKED: certificate revoked>
+
+the certificate has been revoked. Unused.
+
+=item B<24 X509_V_ERR_INVALID_CA: invalid CA certificate>
+
+a CA certificate is invalid. Either it is not a CA or its extensions are not consistent
+with the supplied purpose.
+
+=item B<25 X509_V_ERR_PATH_LENGTH_EXCEEDED: path length constraint exceeded>
+
+the basicConstraints pathlength parameter has been exceeded.
+
+=item B<26 X509_V_ERR_INVALID_PURPOSE: unsupported certificate purpose>
+
+the supplied certificate cannot be used for the specified purpose.
+
+=item B<27 X509_V_ERR_CERT_UNTRUSTED: certificate not trusted>
+
+the root CA is not marked as trusted for the specified purpose.
+
+=item B<28 X509_V_ERR_CERT_REJECTED: certificate rejected>
+
+the root CA is marked to reject the specified purpose.
+
+=item B<50 X509_V_ERR_APPLICATION_VERIFICATION: application verification failure>
+
+an application specific error. Unused.
+
+=back
+
+=head1 SEE ALSO
+
+x509(1)
+
+=cut
diff --git a/doc/apps/version.pod b/doc/apps/version.pod
new file mode 100644
index 0000000000..69421d52cb
--- /dev/null
+++ b/doc/apps/version.pod
@@ -0,0 +1,56 @@
+=pod
+
+=head1 NAME
+
+version - print version information
+
+=head1 SYNOPSIS
+
+B<openssl version>
+[B<-a>]
+[B<-v>]
+[B<-b>]
+[B<-o>]
+[B<-f>]
+[B<-p>]
+
+=head1 DESCRIPTION
+
+This command is used to print out version information about OpenSSL.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-a>
+
+all information, this is the same as setting all the other flags.
+
+=item B<-v>
+
+the current OpenSSL version.
+
+=item B<-b>
+
+the date the current version of OpenSSL was built.
+
+=item B<-o>
+
+option information: various options set when the library was built.
+
+=item B<-c>
+
+compilation flags.
+
+=item B<-p>
+
+platform setting.
+
+=back
+
+=head1 NOTES
+
+The output of B<openssl version -a> would typically be used when sending
+in a bug report.
+
+=cut
diff --git a/doc/apps/x509.pod b/doc/apps/x509.pod
new file mode 100644
index 0000000000..52ac949b18
--- /dev/null
+++ b/doc/apps/x509.pod
@@ -0,0 +1,541 @@
+
+=pod
+
+=head1 NAME
+
+x509 - Certificate display and signing utility
+
+=head1 SYNOPSIS
+
+B<openssl> B<x509>
+[B<-inform DER|PEM|NET>]
+[B<-outform DER|PEM|NET>]
+[B<-keyform DER|PEM>]
+[B<-CAform DER|PEM>]
+[B<-CAkeyform DER|PEM>]
+[B<-in filename>]
+[B<-out filename>]
+[B<-serial>]
+[B<-hash>]
+[B<-subject>]
+[B<-issuer>]
+[B<-startdate>]
+[B<-enddate>]
+[B<-purpose>]
+[B<-dates>]
+[B<-modulus>]
+[B<-fingerprint>]
+[B<-alias>]
+[B<-noout>]
+[B<-trustout>]
+[B<-clrtrust>]
+[B<-clrreject>]
+[B<-addtrust arg>]
+[B<-addreject arg>]
+[B<-setalias arg>]
+[B<-days arg>]
+[B<-signkey filename>]
+[B<-x509toreq>]
+[B<-req>]
+[B<-CA filename>]
+[B<-CAkey filename>]
+[B<-CAcreateserial>]
+[B<-CAserial filename>]
+[B<-text>]
+[B<-C>]
+[B<-md2|-md5|-sha1|-mdc2>]
+[B<-clrext>]
+[B<-extfile filename>]
+[B<-extensions section>]
+
+=head1 DESCRIPTION
+
+The B<x509> command is a multi purpose certificate utility. It can be
+used to display certificate information, convert certificates to
+various forms, sign certificate requests like a "mini CA" or edit
+certificate trust settings.
+
+Since there are a large number of options they will split up into
+various sections.
+
+
+=head1 INPUT, OUTPUT AND GENERAL PURPOSE OPTIONS
+
+=over 4
+
+=item B<-inform DER|PEM|NET>
+
+This specifies the input format normally the command will expect an X509
+certificate but this can change if other options such as B<-req> are
+present. The DER format is the DER encoding of the certificate and PEM
+is the base64 encoding of the DER encoding with header and footer lines
+added. The NET option is an obscure Netscape server format that is now
+obsolete.
+
+=item B<-outform DER|PEM|NET>
+
+This specifies the output format, the options have the same meaning as the 
+B<-inform> option.
+
+=item B<-in filename>
+
+This specifies the input filename to read a certificate from or standard input
+if this option is not specified.
+
+=item B<-out filename>
+
+This specifies the output filename to write to or standard output by
+default.
+
+=item B<-md2|-md5|-sha1|-mdc2>
+
+the digest to use. This affects any signing or display option that uses a message
+digest, such as the B<-fingerprint>, B<-signkey> and B<-CA> options. If not
+specified then MD5 is used. If the key being used to sign with is a DSA key then
+this option has no effect: SHA1 is always used with DSA keys.
+
+
+=back
+
+=head1 DISPLAY OPTIONS
+
+Note: the B<-alias> and B<-purpose> options are also display options
+but are described in the B<TRUST OPTIONS> section.
+
+=over 4
+
+=item B<-text>
+
+prints out the certificate in text form. Full details are output including the
+public key, signature algorithms, issuer and subject names, serial number
+any extensions present and any trust settings.
+
+=item B<-noout>
+
+this option prevents output of the encoded version of the request.
+
+=item B<-modulus>
+
+this option prints out the value of the modulus of the public key
+contained in the certificate.
+
+=item B<-serial>
+
+outputs the certificate serial number.
+
+=item B<-hash>
+
+outputs the "hash" of the certificate subject name. This is used in OpenSSL to
+form an index to allow certificates in a directory to be looked up by subject
+name.
+
+=item B<-subject>
+
+outputs the subject name.
+
+=item B<-issuer>
+
+outputs the issuer name.
+
+=item B<-startdate>
+
+prints out the start date of the certificate, that is the notBefore date.
+
+=item B<-enddate>
+
+prints out the expiry date of the certificate, that is the notAfter date.
+
+=item B<-dates>
+
+prints out the start and expiry dates of a certificate.
+
+=item B<-fingerprint>
+
+prints out the digest of the DER encoded version of the whole certificate.
+
+=item B<-C>
+
+this outputs the certificate in the form of a C source file.
+
+=back
+
+=head1 TRUST SETTINGS
+
+Please note these options are currently experimental and may well change.
+
+A B<trusted certificate> is an ordinary certificate which has several
+additional pieces of information attached to it such as the permitted
+and prohibited uses of the certificate and an "alias".
+
+Normally when a certificate is being verified at least one certificate
+must be "trusted". By default a trusted certificate must be stored
+locally and must be a root CA: any certificate chain ending in this CA
+is then usable for any purpose.
+
+Trust settings currently are only used with a root CA. They allow a finer
+control over the purposes the root CA can be used for. For example a CA
+may be trusted for SSL client but not SSL server use.
+
+See the description of the B<verify> utility for more information on the
+meaning of trust settings.
+
+Future versions of OpenSSL will recognise trust settings on any
+certificate: not just root CAs.
+
+
+=over 4
+
+=item B<-trustout>
+
+this causes B<x509> to output a B<trusted> certificate. An ordinary
+or trusted certificate can be input but by default an ordinary
+certificate is output and any trust settings are discarded. With the
+B<-trustout> option a trusted certificate is output. A trusted
+certificate is automatically output if any trust settings are modified.
+
+=item B<-setalias arg>
+
+sets the alias of the certificate. This will allow the certificate
+to be referred to using a nickname for example "Steve's Certificate".
+
+=item B<-alias>
+
+outputs the certificate alias, if any.
+
+=item B<-clrtrust>
+
+clears all the permitted or trusted uses of the certificate.
+
+=item B<-clrreject>
+
+clears all the prohibited or rejected uses of the certificate.
+
+=item B<-addtrust arg>
+
+adds a trusted certificate use. Currently acceptable values
+are B<all> (any purpose), B<sslclient> (SSL client use), B<sslserver>
+(SSL server use) B<email> (S/MIME email) and B<objsign> (Object signing).
+
+=item B<-addreject arg>
+
+adds a prohibited use. It accepts the same values as the B<-addtrust>
+option.
+
+=item B<-purpose>
+
+this option performs tests on the certificate extensions and outputs
+the results. For a more complete description see the B<CERTIFICATE
+EXTENSIONS> section.
+
+=back
+
+=head1 SIGNING OPTIONS
+
+The B<x509> utility can be used to sign certificates and requests: it
+can thus behave like a "mini CA".
+
+=over 4
+
+=item B<-signkey filename>
+
+this option causes the input file to be self signed using the supplied
+private key. 
+
+If the input file is a certificate it sets the issuer name to the
+subject name (i.e.  makes it self signed) changes the public key to the
+supplied value and changes the start and end dates. The start date is
+set to the current time and the end date is set to a value determined
+by the B<-days> option. Any certificate extensions are retained unless
+the B<-clrext> option is supplied.
+
+If the input is a certificate request then a self signed certificate
+is created using the supplied private key using the subject name in
+the request.
+
+=item B<-clrext>
+
+delete any extensions from a certificate. This option is used when a
+certificate is being created from another certificate (for example with
+the B<-signkey> or the B<-CA> options). Normally all extensions are
+retained.
+
+=item B<-keyform PEM|DER>
+
+specifies the format (DER or PEM) of the private key file used in the
+B<-signkey> option.
+
+=item B<-days arg>
+
+specifies the number of days to make a certificate valid for. The default
+is 30 days.
+
+=item B<-x509toreq>
+
+converts a certificate into a certificate request. The B<-signkey> option
+is used to pass the required private key.
+
+=item B<-req>
+
+by default a certificate is expected on input. With this option a
+certificate request is expected instead.
+
+=item B<-CA filename>
+
+specifies the CA certificate to be used for signing. When this option is
+present B<x509> behaves like a "mini CA". The input file is signed by this
+CA using this option: that is its issuer name is set to the subject name
+of the CA and it is digitally signed using the CAs private key.
+
+This option is normally combined with the B<-req> option. Without the
+B<-req> option the input is a certificate which must be self signed.
+
+=item B<-CAkey filename>
+
+sets the CA private key to sign a certificate with. If this option is
+not specified then it is assumed that the CA private key is present in
+the CA certificate file.
+
+=item B<-CAserial filename>
+
+sets the CA serial number file to use.
+
+When the B<-CA> option is used to sign a certificate it uses a serial
+number specified in a file. This file consist of one line containing
+an even number of hex digits with the serial number to use. After each
+use the serial number is incremented and written out to the file again.
+
+The default filename consists of the CA certificate file base name with
+".srl" appended. For example if the CA certificate file is called 
+"mycacert.pem" it expects to find a serial number file called "mycacert.srl".
+
+=item B<-CAcreateserial filename>
+
+with this option the CA serial number file is created if it does not exist:
+it will contain the serial number "01". Normally if the B<-CA> option is
+specified and the serial number file does not exist it is an error.
+
+=item B<-extfile filename>
+
+file containing certificate extensions to use. If not specified then
+no extensions are added to the certificate.
+
+=item B<-extensions section>
+
+the section to add certificate extensions from. If this option is not
+specified then the extensions should either be contained in the unnamed
+(default) section or the default section should contain a variable called
+"extensions" which contains the section to use.
+
+=back
+
+=head1 EXAMPLES
+
+Note: in these examples the '\' means the example should be all on one
+line.
+
+Display the contents of a certificate:
+
+	openssl x509 -in cert.pem -noout -text
+
+Display the certificate serial number:
+
+	openssl x509 -in cert.pem -noout -serial
+
+Display the certificate MD5 fingerprint:
+
+	openssl x509 -in cert.pem -noout -fingerprint
+
+Display the certificate SHA1 fingerprint:
+
+	openssl x509 -sha1 -in cert.pem -noout -fingerprint
+
+Convert a certificate from PEM to DER format:
+
+	openssl x509 -in cert.pem -inform PEM -out cert.der -outform DER
+
+Convert a certificate to a certificate request:
+
+	openssl x509 -x509toreq -in cert.pem -out req.pem -signkey key.pem
+
+Convert a certificate request into a self signed certificate using
+extensions for a CA:
+
+	openssl x509 -req -in careq.pem -config openssl.cnf -extensions v3_ca \
+		-signkey key.pem -out cacert.pem
+
+Sign a certificate request using the CA certificate above and add user
+certificate extensions:
+
+	openssl x509 -req -in req.pem -config openssl.cnf -extensions v3_usr \
+		-CA cacert.pem -CAkey key.pem -CAcreateserial
+
+
+Set a certificate to be trusted for SSL client use and change set its alias to
+"Steve's Class 1 CA"
+
+	openssl x509 -in cert.pem -addtrust sslclient \
+		-alias "Steve's Class 1 CA" -out trust.pem
+
+=head1 NOTES
+
+The PEM format uses the header and footer lines:
+
+ -----BEGIN CERTIFICATE----
+ -----END CERTIFICATE----
+
+it will also handle files containing:
+
+ -----BEGIN X509 CERTIFICATE----
+ -----END X509 CERTIFICATE----
+
+Trusted certificates have the lines
+
+ -----BEGIN TRUSTED CERTIFICATE----
+ -----END TRUSTED CERTIFICATE----
+
+The B<-fingerprint> option takes the digest of the DER encoded certificate.
+This is commonly called a "fingerprint". Because of the nature of message
+digests the fingerprint of a certificate is unique to that certificate and
+two certificates with the same fingerprint can be considered to be the same.
+
+The Netscape fingerprint uses MD5 whereas MSIE uses SHA1.
+
+=head1 CERTIFICATE EXTENSIONS
+
+The B<-purpose> option checks the certificate extensions and determines
+what the certificate can be used for. The actual checks done are rather
+complex and include various hacks and workarounds to handle broken
+certificates and software.
+
+The same code is used when verifying untrusted certificates in chains
+so this section is useful if a chain is rejected by the verify code.
+
+The basicConstraints extension CA flag is used to determine whether the
+certificate can be used as a CA. If the CA flag is true then it is a CA,
+if the CA flag is false then it is not a CA. B<All> CAs should have the
+CA flag set to true.
+
+If the basicConstraints extension is absent then the certificate is
+considered to be a "possible CA" other extensions are checked according
+to the intended use of the certificate. A warning is given in this case
+because the certificate should really not be regarded as a CA: however
+it is allowed to be a CA to work around some broken software.
+
+If the certificate is a V1 certificate (and thus has no extensions) and
+it is self signed it is also assumed to be a CA but a warning is again
+given: this is to work around the problem of Verisign roots which are V1
+self signed certificates.
+
+If the keyUsage extension is present then additional restraints are
+made on the uses of the certificate. A CA certificate B<must> have the
+keyCertSign bit set if the keyUsage extension is present.
+
+The extended key usage extension places additional restrictions on the
+certificate uses. If this extension is present (whether critical or not)
+the key can only be used for the purposes specified.
+
+A complete description of each test is given below. The comments about
+basicConstraints and keyUsage and V1 certificates above apply to B<all>
+CA certificates.
+
+
+=over 4
+
+=item B<SSL Client>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID.  keyUsage must be absent or it must have the
+digitalSignature bit set. Netscape certificate type must be absent or it must
+have the SSL client bit set.
+
+=item B<SSL Client CA>
+
+The extended key usage extension must be absent or include the "web client
+authentication" OID. Netscape certificate type must be absent or it must have
+the SSL CA bit set: this is used as a work around if the basicConstraints
+extension is absent.
+
+=item B<SSL Server>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs.  keyUsage must be absent or it
+must have the digitalSignature, the keyEncipherment set or both bits set.
+Netscape certificate type must be absent or have the SSL server bit set.
+
+=item B<SSL Server CA>
+
+The extended key usage extension must be absent or include the "web server
+authentication" and/or one of the SGC OIDs.  Netscape certificate type must
+be absent or the SSL CA bit must be set: this is used as a work around if the
+basicConstraints extension is absent.
+
+=item B<Netscape SSL Server>
+
+For Netscape SSL clients to connect to an SSL server it must have the
+keyEncipherment bit set if the keyUsage extension is present. This isn't
+always valid because some cipher suites use the key for digital signing.
+Otherwise it is the same as a normal SSL server.
+
+=item B<Common S/MIME Client Tests>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. Netscape certificate type must be absent or should have the
+S/MIME bit set. If the S/MIME bit is not set in netscape certificate type
+then the SSL client bit is tolerated as an alternative but a warning is shown:
+this is because some Verisign certificates don't set the S/MIME bit.
+
+=item B<S/MIME Signing>
+
+In addition to the common S/MIME client tests the digitalSignature bit must
+be set if the keyUsage extension is present.
+
+=item B<S/MIME Encryption>
+
+In addition to the common S/MIME tests the keyEncipherment bit must be set
+if the keyUsage extension is present.
+
+=item B<S/MIME CA>
+
+The extended key usage extension must be absent or include the "email
+protection" OID. Netscape certificate type must be absent or must have the
+S/MIME CA bit set: this is used as a work around if the basicConstraints
+extension is absent. 
+
+=item B<CRL Signing>
+
+The keyUsage extension must be absent or it must have the CRL signing bit
+set.
+
+=item B<CRL Signing CA>
+
+The normal CA tests apply. Except in this case the basicConstraints extension
+must be present.
+
+=back
+
+=head1 BUGS
+
+The way DNs are printed is in a "historical SSLeay" format which doesn't
+follow any published standard. It should follow some standard like RFC2253
+or RFC1779 with options to make the stuff more readable.
+
+Extensions in certificates are not transferred to certificate requests and
+vice versa.
+
+It is possible to produce invalid certificates or requests by specifying the
+wrong private key or using inconsistent options in some cases: these should
+be checked.
+
+There should be options to explicitly set such things as start and end
+dates rather than an offset from the current time.
+
+The code to implement the verify behaviour described in the B<TRUST SETTINGS>
+is currently being developed. It thus describes the intended behavior rather
+than the current behaviour. It is hoped that it will represent reality in
+OpenSSL 0.9.5 and later.
+
+=head1 SEE ALSO
+
+req(1), ca(1), genrsa(1), gendsa(1), verify(1)
+
+=cut