Chapter 4: Tutorial: Configuring SSL Security in the Server

This tutorial shows how to configure SSL security in reUZE Server.

Introduction

In this tutorial you take two different roles:

  1. In the role of the server administrator, you configure SSL security in reUZE Server.

    You create an HTTPS listener and you install the server certificate and private key file that you created in the previous tutorial.

  2. In the role of a user, you connect to the server from a Web browser. You (as a user) want reassurance that you have connected to the correct Web site and that it is trustworthy.

    When you first try and access the server, a security alert appears. You install the CA's root certificate in response to this alert. In practice, you rarely need to install CA root certificates.

In this tutorial, you use reUZE Server to create enterprise servers, including one called ESDEMO, which is created by default. Within an enterprise server, you can create listeners for different kinds of communication. One listener created by default is HTTP Echo, intended as a simple test of Web communication. When a Web browser connects to HTTP Echo, the latter sends it a simple Web page with some identifying details.

Creating a Secure HTTPS Listener

This section describes the process that the server owner uses to configure an enterprise server to use SSL. In this tutorial, you create an HTTPS version of the HTTP Echo listener. .

  1. In a web browser, connect to ES Admin, for example by entering: http://localhost:86 Make sure the enterprise server you're going to use, for example ESDEMO, is stopped.
  2. Click Edit > Listeners to access the Listeners page. Make sure the Process filter is set to All so you can see all the listeners.
  3. Click Add to create a listener for HTTPS.
  4. In the Name field, enter HTTPS Echo as the name.
  5. Change the Endpoint Address to *.9443.

    Although you can use port 443, it might already be in use. For example, IIS listens by default on port 443. If you want to use port 443, you can check whether it is in use, by running the following command: 

    netstat -an | findstr 443
  6. Specify that this will be an "HTTP echo" listener, which provides a simple response to HTTP requests. To do this, select Custom under Supported Conversation Type and enter http-echo in the field alongside.
  7. In the Description field, type:
    Simple secure HTTP test
  8. Click Add.

On the Listeners page, the new entry for HTTP Echo appears.

Installing the Server Certificate

In this section you take the role of the server owner installing the server certificate on the server so that remote Web users will be able to request it. To install a certificate, you store the certificate and the key file in a folder accessible to your server software.

  1. Edit the new HTTPS Echo listener . To do this, select the new listener on the Listeners page and click Edit.
  2. Check Secure Sockets Layer.
  3. Enter the full path and filenames of your server certificate and private key in the Certificate and Keyfile fields. These are by default srvcert.pem and srvkey.pem, and you created them in the DemoCA directory.
  4. Click OK.

    On the Listeners page, the entry for HTTP Echo now has a padlock symbol, which shows that it uses SSL.

Setting a Pass Phrase

To enable the HTTPS listener to run, you need to enter the pass phrase that you defined for the private key file. In other situations, you might also have a pass phrase for the server certificate, which you would also need to enter. This tutorial does not require one.

There are two ways of setting the pass phrases. One way is to store the pass phrases in a file, and the other is to enter them once the enterprise server is started.

To set the pass phrase in a file:

  1. Create the file mf-server.dat in the base\bin directory, if the file doesn't already exist.
  2. Add the following lines to mf-server.dat: 
    [HTTPS Echo/SSL/passphrases]
certificate=
keyfile=open sesame

    Make sure the name HTTPS Echo is spelled exactly as it is in ES Admin.

  3. Start ESDEMO from the home page of ES Admin.
  4. When ESDEMO has started, look at the Listeners page to make sure that the new listener HTTPS Echo has started, as with the other listeners.

To set the pass phrase manually without using a file:

  1. Start ESDEMO from the home page of ES Admin.
  2. When ESDEMO has started, go to the Listeners page. If you didn't enter the pass phrase in the above file, the status of the listener HTTPS Echo is Start pending.
  3. Click Authorize in the Status column of HTTPS Echo. This displays the SSL Listeners page in a separate browser window.
  4. Enter open sesame in the Keyfile Passphrase field, then click Set passphrases. You can leave the Certificate Passphrase field blank, since you did not define a certificate passphrase.
  5. Confirm that the HTTPS Echo is now started by viewing the main Listeners page (and clicking Refresh if necessary).

