wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Very preliminary POD format documentation for some

Browse source 
of the openssl utility commands...
This commit is contained in:
Dr. Stephen Henson 1999-11-10 02:52:17 +00:00
parent 0d9cfe1ae7
commit aba3e65f2c
16 changed files with 2488 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
CHANGES
View file

@ -4,6 +4,9 @@
Changes between 0.9.4 and 0.9.5 [xx XXX 1999]
*) Add a few manpages for some of the openssl commands.
[Steve Henson]
*) Fix the -revoke option in ca. It was freeing up memory twice,
leaking and not finding already revoked certificates.
[Steve Henson]

11
doc/man/README Normal file
View file

@ -0,0 +1,11 @@
This is *very* preliminiary documentation for some
of the main commands in the openssl utility. The
information reflects the way the commands may work
when OpenSSL 0.9.5 is released. They are subject
to change though.
The stuff is in POD format and has just been tested
with pod2man where is looks passable. It may well
look odd in html or other formats. Feel free to tidy
up, reformat or convert to a completely different
format if so desired...

129
doc/man/asn1parse.pod Normal file
View file

@ -0,0 +1,129 @@
=pod
=head1 NAME
asn1parse - ASN.1 parsing tool
=head1 SYNOPSIS
=item 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 ouput 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

456
doc/man/ca.pod Normal file
View file

@ -0,0 +1,456 @@
=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 encrrypt 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 for compatability 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>
this option is also for compatability with the older IE enrollment
control. It only accepts 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<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,
configration 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. Netscape apparently 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/man/config.pod Normal file
View file

@ -0,0 +1,138 @@
=pod
=head1 NAME
config - OpenSSL CONF library configuaration files
=head1 DESCRIPTION
The OpenSSL CONF library can be used to read confiuration 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> environement
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 varible 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

48
doc/man/dgst.pod Normal file
View file

@ -0,0 +1,48 @@
=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

124
doc/man/dsa.pod Normal file
View file

@ -0,0 +1,124 @@
=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<-out filename>]
[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 outputs a
SEQUENCE of the public key component, p, q and g respectively.
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 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<-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<-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 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

92
doc/man/dsaparam.pod Normal file
View file

@ -0,0 +1,92 @@
=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:file>]
[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:file>
a file or files containing random data used to seed the random number
generator. Multiple files can be specified separated by 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
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

54
doc/man/gendsa.pod Normal file
View file

@ -0,0 +1,54 @@
=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:file>]
[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:file>
a file or files containing random data used to seed the random number
generator. Multiple files can be specified separated by 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

70
doc/man/genrsa.pod Normal file
View file

@ -0,0 +1,70 @@
=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:file>]
[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:file>
a file or files containing random data used to seed the random number
generator. Multiple files can be specified separated by 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)

236
doc/man/openssl.pod Normal file
View file

@ -0,0 +1,236 @@
=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
crypto(3), ssl(3)
=head1 HISTORY
The openssl(3) document appeared in OpenSSL 0.9.2
=cut

133
doc/man/pkcs8.pod Normal file
View file

