generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

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

Browse Source 
could rename too :-(
This commit is contained in:
Dr. Stephen Henson
2000-01-21 02:17:04 +00:00
parent e7f97e2d22
commit dd46d58f65
28 changed files with 0 additions and 11 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
doc/apps/asn1parse.pod Normal file
View File

@@ -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

472
doc/apps/ca.pod Normal file
View File

@@ -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

138
doc/apps/config.pod Normal file
View File

@@ -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

110
doc/apps/crl.pod Normal file
View File

@@ -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

90
doc/apps/crl2pkcs7.pod Normal file
View File

@@ -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

49
doc/apps/dgst.pod Normal file
View File

@@ -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

87
doc/apps/dh.pod Normal file
View File

@@ -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

154
doc/apps/dsa.pod Normal file
View File

@@ -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

100
doc/apps/dsaparam.pod Normal file
View File

@@ -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

248
doc/apps/enc.pod Normal file
View File

@@ -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

74
doc/apps/gendh.pod Normal file
View File

@@ -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

56
doc/apps/gendsa.pod Normal file
View File

@@ -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

72
doc/apps/genrsa.pod Normal file
View File

@@ -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)

70
doc/apps/nseq.pod Normal file
View File

@@ -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

240
doc/apps/openssl.pod Normal file
View File

@@ -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

286
doc/apps/pkcs12.pod Normal file
View File

@@ -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)

85
doc/apps/pkcs7.pod Normal file
View File

@@ -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

224
doc/apps/pkcs8.pod Normal file
View File

@@ -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

530
doc/apps/req.pod Normal file
View File

@@ -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

160
doc/apps/rsa.pod Normal file
View File

@@ -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

211
doc/apps/s_client.pod Normal file
View File

@@ -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

262
doc/apps/s_server.pod Normal file
View File

@@ -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

313
doc/apps/smime.pod Normal file
View File

@@ -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

115
doc/apps/spkac.pod Normal file
View File

@@ -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

273
doc/apps/verify.pod Normal file
View File

@@ -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

56
doc/apps/version.pod Normal file
View File

@@ -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

541
doc/apps/x509.pod Normal file
View File

@@ -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