Introducing SSL and Certificates using SSLeay

Abstract

Security is important on the Web.
Whether sharing financial, business, or personal information,
people want to know with whom they are communicating
(authentication), they want to ensure that what is sent is what
is received (integrity), and they want to prevent others from
intercepting what they are communicating (privacy).
The Secure Sockets Layer protocol
[13]
provides one means for achieving these goals and is the subject of this
article.
We introduce SSL by reviewing cryptographic
techniques and by discussing certificates.
We then describe SSL and packages for implementing SSL.
We conclude with examples of how to use SSLeay, the free
implementation of SSL by Eric Young. We
use the SSLeay toolkit to create
a Certificate Authority, as well as server and client certificates.

1. Introduction

An introduction to SSL, this article is aimed at
readers who are familiar with the Web, HTTP, and Web
servers, but are not security experts.
It is not intended to
be a definitive guide to the SSL protocol, nor does it discuss
specific servers, techniques for managing certificates in an
organization, or the important legal issues of patents and
import and export restrictions *.
Rather, this article guides users in implementing SSL, and pulls together
various concepts, definitions, and examples as a starting point for further
exploration.

2. Cryptographic Techniques

Understanding SSL requires an understanding of cryptographic algorithms,
message digest functions, and digital signatures. These techniques are the
subject of entire books [8], and provide
the basis for privacy, integrity, and authentication.

Cryptographic Algorithms

Suppose Alice wants to send a message to her bank to transfer some money.
Alice would like the message to be private, since it will include
information such as her account number and transfer amount.
One solution is to use a cryptographic algorithm, a technique that would
transform her message into an encrypted form,
unreadable except by those it is intended for.
Once in this form,
the message may only be interpreted
through the use of a secret key. Without the key the
message is useless: good cryptographic algorithms
make it so difficult for intruders to decode the original text
that it isn't worth their effort.

There are two categories of cryptographic algorithms:
conventional and public key.

Conventional cryptography, also known as symmetric
cryptography, requires the sender and receiver to share a key: a secret
piece of information that may be used to encrypt or decrypt a message.
If this key is secret, then nobody other than the sender or receiver may
read the message. If Alice and the bank know a secret key, then they
may send each other private messages. The task of privately choosing a key
before communicating, however, can be problematic.

Public key cryptography,
also known as asymmetric cryptography,
solves the key exchange problem by defining
an algorithm
which uses two keys, each of which may be used to encrypt a message.
If one key is used to encrypt a message then the other must
be used to decrypt it.
This makes it possible to receive secure messages
by simply publishing one key
(the public key) and keeping the other secret (the private key).
Anyone may encrypt a message using the public key, but only the
owner of the private key will be able
to read it.
In this way, Alice may send private messages to the owner of a key-pair
(the bank),
by encrypting it using their public key.
Only the bank will be able to decrypt it.

Message Digests

Although Alice may encrypt her message to make it private,
there is still a concern
that someone might modify her original message message or
substitute it with a different one, in order to transfer the money to
themselves, for instance.
One way of guaranteeing the integrity of Alice's message is to create
a concise summary of her message and send this to the bank as well.
Upon receipt of the mesage, the bank creates its own summary and compares
it with the one Alice sent. If they agree then the message was
received intact.

A summary such as this is called a message digest,
or one-way hash. Message
digests are used to create short,
fixed-length representations of longer, variable-length messages.
Digest algorithms are designed to produce unique digests for
different messages.
Message digests are designed to
make it too difficult to determine the message
from the digest, and also impossible
to find two different messages which create the same digest -- thus
eliminating
the possibility of substituting one message for another while maintaining
the same digest.

Another challenge that Alice faces is finding a way to
send the digest to the bank securely; when this is achieved, the
integrity of the associated message is assured. One way to to this is to
include the digest in a digital signature.

Digital Signatures

When Alice sends a message to the bank, the bank needs to ensure
that the message is really from her, so an intruder does not request a
transaction involving her account.
A digital signature, created by Alice and included with the message,
serves this purpose **.

