path: root/doc/openssl.txt

This is some preliminary documentation for OpenSSL.

Contents:

 OpenSSL X509V3 extension configuration
 X509V3 Extension code: programmers guide
 PKCS#12 Library


==============================================================================
               OpenSSL X509V3 extension configuration
==============================================================================

OpenSSL X509V3 extension configuration: preliminary documentation.

INTRODUCTION.

For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
possible to add and print out common X509 V3 certificate and CRL extensions.

BEGINNERS NOTE

For most simple applications you don't need to know too much about extensions:
the default openssl.cnf values will usually do sensible things.

If you want to know more you can initially quickly look through the sections
describing how the standard OpenSSL utilities display and add extensions and
then the list of supported extensions.

For more technical information about the meaning of extensions see:

http://www.imc.org/ietf-pkix/
http://home.netscape.com/eng/security/certs.html

PRINTING EXTENSIONS.

Extension values are automatically printed out for supported extensions.

openssl x509 -in cert.pem -text
openssl crl -in crl.pem -text

will give information in the extension printout, for example:

        X509v3 extensions:
            X509v3 Basic Constraints: 
                CA:TRUE
            X509v3 Subject Key Identifier: 
                73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15
            X509v3 Authority Key Identifier: 
                keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00
            X509v3 Key Usage: 
                Certificate Sign, CRL Sign
            X509v3 Subject Alternative Name: 
                email:email@1.address, email:email@2.address

CONFIGURATION FILES.

The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
which certificate extensions to include. In each case a line:

x509_extensions = extension_section

indicates which section contains the extensions. In the case of 'req' the
extension section is used when the -x509 option is present to create a
self signed root certificate.

The 'x509' utility also supports extensions when it signs a certificate.
The -extfile option is used to set the configuration file containing the
extensions. In this case a line with:

extensions = extension_section

in the nameless (default) section is used. If no such line is included then
it uses the default section.

You can also add extensions to CRLs: a line

crl_extensions = crl_extension_section

will include extensions when the -gencrl option is used with the 'ca' utility.
You can add any extension to a CRL but of the supported extensions only
issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
CRL entry extensions can be displayed.

NB. At this time Netscape Communicator rejects V2 CRLs: to get an old V1 CRL
you should not include a crl_extensions line in the configuration file.

As with all configuration files you can use the inbuilt environment expansion
to allow the values to be passed in the environment. Therefore if you have
several extension sections used for different purposes you can have a line:

x509_extensions = $ENV::ENV_EXT

and set the ENV_EXT environment variable before calling the relevant utility.

EXTENSION SYNTAX.

Extensions have the basic form:

extension_name=[critical,] extension_options

the use of the critical option makes the extension critical. Extreme caution
should be made when using the critical flag. If an extension is marked
as critical then any client that does not understand the extension should
reject it as invalid. Some broken software will reject certificates which
have *any* critical extensions (these violates PKIX but we have to live
with it).

There are three main types of extension: string extensions, multi-valued
extensions, and raw extensions.

String extensions simply have a string which contains either the value itself
or how it is obtained.

For example:

nsComment="This is a Comment"

Multi-valued extensions have a short form and a long form. The short form
is a list of names and values:

basicConstraints=critical,CA:true,pathlen:1

The long form allows the values to be placed in a separate section:

basicConstraints=critical,@bs_section

[bs_section]

CA=true
pathlen=1

Both forms are equivalent. However it should be noted that in some cases the
same name can appear multiple times, for example,

subjectAltName=email:steve@here,email:steve@there

in this case an equivalent long form is:

subjectAltName=@alt_section

[alt_section]

email.1=steve@here
email.2=steve@there

This is because the configuration file code cannot handle the same name
occurring twice in the same section.

The syntax of raw extensions is governed by the extension code: it can
for example contain data in multiple sections. The correct syntax to
use is defined by the extension code itself: check out the certificate
policies extension for an example.

There are two ways to encode arbitrary extensions.

The first way is to use the word ASN1 followed by the extension content
using the same syntax as ASN1_generate_nconf(). For example:

1.2.3.4=critical,ASN1:UTF8String:Some random data

1.2.3.4=ASN1:SEQUENCE:seq_sect

[seq_sect]

field1 = UTF8:field1
field2 = UTF8:field2

It is also possible to use the word DER to include arbitrary data in any
extension.

1.2.3.4=critical,DER:01:02:03:04
1.2.3.4=DER:01020304

The value following DER is a hex dump of the DER encoding of the extension
Any extension can be placed in this form to override the default behaviour.
For example:

basicConstraints=critical,DER:00:01:02:03

WARNING: DER should be used with caution. It is possible to create totally
invalid extensions unless care is taken.

CURRENTLY SUPPORTED EXTENSIONS.

If you aren't sure about extensions then they can be largely ignored: its only
when you want to do things like restrict certificate usage when you need to
worry about them. 

