HELIOS WebShare HTTPS/SSL support

Introduction

This document outlines how to configure your SSL setup. HELIOS WebShare SSL support is built using the standard Java security SSL implementation. Java security allows implementations of the JVM flexibility in how security is implemented. Unfortunately, the flexibility means there is no definitive mechanism for configuring SSL security on all JVMs. In this document, we will describe how to use the standard JDK 1.4 tools to accomplish these tasks.

What does SSL mean?

SSL (Secure Sockets Layer) is a protocol designed by Netscape Communications Corporation to provide encrypted communications on the Internet. SSL is layered beneath application protocols such as HTTP, SMTP, FTP, Telnet, Gopher, and NNTP and is layered above the connection protocol TCP/IP. It is used by the HTTPS access method. SSL works by using a private key to encrypt data that is transferred over the SSL connection. Both Netscape Navigator and Internet Explorer support SSL, and many Web sites use the protocol to obtain confidential user information, such as credit card numbers. By convention, URLs that require an SSL connection start with https: instead of http:.

Background

A server SSL connection uses two sets of certificates to secure the connection. The first set is called a "keystore". The keystore contains the keys and certificates for the server. These security credentials are used to prove to clients that the server is legitimately operating on behalf of a particular domain. If your server will only need to act as one domain, you only need one key entry and certificate in the keystore. Keys are stored in the keystore under aliases. Each alias corresponds to a domain name, e.g.: webshare.yourserver.com.

Certificates attempt to guarantee that a particular party is who they claim to be. Certificates are trusted based on who signed the certifcate. If you only require light security, are deploying for internal use on trusted networks, etc. you can use "self-signed" certificates. Self-signed certificates encrypts the communication channel between client and server. However the client must verify the legitimacy of the self-signed certificate through some other channel. The most common client reaction to a self-signed certificate is to ask the user whether to trust the certificate, or to silently trust the certificate is legitimate. Unfortunately, blindly accepting self-signed certificates opens up the system to "man-in-the-middle" attacks.

The advantage of a self-signed certificate is that you can create them for free which is great when yearly certificate signature cost is a major concern, or for testing and evaluation. In addition, you can safely use a self-signed certificate if you can verify that the certificate you are using is legitimate. So if a system administrator creates a self-signed certificate, then personally installs it on a client's truststore (so that the certificate is trusted) you can be assured that the SSL connection will only work between the client and the correct server.

For higher security deployments, you should get your certificate signed by a CA (Certificate Authority). Clients truststores will usually contain the certificates of the major CAs and can verify that a CA has signed a certificate. This chain of trust allows clients to trust certificate from servers they have never interacted with before. Certificate signing is similar to a public notary (with equivalent amounts of verification of identity, record keeping, and costs).

Quick Setup with the built-in "default" certificate
On the WebShare WebObjects Server it is required to configure the HTTPS/SSL port. A good port number is 443 (default for HTTPS). The "prefvalue" command for this to set is:

# cd HELIOSDIR
# bin/srvutil stop websharewoa
# bin/srvutil start websharewoa
# bin/prefvalue -k Programs/websharewoa/SSLPort -t int 443

Note: The preference SSLPort specifies the WebShare WebObjects Server port number for HTTPS/SSL connections to the browser.

# cp var/run/webshare.woa/Contents/Resources/adaptorssl.sample var/conf/adaptorssl.key
# echo hellothere > var/conf/adaptorssl.pass

Restart the WebShare WebObejcts Server via:

# bin/srvutil stop websharewoa
# bin/srvutil start websharewoa

The WebShare WebObjects Server will now be available via standard HTTP as well as HTTPS. The HTTPS connections can be started via the following browser URL:

https://webshare.yourdomain.com

The DNS name must be replaced with the correct name for your WebShare Server.

Note: If the default port for SSL is not 443 the URL must include the port number, e.g. for port 3009 the browser URL is:

https://webshare.yourdomain.com:3009

Sun JDK 1.4 security tools

The Sun JDK (version 1.4.x) ships with all the security tools you need to configure SSL with HELIOS WebShare WebObjects Server. The most important is the "keytool" located in the "JAVA_HOME/bin" directory of the Java runtime. Sun JVMs persist keystores and truststores on the file system as encrypted files. The "keytool" is used to create, read, update, and delete entries in these files. HELIOS WebShare WebObjects ships with a self-signed "dummy" certificate designed for initial evaluation testing.

In order to configure SSL on your server you need to complete the following tasks:

  1. Decide on your HELIOS WebShare server's domain.

  2. Create a self-signed SSL server certificate for your server domain. Note: you may already have one if your HELIOS WebShare WebObjects server domain matches an existing web domain with SSL. If so, you can skip to step 4.

  3. [Optional] Have a Certificate Authority (CA) certify the SSL server certificate.

    a) Generate a certificate signing request (CSR).
    b) Submit your CSR to a CA for signing.

  4. Import the server certificate into the keystore. Note: if you are going to use a self-signed certificate generated in step 2, the certificate is already imported and you can skip this step.