Digital signatures are created by encrypting a digest of the message,
and other information (such as a sequence number) with the sender's
private key. Though anyone may decrypt
the signature using the public key, only the signer knows the private key.
This means that only they may have signed it.
Including the digest in the signature means the signature is only good
for that message; it also ensures the integrity of the message since no
one can change the digest and still sign it.
To guard against interception and reuse of the signature by an intruder
at a later date, the signature contains a
unique sequence number. This protects the bank from a fraudulent
claim from Alice that she did not send the message -- only she could have
signed it (non-repudiation).

3. Certificates

Although Alice could have sent a private message to the bank, signed it,
and ensured the integrity of the message, she still
needs to be sure that she is really communicating with the bank.
This means that she needs to be sure that the public key she is using
corresponds to the bank's private key.
Similarly, the bank also needs to verify
that the message signature really corresponds to Alice's signature.
If each party has a
certificate which validates the other's identity, confirms the public key,
and is signed by a trusted agency,
then they both will be assured that they are
communicating with whom they think they are. Such a trusted agency
is called a Certificate Authority, and certificates are used for
authentication.

Certificate Contents

A certificate associates a public key with the real identity of
an individual, server, or other entity, known as the subject.
As shown in Table 1,
information about the subject includes identifying
information (the distinguished name), and the public key.
It also includes the identification and signature
of the Certificate Authority that issued the certificate, and
the period of time during which the certificate is valid. It may have
additional information (or extensions) as well as
administrative information for the Certificate Authority's
use, such as a serial number.

Table 1: Certificate Information

Subject

Distinguished Name, Public Key

Issuer

Distinguished Name, Signature

Period of Validity

Not Before Date, Not After Date

Administrative Information

Version, Serial Number

Extended Information

A distinguished name is used to provide an identity in a specific context
-- for instance, an individual might have a personal certificate as well as
one for their identity as an employee.
Distinguished names are defined by the X.509 standard
[2], which defines
the fields, field names, and abbreviations used to refer to
the fields (Table 2).

Table 2: Distinguished Name Information

Field

Abbreviation

Description

Example

Common Name

CN

Name being certified

CN=Frederick Hirsch

Organization or Company

O

Name is associated with thisorganization

O=The Open Group

Organizational Unit

OU

Name is associated with this organization unit, such as a
department

OU=Research Institute

City/Locality

L

Name is located in this City

L=Cambridge

State/Province

SP

Name is located in this State/Province

SP=Massachussetts

Country

C

Name is located in this Country(ISO code)

C=US

A Certificate Authority may define a
policy specifying which distinguished field names are optional,
and which are required. It may also place requirements upon the field
contents, as may users of certificates. As an example, a Netscape browser
requires that the Common Name for a certificate representing a server
have a name which matches a regular expression for the domain name of that
server, such as *.opengroup.org.

The binary format of a certificate is defined using the ASN.1 notation
[ 1],
[4].
This notation defines how to specify the contents, and encoding rules
define how this information is translated into binary form.
The binary encoding of
the certificate is defined using Distinguished Encoding Rules (DER),
which are based on the more general Basic Encoding Rules (BER).
For those transmissions which cannot handle binary,
the binary form may be translated into an ASCII form
by using base64 encoding. This encoded
version is called PEM encoded, when placed between the following lines:

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

Certificate Authorities

By first verifying the information in a certificate request
before granting the certificate,
the Certificate Authority assures
the identity of the private key owner of a key-pair.
For instance, if Alice requests a personal certificate,
the Certificate Authority must first make sure that Alice really is
the person the certificate request claims.

Certificate Chains

A Certificate Authority may also issue a certificate for another
Certificate Authority. When examining a certificate, Alice may need
to examine the certificate of the issuer, for each parent Certificate
Authority, until reaching one which she has confidence in. She may decide
to trust only certificates with a limited chain of issuers, to reduce her
risk of a "bad" certificate in the chain.

Creating a Root Level Certificate Authority

As noted earlier,
each certificate requires an issuer to
assert the validity of the identity of the certificate subject, up to
the top-level Certificate Authority. This presents a problem: Since this is
who vouches for the certificate of the top-level authority, which has
no issuer?
In this unique case, the certificate is "self-signed", so the issuer of the
certificate is the same as the subject.
As a result, one must exercise extra care in trusting a self-signed
certificate. The wide publication of a public key by the root authority
reduces the risk in trusting this key -- it would be obvious if someone
else publicized a key claiming to be the authority.
Browsers are preconfigured to trust well-known certificate authorities.

