WASD Hypertext Services - Technical Overview

14 - Secure Sockets Layer

14.1 - SSL Configuration
14.2 - Certificate Management
14.3 - SSL CGI Variables
14.4 - SSL Quick-Start
14.5 - OpenSSL
14.6 - SSL References

[next] [previous] [contents] [full-page]

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.

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

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.

An initial connection establishment, where the client and server exchange cryptographic data and authorize the transaction.
The transaction transfer, where all application data must be processed by the CPU into an encrypted stream, and back ... very expensive processes.
The encrypted data contains more bytes than the raw data, increasing network transfer time.
Other miscellaneous SSL handshaking for the life of the transaction.

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.

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

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

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

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. 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.2 - Certificate Management

This is not a tutorial on 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 associate a public cryptographic key with the identity of the certificate holder, usually an individual or server. It includes a distinguishing 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 two types of certifcates of interest here should not be confused.

CA - The Certificate Authority identifies the authority, or organization, that issues a server certificate.
Server - Identifies a particular end-service. It's value as an guarantee of identity is founded in the authority of the organization that issues the certificate. It is the certificate specified to the server at startup.

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.

Loading Authority Certificates

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) and MS Internet Explorer (v4.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 seems 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.3 - SSL CGI Variables

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 some variables will contain newline characters (0x10). The line breaks in the examples do not necesarily reflect those characters. As WASD v7.1 does not support X.509 client certificate authentication CGI variables related to these are (obviously) not available.

set /path/* SSLCGI=purveyor

  WWW_SECURITY_STATUS == "SSL"
  WWW_SSL_CIPHER == "RC4-MD5"
  WWW_SSL_CIPHER_KEYSIZE == "128"
  WWW_SSL_CLIENT_AUTHENTICATED == "FALSE"
  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"

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"

14.4 - SSL Quick-Start

If the basic WASD v6.n package is installed, configured and performing satisfactorily the following steps give a quick outline for support of SSL.

The ZIP archive will contain brief installation instructions. Use the following command to read this and any other information provided.
```
  $ UNZIP -z device:[dir]archive.ZIP
```

UNZIP the WASD SSL package.

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

Once UNZIPped it will be necessary to link the executables. This should be performed using the UPDATE.COM procedure.
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
```
Once linked the UPDATE.COM procedure will prompt for permission to execute the demonstration/check procedure.
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
```
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.
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
```
  [Service]
  alpha.dsto.defence.gov.au
  https://alpha.dsto.defence.gov.au
```

Shutdown the server completely, then restart.

  $ HTTPD /DO=EXIT
  $ @HT_ROOT:[LOCAL]STARTUP

To check the functionality (on default ports) access the server via
- Standard HTTP
```
  http://the.host.name/
```
- SSL HTTP
```
  https://the.host.name/
```
Once the server has been proved functional with the example certificate it is recommended that a server-specific certificate be created using the WASD support procedures described in 14.2 - Certificate Management. This may then be used by placing it in the appropriate local directory, assigning the WASD_SSL_CERT symbol appropriately before startup.

14.5 - OpenSSL

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

http://www.openssl.org/
OpenSSL Project. This site is the prime source for the full toolkit, documentation, related links, news and support via mailing lists, etc.
http://www.free.lp.se/openssl/
OpenSSL on the VMS platform (Richard Levitte).
http://www.free.lp.se/openssl/docs/
Certificate management, building the full package, etc., (Robert Byer).
http://docs.iplanet.com/docs/manuals/security/sslin/index.htm
iPlanet Introduction to SSL
http://docs.iplanet.com/docs/manuals/security/pkin/index.htm
iPlanet Introduction to Public-Key Cryptography
http://www.cs.auckland.ac.nz/~pgut001/links.html
"Encryption and Security-related Resources" ... an (almost rediculously) exhaustive list of security and cryptography links, including some on SSL.

[next] [previous] [contents] [full-page]