Security

Enabling SSL communication security on Apache 1.3 web server

To enable the SSL facility on Apache 1.3, an SSL (Digi-SSL™) certificate is required.
Digi-SSL™ certificate can be obtained directly from Digi-Sign and requires a CSR (Certificate Signing Request) code.
A CSR is a file/string containing your certificate application information, including your Public Key, Company Name and the Common Name (in most cases FQDN - Fully Qualified Domain Name host name).

Generate your CSR and then copy and paste the contents of the CSR file into the
Digi-Sign Digi-SSL™ web application form:

https://www.digi-sign.com/order/digi-ssl/index.php [2]

1.1 Generating a Certificate Signing Request (CSR) using Apache 1.3

To generate keys (private and public) and Certificate Signing Request do:

For a 128 bit Certificate:
openssl req -new -newkey rsa:1024 -keyout myserver.key -nodes -out server.csr

For a 256 bit Certificate:
openssl req -new -newkey rsa:2048 -keyout myserver.key -nodes -out server.csr

This creates two files. The file myserver.key contains a private key; do not disclose this file to anyone. Carefully protect the private key.

In particular, be sure to backup the private key, as there is no means to recover it should it be lost. The private key is used as input in the command to generate a Certificate Signing Request (CSR).

You will now be asked to enter details to be entered into your CSR. What you are about to enter is what is called a Distinguished Name or a DN.

For some fields there will be a default value, If you enter '.', the field will be left blank.

-----
Country Name (2 letter code) [AU]: GB
State or Province Name (full name) [Some-State]: Yorks
Locality Name (eg, city) []: York
Organization Name (eg, company) [Internet Widgits Pty Ltd]: MyCompany Ltd
Organizational Unit Name (eg, section) []: IT
Common Name (eg, YOUR name) []: mysubdomain.mydomain.com
Email Address []:

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

A challenge password []:
An optional company name []:
-----

Use the name of the web server as Common Name (CN). If the domain name is mydomain.com append the domain to the hostname (use the fully qualified domain name).

The fields email address, optional company name and challenge password can be left blank for a web server certificate.

Your CSR will now be created. Open the server.csr in a text editor and copy and paste the contents into the online enrolment form when requested.

When you make your application, make sure you include the CSR in its entirety into the appropriate section of the Digi-SSL™ web application form – including:

-----BEGIN CERTIFICATE REQUEST-----to-----END CERTIFICATE REQUEST-----
- Click Submit
- Confirm your details in the Digi-SSL™ web application form
- Finish the Digi-SSL™ web application form

Installation

Installing your Digi-SSL™ Certificate

You will receive 2 Certificates from Digi-Sign. When viewed in a text editor, these certificates will look something like:

-----BEGIN CERTIFICATE-----
MIAGCSqGSIb3DQEHAqCAMIACAQExADALBgkqhkiG9w0BBwGggDCCAmowggHXAhAF
UbM77e50M63v1Z2A/5O5MA0GCSqGSIb3DQEOBAUAMF8xCzAJBgNVBAYTAlVTMSAw
(.......)
E+cFEpf0WForA+eRP6XraWw8rTN8102zGrcJgg4P6XVS4l39+l5aCEGGbauLP5W6
K99c42ku3QrlX2+KeDi+xBG2cEIsdSiXeQS/16S36ITclu4AADEAAAAAAAAA
-----END CERTIFICATE-----

Save/upload these Certificates to the web server configuration directory (or other safe directory on the server hard drive that you will be using to hold your certificates). In this example we will use /etc/ssl/crt/. Both the public and private key files will already be in this directory. The private key used in the example will be labeled private.key and the public key will be yourdomainname.cer.

It is recommended that you make the directory that contains the private key file only readable by root.

1.2.2 Installing the CA Chain file containing the Root & Intermediate Certificates

You will need to install the chain certificates (root and intermediates) in order for browsers to trust your certificate.

As well as your Digi-SSL™ certificate (yourdomainname.cer), two other certificates, named UTN-USERFirst-Hardware.crt and Digi-SignCADigi-SSLXp.crt or Digi-SignCADigi-SSLXs.crt, might also be attached to the email from Digi-Sign.

Apache users will not require these certificates. Instead you can install the root and intermediate certificates (CA Chain) using a 'bundle' file method. The CA 'bundle' file - in most cases will be attached to the email from Digi-Sign, however you can also download it from the following URLs:

CA Bundle for Digi-Acess™ setup with Digi-SSL™ Xp CA:
http://www.digi-sign.com/downloads/certificates/digi-access/BundledCAXp.pem [3]