A number of companies, such as VeriSign
[11]
have established themselves as certificate authorities.
These companies provide the following services:

Verifying certificate requests

Processing certificate requests

Issuing and managing certificates

It is also possible to create your own Certificate Authority.
Although risky in the Internet environment, it may be useful
within an Intranet
where the organization can easily verify the identities of
individuals and servers.

Certificate Management

Establishing a Certificate Authority
is a responsibility which requires a solid administrative, technical, and
management framework.
Certificate Authorities not only issue certificates, they also manage
them -- that is,
they determine how long certificates are valid, they renew them, and they
keep lists of certificates that have already been issued but are no longer
valid (certificate revocation lists, or CRLs).
Say Alice is entitled to a certificate
as an employee of a company. Say too, that the certificate
needs to be revoked when Alice leaves the company.
Since certificates
are objects that get passed around, it is impossible to tell from
the certificate alone that it has been revoked.
When examining certificates
for validity, therefore, it is necessary to contact the issuing Certificate
Authority to check CRLs -- this is not usually
an automated part of the process.

NOTE

If you use a Certificate Authority that is not configured into browsers
by default, it is necessary to load the Certificate Authority certificate
into the browser, enabling the browser to validate server certificates signed
by that Certificate Authority. Doing so may be dangerous, since once
loaded, the browser will accept all certificates signed by that Certificate
Authority.

4. SSL

The Secure Sockets Layer protocol (SSL) is a protocol layer which may be
placed between a reliable connection-oriented network layer protocol
(e.g. TCP/IP) and the
application protocol layer (e.g. HTTP). SSL provides for secure
communication between client and server by allowing mutual authentication,
the use of digital signatures for integrity, and encryption for
privacy.

The protocol is designed to support a range of choices for
specific algorithms used for cryptography, digests, and signatures. This
allows algorithm selection for specific servers
to be made based on legal, export or other concerns, and also
enables the protocol to take advantage of new algorithms. Choices are
negotiated between client and server at the start of establishing a
protocol session.

There are a number of versions of the SSL protocol, as shown in Table 3.

As noted in Table 3, one of the benefits in SSL 3.0 is that it adds
support of certificate chain loading.
This feature allows a server to pass a server certificate along with issuer
certificates to the browser. Chain loading also permits the browser to
validate the server certificate, even if Certificate Authority certificates
are not installed for the intermediate issuers, since they are included
in the certificate chain. SSL 3.0 is the basis for the Transaction Layer
Security [TLS]
protocol standard, currently in development by the
Internet Engineering Task Force (IETF).

Session Establishment

The SSL session is established by following a handshake sequence between
client and server, as shown in Figure 1.
This sequence may vary, depending on whether the server
is configured to provide a server certificate or request a client
certificate.
Though cases exist, where additional handshake steps are
required for management of cipher information, this article summarizes
one common scenario: see the SSL specification for the full range of
possibilities.

Note

Once an SSL session has been established
it may be reused, thus avoiding the performance penalty of
repeating the many steps needed to start a session.

The elements of the handshake sequence, as used by the client and server,
are listed below:

Negotiate the Cipher Suite to be used during data transfer

Establish and share a session key between client and server

Optionally authenticate the server to the client

Optionally authenticate the client to the server

Figure 1: Simplified Handshake Sequence

The first step, Cipher Suite Negotiation, allows the client and server to
choose a Cipher Suite supportable by both of them.
The SSL3.0 protocol specification defines 31 Cipher Suites. A Cipher Suite
is defined by the following components:

Key Exchange Method

Cipher for Data Transfer

Message Digest for creating the Message Authentication Code (MAC)

These three elements are described in the sections that follow.

Key Exchange Method

The key exchange method defines how the shared secret symmetric
cryptography key used for application data transfer will be agreed
upon by client and server. SSL 2.0 uses RSA key exchange, while SSL 3.0
supports a choice of key exchange algorithms including the RSA key
exchange when certificates are used, and Diffie-Hellman key exchange
for exchanging keys without certificates and without prior communication
between client and server [5].

One variable in the choice of key exchange methods
is digital signatures -- whether or not to use them, and if so,
what kind of signatures to use.
Signing with a private key provides assurance
against a man-in-the-middle-attack during the information exchange
used in generating the shared key [8, p516].

