Very preliminary POD format documentation for some

 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]

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

=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

=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

=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