The only extension that a beginner might want to look at is Basic Constraints.
If in addition you want to try Netscape object signing the you should also
look at Netscape Certificate Type.

Literal String extensions.

In each case the 'value' of the extension is placed directly in the
extension. Currently supported extensions in this category are: nsBaseUrl,
nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl,
nsSslServerName and nsComment.

For example:

nsComment="This is a test comment"

Bit Strings.

Bit string extensions just consist of a list of supported bits, currently
two extensions are in this category: PKIX keyUsage and the Netscape specific
nsCertType.

nsCertType (netscape certificate type) takes the flags: client, server, email,
objsign, reserved, sslCA, emailCA, objCA.

keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
encipherOnly, decipherOnly.

For example:

nsCertType=server

keyUsage=digitalSignature, nonRepudiation

Hints on Netscape Certificate Type.

Other than Basic Constraints this is the only extension a beginner might
want to use, if you want to try Netscape object signing, otherwise it can
be ignored.

If you want a certificate that can be used just for object signing then:

nsCertType=objsign

will do the job. If you want to use it as a normal end user and server
certificate as well then

nsCertType=objsign,email,server

is more appropriate. You cannot use a self signed certificate for object
signing (well Netscape signtool can but it cheats!) so you need to create
a CA certificate and sign an end user certificate with it.

Side note: If you want to conform to the Netscape specifications then you
should really also set:

nsCertType=objCA

in the *CA* certificate for just an object signing CA and

nsCertType=objCA,emailCA,sslCA

for everything. Current Netscape software doesn't enforce this so it can
be omitted.

Basic Constraints.

This is generally the only extension you need to worry about for simple
applications. If you want your certificate to be usable as a CA certificate
(in addition to an end user certificate) then you set this to:

basicConstraints=CA:TRUE

if you want to be certain the certificate cannot be used as a CA then do:

basicConstraints=CA:FALSE

The rest of this section describes more advanced usage.

Basic constraints is a multi-valued extension that supports a CA and an
optional pathlen option. The CA option takes the values true and false and
pathlen takes an integer. Note if the CA option is false the pathlen option
should be omitted. 

The pathlen parameter indicates the maximum number of CAs that can appear
below this one in a chain. So if you have a CA with a pathlen of zero it can
only be used to sign end user certificates and not further CAs. This all
assumes that the software correctly interprets this extension of course.

Examples:

basicConstraints=CA:TRUE
basicConstraints=critical,CA:TRUE, pathlen:0

NOTE: for a CA to be considered valid it must have the CA option set to
TRUE. An end user certificate MUST NOT have the CA value set to true.
According to PKIX recommendations it should exclude the extension entirely,
however some software may require CA set to FALSE for end entity certificates.

Extended Key Usage.

This extensions consists of a list of usages.

These can either be object short names of the dotted numerical form of OIDs.
While any OID can be used only certain values make sense. In particular the
following PKIX, NS and MS values are meaningful:

Value			Meaning
-----			-------
serverAuth		SSL/TLS Web Server Authentication.
clientAuth		SSL/TLS Web Client Authentication.
codeSigning		Code signing.
emailProtection		E-mail Protection (S/MIME).
timeStamping		Trusted Timestamping
msCodeInd		Microsoft Individual Code Signing (authenticode)
msCodeCom		Microsoft Commercial Code Signing (authenticode)
msCTLSign		Microsoft Trust List Signing
msSGC			Microsoft Server Gated Crypto
msEFS			Microsoft Encrypted File System
nsSGC			Netscape Server Gated Crypto

For example, under IE5 a CA can be used for any purpose: by including a list
of the above usages the CA can be restricted to only authorised uses.

Note: software packages may place additional interpretations on certificate 
use, in particular some usages may only work for selected CAs. Don't for example
expect just including msSGC or nsSGC will automatically mean that a certificate
can be used for SGC ("step up" encryption) otherwise anyone could use it.

Examples:

extendedKeyUsage=critical,codeSigning,1.2.3.4
extendedKeyUsage=nsSGC,msSGC

Subject Key Identifier.

This is really a string extension and can take two possible values. Either
a hex string giving details of the extension value to include or the word
'hash' which then automatically follow PKIX guidelines in selecting and
appropriate key identifier. The use of the hex string is strongly discouraged.

Example: subjectKeyIdentifier=hash

Authority Key Identifier.

The authority key identifier extension permits two options. keyid and issuer:
both can take the optional value "always".

If the keyid option is present an attempt is made to copy the subject key
identifier from the parent certificate. If the value "always" is present
then an error is returned if the option fails.

The issuer option copies the issuer and serial number from the issuer
certificate. Normally this will only be done if the keyid option fails or
is not included: the "always" flag will always include the value.

Subject Alternative Name.

The subject alternative name extension allows various literal values to be
included in the configuration file. These include "email" (an email address)
"URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
registered ID: OBJECT IDENTIFIER), IP (and IP address) and otherName.

Also the email option include a special 'copy' value. This will automatically
include and email addresses contained in