Cipher for Data Transfer

SSL uses the conventional cryptography algorithm (symmetric cryptography)
described earlier for
encrypting messages in a sesson.
There are nine choices, including the choice to perform no encryption:

No encryption

Stream Ciphers

RC4 with 40-bit keys

RC4 with 128-bit keys

CBC Block Ciphers

RC2 with 40 bit key

DES40, DES, 3DES_EDE.

Idea

Fortezza

"CBC" refers to Cipher Block Chaining, which means that a portion of the
previously encrypted cipher text is used in the encryption of the current
block. "DES" refers to the Data Encryption Standard
[8, ch12], which has a number of variants
(including DES40 and 3DES_EDE). "Idea" is one of the best and
cryptographically strongest available algorithms, and "RC2" is
a proprietary algorithm from RSA [8, ch13].

Digest Function

The choice of digest function determines how a digest is created
from a record unit. SSL supports the following:

No digest (Null choice)

MD5, a 128-bit hash

Secure Hash Algorithm (SHA), a 160-bit hash
designed for use with the Digital Signature Standard (DSS)
[5].

The message digest is used to create a Message Authentication Code (MAC)
which is encrypted with the message to provide integrity and to prevent
against replay attacks.

Handshake Sequence Protocol

The handshake sequence uses three protocols:

The "SSL Handshake Protocol"
for performing the client and server SSL session establishment.

The "SSL Change Cipher Spec protocol" for actually establishing agreement
on the Cipher Suite for the session.

The "SSL Alert Protocol" for
conveying SSL error messages between client and server.

These protocols, as well as application protocol data, are
encapsulated in the "SSL Record Protocol", as shown in
Figure 2.
An encapsulated protocol is
transferred as data by the lower layer protocol, which does not examine the
data. The encapsulated protocol has no knowledge of the underlying
protocol.

Figure 2: SSL Protocol Stack

The encapsulation of SSL control protocols by the record protocol means
that if an active session is renegotiated the control protocols will be
transmitted securely. If there were no session before, then the NULL cipher
suite is used, which means there is no encryption and messages have
no integrity digests until the session has been established.

Data Transfer

The SSL Record Protocol, shown in Figure 3,
is used to transfer
application and SSL Control
data between the client and server, possibly
fragmenting this data into smaller units, or combining multiple higher
level protocol data messages into single units. It may compress, attach
digest signatures, and encrypt these units before transmitting them using
the underlying reliable transport protocol.

Figure 3: SSL Record Protocol

Securing Web HTTP Communication

One common use of SSL is to secure Web HTTP communication between a browser
client and a Web server. This case does not preclude the use of non-secured
HTTP. The secure version uses URLs that begin with https rather than
http, and a different server port (by default 443).
The browser will maintain client certificate private keys when they are
generated, and display an indicator if a secure connection is being used.

Implementing SSL

Although one might write an SSL implementation from scratch following the
specification, it is much easier to use one of the existing SSL toolkit
libraries. In addition, because of patents, it is usually necessary to
license some of the cryptography libraries, at least in the United States.
SSL toolkits include encryption, message
digest, and certificate management routines. Each also requires the use
of a licensed public key package in the United States, from Security
Dynamics (Originally available from the Public Key
Partners [RFC1170] and then from RSA, which was acquired by Security
Dynamics
[17]
.)

The RSA Reference implementation, an unsupported source code toolkit from RSA,
may be used for freeware and non-commercial
applications. Consensus Development Corp used to market a license
for commercial use but will no longer do so
[17].

These two public key implementations include a complete toolkit of
public key algorithms (including RSA encryption and
Diffie-Hellman key exchange), symmetric encryption algorithms, and digest
functions. They may be used with SSL Toolkits,
the most prominent of which include the following:

SSLeay-0.8.1 [21] is a free
non-commercial implementation of SSL 2.0 and 3.0.
It includes a public key implementation which may be used
outside the United States. In the United States, RSARef or BSAFE3.0 must be
used due to patent requirements. SSLeay offers an inexpensive way to get
started with SSL, and is the subject of the next section.

6. SSLeay Examples