CA Bundle for Digi-Acess™ setup with Digi-SSL™ Xs CA:
http://www.digi-sign.com/downloads/certificates/digi-access/BundledCAXs.pem [4]

In the Virtual Host settings for your site, in the httpd.conf file (or other file where you keep your Virtual Host configuration), you will need to complete the following:

1. Copy the ca-bundle file to the same directory as httpd.conf (this contains all of the CA certificates in the chain

2. Add the following line to the SSL section of the httpd.conf (assuming /etc/httpd/conf is the directory to where you have copied the BundledCA.cer file). If the line already exists amend it to read the following:
SSLCACertificateFile /etc/httpd/conf/ca-bundle/BundledCA.cer

If you are using a different location and certificate file names you will need to change the path and filename to reflect your server.
The SSL section of the updated httpd config file should now read similar to this example (depending on your naming and directories used):

SSLCertificateFile /etc/ssl/crt/yourdomainname.cer

SSLCertificateKeyFile /etc/ssl/crt/private.key

SSLCACertificateFile /etc/httpd/conf/ca-bundle/BundledCA.cer

Important: Save your httpd.conf file and restart Apache.

Enabling Client Authentication

Enabling Client Certificate Authentication on Apache web server

To enable Client Certificate Authentication on Apache 1.3 you will need to obtain your own Digi-ID™ [1] Client Certificate, Certification Authority Certificate Chain (CA Chain) and setup Authentication Rules using the httpd.conf file and Apache configuration directives.

2.1 Obtaining the Digi-Sign Certification Authority Certificate Chain

Since Apache is using the SSLCACertificateFile configuration directive to point to the Certification Authority Chain for both SSL Certificates [5] and Client Certificate Authentication, assuming you have already setup this directive in step 1.2.2, you can omit this section.
If however, you have not obtained/received the ca-bundle file, you may download it from the following URLs:

CA Bundle for Digi-Acess™ setup with Digi-SSL™ Xp CA:
http://www.digi-sign.com/downloads/certificates/digi-access/BundledCAXp.pem [3]

CA Bundle for Digi-Acess™ setup with Digi-SSL™ Xs CA:
http://www.digi-sign.com/downloads/certificates/digi-access/BundledCAXs.pem [4]

Configuring for Digi-Access™

Configuring Apache 1.3 for Digi-Access™ Client Certificate Authentication

To configure Apache, do:

- Open for editing the httpd.conf Apache configuration file
- Locate the Virtual Host section for your SSL secured site
- You will need to decide whether you wish to secure the entire site or just a particular directory. Both options will use the same Apache configuration directives, however if you wish to implement per directory authentication, you will need to add all of the necessary directives below into the specified directory options section, i.e. within the following directory directives:

…

- Add the following directive line into your site/directory configuration section:

SSLOptions +StdEnvVars +ExportCertData

This directive can be used to control various run-time options on a per-site and per- directory basis. Normally, if multiple SSLOptions could apply to a directory, then the most specific one is taken completely; the options are not merged. However if all the options on the SSLOptions directive are preceded by a plus (+) or minus (-) symbol, the options are merged. Any options preceded by a (+) are added to the options currently in force, and any options preceded by a (-) are removed from the options currently in force.
When the option StdEnvVars is enabled, the standard set of SSL related CGI/SSI environment variables are created. This per default is disabled for performance reasons, because the information extraction step is a rather expensive operation. Enable this option for CGI and SSI requests only.

When the option ExportCertData is enabled, additional CGI/SSI environment variables are created: SSL_SERVER_CERT, SSL_CLIENT_CERT and SSL_CLIENT_CERT_CHAIN (with n = 0,1,2,..). These contain the PEM-encoded X.509 Certificates of server and client for the current HTTPS connection and can be used by CGI scripts for deeper Certificate checking. Additionally all other certificates of the client certificate [6] chain are provided, too. This bloats up the environment a little bit which is why you have to use this option to enable it on demand.

Digi-Access™ (part II)

Client Certificate Authentication

• Add the following directive line into your site/directory configuration section:

SSLVerifyClient require

This directive sets the Certificate verification level for the Client Certificate Authentication. Notice that this directive can be used both in per-server and per- directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL re-negotiation with the reconfigured client verification level after the HTTP request was read but before the HTTP response is sent.
• The following levels are available for level:
none: no client Certificate is required at all
optional: the client may present a valid Certificate
require: the client has to present a valid Certificate
optional_no_ca: the client may present a valid Certificate but it need not to be (successfully) verifiable.
In practice only levels none and require are really interesting, because level optional doesn't work with all browsers and level optional_no_ca is actually against the idea of authentication (but can be used to establish SSL test pages, etc.)
• Add the following directive line into your site/directory configuration section:

SSLVerifyDepth 10

This directive sets how deeply mod_ssl should verify before deciding that the clients don't have a valid certificate. Notice that this directive can be used both in per- server and per-directory context. In per-server context it applies to the client authentication process used in the standard SSL handshake when a connection is established. In per-directory context it forces a SSL re-negotiation with the reconfigured client verification depth after the HTTP request was read but before the HTTP response is sent.
The depth actually is the maximum number of intermediate certificate issuers, i.e.: the number of CA Certificates in CA Chain, which are max allowed to be followed while verifying the client certificate [6]. A depth of 0 means that self-signed client certificates are accepted only, the default depth of 1 means the client certificate can be self-signed or has to be signed by a CA which is directly known to the server (i.e.: the CA's certificate is under SSLCACertificatePath), etc.
• Depending on the Digi-Access™ implementation level, you may need to add the following directive(s) to enable a customized authentication rules if you choose the Apache web server to be the authentication level:
SSL Require

This directive specifies a general access requirement which has to be fulfilled in order to allow access. It's a very powerful directive because the requirement specification is an arbitrarily complex Boolean expression containing any number of access checks.

Digi-Access™ (part III)

Client Certificate Authentication

The expression must match the following syntax (given as a BNF grammar notation):

expr ::= "true" | "false"
| "!" expr
| expr "&&" expr
| expr "||" expr
| "(" expr ")"
| comp

comp ::= word "==" word | word "eq" word
| word "!=" word | word "ne" word
| word "<" word | word "lt" word
| word "<=" word | word "le" word
| word ">" word | word "gt" word
| word ">=" word | word "ge" word
| word "in" "{" wordlist "}"
| word "=~" regex
| word "!~" regex

wordlist ::= word
| wordlist "," word
word ::= digit
| cstring
| variable
| function

digit ::= [0-9]+
cstring ::= "..."
variable ::= "%{" varname "}"
function ::= funcname "(" funcargs ")"

while for varname any variable from Table 1 can be used. Finally for funcname the following functions are available: file(filename)
This function takes one string argument and expands to the contents of the file. This is especially useful for matching these contents against a regular expression, etc.
Notice that expression is first parsed into an internal machine representation and then evaluated in a second step. Actually, in Global and Per-Server Class context expression is parsed at start-up time and at runtime only the machine representation is executed. For Per-Directory context this is different: here expression has to be parsed and immediately executed for every request.

Example:
SSLRequire ( %{SSL_CIPHER} !~ m/^(EXP|NULL)-/ \
and %{SSL_CLIENT_S_DN_O} eq "Snake Oil, Ltd." \
and %{SSL_CLIENT_S_DN_OU} in {"Staff", "CA", "Dev"} \
and %{TIME_WDAY} >= 1 and %{TIME_WDAY} <= 5 \
and %{TIME_HOUR} >= 8 and %{TIME_HOUR} <= 20 ) \
or %{REMOTE_ADDR} =~ m/^192\.76\.162\.[0-9]+$/

Digi-Access™ (part IV)

Client Certificate Authentication (part IV)

For more information about the above directive, visit the Apache home website (http://www.apache.org [7]) or contact Digi-Sign Support at support@digi-sign.com [8]

- Some Apache versions, depending if you are implementing a CGI application with
Digi-Access™ may require the following directive to be present:

SetEnvIf User-Agent ".*MSIE.*" \
nokeepalive ssl-unclean-shutdown \
downgrade-1.0 force-response-1.0

This directive defines environment variables based on attributes of the request. These attributes can be the values of various HTTP request header fields (see RFC2616 (http://www.rfc-editor.org/rfc/rfc2616.txt [9]) for more information about these), or of other aspects of the request, including the following:

Remote_Host - the hostname (if available) of the client making the request
Remote_Addr - the IP address of the client making the request
Request_Method - the name of the method being used (GET, POST, et cetera)
Request_Protocol - the name and version of the protocol with which the request was made (e.g., "HTTP/0.9", "HTTP/1.1", etc.)
Request_URI - the portion of the URL following the scheme and host portion
Some of the more commonly used request header field names include Host, User- Agent, and Referer.

If the attribute name doesn't match any of the special keywords, nor any of the request's header field names, it is tested as the name of an environment variable in the list of those associated with the request. This allows SetEnvIf directives to test against the result of prior matches.

Only those environment variables defined by earlier SetEnvIf[NoCase] directives are available for testing in this manner. 'Earlier' means that they were defined at a broader scope (such as server-wide) or previously in the current directive's scope.

Important: Save your httpd.conf file and restart Apache.