[next] [previous] [contents] [full-page]14.1 - SSL Configuration
14.1.1 - HTTPD$CONFIG [Service]
14.1.2 - HTTPD$SERVICE
14.1.3 - SSL Server Certificate
14.1.4 - SSL Private key
14.1.5 - SSL Virtual Services
14.1.6 - SSL Access Control
14.1.7 - Authorization Using X.509 Certification
14.1.8 - Features
14.1.9 - X509 Configuration
14.1.10 - Certificate Authority Verification File
14.1.11 - X.509 Authorization CGI Variables
14.2 - Certificate Management
14.2.1 - Server Certificate
14.2.2 - Client Certificate
14.3 - SSL CGI Variables
14.4 - WASD SSL Quick-Start
14.5 - OpenSSL
14.6 - SSL References
This section is not a tutorial on SSL. It contains only information relating to WASD's use of it. Refer to the listed references, 14.6 - SSL References, for further information on SSL technology.
The 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 establishes server and optionally client identity. SSL operates by establishing an encrypted communication path between the two applications, "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.
![]() |
WASD implements SSL using a freely available software toolkit known as "OpenSSL", see 14.5 - OpenSSL. |
SSL functionality is not supplied with the basic WASD package. In part this is due to the relative bulk of this component, but also considers potential patent issues and export restrictions on some cryptographic technology in some jurisdictions.
Considerations
During early 2000 the USA Federal Government eased some export restrictions on technologies used within OpenSSL, and a USA patent held on one of the them by RSA Security Inc. expired in late 2000. Both of these developments would be expected to clear the way for use of OpenSSL and OpenSSL-based applications, and the redistribution of such, within and out-of the USA. Aside: it also indicates to many that 128 bit, "strong" encryption is now less of a concern to national security agencies than before (i.e. technologies now exist that effectively make this a non-issue). No recommendations are made by this author on the use of the OpenSSL package in any particular locality, except to comment that it is in commercial and non-commercial use in many applications across across North America, Europe, Asia and Australia, in both OpenSSL and SSLeay incarnations. For further comment on these aspects check the OpenSSL Project's Web site (see 14.6 - SSL References).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 PLEASE PAY CLOSE ATTENTION TO ANY APPLICABLE EXPORT/IMPORT LAWS. The author of this package is not liable for any violations you make here.
The WASD SSL component is available as a separate, easily integrated
package, with OpenSSL object libraries, OpenSSL utility object modules for
building executables and WASD support files. It requires no compilation, only
linking. Obtain these from the same source as the main package.
Some Thoughts From R. S. Engelschall
Ralf S. Engelschall (rse@engelschall.com) is the author of the popular Apache mod_ssl package. This section is taken from the mod_ssl read-me and is well-worth some consideration for this and software security issues in general.
" You should be very sensible when using cryptography software, because just running an SSL server DOES NOT mean your system is then secure! This is for a number of reasons. The following questions illustrate some of the problems.
If you can't answer these questions to your personal satisfaction, then you
usually have a problem. Even if you can, you may still NOT be
secure. Don't blame the authors if it all goes horribly wrong. Use it at your
own risk!
"
SSL Overhead
SSL adds a significant overhead to an HTTP transaction for the following reasons.
For these reasons SSL HTTP is slower and has far greater impact
on the server system CPU 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.
Interoperability
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.
To date OpenSSL certificates, and those from Thawte and VeriSign have been deployed on WASD servers.
WASD supports both 40bit, USA "export-grade" encryption, as well as 128-bit, full-strength, USA "domestic-grade" 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.
The "/SSL" qualifier controls which version(s) of the SSL protocol
the server will support; "2", "3" or "23" (i.e. versions 2
and 3, also the default). Using /NOSSL disables the SSL functionality of an
SSL executable.
14.1 - SSL Configuration
WASD SSL installation creates an OpenSSL directory in the source area,
HT_ROOT:[SRC.OPENSSL-n_n_n] (look for it here)containing the OpenSSL copyright notice, object libraries, object modules for building executables, example certificates, and some other support files and documentation.
The example HTTPd startup procedure already contains support for the SSL executable. If this has been used as the basis for startup then only the respective boolean needs to be altered to use the SSL 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 "https:" in the parameter. The default port for an SSL service is 443.
WASD can configure services using the HTTPD$CONFIG [service] directive, the
HTTPD$SERVICE configuration file, or even the /SERVICE= qualifier.
14.1.1 - HTTPD$CONFIG [Service]
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.
[Service]
alpha.wasd.dsto.defence.gov.au
https://alpha.wasd.dsto.defence.gov.au
The one further requirement of an SSL server is a 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.
[Service]
alpha.wasd.dsto.defence.gov.au
https://alpha.wasd.dsto.defence.gov.au;cert=ht_root:[local]alpha.pem
https://beta.wasd.dsto.defence.gov.au;cert=ht_root:[local]beta.pem
14.1.2 - HTTPD$SERVICE
SSL service configuration using the HTTPD$SERVICE configuration is slightly
simpler, with a specific configuration directive for each aspect. See
8 - Service Configuration. This example illustrates configuring
the same services as used in the previous section.
[[http://alpha.wasd.dsto.defence.gov.au:80]]
[[https://alpha.wasd.dsto.defence.gov.au:443]]
[ServiceSSLcert] ht_root:[local]alpha.pem
[[https://beta.wasd.dsto.defence.gov.au:443]]
[ServiceSSLcert] ht_root:[local]beta.pem
14.1.3 - SSL Server Certificate
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.
14.1.4 - SSL Private key
The private key is used to validate and enable the server certificate. A private key is enabled using a 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.
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 "STATUS:" line (see 20.5 - HTTPd Monitor), and if any OPCOM category is enabled via an operator message (see 6.6 - OPCOM Logging). If the private key password is not available with the key it is recommended that OPCOM be configured, enabled and monitored at all times.
When a private key password is requested by the server it is supplied using
the /DO=SSL=KEY=PASSWORD directive (see 5.3.2 - Server Command Line 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.
Enter private key password []:
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.
14.1.5 - SSL Virtual Services
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).
This is not a WASD restriction, it applies to all servers for significant technical reasons. Secure Sockets Layer is designed to wrap an entire application protocol (in this case HTTP). HTTP virtual services use the "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.
For example, unique certificates for https://www.company1.com:443/ and
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
"sharing".
14.1.6 - SSL Access Control
When authorization is in place (see 12 - Authentication and 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 (see
14.1.7 - Authorization Using X.509 Certification). SSL may be used as part of the site's
access control policy, as whole-of-site, see 12.1 - Authentication Policy, or
on a per-path basis, see Conditionals and
Access Restriction List.
14.1.7 - Authorization Using X.509 Certification
The server access control functionality (authentication and authorization) allows the use of public key infrastructure (PKI) X.509 v3 client certificates for establishing identity and based on that apply authorization constraints. See 12 - Authentication and Authorization for general information on WASD authorization and 12.3 - Authorization Configuration File for configuring a X509 realm. 14.6 - SSL References provides introductory references on public-key cryptography and PKI.
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.
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.
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 "[LT:integer]" and "[TO:integer]" directives described below.
14.1.8 - Features
WASD provides a range of capabilities when using X.509 client certificates.
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.
General Setup
Client certificate authorization has reasonable defaults. If some aspect requires site refinement the following /SSL= qualifier parameters can provide per-server defaults.
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
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.
[Service]
https://the.host.name;verify
https://the.host.name;cafile=HT_ROOT:[LOCAL]CA_THE_HOST_NAME.TXT
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).
[[https://the.host.name:443]]
[ServiceSSLclientVerifyRequired] enabled
[ServiceSSLclientCAfile] HT_ROOT:[LOCAL]CA_THE_HOST_NAME.TXT
By Resource
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 "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.
[X509]
/path/requiring/cert/* r
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 "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 "[to:EXPIRED]"
directive forcing the client to explicitly select a certificate with each
access.
[X509]
/cgi-bin/client_cert_details r,param="[vf:OPTIONAL][to:EXPIRED]"
A number of such directives are available controlling some aspects of the certificate negotiation and verification. The "[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).
Optional "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.
These function and can be used in a similar fashion to mapping rule conditionals (see 10.7 - Conditional Mapping). 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.
Note that the "IS:" and "SU:" conditionals each have a specific-record and an 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,
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
14.6 - SSL References for some basic resources).
[X509]
# only give "VeriSign"ed ones access
/controlled/path1/* r+w,param="[IS:/O=VeriSign\ Inc.]"
# only give non-"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 "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]"
Of course, access control via group membership is also available. The
effective username for the list is the 32 digit fingerprint of the
client certificate (shown as REMOTE_USER IN the first example of
14.1.11 - X.509 Authorization CGI Variables), or the Subject DN record as specified using
the [RU:/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.
# 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
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.
[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=]"
14.1.10 - Certificate Authority Verification File
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 ";cafile=" or "[ServiceSSLclientCAfile]" directives.
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 "#" or "!" characters. For WASD this would be best stored in the HT_ROOT:[LOCAL] directory, or site equivalent.
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.
################################################################
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
...
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
...
35:b0:7b:25:ba:b8:d3:8e:ab:3f:38:9d:00:34:00:98:f3:d1:
71:94
################################################################
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 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 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.
14.1.11 - X.509 Authorization CGI Variables
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.
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"
Other CGI variables optionally may be enabled using HTTPD$MAP mapping
rules. See 14.3 - SSL CGI Variables. 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.
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"
14.2 - Certificate Management
This is not a tutorial on X.509 certificates and their management. Refer to the listed references, 14.6 - SSL References, for further information on this aspect. It does provide some basic guidelines.
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.
The three types of certifcates of interest here should not be confused.
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. This is the default used by the example startup procedure and will suffice to demonstrate the server's functionality. If a "live" SSL site is required a unique certificate issued by a third-party Certificate Authority is desirable.
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.
The first requirement may be a tailored "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 "Server Certificates" for specific host names are required. Procedures and brief notes in the
HT_ROOT:[SRC.OPENSSL-n_n_n.WASD] (look for it here)directory provide some support for these activities.
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.n & v4.n, v5.n, v6.n) and MS Internet Explorer (v4.n, v5.n) automatically invokes a server certificate load dialog when it encounters a site using a valid but unknown server certificate.
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.
To facilitate loading CA certificates into a browser ensure the following
entries are contained in the HTTP$CONFIG configuration file:
[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
Then just provide a link to the required certificate file(s), and click.
Navigator should be able to load using either certificate format. MSIE
v3.n will load and report on the ".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.n and
v5.n seem able to use the ".CRT" certificate.
Changing Server Certificates
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.
14.2.2 - Client Certificate
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.
Manual Generation
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 on-line HTML
form.
Semi-Automatic Generation
Using this approach the user generates a Certificate Signing Request (CSR) on-line, which is then further processed off-line, at the discretion of the site administrator. Only Netscape browsers are supported for what is described below.
A basic DCL procedure providing such a facility is
HT_ROOT:[SRC.OPENSSL-n_n_n.WASD]CLIENT_CERT_REQUEST.COM
This semi-automatic method would probably be the author's preference over
the on-demand approach (see below).
Generation On-Demand
Automatic, on-demand client certificate generation allows any user (subject to access controls) to generate a client certificate automatically via an on-line 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.
HT_ROOT:[SRC.OPENSSL-n_n_n.WASD]CLIENT_CERT_REQUEST.COM(and yes, it's the same procedure as used with the semi-automatic approach, just configured differently).
CGI variables specific to SSL transactions optionally may be enabled using
HTTPD$MAP mapping rules. See 10.3.5 - SET Rule in
10 - Mapping Rules. 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 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.
set /path/* SSLCGI=purveyor 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"
Note that this example also shows SSL_CLIENT_...
variables. These will only be present if the request is X.509 certificate
authenticated.
set /path/* SSLCGI=apache_mod_ssl 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"
The Apache mod_ssl client certificate details described in
14.1.11 - X.509 Authorization CGI Variables above are not shown in the above example but
would be included if the request was X.509 authenticated.
14.4 - WASD SSL Quick-Start
If the basic WASD package is installed, configured and performing satisfactorily the following steps give a quick outline for support of SSL.
$ UNZIP -z device:[dir]archive.ZIP
$ SET DEFAULT HT_ROOT:[000000] $ UNZIP "-V" device:[dir]archive.ZIP
It assumes a vanilla setup, using the standard directories and
account environment described in this document. All sections prompt before
performing any action and default to "no". The SSL parameter indicates
the SSL components should be processed.
$ @UPDATE SSL
It is also possible to check the SSL package at any other time using the
FREEWARE_DEMO.COM
procedure. It is necessary to specify that it is to use the SSL executable.
Follow the displayed instructions.
$ @HT_ROOT:[000000]FREEWARE_DEMO SSL
[Service] alpha.dsto.defence.gov.au https://alpha.dsto.defence.gov.au
$ HTTPD /DO=EXIT $ @HT_ROOT:[LOCAL]STARTUP
http://the.host.name/
https://the.host.name/
WASD implements SSL using a freely available software toolkit supported by the OpenSSL Project, and in particular the VMS port package supported by Richard Levitte (levitte@lp.se) and Robert Byer (ByerRA@aol.com). OpenSSL is a continuing development of the "SSLeay" toolkit (pronounced "S-S-L-E-A-Y", i.e. all letters spelt), authored by Eric Young and Tim Hudson. OpenSSL is not a GNU-licensed package, but does makes unrestricted commercial and non-commercial use available. See references below.
If the OpenSSL component of WASD is installed it can be found in
HT_ROOT:[SRC.OPENSSL-n_n_n] (look for it here).
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 ;^).
14.6 - SSL References
The following provide a starting-point for investigating SSL and OpenSSL further (verified available at time of publication).