This section offers examples for creating a Certificate Authority,
as well as requesting, signing, and using certificates with SSLeay.
The
Appendix offers
brief instructions for
installing SSLeay, establishing the SSLeay
certificate environment, information on the
SSLeay configuration file,
and sample HTML pages and CGI scripts.
SSLeay 0.6.6 supports SSL 2.0, and SSLeay-0.8.1 supports both
SSL 2.0 and 3.0.
SSL 2.0 is widely
implemented and interoperation is easier than with SSL 3.0;
we use SSLeay with SSL 2.0 in the examples that follow.

a. Creating a Self-Signed CA Certificate

The first step in creating a Certificate Authority (apart from designing
the management, administrative and legal framework) is to create a
self-signed certificate for the Certificate Authority. This is done in
SSLeay by running the req command
(see Example 5 in the Appendix).
This command produces a
certificate file (CAcert.pem) and key file (CAkey.pem).
The CA certificate and key files must remain in $SSLDIR/private,
which is where SSLeay will look for them by default (as specified in the
ssleay.cnf CA default section),
both when acting as a certificate authority, and also when used by the
server to implement SSL and validate client certificates signed by the CA.

Install the self-signed certificate in a browser so the browser will
recognize server
certificates signed by the Certificate Authority. Installing a CA
certificate in a browser is somewhat dangerous, unless you trust
that certificate and the security of the Certificate Authority.
Once installed, the browser accepts any certificate signed by
that authority.

To install the CA certificate, load it using HTTP
Content-Type application/x-x509-ca-cert. To do
this in a manner which does not depend on the server, use the
cgi-script (Example 6 in the Appendix),
or save the certificate in a file with a
cacert suffix and define this suffix in the server
configuration file to correspond to the
application/x-x509-ca-cert
MIME type. For the Apache server, for example, add the line AddType
application/x-x509-ca-cert cacert to srm.conf. The
certificate and key files must also remain available to SSLeay for
the server to be able to use the public key, and the certificate
authority to use the private key.

b. Creating a Server Certificate

A server certificate
authenticates the server to the client. To make a server
certificate, create a certificate request, sign it with the
self-signed CA certificate, and then install the certificate as follows:

Use the "req" command to
create a new certificate request with SSLeay
(See Example 8 in the Appendix).
This command creates files containing a certificate request
and the private key.

Sign the request using the "ca" command
(see Example 11 in the Appendix).
This will produce a file containing the certificate.

Copy the certificate and key files to the
server certificate directories.

Update the server configuration file to specify that this is the
server certificate to use.

In order to easily find certificates, SSLeay uses hashes of the certificate
subject names. Thus, when looking for the certificate of the issuer
of a certificate, it looks for a file named with the hash value of the
issuer name. The avoids opening files and examining certificates to find a
match. The SSLeay x509 command may be used to manipulate certificates;
one option is to create a hash of the subject name.

Once these steps have been completed, an SSL
connection may be established if the server does not require client
certificates.

b. Creating a Client Certificate

A client certificate is used to authenticate a client to a server.
Creating and installing a client certificate
is more difficult than creating a server
certificate because the client must generate a key-pair, keep the
private key to itself, and send the public key to the certificate
authority to be incorporated into a certificate request. Once a signed
certificate has been created using the Certificate Authority, this client
certificate must be installed in the client so that the client may
present it when needed.

Different clients such as Netscape Navigator 3.01 Gold and Microsoft Internet
Explorer 3.02 support different mechanisms for creating client
certificates.
In this section, we demonstrate a technique for creating and installing
a client certificate for each, using SSLeay certificate routines to
sign certificate requests
(Back up the Windows NT registry before creating
client certificates with Internet Explorer).

The procedure for creating a client certificate
involves HTML forms; these forms include
client specific features such as special tags or JavaScript programs,
and Perl CGI scripts that call SSLeay certificate handling applications.
The procedures do not rely on special server features, other than the
ability to run Perl CGI scripts. The examples completely automate the
process, causing a client certificate to be installed once the request
form is submitted. (In a production environment the Certificate Authority
would need to perform validation instead of automatically issuing the
certificate.)

The general steps for creating a client certificate are
as follows:

User requests HTML page that displays form on client

User enters identification inoformation

Submission of the form causes the following sequence to occur:

Browser generates a key pair (public and private key)

Private key is stored in browser

Public key is sent with identification information to the server

Server CGI script creates certificate and loads it into the client

