<COMMENT>(--------------------------------------------------------------------)

<CHAPTER>(Secure Sockets Layer\chapter_ssl)

<P> This section is not a tutorial on SSL.  It contains only information
relating to WASD's use of it. Refer to the listed references,
<REFERENCE>(head_ssl_ref), for further information on SSL technology.

<P> The <EMPHASIS>(Secure Sockets Layer) protocol (SSL) is designed to provide
a secure channel between two communicating applications, in the case of HTTP
between the browser (client) and the HTTPd (server).  It also authenticates
server and optionally client identity.  SSL operates by establishing an
encrypted communication path between the two applications,
<QUOTE>(wrapping) the entire application protocol inside the secure link,
providing complete privacy for the entire transaction.  In this way
security-related data such as user identification and password, as well as
sensitive transaction information can be effectively protected from
unauthorized access while in transit.

<P> <EMPHASIS>(SSL functionality is not supplied with the basic WASD
package.\BOLD)  In part this is due to the relative bulk of this component, but
also considers potential patent issues and export restrictions on some
cryptography technology in some jurisdictions.

<COMMENT>(HTML=
<P>
<TABLE BORDER=0>
<TR><TD VALIGN=top><IMG SRC="OpenSSL.gif"></TD><TD>&nbsp;&nbsp;</TD><TD>
)

<P> WASD implements SSL using a freely available software toolkit supported by
the <EMPHASIS>(OpenSSL Project\BOLD), in particular the VMS port, to which
Richard Levitte 

<COMMENT>(HTML=(<A HREF="mailto:levitte@lp.se">levitte@lp.se</A>))

<COMMENT>(HTML/OFF)
(levitte@lp.se)
<COMMENT>(HTML/ON)

and Robert Byer

<COMMENT>(HTML=(<A HREF="mailto:ByerRA@aol.com">ByerRA@aol.com</A>))

<COMMENT>(HTML/OFF)
(ByerRA@aol.com)
<COMMENT>(HTML/ON)

have been significant contributors.

<COMMENT>(HTML=
</TD></TR>
</TABLE>
)

<P> <EMPHASIS>(OpenSSL\BOLD) is a continuing development of the
<EMPHASIS>(SSLeay\BOLD) toolkit (pronounced <QUOTE>(S-S-L-E-A-Y), i.e. all
letters spelt), authored by  Eric Young and Tim Hudson. OpenSSL licensing
allows unrestricted commercial and non-commercial use. This toolkit is in use
regardless of whether the WASD OpenSSL package, HP SSL for OpenVMS Alpha, IA64
and (now - late 2003) VAX product, or other stand-alone OpenSSL environment is
installed.

<P> It is always preferable to move to the latest support release of OpenSSL
as known bugs in previous versions are progressively addressed (ignoring the
issue of new bugs being introduced ;^).

<HEAD>(Cryptography Software\head_ssl_crypto)

<P> Be aware that export/import and/or use of cryptography software, or even
just providing cryptography hooks, is illegal in some parts of the world.  When
you re-distribute this package or even email patches/suggestions to the author
or other people <EMPHASIS>(PLEASE PAY CLOSE ATTENTION TO ANY APPLICABLE
EXPORT/IMPORT LAWS\BOLD).  The author of this package is not liable for any
violations you make here.

<HEAD>(Some Thoughts From R. S. Engelschall\head_ssl_thoughts)

<P> Ralf S. Engelschall (rse@engelschall.com) is the author of the popular
Apache <EMPHASIS>(mod_ssl) package.  This section is taken from the
<EMPHASIS>(mod_ssl) read-me and is well-worth some consideration for this and
software security issues in general.

<COMMENT>(HTML=
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=15>
<TR><TD>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=10>
<TR><TD BGCOLOR="#eeeeee"><P>
)

<COMMENT>(HTML/OFF)
<P><QUOTE>
<COMMENT>(HTML/ON)

You should be very sensible when using cryptography software, because just
running an SSL server <UNDERLINE>(DOES NOT) mean your system is then secure! 
This is for a number of reasons. The following questions illustrate some of the
problems.

<LIST>(UNNUMBERED)
<LE> SSL itself may not be secure. People think it is, do you?
<LE> Does this code implement SSL correctly?
<LE> Have the authors of the various components put in back doors?
<LE> Does the code take appropriate measures to keep private keys private?  To
what extent is your cooperation in this process required? 
<LE> Is your system physically secure?
<LE> Is your system appropriately secured from intrusion over the network?
<LE> Whom do you trust?  Do you understand the trust relationship involved in
SSL certificates?  Do your system administrators? 
<LE> Are your keys, and keys you trust, generated careful[ly] enough to avoid
reverse engineering of the private keys? 
<LE> How do you obtain certificates, keys, and the like, securely?
<LE> Can you trust your users to safeguard their private keys?
<LE> Can you trust your browser to safeguard its generated private key?
<ENDLIST>

<P> If you can't answer these questions to your personal satisfaction, then you
usually have a problem.  Even if you can, you may still <UNDERLINE>(NOT) be
secure.  Don't blame the authors if it all goes horribly wrong.  Use it at your
own risk!

<COMMENT>(HTML=
</TD></TR>
</TABLE>
</TD></TR>
</TABLE>
)

<COMMENT>(HTML/OFF)
<ENDQUOTE>
<COMMENT>(HTML/ON)

<HEAD>(SSL Overhead\head_ssl_overhead)

<P> SSL <EMPHASIS>(adds a significant overhead\BOLD) to an HTTP transaction for
the following reasons.

<LIST>(UNNUMBERED)

<LE> An initial <EMPHASIS>(connection establishment), where the client and
server exchange cryptographic data and authorize the transaction.

<LE> The transaction transfer, where all <EMPHASIS>(application data) must be
processed by the CPU into an encrypted stream, and back <HELLIPSIS> very
expensive processes.

<LE> The encrypted data contains more bytes than the raw data, increasing
network transfer time.

<LE> Other miscellaneous SSL handshaking for the life of the transaction.

<ENDLIST>

<P> For these reasons <EMPHASIS>(SSL HTTP is slower and has far greater impact
on the server system CPU\BOLD) than standard HTTP and therefore should only be
used when transaction privacy is required, not as a general HTTP service.
Also, if a general HTTP and an SSL HTTP service is provided on a
multi-processor system, with one or other or both experiencing significant
traffic, then the two services should be run in separate processes.

<HEAD>(Interoperability\head_ssl_interop)

<P> WASD SSL has been used against a wide variety of browsers and certificates. 
Most combinations work.  Some do not, usually related to the level of
encryption required by some certificates precluding export-grade browsers from
connecting.

<P> To date OpenSSL certificates, and those from Thawte and VeriSign have been
deployed on WASD servers.

<P> WASD supports both 40bit, USA <QUOTE>(export-grade) encryption, as well as
<COMMENT>(HTML=<A HREF="ssl128.gif">)128-bit<COMMENT>(HTML=</A>),
<EMPHASIS>(full-strength, USA <QUOTE>(domestic-grade)\BOLD) encryption.   Note
that as of early 2000, 128-bit USA domestic-grade encryption has been generally
available due to changes in USA Federal Government export restriction policy. 
Netscape Navigator 4.73 and Microsoft Internet Explorer 5.5 and later now
provide this level of encryption as standard.

<P> The <QUOTE>(/SSL) qualifier controls which version(s) of the SSL protocol
the server will support; <QUOTE>(2), <QUOTE>(3) or <QUOTE>(23) (i.e. versions 2
and 3, also the default).  Using /NOSSL disables the SSL functionality of an
SSL executable.  There are also per-service configuration directives for
tailoring the protocol version.

<HEAD>(HTTP-to-SSL Gateway\head_ssl_gateway)

<P> The WASD proxy service can provide an HTTP-to-SSL gateway, allowing
standard HTTP clients to connect to Secure Sockets Layer services.  See
<REFERENCE>(head_proxy_gateway_ssl).

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(SSL Functionality Sources\head_ssl_sources)

<P> Secure Sockets Layer functionality is easily integrated into WASD and is
available from one (or more) of three sources.  See
<REFERENCE>(head_ssl_quick_start) for the basics of installing WASD SSL and
<REFERENCE>(head_ssl_config) for configuration of various aspects.

<LIST>(NUMBERED)

<LE> The <EMPHASIS>(HP SSL (Secure Sockets Layer) for OpenVMS
Alpha/IA64/VAX\BOLD) product

<P>

<COMMENT>(HTML=
<A HREF="http://www.openvms.compaq.com/openvms/products/ssl/ssl.html">
http://www.openvms.compaq.com/openvms/products/ssl/ssl.html</A>
)

<COMMENT>(HTML/OFF)
http://www.openvms.compaq.com/openvms/products/ssl/ssl.html
<COMMENT>(HTML/ON)

<P> This is provided from the directory

<COMMENT>(....................................................................)