1 Decide on a Server Domain
The WebShare WebObjects Server domain should match the server host name, e.g. "webshare.yourdomain.com".

2 Create a self-signed server certificate
In order to create a self-signed server certificate go to the command line on the WebShare WebObjects Server. "HELIOSDIR" must be replaced with the HELIOS installation directory, e.g. "/usr/local/helios" for the default installation:

# cd HELIOSDIR/var/conf

Generate a key using the Java "keytool", which is located in the Java "/bin" directory.

# keytool -genkey -keystore adaptorssl.key -keyalg rsa -alias webshare.yourdomain.com

Please complete the following questions:

Enter the keystore password:
hellothere (you should use your private password)

What is your first and last name?:
webshare.yourdomain.com

What is the name of your organizational unit?:
Server Department

What is the name of your organization?:
Your Company Name

What is the name of your city or locality?:
Garbsen

What is the name of your state or province?:
Germany

What is the two-letter country code for this unit?:
Example: DE (for "Germany" - check with your CA)

Answer that the settings are correct or abort via "CRTL-C" and start over again.

Enter key password for <webshare.yourdomain.com>:
hellothere

You should see the "adaptorssl.key" file.

As a next step enter the keystore password in a configuration file, which will be used by the WebShare WebObjects Server, to allow access to the "adaptorssl.key" content.

Create the "adaptorssl.pass" password file via:

# cd HELIOSDIR/var/conf
# echo "yourpassword" > adaptorssl.pass

To secure your keystore password the file permissions "adaptorssl.pass" can be changed that no user can access this file, only the WebShare WebObjects root user could have access, e.g.

# chmod 700 adaptorssl.pass

If you do not plan a CA signed certificate the self made HTTPS certificates should work and the additional steps are not required. Continue with a server restart to complete it (go to Completion below).

3 Obtain a CA signed certificate
If you decide to get a CA signed certificate, you must first export the certificate in the standard CSR format. You can do this with the "keytool":

# keytool -certreq -keystore adaptorssl.key -alias webshare.yourdomain.com -file cert.webshare.yourdomain.com

Substitute your server name for "webshare.yourdomain.com" and the name of the certificate file you wish to produce for "cert.webshare.yourdomain.com". Submit the generated CSR to the CA and follow their instructions to get it signed.

4 Import server certificates
If you had a CA sign your server certificate, or if you have an existing SSL certificate, you must import it using the Java "keytool":

# keytool -import -keystore adaptorssl.key -alias webshare.yourdomain.com -file signed_certificate_file

It is important that the alias has not already an associated key. Otherwise you will receive an error.

Completion

Now restart of the WebShare WebObejcts Server via:

# srvutil stop websharewoa
# srvutil start websharewoa

Q & A

How will a "Certificate Request" look like?
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBxzCCATACAQAwgYYxCzAJBgNVBAYTAkRFMRAwDgYDVQQIEwdHZXJtYW55MRAwDgYDVQQHEwdH
YXJic2VuMR0wGwYDVQQKExRIRUxJT1MgU29mdHdhcmUgR21iSDEXMBUGA1UECxMOSEVMSU9TIFN1
...
-----END NEW CERTIFICATE REQUEST-----

Usually this needs to be submitted including the "----BEGIN..." and "----END..." lines into your CA (Certificate Authority, e.g. verisign.com)

Why is my browser telling me that the certificate does not match?
There are multiple reasons for this:

a) Your server domain name URL does not match the certificate
b) Your certificate has not been sign by a CA
c) You certificate has expired
d) Your browser does not know about your CA, e.g. VeriSign is installed in all major browsers.

Our experience is that Netscape browsers provide more detailed information on certificates than others. In a case of a problem Netscape can be used to show how the CA certificate response will look like.

-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBxzCCATACAQAwgYYxCzAJBgNVBAYTAkRFMRAwDgYDVQQIEwdHZXJtYW55MRAwDgYDVQQHEwdH
YXJic2VuMR0wGwYDVQQKExRIRUxJT1MgU29mdHdhcmUgR21iSDEXMBUGA1UECxMOSEVMSU9TIFN1
...
-----END NEW CERTIFICATE REQUEST-----

Known Issues

In case "websharewoa" does issue an error message during startup :

websharewoa: [2004-04-30 15:54:30 MEST] <main> Unable to establish an SSL connection to port 443 on this host

and then exits, make sure that the SSL port is not used by another application, e.g.:

netstat -an | grep 443

should not list a line like below:

*.443 *.* 0 0 24576 0 LISTEN

Also check for the following message:

websharewoa: [2004-04-30 15:54:30 MEST] <main> com.webobjects.foundation.NSForwardException for com.webobjects.foundation.NSForwardException for java.security.NoSuchAlgorithmException: Algorithm SunX509 not available "Algorithm SunX509 not available"

indicates that the used JVM implementation does not offer SSL support. Check for an update to that JVM or install the Sun JVM.


The Microsoft Internet Explorer 6 cannot use a port other than 443 (default) for a "websharewoa" secure HTTPS connection.