The HTML form includes fields (containing defaults) for the different
distinguished name attributes which are to be used in the client
certificate, information allowing the browser
to generate a key-pair, and a hidden field used to return this
information to the CGI script.
This hidden information is browser dependent.

In
Netscape Navigator, the form contains an additional FORM
tag, the <KEYGEN> tag. This tag creates a key pair,
and causes the public key to be
returned as a form value when the form is submitted
(see Example 12 in the Appendix for source of a
sample form).
The <KEYGEN> tag causes the browser to display a
choice of security grades, depending on the version of Navigator.
All of the form information is used by the CGI script to create a
certificate request, and this request is used to create a client
certificate (See Figure 4).

Figure 4: Sample Netscape Navigator User Certificate Form

The Microsoft Internet Explorer HTML form in
Figure 5 is more complicated,
because
Internet Explorer requires a JavaScript (or Visual Basic) program in the
page to use an ActiveX control to generate a key pair and create a
certificate request. The JavaScript program is downloaded with the
HTML page, and called when you press the Submit form button.
The program calls the GenReqForm method of the
certenr3 ActiveX control, passing it the distinguished name values
from the
form. The certificate request produced by the control is then loaded
into a hidden field of the form, and returned with the form values
to the server CGI script
(see Example 15 in the Appendix for a sample HTML
page).

Figure 5: Sample Internet Explorer User Certificate Form

Both Netscape Navigator and Microsoft Internet Explorer present a sequence
of dialogs as part of the key-pair creation. If this sequence is
sucessfully completed then the form will cause the server CGI script
to be called with the data from the form. Examples 13 and 15 in the
Appendix present two CGI
scripts, one for each browser, since the processing is different.

The CGI script for Netscape Navigator
(Example 14 in the Appendix) creates a file containing the
distinguished name values returned by the form, and a special
SPKAC value for the "Signed Public Key And Challenge"
generated by Navigator The "ca" command is called with this file as
an argument to generate a client certificate. If successful this is
returned by the CGI script as an application/x-x509-user-cert
HTTP Content-Type. Navigator recognizes this type, and prompts the
user for the remainder of the steps required to install the
user certificate in the browser.
(See Example 13 for the sample CGI script for
Netscape Navigator).

The CGI script for processing the Internet Explorer request
(Example 16 in the Appendix) is more
complicated.
It takes the certificate request returned by the form
and reformats it to conform to lines of length 72, and then uses the
SSLeay ca command to create a signed user certificate based on this
request. It then takes the client certificate and combines it with
the SSLeay certificate revocation list (CRL) to create a PKCS#7 certificate
using the SSLeay crl2pkcs7 utility.
The CGI Perl script then dynamically
creates an HTML page which includes a JavaScript program to call the
AcceptCredentials method of the certenr3
ActiveX control to install
the PKCS#7 certificate.
This page is designed to take advantage of the
JavaScript onLoad method to automatically call the
JavaScript program when the page is loaded, so that the certificate is
immediately installed without user interaction.
(In a production system such automatic installation may not be desired.)

NOTE

Although I was able to establish an SSL connection using client
certificates with Netscape Navigator, and estalish an SSL connection with
a VeriSign client certificate and the
VeriSign client certificate test page, I was unable
to establish an SSL client-certificate connection using my client
certificate with Microsoft Internet Explorer. The reason for this
discrepancy will require more research or additional information from
Microsoft.

Once the HTML forms and CGI scripts have been written, and the ActiveX
control installed, the process of creating client certificates using
SSLeay is simple for users.

Configuring a Server and Establishing an SSL connection

The server must have a server certificate installed, and the server's CA
certificate must have been installed in the browser. The server will only
request a client certificate from the browser if it is required in the
server configuration file. Apache uses the following directive in
httpd.conf :

# Set SSLVerifyClient to:
# 0 if no certicate is required
# 1 if the client may present a valid certificate
# 2 if the client must present a valid certificate
# 3 if the client may present a valid certificate but it is not required to
# have a valid CA
SSLVerifyClient 0

An SSL connection is established by requesting a URL from the browser of
the form "https://example.opengroup.org/", where the domain refers to the
server which supports SSL.

Conclusion