@ -0,0 +1,133 @@
=pod
=head1 NAME
pkcs8 - PKCS#8 format private key processing tool
=head1 SYNOPSIS
B<openssl> B<pkcs8>
[B<-topk8>]
[B<-inform PEM|DER>]
[B<-outform PEM|DER>]
[B<-in filename>]
[B<-out filename>]
[B<-noiter>]
[B<-nocrypt>]
[B<-nooct>]
[B<-v2 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|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<-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<-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 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 BUGS
It should be possible to read or produce PKCS#8 format encrypted RSA keys:
at present it isn't.
=head1 SEE ALSO
L<pkcs8>, dsa(1), genrsa(1), gendsa(1)
=cut

403
doc/man/req.pod Normal file
View file

@ -0,0 +1,403 @@
=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<-out filename>]
[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<-out filename>
This specifies the output filename to write to or standard output by
default.
=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 ignore 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 configuation 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<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
overriden 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
overriden 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 numerical form
of the object identifier followed by B<=> and its name. 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_rsa_key|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.
=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<dirstring_type>
This option specifies which string types are permissible in a
B<DirectoryString>. 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<nobmp>
option just uses PrintableStrings and T61Strings: certain software has
problems with BMPStrings.
=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<attributes>
this specifies the section containing any request attributes: its format
is the same as B<distinguished_name> described below. Typically these
may contain the challengePassword or unstructuredName types. They are
currently ignored by OpenSSLs request signing utilities but some CAs might want
want them.
=item B<distinguished_name>
This specifies the section containing the distiguished name fields to
prompt for when generating a certificate or certificate request. This
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.
The "prompt" string is used to ask the user to enter the relvant
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 recognise 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
=head1 NOTES
The header and footer lines in the B<PEM> format contain the words
B<BEGIN CERTIFICATE REQUEST> and B<END CERTIFICATE REQUEST> some software
(for example some versions of Netscape certificate server) requires the
words B<BEGIN NEW CERTIFICATE REQUEST> and B<END NEW CERTIFICATE REQUEST>
instead.
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
certficates 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 compatability reasons the B<SSLEAY_CONF>
environment variable serves the same purpose but its use is discouraged.
=head1 BUGS
OpenSSLs 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 exits if you get the strings
wrong and 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.
There should be a way to have a friendly front end (e.g. perl script or GUI)
handle all user input and then just feed a "template" file into B<req> which
then silently creates the request or certificate. This would also shift the
responsibility for handling such problems as internationalisation of characters
onto the front end: the template could then just expect valid UTF8 character
strings for example.
=head1 SEE ALSO
x509(1), ca(1), genrsa(1), gendsa(1), config(5)
=cut

135
doc/man/rsa.pod Normal file
View file

@ -0,0 +1,135 @@
=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<-out filename>]
[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 RSAPublicKey format. The B<PEM>
form is the default format: it consists of the B<DER> format base64 encoded with
additional header and footer lines. 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<-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<-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 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 CAVEATS
It should be possible to read or produce PKCS#8 format encrypted RSA keys:
at present it isn't.
=head1 SEE ALSO
pkcs8(1), dsa(1), genrsa(1), gendsa(1)
=cut

56
doc/man/version.pod Normal file
View file

@ -0,0 +1,56 @@
=pod
=head 1 NAME
version - print version information
=head1 SYNOPSIS
=item 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

400
doc/man/x509.pod Normal file
View file

@ -0,0 +1,400 @@
=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<-clrnotrust>]
[B<-addtrust arg>]
[B<-addnotrust 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 AND OUTPUT 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.
=back
=head1 DISPLAY OPTIONS
Note: the B<-alias> and B<-purpose> options are also display options
but are desribed 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 issuer name. This is used in OpenSSL to
form an index to allow certificates in a directory to be lookup up by issuer
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 MD5 digest 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.
Adding trust settings modifies this behaviour: if a certificate is being
verified and one of the certificate chain is marked as trusted for that
specific purpose then the verify succeeds without looking up any more
certificates. Similarly if the use is prohibited then the certificate
is automatically rejected. If a purpose is neither permitted nor prohibited
then the certificate extensions are checked for consistency with the required
purpose and the process continues.
If a root CA is reached then it must be marked as trusted for the required
purpose or the verify fails.
See the description of the B<verify> utility for more information on the
meaning of trust settings.
=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 reffered 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<-clrnotrust>
clears all the prohibited or untrusted uses of the certificate.
=item B<-addtrust arg>
adds a trusted certificate use. Currently acceptable values
are all (any purpose), sslclient (SSL client use), sslserver
(SSL server use) email (S/MIME email) and objsign (Object signing).
=item B<-addnotrust 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. It checks to see if the certificate can be used as an
end user or CA certificate for various purposes. Since many commercial
certificates have invalid extensions it is possible that warnings will
be output for some certificates. Known problems have work arounds added.
=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<-md2|-md5|-sha1|-mdc2>
the digest to sign with. It affects all commands that sign a certificate
or request.
=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
Displa the certificate serial number:
openssl x509 -in cert.pem -noout -serial
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 certifcate 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 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 are 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)
=cut