<COMMENT>(HTML= 
<BLOCKQUOTE>
SYS$COMMON:[<A HREF="/sys$common/ssl/*.*">SSL</A>]
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
SYS$COMMON:[SSL]
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

containing shared libraries, executables and templates for certificate
management, etc.  If this product is installed and started up the WASD
installation and update procedures should detect it and provide the option of
compiling and/or linking WASD against it's sharable libraries.

<LE> As a separate, easily integrated <EMPHASIS>(WASD OpenSSL package\BOLD),
with OpenSSL object  libraries, OpenSSL utility object modules for building
executables and WASD support files.  It requires no compilation, only linking,
and is available for Alpha, IA64 (Itanium) and VAX for VMS version 6.0 up to
current.  Obtain these from the same source as the main package.

<P> WASD SSL installation creates an OpenSSL directory in the source

<COMMENT>(....................................................................)

<COMMENT>(HTML=area 
<BLOCKQUOTE>
HT_ROOT:[SRC.<A HREF="/ht_root/src/">OPENSSL-n_n_n</A>]
&nbsp;(look for it here)
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
area, HT_ROOT:[SRC.OPENSSL-n_n_n],
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

containing the OpenSSL copyright notice, object libraries, object modules for
building executables, example certificates, and some other support files and
documentation.

<LE> Using a locally compiled and installed <EMPHASIS>(OpenSSL toolkit\BOLD).

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(WASD SSL Quick-Start\head_ssl_quick_start)

<P> SSL functionality can be installed with a new package, or with an update,
or it can be added to an existing non-SSL enabled site.  The following steps
give a quick outline for support of SSL.

<LIST>(NUMBERED)

<LE> If using the HP SSL for OpenVMS Alpha/IA64/VAX product or an already
installed OpenSSL toolkit go directly to step 2.  To install the WASD OpenSSL
package the ZIP archive needs to be restored.

<LIST>(UNNUMBERED)

<LE> The ZIP archive will contain brief installation instructions.  Use the
following command to read this and any other information provided.

<CODE_EXAMPLE>
  $ UNZIP -z device:[dir]archive.ZIP
<ENDCODE_EXAMPLE>

<LE> UNZIP the WASD SSL package.

<CODE_EXAMPLE>
  $ SET DEFAULT HT_ROOT:[000000]
  $ UNZIP "-V" device:[dir]archive.ZIP
<ENDCODE_EXAMPLE>

<ENDLIST>

<LE> It is then necessary to build the HTTPd SSL executables.  This can be done
in either of two ways.

<LIST>(UNNUMBERED)

<LE> During an original INSTALL or subsequent UPDATE of the entire package.  As
of v8.1 these procedures detect a suitable SSL toolkit and prompt the user
whether an SSL enabled server should be built.

<LE> To to add SSL functionality to an existing but non-SSL site just the SSL
components can be built using the following procedure.

<CODE_EXAMPLE>
  $ @HT_ROOT:[INSTALL]UPDATE SSL
<ENDCODE_EXAMPLE>

<ENDLIST>

<LE> Once linked the UPDATE.COM procedure will prompt for permission to execute
the demonstration/check procedure.

<P> It is also possible to check the SSL package at any other time using the
server demonstration procedure. It is necessary to specify that it is to use
the SSL executable.  Follow the displayed instructions.

<CODE_EXAMPLE>
  $ @HT_ROOT:[INSTALL]DEMO.COM SSL
<ENDCODE_EXAMPLE>

<LE> Modification of server startup procedures should not be necessary.  If an
SSL image is detected during startup it will be used in preference to the
standard image.

<LE> Modify the HTTPD$CONFIG configuration file to specify an SSL service. For
example the following creates both a standard HTTP service on the default port
80 and an SSL service on the default port 443

<CODE_EXAMPLE>
  [Service]
  the.host.name
  https://the.host.name
<ENDCODE_EXAMPLE>

<LE> Shutdown the server completely, then restart.

<CODE_EXAMPLE>
  $ HTTPD /DO=EXIT
  $ @HT_ROOT:[STARTUP]STARTUP
<ENDCODE_EXAMPLE>

<LE> To check the functionality (on default ports) access the server via

<LIST>(SIMPLE)

<LE> Standard HTTP
<CODE_EXAMPLE>
  http://the.host.name/
<ENDCODE_EXAMPLE>

<P>

<LE> SSL HTTP
<CODE_EXAMPLE>
  https://the.host.name/
<ENDCODE_EXAMPLE>

<ENDLIST>

<LE> Once the server has been proved functional with the example certificate
it is recommended that a server-specific certificate be created using the tools
described in <REFERENCE>(head_ssl_cert).  This may then be used by placing it
in the appropriate local directory, assigning the WASD_SSL_CERT symbol
appropriately before startup.

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(SSL Configuration\head_ssl_config)

<P> The example HTTPd startup procedure already contains support for the SSL
executable.  If this has been used as the basis for startup then an SSL
executable will be started automatically, rather than the standard
executable. The SSL executable supports both standard HTTP services (ports) and
HTTPS services (ports).  These must be configured using the [service]
parameter.  SSL services are distinguished by specifying <QUOTE>(https:) in the
parameter.  The default port for an SSL service is 443.

<P> WASD can configure services using the HTTPD$CONFIG [service] directive, the
HTTPD$SERVICE configuration file, or even the /SERVICE= qualifier. 

<HEAD2>(HTTPD$CONFIG [Service]\head_ssl_httpd_config)

<P> The following example illustrates creating two services using the
HTTPD$CONFIG [Service] directive; a standard HTTP service on the default port
80, and an SSL service on the default port 443.

<CODE_EXAMPLE>
  [Service]
  alpha.host.name
  https://alpha.host.name
<ENDCODE_EXAMPLE>

<P> The one further requirement of an SSL server is a <EMPHASIS>(certificate).
By default this is located using the HTTPD$SSL_CERT logical name during
startup, however if required, each SSL service can have an individual
certificate configured against it using the syntax shown in this example.

<CODE_EXAMPLE>
  [Service]
  alpha.host.name
  https://alpha.host.name;cert=ht_root:[local]alpha.pem
  https://beta.host.name;cert=ht_root:[local]beta.pem
<ENDCODE_EXAMPLE>

<HEAD2>(HTTPD$SERVICE\head_ssl_config_service)

<P> SSL service configuration using the HTTPD$SERVICE configuration is slightly
simpler, with a specific configuration directive for each aspect.  See
<REFERENCE>(chapter_service_directives).   This example illustrates configuring
the same services as used in the previous section.

<CODE_EXAMPLE>
  [[http://alpha.host.name:80]]

  [[https://alpha.host.name:443]]
  [ServiceSSLcert]  ht_root:[local]alpha.pem

  [[https://beta.host.name:443]]
  [ServiceSSLcert]  ht_root:[local]beta.pem
<ENDCODE_EXAMPLE>

<HEAD2>(SSL Server Certificate\head_ssl_server_cert)

<P> The server certificate is used by the browser to authenticate the server
against the server certificate Certificate Authority (CA), in making a secure
connection, and in establishing a trust relationship between the browser and
server.  By default this is located using the HTTPD$SSL_CERT logical name
during startup, however if required, each SSL service can have an individual
certificate configured against it as shown above.

<HEAD2>(SSL Private key\head_ssl_private_key)

<P> The <EMPHASIS>(private key) is used to validate and enable the server
certificate.  A  private key is enabled using a <EMPHASIS>(secret), a password. 
It is common practice to embed this (encrypted) password within the private key
data.  This private key can be appended to the server certificate file, or it
can be supplied separately.  If provided separately it is by default located
using the HTTPD$SSL_KEY logical, though can be specified on a per-service
basis.   When the password is embedded in the private key information it
becomes vulnerable to being stolen as an enabled key.  For this reason it is
possible to provide the password separately and manually.

<P> If the password key is not found with the key during startup the server
will request that it be entered at the command-line.  This request is made via
the HTTPDMON <QUOTE>(STATUS:) line (<REFERENCE>(head_httpdmon)), and if any
OPCOM category is enabled via an operator message (<REFERENCE>(head_opcom)). 
If the private key password is not available with the key it is recommended
that OPCOM be configured, enabled and monitored at all times.

<P> When a private key password is requested by the server it is supplied using
the /DO=SSL=KEY=PASSWORD directive (<REFERENCE>(head_httpd_control)).  This
must be used at the command line on the same system as the server is executing. 
The server then prompts for the password.

<CODE_EXAMPLE>
  Enter private key password []:
<ENDCODE_EXAMPLE>

<CP> The password is not echoed.  When entered the password is securely 
supplied to the server and startup progresses.  An incorrect password will be
reprompted for twice (i.e. up to three attempts are allowed) before the startup
continues with the particular service not configured and unavailable.  Entering
a password consisting of all spaces will cause the server to abort the full
startup and exit from the system.

<HEAD2>(SSL Virtual Services\head_ssl_config_virtual)

<P> Multiple virtual SSL services (https:) sharing the same certificate (and
other characteristics) can essentially be configured against any host name
(unique IP address or host name alias) and/or port in the same way as standard
services (http:).  Services requiring unique certificates can only be
configured for the same port number against individual and unique IP addresses
(i.e. not against aliases).

<P> This is not a WASD restriction, it applies to all servers for significant
technical reasons.  Secure Sockets Layer is designed to <EMPHASIS>(wrap) an
entire application protocol (in this case HTTP).  HTTP virtual services use
the <QUOTE>(Host:) field of the request header to determine which service the
client intended to use.  This requires the network connection established and
at least the request header transfered and processed.  For an SSL service
establishing the connection requires a complex transaction involving, amongst
other things, certificate exchange.  Hence, the certificate (and all other SSL
parameters) must be determined at the time the server accepts the initial
connection request.  At that point the only defining characteristics can be IP
address and port, and therefore services requiring unique certificates must be
unique either by address or port.  Services sharing certificates do not have
this restriction and so may be configured against host name aliases.

<P> For example, unique certificates for https://www.company1.com:443/ and
<COMMENT>(HTML/OFF)
<LINE>
<COMMENT>(HTML/ON)
https://www.company2.com:443/ can be configured only if COMPANY1 and COMPANY2
have unique IP addresses.  If COMPANY2 is an host name alias for COMPANY1 they
must share the same certificate.  During startup service configuration the
server checks for such conditions, forces subsequent services to use the same
SSL characteristsics as the first configured, and issues a warning about this
<QUOTE>(sharing).

<HEAD2>(SSL Access Control\head_ssl_access_control)

<P> When authorization is in place (<REFERENCE>(chapter_authorization))
access to username/password controlled data/functionality benefits enormously
from the privacy of an authorization environment inherently secured via the
encrypted communications of SSL.  In addition there is the possibility of
authentication via client X.509 certification
(<REFERENCE>(head_ssl_x509_auth)).  SSL may be used as part of the site's 
access  control policy, as whole-of-site, see <REFERENCE>(head_auth_policy), or
on a per-path basis, see  <REFERENCE>(head_mapping_conditional) and
<REFERENCE>(head_auth_access_restrict).

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(Authorization Using X.509 Certification\head_ssl_x509_auth)

<P> The server access control functionality (authentication and authorization)
allows the use of <EMPHASIS>(public key infrastructure) (PKI) X.509 v3 client
certificates for establishing  identity and based on that apply authorization
constraints.  See <REFERENCE>(chapter_authorization) for general information on
WASD authorization and <REFERENCE>(head_auth_file) for configuring a X509
realm.  <REFERENCE>(head_ssl_ref) provides introductory references on
public-key cryptography and PKI. 

<P> A client certificate is stored by the browser.  During an SSL transaction
the server can request that such a certificate be provided.  For the initial
instance of such a request the browser activates a dialog requesting the user
select one of any certificates it has installed.  If selected it is transmitted 
securely to the server which will usually (though optionally not) authenticate
it's Certificate Authority to establish it's integrity.  If accepted it can
then be used as an authenticated identity.  This obviates the use of
username/password dialogs.

<NOTE>(Important)

Neither username/password nor certificate-based authentication addresses
security issues related to access to individual machines and stored
certificates, or to password confidentiality.  Public-key cryptography only
verifies that a private key used to sign some data corresponds to the public
key in a certificate.  It is a user responsibility to protect a machine's
physical security and to keep private-key passwords secret.

<ENDNOTE>

<P> The initial negotiation and verification of a client certificate is a
relatively resource intensive process.  Once established however, OpenSSL
sessions are stored in a cache, reducing subsequent request overheads
significantly.  Each cache entry has a specified expiry period after which the
client is forced to negotiate a new session.  This period is adjustable using
the <QUOTE>([LT:integer]) and <QUOTE>([TO:integer]) directives described below.

<HEAD2>(Features\head_ssl_x509_features)

<P> WASD provides a range of capabilities when using X.509 client certificates.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(By Service - \BOLD) all SSL connections to such a
service will be requested to supply a client certificate during the initial SSL
handshake.  This is more efficient than requesting later in the transaction, as
happens with per-resource authorization.  A client cannot connect successfully
to this type of service without supplying an acceptable certificate.
                 
<LE> <EMPHASIS>(By Resource - \BOLD) using authorization rules in
the HTTPD$AUTH file specifying a path against an [X509] realm causes the server
to suspend request processing and renegotiate with the client to supply a
certificate.  If a suitable certificate is supplied the request authorization
continues with normal processing.  This obviously incurs an additional network
transaction.

<LE> <EMPHASIS>(Optional access control - \BOLD) once an acceptable certificate
is supplied it can be subject to further access control by matching against its
contents.  The <EMPHASIS>(Issuer) (CA) and the <EMPHASIS>(Subject) (client)
<EMPHASIS>(Distinguished Name) (DN) has various  components including the name
of the organization providing the certificate (e.g. <QUOTE>(VeriSign),
<QUOTE>(Thawte)), location, common name, email address, etc.  Those
certificates matching or not matching the parameters are allowed or denied
access.

<LE> <EMPHASIS>(Certificate verification - \BOLD) by default supplied
certificates have their CA verified by comparing to a list of recognised CA
certificates stored in a server configuration file.  If the CA component of the
client certificate cannot be verified the connection is terminated before the
HTTP request can begin.  Although this is obviously required behaviour for
authentication there may be other circumstances where verification is not
required, a certificate content display service for instance.  WASD optionally
allows non-verified certificates to be used on a per-resource basis.

<LE> <EMPHASIS>(<QUOTE>(Fingerprint) REMOTE_USER - \BOLD) when a certificate is
accepted by the server it generates a unique <EMPHASIS>(fingerprint) of the
certificate.  By default, this 32 digit hexadecimal number is used by the
server as an <EMPHASIS>(effective username), one that would normally be
supplied via a  username/password dialog (as an alternative see the section
immediately below).  This effective username becomes that available via the CGI
variable REMOTE_USER.  Although a 32 digit number is not particularly
site-administrator friendly it is a <UNDERLINE>(unique) representation (MD5
digest) of the individual certificate and can be used in HTTPD$AUTH
access-restriction directives and included in group lists and databases for
full WASD authorization control.

<LE> <EMPHASIS>(DN record REMOTE_USER - \BOLD) provides an alternative to using
a <QUOTE>(fingerprint) REMOTE_USER.  Using the [RU:/<EMPHASIS>(record)=]
conditional (see below) is becomes possible to specify that the remote-user
string be obtained from the specified record of the client certificate subject
field.  Note that there is a (fairly generous) size limitation on the user name
and that any white-space in such a record is converted to underscores. 
Although any record can be used the more obvious candidates are /O=, /OU=,
/CN=, /S=, /UID= and /EMAIL=.  Note that (even with the default CA verfication)
the certificate CAs that this is possible against should be further constrained
through the use of a [IS:/<EMPHASIS>(record)=<EMPHASIS>(string)] conditional
(see example below).

<ENDLIST>

<HEAD2>(X509 Configuration\head_ssl_x509_config)

<P> Of course, the WASD SSL component must be installed and in use to apply
client X.509 certificate authorization.  There is general server setup, then
per-service and per-resource configuration.

<HEAD>(General Setup\head_ssl_x509_config_general)

<P> Client certificate authorization has reasonable defaults.  If some aspect
requires site refinement the following /SSL= qualifier parameters can provide
per-server defaults.

<LIST>(UNNUMBERED)

<LE> (CACHE=integer) sets the session size (128 entries by default)
<LE> (CAFILE=file-name) sets the location of the CA verification store file
(also can be set via HTTPD$SSL_CAFILE logical).
<LE> (TIMEOUT=integer) sets the session expiry period in minutes (5 by default)
<LE> (VERIFY=integer) sets the depth to which client certificate CAs are
verified (default is 2)

<ENDLIST>

<P> The location of the CA verification file can also be determined using the
logical name HTTPD$SSL_CAFILE.  The order of precedence for using these
specifications is

<LIST>(NUMBERED)

<LE> per-service configuration using HTTPD$SERVICE or HTTPD$CONFIG
<LE> per-server using /SSL=CAFILE=filename
<LE> per-server using HTTPD$SSL_CAFILE

<ENDLIST>

<HEAD>(By Service\head_ssl_x509_config_service)

<P> To enable client certification for all requests on a per-service basis the
following HTTPD$CONFIG directive may be used.  A non-default CA verification
file can also optionally be supplied.

<CODE_EXAMPLE>
  [Service]
  https://the.host.name;verify
  https://the.host.name;cafile=HT_ROOT:[LOCAL]CA_THE_HOST_NAME.TXT
<ENDCODE_EXAMPLE>

<P> When HTTPD$SERVICE is in use a service-specific directive is provided for
both per-service verification and per-service CA file specification (allowing
different services to accept a different mix of CAs).

<CODE_EXAMPLE>
  [[https://the.host.name:443]]
  [ServiceSSLclientVerifyRequired]  enabled
  [ServiceSSLclientCAfile]  HT_ROOT:[LOCAL]CA_THE_HOST_NAME.TXT
<ENDCODE_EXAMPLE>

<HEAD>(By Resource\head_ssl_x509_config_resource)

<P> Client certificate authorization is probably most usefully applied on a
per-resource (per-request-path) basis using HTTPD$AUTH configuration file
rules.  Of course, per-resource control also applies to services that always
require a client  certificate (the only difference is the certificate has
already been negotiated for during the initial connection handshake).  The
reserved realm name <QUOTE>(X509) activates client certificate authentication
when a rule belonging to that realm is triggered.  The following example shows
such a rule providing read access to those possessing any verified certificate.

<CODE_EXAMPLE>
  [X509]
  /path/requiring/cert/* r
<ENDCODE_EXAMPLE>

<P> Optional directives may be supplied to the X.509 authenticator controlling
what mode the certificate is accepted in, as well a further access-restriction
rules on specifically which certificates may or may not be accepted for
authorization.  Such directives are passed via the <QUOTE>(param=) mechanism.
The following real-life example shows a script path requiring a mandatory
certificate, but not necessarily having the CA verified.  This would allow a
certificate display service to be established, the <QUOTE>([to:EXPIRED])
directive forcing the client to explicitly select a certificate with each
access.

<CODE_EXAMPLE>
  [X509]
  /cgi-bin/client_cert_details r,param="[vf:OPTIONAL][to:EXPIRED]"
<ENDCODE_EXAMPLE>

<P> A number of such directives are available controlling some aspects of the
certificate negotiation and verification.  The <QUOTE>([LT:integer]) directive
causes a verified certificate selection to continue to be valid for the
specified period as long as requests continue during that period (lifetime is
reset with each access).

<LIST>(UNNUMBERED)

<LE> [DP:integer] verify certificate CA chain to this depth (default 10)
<LE> [LT:integer] verified certificate lifetime in minutes (disabled by default)
<LE> [RU:/record=] derive the remote-user name from the specified certificate
subject field DN record
<LE> [TO:integer] session cache entry timeout in minutes (default 5)
<LE> [TO:EXPIRED] session cache entry is forced to expire (initating
renegotiation)
<LE> [VF:NONE] no certificate is required (any existing is cancelled)
<LE> [VF:OPTIONAL] certificate is required, CA verification is not required
<LE> [VF:REQUIRED] the certificate must pass CA verification (the default) 

<ENDLIST>

<P> Optional <QUOTE>(param=) passed conditionals may also be used to provide
additional filtering on which certificates may or may not be used against the
particular path.  This is based on pattern matching against client certificate
components.

<LIST>(UNNUMBERED)

<LE> [CI:string] transaction cipher
<LE> [IS:/record=string] specified Issuer (CA) DN record only
<LE> [IS:string] entire Issuer (CA) DN
<LE> [KS:integer] minimum key size
<LE> [SU:/record=string] specified Subject (client) DN record only
<LE> [SU:string] entire Subject (client) DN

<ENDLIST>

<P> These function and can be used in a similar fashion to mapping rule
conditionals (<REFERENCE>(head_mapping_conditional)).  This includes the
logical ORing, ANDing and negating of conditionals.  Asterisk wildcards match
any zero or more characters, percent characters any single character.  Matching
is case-insensitive.

<P> Note that the <QUOTE>(IS:) and <QUOTE>(SU:) conditionals each have a
<EMPHASIS>(specific-record) and an <EMPHASIS>(entire-field) mode.  If the
conditional string begins with a slash then it is considered to be a  match
against a specified record contents within the field.  If it begins with a
wildcard then it is matched against the entire field contents.  Certificate DN
records recognised by WASD,

<LIST>(SIMPLE)
<LE> <EMPHASIS>(/C=\BOLD) countryName
<LE> <EMPHASIS>(/ST=\BOLD) stateOrProvinceName
<LE> <EMPHASIS>(/SP=\BOLD) stateOrProvinceName
<LE> <EMPHASIS>(/L=\BOLD) localityName
<LE> <EMPHASIS>(/O=\BOLD) organizationName
<LE> <EMPHASIS>(/OU=\BOLD) organizationalUnitName
<LE> <EMPHASIS>(/CN=\BOLD) commonName
<LE> <EMPHASIS>(/T=\BOLD) title
<LE> <EMPHASIS>(/I=\BOLD) initials
<LE> <EMPHASIS>(/G=\BOLD) givenName
<LE> <EMPHASIS>(/S=\BOLD) surname
<LE> <EMPHASIS>(/D=\BOLD) description
<LE> <EMPHASIS>(/UID=\BOLD) uniqueIdentifier
<LE> <EMPHASIS>(/Email=\BOLD) pkcs9_emailAddress
<ENDLIST>

<P> The following (fairly contrived) examples provide an illustration of the
basics of X509 conditionals.  When matching against Issuer and Subject DNs some
knowlege of their contents and structure is required (see
<REFERENCE>(head_ssl_ref) for some basic resources).

<CODE_EXAMPLE>
  [X509]
  # only give <QUOTE>(VeriSign)ed ones access
  /controlled/path1/* r+w,param="[IS:/O=VeriSign\ Inc.]"
  # only give non-<QUOTE>(VeriSign)ed ones access
  /controlled/path2/* r+w,param="[!IS:/O=VeriSign\ Inc.]"
  # only allow 128 bit keys using RC4-MD5 access
  /controlled/path3/* r+w,param="[KS:128][CI:RC4-MD5]"
  # only give a <QUOTE>(Thawte)-signed client based in Australia
  # with the following email address access
  /controlled/path4/* r+w,param="\
  [IS:*/O=Thawte\ Consulting\ cc/*]\
  [SU:*/C=AU/*/Email=mark.daniel@wasd.vsm.com.au*]"
  # use the subject DN common-name record as the remote-user name
  # furthermore, restrict the CA's allowed to be used this way
  /VMS/* r+w,param="[RU:/CN=][IS:/O=WASD\ HTTPd\ CA\ Cert]"
<ENDCODE_EXAMPLE>

<P> Of course, access control via group membership is also available.  The
<EMPHASIS>(effective username) for the list is the 32 digit fingerprint of the
client certificate (shown as REMOTE_USER IN the first example of
<reference>(head_ssl_x509_cgi)), or the Subject DN record as specified using
the [RU:/<EMPHASIS>(record)=] directive.  This may be entered into simple lists
as part of a group of which membership then controls access to the resource. 
The following examples show the contents of simple list files containing the
X.509 fingerprints, derived remote-user names, and the required HTTPD$AUTH
realm entries. 

<CODE_EXAMPLE>
  # FINGERPRINTS.$HTL
  # (a file of X.509 fingerprints for access to "/path/requiring/cert/")
  106C8342890A1703AAA517317B145BF7  mark.daniel@wasd.vsm.com.au
  6ADA07108C20338ADDC3613D6D8B159D  just.another@where.ever.com

  # CERT_CN.$HTL
  # (a file of X.509 remote-user names derived using [RU:/CN=]
  Mark_Daniel mark.daniel@wasd.vsm.com.au
  Just_Another just.another@where.ever.com

  [X509;FINGERPRINTS=list]
  /path/requiring/cert/* r+w

  [X509;CERT_CN=list]
  /path/requiring/cn/* r+w
<ENDCODE_EXAMPLE>

<P> In a similar fashion the effective username can be placed in an access
restriction list.  The following configuration would only allow the user of
the certificate access to the specified resources.  Other verified certificate
holders would be denied access.

<CODE_EXAMPLE>
  [X509]
  /httpd/-/admin/* ~106C8342890A1703AAA517317B145BF7,r+w
  /ht_root/local/* ~106C8342890A1703AAA517317B145BF7,r+w

  /other/path/* ~Mark_Daniel,r+w,param="[ru:/cn=]"
  /yet/another/path/* ~Just_Another,r+w,param="[ru:/cn=]"
<ENDCODE_EXAMPLE>

<HEAD2>(Certificate Authority Verification File\head_ssl_x509_cafile)

<P> For the CA certificate component of the client certificate to be verified
as being what it claims to be (and thus establishing the integrity of the
client certificate) a list of such certificates must be provided for comparison
purposes.  For WASD this list is contained in a single, plain-text file
variously specified using either the HTTPD$SSL_CAFILE logical or per-service
<QUOTE>(;cafile=) or <QUOTE>([ServiceSSLclientCAfile]) directives.

<P> Copies of CA certificates are available for such purposes.  The PEM copies
(base-64 encoded versions of the binary certificate) can be placed into this
file using any desired text editor.  Comments may be inserted by prefixing with
the <QUOTE>(#) or <QUOTE>(!) characters.  For WASD this would be best stored in
the HT_ROOT:[LOCAL] directory, or site equivalent.

<P> An example of how such a file appears is provided below (ellipses inserted
to reduce the bulk of example).  There is one of these per certificate
authority.

<CODE_EXAMPLE>
  ################################################################

  Verisign Class 1 Public Primary Certification Authority
  =======================================================
  MD5 Fingerprint: 97:60:E8:57:5F:D3:50:47:E5:43:0C:94:36:8A:B0:62
  PEM Data:
  -----BEGIN CERTIFICATE-----
  MIICPTCCAaYCEQDNun9W8N/kvFT+IqyzcqpVMA0GCSqGSIb3DQEBAgUAMF8xCzAJ
  BgNVBAYTAlVTMRcwFQYDVQQKEw5WZXJpU2lnbiwgSW5jLjE3MDUGA1UECxMuQ2xh
  c3MgMSBQdWJsaWMgUHJpbWFyeSBDZXJ0aWZpY2F0aW9uIEF1dGhvcml0eTAeFw05
   <HELLIPSIS>
  FvjqBUuUfx3CHMjjt/QQQDwTw18fU+hI5Ia0e6E1sHslurjTjqs/OJ0ANACY89Fx
  lA==
  -----END CERTIFICATE-----
  Certificate Ingredients:
      Data:
          Version: 1 (0x0)
          Serial Number:
              cd:ba:7f:56:f0:df:e4:bc:54:fe:22:ac:b3:72:aa:55
          Signature Algorithm: md2WithRSAEncryption
          Issuer: C=US, O=VeriSign, Inc., OU=Class 1 Public Primary
   <HELLIPSIS>
          35:b0:7b:25:ba:b8:d3:8e:ab:3f:38:9d:00:34:00:98:f3:d1:
          71:94

  ################################################################
<ENDCODE_EXAMPLE>

<P> The WASD SSL package provides an example CA verification file constructed
from all the certificates provided in Netscape Navigator CERT7.DB file.  This
has been generated for and obtained from the Apache <EMPHASIS>(mod_ssl)
package, being used for the same purpose with that.  The WASD file name is
CA-BUNDLE_CRT.TXT and is usually located in HT_ROOT:[LOCAL].  The exact date
and <EMPHASIS>(mod_ssl) version it was obtained from can be found in the
opening commentary of the file itself.  The contents of this file can easily be
pared down to the minimum certificates required for any given site.  The more
certificates in the file the greater the overhead in verifying any given
client.

<COMMENT>(--------------------------------------------------------------------)

<HEAD2>(X.509 Authorization CGI Variables\head_ssl_x509_cgi)

<P> CGI variables specific to client certificate authorization are always
generated for use by scripts and SSI documents.  These along with the general
WASD authorization variables are shown in the example below.  Note, that due to
length of particular items some in this example are displayed wrapped.

<CODE_EXAMPLE>
  WWW_AUTH_ACCESS == "READ+WRITE"
  WWW_AUTH_GROUP == ""
  WWW_AUTH_REALM == "X509"
  WWW_AUTH_REALM_DESCRIPTION == "X509 Client Certs"
  WWW_AUTH_TYPE == "X509"
  WWW_AUTH_USER == "Mark Daniel, mark.daniel@wasd.vsm.com.au"
  WWW_AUTH_X509_CIPHER == "RC4-MD5"
  WWW_AUTH_X509_FINGERPRINT == "10:6C:83:42:89:0A:17:03:AA:A5:17:31:7B:14:5B:F7"
  WWW_AUTH_X509_ISSUER == "/O=VeriSign, Inc./OU=VeriSign Trust
  Network/OU=www.verisign.com/repository/RPA Incorp. By
  Ref.,LIAB.LTD(c)98/CN=VeriSign Class 1 CA Individual Subscriber-Persona Not
  Validated"
  WWW_AUTH_X509_KEYSIZE == "128"
  WWW_AUTH_X509_SUBJECT == "/O=VeriSign, Inc./OU=VeriSign Trust
  Network/OU=www.verisign.com/repository/RPA Incorp. by
  Ref.,LIAB.LTD(c)98/OU=Persona Not Validated/OU=Digital ID Class 1 - Netscape
  /CN=Mark Daniel/Email=mark.daniel@wasd.vsm.com.au"
  WWW_REMOTE_USER == "106C8342890A1703AAA517317B145BF7"
<ENDCODE_EXAMPLE>

<P> Other CGI variables optionally may be enabled using HTTPD$MAP mapping
rules.  See <REFERENCE>(head_ssl_cgi).  Specific client certificate variables
providing the details of such certificates are available with
SSLCGI=apache_mod_ssl.  These are of course in addition to the more general
apache_mod_ssl variables described in the above section.  Note that where some
ASN.1 records are duplicated (as in SSL_CLIENT_S_DN) some variables will
contain newline characters (0x10) between those elements (e.g.
SSL_CLIENT_S_DN_OU).  The line breaks in this example do not necesarily reflect
those characters.

<CODE_EXAMPLE>
  WWW_SSL_CLIENT_A_KEY == "rsaEncryption"
  WWW_SSL_CLIENT_A_SIG == "md5WithRSAEncryption"
  WWW_SSL_CLIENT_I_DN == "/O=VeriSign, Inc./OU=VeriSign Trust Network
  /OU=www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98
  /CN=VeriSign Class 1 CA Individual Subscriber-Persona Not Validated"
  WWW_SSL_CLIENT_I_DN_CN == "VeriSign Class 1 CA Individual Subscriber-Persona
  Not Validated"
  WWW_SSL_CLIENT_I_DN_O == "VeriSign, Inc."
  WWW_SSL_CLIENT_I_DN_OU == "VeriSign Trust Network
  www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98"
  WWW_SSL_CLIENT_M_SERIAL == "0BF233D4FE232A90F3F98B2CE0D7DADA"
  WWW_SSL_CLIENT_M_VERSION == "3"
  WWW_SSL_CLIENT_S_DN == "/O=VeriSign, Inc./OU=VeriSign Trust Network
  /OU=www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98
  /OU=Persona Not Validated/OU=Digital ID Class 1 - Netscape
  /CN=Mark Daniel/Email=mark.daniel@wasd.vsm.com.au"
  WWW_SSL_CLIENT_S_DN_CN == "Mark Daniel"
  WWW_SSL_CLIENT_S_DN_EMAIL == "mark.daniel@wasd.vsm.com.au"
  WWW_SSL_CLIENT_S_DN_O == "VeriSign, Inc."
  WWW_SSL_CLIENT_S_DN_OU == "VeriSign Trust Network
  www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98
  Persona Not Validated.Digital ID Class 1 - Netscape"
  WWW_SSL_CLIENT_V_END == "Feb 10 23:59:59 2001 GMT"
  WWW_SSL_CLIENT_V_START == "Dec 12 00:00:00 2000 GMT"
<ENDCODE_EXAMPLE>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(Certificate Management\head_ssl_cert)

<P> This is not a tutorial on X.509 certificates and their management. Refer
to the listed references, <REFERENCE>(head_ssl_ref), for further information on
this aspect.  It does provide some basic guidelines.

<P> Certificates identify something or someone, associating a public
cryptographic key with the identity of the certificate holder.  It includes a
distinguished name, identification and signature of the certificate authority
(CA, the issuer and guarantor of the certificate), and the period for which the
certificate is valid, possibly with other, additional information.

<P> The three types of certificates of interest here should not be confused.

<LIST>(UNNUMBERED)

<LE> <EMPHASIS>(CA - \BOLD) The Certificate Authority identifies the
<EMPHASIS>(authority), or organization, that issues a certificate.

<LE> <EMPHASIS>(Server - \BOLD) Identifies a particular end-service.  It's
value as an guarantee of identity is founded in the <EMPHASIS>(authority) of
the organization that issues the certificate. It is the certificate specified
to the server at startup.

<LE> <EMPHASIS>(Client - \BOLD) Identifies a particular client to a server via
SSL (client authentication). Typically, the identity of the client is assumed
to be the same as the identity of a human being.  Again, it's value as an
guarantee of identity is founded in the <EMPHASIS>(authority) of the
organization that issues the certificate.

<ENDLIST>

<P> The various OpenSSL tools are available for management of all of these
certificate types in each of the three SSL environments.

<LIST>(UNNUMBERED)

<LE> The HP SSL for OpenVMS Alpha/IA64/VAX product provides the <QUOTE>(SSL
Certificate Tool) procedure can be used to perform most required certificate
management tasks from a menu-driven interface.

<CODE_EXAMPLE>
  $ @SSL$COM:SSL$CERT_TOOL.COM

           <EMPHASIS>(S S L   C e r t i f i c a t e   T o o l\BOLD)

                           Main Menu

      1. View a Certificate
      2. View a Certificate Signing Request
      3. Create a Certificate Signing Request
      4. Create a Self-Signed Certificate
      5. Create a CA (Certification Authority) Certificate
      6. Sign a Certificate Signing Request
      7. Hash Certificates
      8. Hash Certificate Revocations
      9. Exit

     Enter Option:
<ENDCODE_EXAMPLE>

<LE> The WASD OpenSSL kit provides elementary DCL procedures and brief notes in
the

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<BLOCKQUOTE>
HT_ROOT:[SRC.<A HREF="/ht_root/src/">OPENSSL-n_n_n</A>.WASD]
&nbsp;(look for it here)
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.OPENSSL-n_n_n.WASD]
<COMMENT>(HTML/ON)

directory for some procedure-driven support of these activities.

<LE> The standard OpenSSL toolkit provides a number of command-line tools for
creation and management of X.509 certificates.

<ENDLIST>

<COMMENT>(....................................................................)

<HEAD2>(Server Certificate\head_ssl_cert_server)

<P> The server uses a certificate to establish it's identity during the
initial phase of the SSL protocol exchange. Each server should have a unique
certificate. An example certificate is provided with the WASD SSL package.  If
this is not available (for instance when using the HP SSL for OpenVMS
Alpha/IA64/VAX product) then the server will fallback to an internal, default
certificate that allows SSL functionality even when no external certification
is available. If a <QUOTE>(live) SSL site is required a unique certificate
issued by a third-party Certificate Authority is desirable.

<P> A working alternative to obtaining one of these certificates is
provided by the WASD support DCL procedures, which are quick hacks to ease the
production of certificates on an ad hoc basis.  In all cases it is preferable
to directly use the utilities provided with OpenSSL, but the documentation
tends to be rather sparse.

<P> The first requirement may be a tailored <QUOTE>(Certificate Authority)
certificate. As the Certificate Authority is non-authoritative (not trying to be
too oxymoronic, i.e. not a well-known CA) these certificates have little value
except to allow SSL transactions to be established with trusting clients.
More commonly <QUOTE>(Server Certificates) for specific host names are
required.

<HEAD>(Loading Authority Certificates\head_ssl_loading_auth_cert)

<P> CA certificates can be loaded into browsers to allow sites using that CA
to be accessed by that browser without further dialog. Both Netscape Navigator
(v3.<EMPHASIS>(n) & v4.<EMPHASIS>(n), v5.<EMPHASIS>(n), v6.<EMPHASIS>(n)) and
MS Internet Explorer (v4.<EMPHASIS>(n), v5.<EMPHASIS>(n)) automatically invokes
a server certificate load dialog when it encounters a site using a valid but
unknown server certificate.

<P> A manual load is accomplished by requesting the certificate in a format
appropriate to the particular browser.  This triggers a browser dialog with the
user to confirm or refuse the loading of that certificate into the browser
Certificate Authority database.

<P> To facilitate loading CA certificates into a browser ensure the following
entries are contained in the HTTP$CONFIG configuration file:

<CODE_EXAMPLE>
  [AddIcon]
  /httpd/-/binary.gif  [BIN]  application/x-x509-ca-cert

  [AddType]
  .CRT  application/x-x509-ca-cert  -  DER certifcate (MSIE)
  .PEM  application/x-x509-ca-cert  -  Privacy Enhanced Mail certificate
<ENDCODE_EXAMPLE>

<P> Then just provide a link to the required certificate file(s), and click.

<CP> Navigator should be able to load using either certificate format. MSIE
v3.<EMPHASIS>(n) will load and report on the <QUOTE>(.CRT) certificate quite
contentedly, but then will not allow it to be used because it does not
represent a well-known Certficate Authority.  MSIE v4.<EMPHASIS>(n) and
v5.<EMPHASIS>(n) seem able to use the <QUOTE>(.CRT) certificate.

<HEAD>(Changing Server Certificates\head_ssl_changing_certs)

<P> If a site's server (or CA certificate) is changed and the server restarted
any executing browsers will probably complain (Netscape Navigator reports an
I/O error). In this case open the browser's certificate database and delete
any relevant, permanently stored certificate entry, then close and restart the
browser. The next access should initiate the server certificate dialog, or the
CA certificate may be explicitly reloaded.

<HEAD2>(Client Certificate\head_ssl_cert_client)

<P> As with server certificates, client certficates are best obtained from a
recognised Certificate Authority.  However, for testing and experimental
purposes WASD provides some elementary CGI scripts and DCL procedures to assist
in locally generating X.509 client certificates and installing them into user
browsers.

<HEAD>(Manual Generation\head_ssl_cert_client_manual)

<P> The OpenSSL CA certificate generation utility can be used at the command
line to process a CSR.  That CSR could have been generated via an online HTML
form.

<HEAD>(Semi-Automatic Generation\head_ssl_cert_client_semiauto)

<P> Using this approach the user generates a Certificate Signing Request (CSR)
online, which is then further processed off-line, at the discretion of the
site administrator.  Only Netscape browsers are supported for what is described
below.

<LIST>(NUMBERED)

<LE> Provide an HTML form with the appropriate fields for each of the required
ASN.1 fields used in X.509 certificates, plus a special, Netscape-sepcific one
named <LITERAL>(<KEYGEN>), which allows the creation of a user's private-key. 
The user completes the elements of that form and when submitted the contents
are emailed to the site administrator.  A CSR can be freely transmitted as
open text because it is secured by the private-key generated and only stored on
the user's local machine.

<LE> The site administrator receives such a CSR by email.  At that person's
discretion and availability the CSR is input (cut-and-paste to eliminate
errors) to a form activating a local CGI script requiring authorization for
activation.  The CGI script processes the CSR submitted by the form and creates
using the OpenSSL CA certificate signing utility to generate a certificate (or
an error if there is a problem).

<LE> If a client certificate is successfully generated it can either be
delivered back to the user via email, for local saving and import, or made
available for a short period via the Web for the user to collect (via a file
with the content-type of <QUOTE>(application/x-x509-user-cert)). Notification
of such availability could be made using email.

<ENDLIST>

<P> A basic DCL procedure providing such a facility is

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<BLOCKQUOTE>
HT_ROOT:[SRC.<A HREF="/ht_root/src/">OPENSSL-n_n_n</A>.WASD]CLIENT_CERT_REQUEST.COM
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.OPENSSL-n_n_n].WASDCLIENT_CERT_REQUEST.COM
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

<P> This semi-automatic method would probably be the author's preference over
the on-demand approach (see below). 

<HEAD>(Generation On-Demand\head_ssl_cert_client_on_demand)

<P> Automatic, on-demand client certificate generation allows any user (subject
to access controls) to generate a client certificate automatically via an
online service.  While this may not generally be a useful thing for a site to
provide there may be occasions for it's use.  It is a three part process. 
Only Netscape browsers are supported for what is described below.

<LIST>(NUMBERED)

<LE> As with the semi-automatic approach an HTML form allows a user to input
and submit certificate details.

<LE> The submitted form activates a CGI script which collates the form
details generating the Certificate Signing Request (CSR).  The CSR is then used
directly by the OpenSSL CA certificate signing utility to generate a
certificate (or an error if there is a problem).

<LE> If a client certificate is successfully generated it is delivered back to
the browser with a content-type of <QUOTE>(application/x-x509-user-cert) which
results in the browser installing it in it's certificate database.

<ENDLIST>

A basic DCL procedure providing such a facility is

<COMMENT>(....................................................................)

<COMMENT>(HTML=
<BLOCKQUOTE>
HT_ROOT:[SRC.<A HREF="/ht_root/src/">OPENSSL-n_n_n</A>.WASD]CLIENT_CERT_REQUEST.COM
</BLOCKQUOTE>
)

<COMMENT>(HTML/OFF)
HT_ROOT:[SRC.OPENSSL-n_n_n].WASDCLIENT_CERT_REQUEST.COM
<COMMENT>(HTML/ON)

<COMMENT>(....................................................................)

(and yes, it's the same procedure as used with the semi-automatic approach,
just configured differently).

<COMMENT>(....................................................................)

<HEAD2>(Certificate Signing Request\head_ssl_cert_sign)

<P> Recognised Certificate Authorities (CAs) such as Thawte and VeriSign
publish lists of requirements for obtaining a server certificate.  These often
include such documents required to prove organisational name and the right to
use the domain name being requested.  Check the particular vendor for the exact
requirements.

<P> In addition, a document containing the site's private key is required. 
This is known as the Certificate Signing Request (CSR) and must be generated
digitally at the originating site.

<P> Using the HP SSL for OpenVMS Alpha/IA64/VAX product
<QUOTE>(SSL Certificate Tool) described in <REFERENCE>(head_ssl_cert) a CSR can
easily be generated using it's menu-driven interface.  The alternative is using
a command-line interface tool.

<P> The following instructions provide the basics for generating a CSR at the
command-line in the WASD and generally the any OpenSSL environment (including
the HP SSL for OpenVMS Alpha/IA64/VAX product).

<LIST>(NUMBERED)

<LE> Change to a secure directory.  The following is a suggestion.

<CODE_EXAMPLE>
  $ SET DEFAULT HT_ROOT:[LOCAL]
<ENDCODE_EXAMPLE>

<LE> Assign a foreign verb for the OPENSSL application.  The location may
vary a little depending on which OpenSSL package you have installed.

<CODE_EXAMPLE>
  $ OPENSSL == "$HT_ROOT:[SRC.OPENSSL-<EMPHASIS>(version).AXP.EXE.APPS]OPENSSL.EXE"
<ENDCODE_EXAMPLE>

<P> When using the HP SSL for OpenVMS Alpha/IA64/VAX product or other OpenSSL
toolkit the verb may already be available.

<CODE_EXAMPLE>
  $ SHOW SYMBOL OPENSSL
    OPENSSL == "$ SSL$EXE:OPENSSL"
<ENDCODE_EXAMPLE>

<LE> Specify a source of lots of <QUOTE>(random) data (can be any big file for
the purposes of this exercise).

<CODE_EXAMPLE>
  $ RANDFILE = "HT_EXE:HTTPD_SSL.EXE"
<ENDCODE_EXAMPLE>

<LE> Find the template configuration file.  You will need to specify this
location in a step described below.  Should be something like the following.

<CODE_EXAMPLE>
  HT_ROOT:[SRC.OPENSSL-<EMPHASIS>(version).WASD]TEMPLATE.CNF
<ENDCODE_EXAMPLE>

<LE> Generate your private key (RANDFILE data is used by this).  The
output from this looks something like what's shown.  Notice the pass
phrase prompts.  <EMPHASIS>(This is your private key, don't forget it!\BOLD)

<CODE_EXAMPLE>
  $ OPENSSL GENRSA -DES3 -OUT SERVER.KEY 1024

  Generating RSA private key, 1024 bit long modulus
  .....++++++
  ......++++++
  e is 65537 (0x10001)
  Enter PEM pass phrase:
  Verifying password - Enter PEM pass phrase:
<ENDCODE_EXAMPLE>

<LE> Generate the Certificate Signing Request using syntax similar to the
following (this is where you are required to specify the location of the
configuration template).  Note that there are quite a few fields -
<EMPHASIS>(GET THEM RIGHT!\bold)  They need to be unique and local - they're
your distinguishing name (DN). <QUOTE>(Common Name) is the host you want the
certificate for.  It can be a  fully qualifier host name (e.g.
<QUOTE>(klaatu.local.net)), or a local <EMPHASIS>(wildcard) (e.g.
<QUOTE>(*.local.net)) for which you may pay more.

<CODE_EXAMPLE>
  $ OPENSSL REQ -NEW -KEY SERVER.KEY -OUT SERVER.CSR -CONFIG -
  HT_ROOT:[SRC.OPENSSL-0_9_6B.WASD]TEMPLATE.CNF

  Using configuration from template.cnf
  Enter PEM pass phrase:
  You are about to be asked to enter information that will be
  incorporated 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) [AU]:AU
  State or Province Name (full name) [Some-State]:South Australia
  Locality Name (eg, city) []:Adelaide
  Organization Name (eg, company) [Internet Widgits Pty Ltd]:Example
  Organizational Unit Name (eg, section) []:WASD
  Common Name (eg, YOUR name) []:klaatu.local.net
  Email Address []:Mark.Daniel@wasd.vsm.com.au
  Please enter the following 'extra' attributes
  to be sent with your certificate request
  A challenge password []:
  An optional company name []:
<ENDCODE_EXAMPLE>

<LE> That's it!  You should have two files in your default directory.

<CODE_EXAMPLE>
  SERVER.CSR;1               2  14-MAR-2002 04:38:26.15
  SERVER.KEY;1               2  14-MAR-2002 04:31:38.76
<ENDCODE_EXAMPLE>

<P> Keep the SERVER.KEY file secure.  You'll need it when you receive the
certificate back from the CA.

<P> The SERVER.CSR is what you send to the CA (usually by mail or Web
form).  It looks something like the following

<CODE_EXAMPLE>
  $ TYPE SERVER.CSR
  -----BEGIN CERTIFICATE REQUEST-----
  MIIBPTCB6AIBADCBhDELMAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2Fw
  ZTESMBAGA1UEBxMJQ2FwZSBUb3duMRQwEgYDVQQKEwtPcHBvcnR1bml0aTEYMBYG
  A1UECxMPT25saW5lIFNlcnZpY2VzMRowGAYDVQQDExF3d3cuZm9yd2FyZC5jby56
  YTBaMA0GCSqGSIb3DQEBAQUAA0kAMEYCQQDT5oxxeBWu5WLHD/G4BJ+PobiC9d7S
  6pDvAjuyC+dPAnL0d91tXdm2j190D1kgDoSp5ZyGSgwJh2V7diuuPlHDAgEDoAAw
  DQYJKoZIhvcNAQEEBQADQQBf8ZHIu4H8ik2vZQngXh8v+iGnAXD1AvUjuDPCWzFu
  pReiq7UR8Z0wiJBeaqiuvTDnTFMz6oCq6htdH7/tvKhh
  -----END CERTIFICATE REQUEST-----
<ENDCODE_EXAMPLE>

<P> You can see the details of this file using

<CODE_EXAMPLE>
  $ OPENSSL RSA -NOOUT -TEXT -IN SERVER.CSR
<ENDCODE_EXAMPLE>

<ENDLIST>

<HEAD>(After Receiving The Certificate\head_ssl_cert_sign_recvd)

<P> Once the signed certificate has been issued by the Certificate Authority it
can be placed directly into the server configuration directory, usually
HT_ROOT:[LOCAL], and configured for use from there.  Using the certificate
direct from the CA requires that the private key password be given to the
server each time (<REFERENCE>(head_ssl_private_key)).  It is possible to embed
the password into the certificate key so that this is not required.

<P> <EMPHASIS>(Remember to keep original files secure, only work on
copies!\BOLD)

<LIST>(NUMBERED)

<LE> Assign a foreign verb for the OPENSSL application.  The location may
vary a little depending on which OpenSSL package you have installed.

<CODE_EXAMPLE>
  $ OPENSSL == "$HT_ROOT:[SRC.OPENSSL-<EMPHASIS>(version).AXP.EXE.APPS]OPENSSL.EXE"
<ENDCODE_EXAMPLE>

<P> When using the HP SSL for OpenVMS Alpha/IA64/VAX product or other OpenSSL
toolkit the verb may already be available.

<CODE_EXAMPLE>
  $ SHOW SYMBOL OPENSSL
    OPENSSL == "$ SSL$EXE:OPENSSL"
<ENDCODE_EXAMPLE>

<LE> Go to wherever you want to do the work.

<CODE_EXAMPLE>
  $ SET DEFAULT HT_ROOT:[LOCAL]
<ENDCODE_EXAMPLE>

<LE> Using the original key file embed your password into a copy.  When
prompted "Enter PEM pass phrase:" enter the password.

<CODE_EXAMPLE>
  $ OPENSSL rsa -in SERVER.KEY -out WORK.PEM
<ENDCODE_EXAMPLE>

<LE> Append this password-embedded key file to your certificate file.

<CODE_EXAMPLE>
  $ COPY CERTIFICATE.PEM,WORK.PEM CERTIFICATE.PEM;0
<ENDCODE_EXAMPLE>

<LE> Delete the temporary file.

<CODE_EXAMPLE>
  $ DELETE WORK.PEM;*
<ENDCODE_EXAMPLE>

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(SSL CGI Variables\head_ssl_cgi)

<P> CGI variables specific to SSL transactions optionally may be enabled using
HTTPD$MAP mapping rules.  See <REFERENCE>(head_set_rules) in
<REFERENCE>(chapter_mapping_rule). The may be done on a specific per-path or
general CGI basis.  Two variations are available, one reflecting Purveyor
Secure Web Server style variables, the other the Apache <EMPHASIS>(mod_ssl)
style.  In the following examples,  due to length of particular items, some in
this example are displayed wrapped. Also, where some ASN.1 records are
duplicated (as in SSL_CLIENT_S_DN), some variables will contain newline
characters (0x10) between those elements (e.g. SSL_CLIENT_S_DN_OU).  The line
breaks in the examples do not necesarily reflect those characters.

<P>
<EMPHASIS>(set /path/* SSLCGI=purveyor\BOLD)

<CODE_EXAMPLE>
  WWW_SECURITY_STATUS == "SSL"
  WWW_SSL_CIPHER == "RC4-MD5"
  WWW_SSL_CIPHER_KEYSIZE == "128"
  WWW_SSL_CLIENT_AUTHENTICATED == "TRUE"
  WWW_SSL_CLIENT_CA == "/O=VeriSign, Inc./OU=VeriSign Trust Network
  /OU=www.verisign.com/repository/RPA Incorp. By Ref.,LIAB.LTD(c)98
  /CN=VeriSign Class 1 CA Individual Subscriber-Persona Not Validated"
  WWW_SSL_CLIENT_DN == "/O=VeriSign, Inc./OU=VeriSign Trust Network
  /OU=www.verisign.com/repository/RPA Incorp. by Ref.,LIAB.LTD(c)98
  /OU=Persona Not Validated/OU=Digital ID Class 1 - Netscape
  /CN=Mark Daniel/Email=mark.daniel@wasd.vsm.com.au"
  WWW_SSL_SERVER_CA == "/C=AU/ST=SA/L=Adelaide/O=WASD HTTPd CA Cert
  /OU=OpenSSL 0.9.6 Testing Only/CN=WASD VMS Hypertext Services
  /Email=Mark.Daniel@wasd.vsm.com.au"
  WWW_SSL_SERVER_DN == "/C=AU/ST=SA/L=Adelaide/O=WASD HTTPd Server Cert
  /OU=OpenSSL 0.9.6 Testing Only/CN=WASD VMS Hypertext Services
  /Email=Mark.Daniel@wasd.vsm.com.au"
  WWW_SSL_VERSION == "SSLv3"
<ENDCODE_EXAMPLE>

<P> Note that this example also shows <EMPHASIS>(SSL_CLIENT_<HELLIPSIS>)
variables.  These will only be present if the request is X.509 certificate
authenticated.

<P>
<EMPHASIS>(set /path/* SSLCGI=apache_mod_ssl\BOLD)

<CODE_EXAMPLE>
  WWW_SSL_CIPHER == "RC4-MD5"
  WWW_SSL_CIPHER_ALGKEYSIZE == "128"
  WWW_SSL_CIPHER_USEKEYSIZE == "128"
  WWW_SSL_PROTOCOL == "SSLv3"
  WWW_SSL_SERVER_A_KEY == "rsaEncryption"
  WWW_SSL_SERVER_A_SIG == "md5WithRSAEncryption"
  WWW_SSL_SERVER_I_DN == "/C=AU/ST=SA/L=Adelaide/O=WASD HTTPd CA Cert
  /OU=OpenSSL 0.9.6 Testing Only/CN=WASD VMS Hypertext Services
  /Email=Mark.Daniel@wasd.vsm.com.au"
  WWW_SSL_SERVER_I_DN_C == "AU"
  WWW_SSL_SERVER_I_DN_CN == "WASD VMS Hypertext Services"
  WWW_SSL_SERVER_I_DN_EMAIL == "Mark.Daniel@wasd.vsm.com.au"
  WWW_SSL_SERVER_I_DN_L == "Adelaide"
  WWW_SSL_SERVER_I_DN_O == "WASD HTTPd CA Cert"
  WWW_SSL_SERVER_I_DN_OU == "OpenSSL 0.9.6 Testing Only"
  WWW_SSL_SERVER_I_DN_ST == "SA"
  WWW_SSL_SERVER_M_SERIAL == "01"
  WWW_SSL_SERVER_M_VERSION == "3"
  WWW_SSL_SERVER_S_DN == "/C=AU/ST=SA/L=Adelaide/O=WASD HTTPd Server Cert
  /OU=OpenSSL 0.9.6 Testing Only/CN=WASD VMS Hypertext Services
  /Email=Mark.Daniel@wasd.vsm.com.au"
  WWW_SSL_SERVER_S_DN_C == "AU"
  WWW_SSL_SERVER_S_DN_CN == "WASD VMS Hypertext Services"
  WWW_SSL_SERVER_S_DN_EMAIL == "Mark.Daniel@wasd.vsm.com.au"
  WWW_SSL_SERVER_S_DN_L == "Adelaide"
  WWW_SSL_SERVER_S_DN_O == "WASD HTTPd Server Cert"
  WWW_SSL_SERVER_S_DN_OU == "OpenSSL 0.9.6 Testing Only"
  WWW_SSL_SERVER_S_DN_ST == "SA"
  WWW_SSL_SERVER_V_END == "Sep 25 00:03:30 2005 GMT"
  WWW_SSL_SERVER_V_START == "Sep 26 00:03:30 2000 GMT"
  WWW_SSL_SESSION_ID == "344d1b01aa0636cb809eacf270279005f56cd5ebe1154569df810e56003ac70f"
  WWW_SSL_VERSION_INTERFACE == "HTTPd-WASD/7.2.0 OpenVMS/AXP SSL"
  WWW_SSL_VERSION_LIBRARY == "OpenSSL 0.9.6 24 Sep 2000"
<ENDCODE_EXAMPLE>

<P> The Apache <EMPHASIS>(mod_ssl) client certificate details described in
<REFERENCE>(head_ssl_x509_cgi) above are not shown in the above example but
would be included if the request was X.509 authenticated.

<COMMENT>(--------------------------------------------------------------------)

<HEAD1>(SSL References\head_ssl_ref)

<P> The following provide a starting-point for investigating SSL and OpenSSL
further (verified available at time of publication).

<LIST>(UNNUMBERED)

<LE>

<COMMENT>(HTML=
<A HREF="http://www.openssl.org/">
http://www.openssl.org/</A>
)

<COMMENT>(HTML/OFF)
http://www.openssl.org/
<COMMENT>(HTML/ON)

<LINE> OpenSSL Project.  This site is the prime source for the full toolkit,
documentation, related links, news and support via mailing lists, etc.

<LE>

<COMMENT>(HTML=
<A HREF="http://www.openvms.compaq.com/openvms/products/ssl/ssl.html">
http://www.openvms.compaq.com/openvms/products/ssl/ssl.html</A>
)

<COMMENT>(HTML/OFF)
http://www.openvms.compaq.com/openvms/products/ssl/ssl.html
<COMMENT>(HTML/ON)

<LINE> The HP SSL (Secure Sockets Layer) for OpenVMS Alpha/IA64/VAX product.
<LINE> The <QUOTE>(Open Source Security for OpenVMS Alpha, Volume 2: Compaq
SSL (Secure Sockets Layer) for OpenVMS Alpha) guide (see next link) available
in PDF or HTML from this site (and the OpenVMS 7.3-1 and later documentation
CD-ROM) is particularly comprehensive and relevant.

<LE>

<COMMENT>(HTML=
<A HREF="http://www.openvms.compaq.com:8000/731final/6661/6661pro.htm">
http://www.openvms.compaq.com:8000/731final/6661/6661pro.htm</A>
<BR><A HREF="http://www.openvms.compaq.com:8000/731final/documentation/pdf/ovms_731_open_source_ssl.pdf">
http://www.openvms.compaq.com:8000/731final/documentation/pdf/ovms_731_open_source_ssl.pdf</A>
)

<COMMENT>(HTML/OFF)
http://www.openvms.compaq.com:8000/731final/6661/6661pro.htm
<LINE>
http://www.openvms.compaq.com:8000/731final/documentation/pdf/ovms_731_open_source_ssl.pdf
<COMMENT>(HTML/ON)

<LINE> Open Source Security for OpenVMS Alpha, Volume 2: Compaq SSL (Secure
Sockets Layer) for OpenVMS Alpha

<LE>

<COMMENT>(HTML=
<A HREF="http://www.openvms.compaq.com/openvms/products/ips/apache/SSL_Resource_Guide.html">
http://www.openvms.compaq.com/openvms/products/ips/apache/SSL_Resource_Guide.html</A>
)

<COMMENT>(HTML/OFF)
http://www.openvms.compaq.com/openvms/products/ips/apache/SSL_Resource_Guide.html
<COMMENT>(HTML/ON)

<LINE> The CSWS SSL Resource Guide.  Contains links to a broad range of
subjects and organisations.

<LE>

<COMMENT>(HTML=
<A HREF="http://www.mozilla.org/projects/security/pki/nss/ref/ssl/">
http://www.mozilla.org/projects/security/pki/nss/ref/ssl/</A>
)

<COMMENT>(HTML/OFF)
http://www.mozilla.org/projects/security/pki/nss/ref/ssl/
<COMMENT>(HTML/ON)

<LINE> Mozilla.org's SSL Reference

<LE>

<COMMENT>(HTML=
<A HREF="http://www.rsasecurity.com/standards/ssl/basics.html">
http://www.rsasecurity.com/standards/ssl/basics.html</A>
)

<COMMENT>(HTML/OFF)
http://www.rsasecurity.com/standards/ssl/basics.html
<COMMENT>(HTML/ON)

<LINE> RSA's SSL Basics for Internet Users 

<LE>

<COMMENT>(HTML=
<A HREF="http://www.rsasecurity.com/rsalabs/faq/">
http://www.rsasecurity.com/rsalabs/faq/</A>
<BR><A HREF="ftp://ftp.rsasecurity.com/pub/labsfaq/rsalabs_faq41.pdf">
ftp://ftp.rsasecurity.com/pub/labsfaq/rsalabs_faq41.pdf</A>
)

<COMMENT>(HTML/OFF)
http://www.rsasecurity.com/rsalabs/faq/
<LINE>ftp://ftp.rsasecurity.com/pub/labsfaq/rsalabs_faq41.pdf
<COMMENT>(HTML/ON)

<LINE> RSA's FAQ on Cryptography

<LE>

<COMMENT>(HTML=
<A HREF="http://docs.sun.com/source/816-6156-10/">
http://docs.sun.com/source/816-6156-10/</A>
)

<COMMENT>(HTML/OFF)
http://docs.sun.com/source/816-6156-10/
<COMMENT>(HTML/ON)

<LINE> Sun Microsystems' Introduction to SSL 

<LE>

<COMMENT>(HTML=
<A HREF="http://docs.sun.com/source/816-6154-10/">
http://docs.sun.com/source/816-6154-10/</A>
)

<COMMENT>(HTML/OFF)
http://docs.sun.com/source/816-6154-10/
<COMMENT>(HTML/ON)

<LINE> Sun Microsystems' Introduction to Public-Key Cryptography

<LE>

<COMMENT>(HTML=
<A HREF="http://www.cs.auckland.ac.nz/~pgut001/links.html">
http://www.cs.auckland.ac.nz/~pgut001/links.html</A>
)

<COMMENT>(HTML/OFF)
http://www.cs.auckland.ac.nz/~pgut001/links.html
<COMMENT>(HTML/ON)

<LINE> <QUOTE>(Encryption and Security-related Resources)
<HELLIPSIS> an (almost rediculously) exhaustive list of security and
cryptography links, including some on SSL. 

<ENDLIST>

<COMMENT>(--------------------------------------------------------------------)