SSL uses encryption, message digests, digital signatures and certificates
to implement a protocol layer for providing privacy, integrity
and authentication to application protocols such as HTTP. This is valuable
in the Web since it will allow a much greater degree of secure
communication than is available without SSL. A number of toolkits exist
for implementing SSL, including SSLeay. These toolkits also provide the
facilities for creating ones own Intranet Certificate Authority and
managing certificates. Many issues exist with respect to certificates,
including those of certificate revocation and expiration, as well
as management issues. Undoubtedly the remaining issues involved in the
management of certificates and Web security will be addressed, but an
implementation of SSL using SSLeay permits much more confidence in Web
communications.

Appendix

This appendix offers a number of examples for certificate
management using SSLeay.
The CGI scripts assume you are using Apache
(tested with 1.2b7). If you have trouble it might be due to a CGI.pm
version issue. The scripts in these examples also assume that the server
installation directory includes the following subdirectories:

htdocs (standard document root)

cgi-bin (standard CGI directory)

certs (new directory for certificate processing)

When the scripts operate they create files containing certificate
requests, and certificates.

SSLeay Installation

We have experimented using SSLeay and RSARef on UNIX with
the Secure Domain Gateway, a special SSL web server that interfaces
with the Distributed Computing Environment (DCE).
We have also experimented using Apache-SSL
(apache_1.2b10+ssl_1.6.tar).
The following examples assume that you are building SSLeay under UNIX
(e.g. HP-UX) but
it is possible to build SSLeay on other platforms such as Windows NT.
The SSLeay-0.8.1 distribution is obtained as a tar file (SSLeay-0.8.1.tar).
Extracting from the tar file will
create a new directory, SSLeay-0.8.1 in which SSLeay is built.

The following examples assume
you are working in the SSLeay-0.8.1 directory.
Change to this directory and
build SSLeay following the directions in the INSTALL file.
The examples assume that the results of building SSLeay are installed in
$SSLDIR (e.g. /opt/dev/ssl).

SSLeay uses a configuration file
(ssleay.cnf) which supports named sections, so one configuration
file may
be used for several purposes. We have modified this file, and show some
of these modifications in the examples that follow.
Subsequent descriptions in this
document show various relevant sections of the log file.

Note that the addition of SSL to the server requires rebuilding the server
to include the SSL toolkit and public key sources, and modifying the server
configuration to support SSL.

The SSLeay Certificate Environment

Before using SSLeay, create an environment for managing
certificates, update the SSLeay configuration file,
and update the server configuration file.
Establish the SSLeay certificate management environment using
the sequence in Example 1.

The SSLeay Configuration File

The SSLeay configuration file (ssleay.cnf) has multiple sections.
These configuration sections must be updated before the certificate
authority may be used, especially the dir specification in the
certificate authority configuration shown in Example 2. The dir
specification value should be the same as $SSLDIR
(e.g. /opt/dev/ssl).

Example 2 SSLeay Configuration File: ca section

####################################################################
[ ca ]
default_ca = CA_default # The default ca section
####################################################################
[ CA_default ]
dir = /opt/dev/ssl # Where everything is kept
certs = $dir/certs # Where the issued certs are kept
crl_dir = $dir/crl # Where the issued crl are kept
database = $dir/index.txt # database index file.
new_certs_dir = $dir/newcerts # default place for new certs.
certificate = $dir/private/CAcert.pem # The CA certificate
serial = $dir/serial # The current serial number
crl = $dir/clr/crl.pem # The current CRL
private_key = $dir/private/CAkey.pem # The private key
RANDFILE = $dir/private/.rand # private random number file
x509_extensions = x509v3_extensions # The extentions to add to the cert
default_days = 365 # how long to certify for
default_crl_days= 30 # how long before next CRL
default_md = md5 # which md to use.
preserve = no # keep passed DN ordering
# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy = policy_match

The "req" section of the configuration file is used when creating
certificate requests, and supplies defaults and length limits for the
various distinguished name fields. In our examples it has the configuration
as shown in Example 3.

The policy section of the configuration file is used to define
different certificate request signing policies. The examples here
include the most lenient policy (policy_anything) and a
stricter policy (policy_match) which restricts the values of
certificate fields. The purpose of a policy is to guide
processing of a certificate request.