If you ever have problems starting or running an SSL-enabled listener, it can be useful to look at the MFCS log. Click Server > Diagnostics > CS Console.

Interpreting a Security Alert

In this section you take the role of a user connecting to the server, seeking reassurance that you have connected to the correct Web site, and that it is trustworthy.

Since the Web site was certified by your Demo CA, you need your Demo CA's self-signed certificate installed in your browser in order for the Web site's certificate to be accepted. The necessary demo CA's self-signed certificate is not installed, so that you can see the messages you get.

  1. In your browser, enter https://localhost:9443.

    You could enter your machine's actual DNS host name or even its dotted decimal IP address rather than localhost. Normally, it should make no difference, but for the purposes of this tutorial please use localhost.

  2. A Security Alert is displayed. It warns you that the Web site's security certificate may not be entirely trustworthy, and it lists what's right and what's wrong with it. In the following browsers, the alert says:

    If this tutorial has been run before and the CA certificate left installed, you will not get this alert. In this case, remove the certificate as shown in the section Tidying Up below, and then restart this section.

  3. Close the security alert.

This security alert indicates that you haven't installed the self-signed certificate of the CA that issued this server certificate.

Importing the CA's Root Certificate

Browsers typically come with certificates for well-known CAs already installed, and you rarely need to install them. If you need a CA's root certificate, you can usually download it from the CA's Web site.

The demonstration CA's certificate is not pre-installed in your browser, so you need to install it. It is supplied in the private directory of the demoCA. You install this certificate, in the role of the user, as follows:

  1. In your browser, go to the options where you manage certificates.
  2. Install the CA's self-signed certificate, which is in the private folder of your DemoCA directory. Specify the file CARootCert.cer. Internet Explorer requires X509 certificates, in DER format, so only those are listed, and not the PEM format files. Mozilla Firefox can handle several types, so several are listed and you need to install the PEM-format certificate.
  3. In Internet Explorer, use the Browse button to enter Trusted Root Certification Authorities in the Certificate Store field.

    In Mozilla Firefox, check Trust this CA to identify Web sites.

  4. Look down the list under Trusted Root Certification Authorities (for IE) and Authorities (for Firefox). You will see that your Demo CA is now listed; look for its Common Name. If when you installed Micro Focus Demo CA you chose to use your computer DNS name as the DemoCA's Common Name, it will appear different to the rest, because real CAs tend to give themselves user-friendly Common Names.

Now that the CA's certificate is installed, you should be able to connect from the client Web browser, but there is one remaining problem.

Verifying the Certificate

Now that the CA's certificate is installed, you should be able to connect from the client Web browser. Here you take the role of a user again.

  1. Try to connect again. In the Web browser, enter https://localhost.
  2. Read the Security Alert again. This time it shows only one problem, which is that the name in the certificate doesn't match the URL you tried to connect to. This is a warning that the certificate might not have come from the desired Web site, but from another Web site masquerading as it.
  3. Click View Certificate. The Issued To name in the certificate is the DNS host name of your computer, and you were trying to connect to localhost, so the discrepancy is explained.
  4. Since this is in fact the desired Web site, click Close > OK.

    The connection is made, and HTTPS Echo sends its usual page with identification details to your browser, confirming that the connection has been made successfully. It is normal for most of the strings to be empty, as shown.

Tidying Up

You should remove your Demo CA's self-signed certificate from your Web browser, both to avoid confusion in real use of your browser and to enable this tutorial to be run again if required.

  1. In your browser, go to the options where you manage certificates.
  2. Select your Demo CA's certificate (the Common Name, not the organization name), then remove it.
  3. Close the browser and re-open it.

Copyright © 2009 Micro Focus (IP) Ltd. All rights reserved.