If you have a comment about the content of this article, please feel free to vent in the OS/2 eZine discussion forums.

Making Keys for Apache SSL

Apache for OS/2

The place to start with setting up an Apache server is at the Apache for OS/2 page at http://silk.apana.org.au/apache/ Here you can download the regular non-SSL version of Apache, or you can get Apache with mod_ssl along with OpenSSL, which you will also need, at http://silk.apana.org.au/apache/apache-ssl.html

Some Very, Very Brief Coverage of SSL Settings for Apache

Once you have unpacked Apache to the directory where it will be located, (there isn't any sort of install script) you should change to the conf directory and copy httpd.conf-dist-os2 to httpd.conf. You can then edit the httpd.conf file and the many settings needed to set up your Apache server. I'm only going to talk about a few of them specifically needed to get the SSL version of Apache running. You'll still need to go through this entire settings file and puzzle out what things need to be changed. I'd recommend you plan to spend some time with the documentation.

The first thing to do is to uncomment the line that loads the SSL module as shown below

LoadModule ssl_module libexec/libssl.dll

The next important setting for SSL is the Servername. This must be set to the name of the server. If it is to be referred to by a URL like www.os2ezine.com then you would enter www.os2ezine.com for this setting, or if it will be referred to by an IP address, enter that in dotted decimal format as shown below.

ServerName 192.168.0.100

Remember this name, as it must be entered later when we create the SSL key and certificate for the Apache server.

You'll also need to set up the virtual host for the SSL section of your website as shown below. Make sure you use / slashes rather than \ slashes for directory paths.

# General setup for the virtual host
DocumentRoot "f:/apache/secure"
ServerName 192.168.0.100
ServerAdmin you@your.address
ErrorLog logs/error_log
TransferLog logs/access_log

You also need to turn on the ciphers, I don't yet understand the syntax for this line, but it is needed for SSL connections to happen.

SSLCipherSuite ALL:!ADH:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP:+eNULL

You also need to tell SSL where to look for the key and certificate which we will create in a moment. These will be called server.crt and server.key.

SSLCertificateFile f:/apache/conf/ssl.crt/server.crt
SSLCertificateKeyFile f:/apache/conf/ssl.key/server.key

I'm not sure what the CA Certificate File does, but there is a giant file provided with Apache for this purpose so why not let it use it?

SSLCACertificateFile f:/apache/conf/ssl.crt/ca-bundle.crt

If you want anyone to be able to connect to the server, you need to change the client verification setting. This is designed to allow the server to verify that clients are who they claim to be when they attempt to connect to your server by requesting certificates from them.

SSLVerifyClient none

There are lots of other settings in the .conf file that you will need to adjust, fortunately most of them are documented right in the file so you don't have to go digging too much.

Creating the Keys

Creating the keys should be a fairly simple task. All I wanted was a self-signed certificate that would allow secure transactions to the web server. I spent most of two weeks fighting to get OpenSSL to produce keys that Apache would accept.

The first hurdle is getting OpenSSL to work. To install OpenSSL, just unzip it on a drive that supports long file names. To make OpenSSL work, you need a configuration file, openssl.cnf. Below is the openssl.cnf file that I was finally able to make work. OpenSSL for OS/2 doesn't come with a configuration file, or even a sample. I went to www.openssl.org for help, but their configuration file produced error messages rather than working keys. If you are planning to go to their documentation, be warned it is definitely not for the novice. Finally, after much hunting, I found the sample .cnf file below and lo and behold, it produced working keys.

#
# SSLeay example configuration file.
# This is mostly being used for generation of certificate requests.
#

RANDFILE = .rnd

####################################################################
[ ca ]
default_ca = CA_default # The default ca section

####################################################################
[ CA_default ]

dir = demoCA # Where everything is kept
certs = $dir\certs # Where the issued certs are kept
crl_dir = $dir\crl # Where the issued crl are kept
database = $dir\index.txt # database index file.
new_certs_dir = $dir\newcerts # default place for new certs.

certificate = $dir\cacert.pem # The CA certificate
serial = $dir\serial # The current serial number
crl = $dir\crl.pem # The current CRL
private_key = $dir\private\cakey.pem # The private key
RANDFILE = $dir\private\private.rnd # private random number file

x509_extensions = x509v3_extensions # The extentions to add to the cert
default_days = 365 # how long to certify for
default_crl_days= 30 # how long before next CRL
default_md = md5 # which md to use.
preserve = no # keep passed DN ordering

# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy = policy_match

# For the CA policy
[ policy_match ]
countryName = optional
stateOrProvinceName = optional
organizationName = optional
organizationalUnitName = optional
commonName = supplied
emailAddress = optional

# For the 'anything' policy
# At this point in time, you must list all acceptable 'object'
# types.
[ policy_anything ]
countryName = optional
stateOrProvinceName = optional
localityName = optional
organizationName = optional
organizationalUnitName = optional
commonName = supplied
emailAddress = optional

####################################################################
[ req ]
default_bits = 1024
default_keyfile = privkey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes

[ req_distinguished_name ]
countryName = Country Name (2 letter code)
countryName_min = 2
countryName_max = 2

stateOrProvinceName = State or Province Name (full name)

localityName = Locality Name (eg, city)

0.organizationName = Organization Name (eg, company)

organizationalUnitName = Organizational Unit Name (eg, section)

commonName = Common Name (eg, your website's domain name)
commonName_max = 64

emailAddress = Email Address
emailAddress_max = 40

[ req_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20

[ x509v3_extensions ]

# under ASN.1, the 0 bit would be encoded as 80
nsCertType = 0x40

#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName
#nsCertSequence
#nsCertExt
#nsDataType

Creating the Certificate Signing Request

The first step is to generate something called a Certificate Signing Request and a private key. These are needed later when we create the Server Key and Certificate. When asked for a PEM pass phrase, enter a password, anything will do, since we are going to remove it later.

[F:\apache\openssl]openssl req -new > server.csr -config openssl.cnf
Using configuration from openssl.cnf
Generating a 1024 bit RSA private key
.........................+++++
.................+++++
writing new private key to 'privkey.pem'
Enter PEM pass phrase:
Verifying password - 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) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (eg, your websites domain name) []:
Email Address []:

Please enter the following 'extra' attributes to be sent with your certificate request

A challenge password []:

You'll notice when you do this that it requires you to enter the data blind, so type carefully. You will be prompted to enter a 2-letter country code, such as US or CA. Next the name of the State or Province where you are located and the city, company, and section name. The common name must be entered exactly as it appears in the ServerName directive in the httpd.conf file or Apache will not accept your certificate. Lastly enter the email address of the server administrator and a challenge password.

Creating the Server Key

Next you need to create the server.key file. Note that this creates an unencrypted version of the key. Normally, these files are encrypted in PEM format to protect them from prying eyes, however this means that each time Apache starts, you need to type in the password for the certificate file at the console. This is a problem if you are going to run an unattended server that needs to be able to start on its own in case of power loss or system problems. The big concern here is that this file must not be accessible by anyone, so set up your security well. The instructions I found also suggested deleting the resulting .rnd file after you are all done since it contains information that might help in a cryptographic attack on your server.

[F:\apache\openssl]openssl rsa -in privkey.pem -out server.key
read RSA private key
Enter PEM pass phrase:
writing RSA private key

Creating the Certificate

Lastly we need to take the Certificate Signing Request, and the Server key, and create a Certificate we can use on our website. If you prefer, you could skip this step and instead send your CSR and KEY to a signing authority to have them signed. I wanted a self-signed certificate, since I didn't want to spend any money to get the certificate. The trade-off is that with a self-signed certificate, the browser will prompt the website user to make sure they are willing to accept a certificate from your website in order to do secure transactions. The simplest way to handle this is to provide an entry page to the secure portion of your website that has instructions on what to do when the dialogs appear in their browser. Since most users are unfamiliar with the security dialogs in browsers, this will help reduce your users' confusion.

[F:\apache\openssl]openssl x509 -in server.csr -out server.crt -req -signkey server.key -days 365
Signature ok
subject=/C=CA/ST=British Columbia/L=Vancouver/O=Fast Widgets, Inc./OU=Website/CN=192.168.0.100/Email=you@yourdomain.com
Getting Private key

This creates a self-signed certificate that is good for 365 days. You now take the server.key and put it in the conf\ssl.key directory, and place the server.crt into conf\ssl.crt.

Starting Apache with SSL

To start Apache and use SSL, you need to add the -DSSL switch to its command line like:

httpd -DSSL

This will cause Apache to include the SSL portions of its .conf file. If all goes well, Apache should start and display its version number. If it doesn't, a good place to look for help is in the \apache\logs\ssl_engine_log file. This is where SSL will write any errors it encounters.

Connecting to the Secure Server

Assuming you have placed some html documents such as index.html in the secure document path of your web server, in this case f:/apache/secure, you should be able to access them in any web browser by entering:

https://192.168.0.100

Note the use of https rather than http before your website name. The first time you access the website, you will be presented with a series of dialogs to confirm that you want to accept a certificate from the web server and that the certificate is OK looking to you. Once that is done, you will be able to access secure documents. The first time I saw that little lock icon locked, I was ecstatic!

Some Gotchas and Final Words of Advice

Please understand that I am a relative novice at this. I don't understand a lot of the facilities provided by SSL and am still learning at a pretty good rate. When I started, all I was looking for was that little lock icon. Had I known it would be this complicated and frustrating, I probably wouldn't have bothered. I got help from quite a few people for which I am grateful, and I'll pass on any help I can, but I am far from an authority on this subject.

I'm not sure what happens when the certificate expires. Apparently they can be renewed, I figure I'll worry about that in a year. I did however keep all of the temporary files generated by this process as I believe at least some of them will be needed.

The key created above is not encrypted so be very careful setting up your website's security, use a good firewall, and have good physical security.

I also played with the REXX utilities by Zdenek Wagner mentioned on the Apache for OS/2 website. While the author is very friendly and helpful, and others have had good luck with them, and reading their documentation helped me understand the whole process a little better, I was not able to make them work. I believe the fault lies with OpenSSL since it offered up a wide varietiy of error messages no-one seemed to be able to explain. I plan to revisit the REXX tools in a year when I need to renew my certificate as I believe they will be a help with that.

If you are planning to use this server for a commercial enterprise, be aware that a number of the algorithms used are patented and subject to licensing and royalty fees from the patent holders. You will need to look into this in your own country as different patents are registered in different countries. Apparently you can use the SSLCipherSuite setting to control which algorithms are used to make sure you aren't infringing any patents. If anyone has any words of advice about this, bring them to the online forums. I'm sure there'll be lots of questions.