In Example 4, match means that the value of the field in the request
must match the value in the CA certificate, or the request will not be
signed. optional means the the field need not be present, while
supplied means
that it must be present in the certificate request.

Creating a Self-Signed CA certificate

The SSLeay req command creates a self-signed certificate when the
-x509 switch is used. The certificate is placed in the file
CAcert.pem,
and the private key in CAkey.pem.
This command prompts for the password
(e.g. caKEY) for the private key, and is used as shown in Example 5.

Example 5: Creating a Self-Signed CA Certificate

$SSLDIR/bin/ssleay req -new -x509 -keyout ${SSLDIR}/private/CAkey.pem \
-out ${SSLDIR}/private/CAcert.pem -config /opt/www/lib/ssleay.cnf
Using configuration from /opt/www/lib/ssleay.cnf
Generating a 512 bit private key
writing new private key to '../private/CAkey.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be incorperated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [US]:
State or Province Name (full name) [MA]:
Locality Name (eg, city) [Cambridge]:
Organization Name (eg, company) [The Open Group]:
Organizational Unit Name (eg, section) [Research Institute]:
Common Name (eg, YOUR name) [example.osf.org]:Example CA
Email Address []:f.hirsch@opengroup.org

The SSLeay configuration file specifies the location of the CA certificate
and key files using the following directives in the ca section:

Loading a CA certificate into a browser using a CGI script

Load the CA certificate into the browser by accessing an HTML form
like that in Example 6. This form calls a CGI script to
load the certificate
using the application/x-x509-ca-cert MIME type as the Content-Type.

Install the Certificate Authority certificate in the server
certificate database as well as the browser,
so that the server is able to locate the
public key and validate certificate signatures signed by the certificate
authority.

Server Certificates

Creating a Certificate Request

The SSLeay req command is used to create a
PKCS#10 (Public-Key Cryptography Standards
[3])
certificate request.
It also generates a key pair when -new is specified, and may
indicate the length of time the certificate is valid with the -days
switch. SSLeay prompts for a new password for this certificate (call it
siteKEY). A certificate request may be created as shown in Example 8.

Example 8: Using SSLeay to Create Certificate Request

cd $SSLDIR/bin
./ssleay req -new -keyout newkey.pem -out newreq.pem -days 360\
-config /opt/www/lib/ssleay.cnf
Using configuration from /opt/www/lib/ssleay.cnf
Generating a 512 bit private key
writing new private key to 'newkey.pem'
Enter PEM pass phrase:
Verifying password - Enter PEM pass phrase:
-----
You are about to be asked to enter information that will be incorperated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [US]:
State or Province Name (full name) [MA]:
Locality Name (eg, city) [Cambridge]:
Organization Name (eg, company) [The Open Group]:
Organizational Unit Name (eg, section) [Research Institute]:
Common Name (eg, YOUR name) [example.osf.org]:
Email Address []:f.hirsch@opengroup.org
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

Example 9 shows the results in a certificate request being
created in newreq.pem
(in this paper certificates and keys are truncated).

Signing a Certificate Request

A server certificate is created by signing the certificate request using
the SSLeay ca command. The -policy
switch specifies the section of the SSLeay configuration file
that defines which distinguished name fields are required, and the order
of the fields. As an example, our test configuration file specifies the
policy_anything section which makes
all the listed distinguished name fields optional.

When this command is executed, it prompts for the certificate
authority password, as shown in Example 11.

The Apache-SSL httpd.conf file must be modified to specify the server
certificate and key files as follows:

# Point SSLCertificateFile at a PEM encoded certificate.
SSLCertificateFile /opt/www/lib/certs/sitecert.pem
# If the key is not combined with the certificate, use this directive to
# point at the key file. If this starts with a '/' it specifies an absolute
# path, otherwise it is relative to the default certificate area. That is,
# it means "/private/".
SSLCertificateKeyFile /opt/www/lib/certs/sitekey.pem

Client Certificates

Form to create Netscape Client Certificate Request

Netscape returns a "Signed Public Key And Challenge" (SPKAC) public key
when the <KEYGEN> form element is
encountered. The form in Example 13 returns this in the SPKAC hidden
field. The CGI script then accesses this field and passes the
SPKAC value to SSLeay using the -spkac switch to the ca
command. (See ns-ca.doc in the doc directory in the
SSLeay distribution).