Overview

Domains

All ePages installations have one web server (say domain www.example.com with IP 192.0.2.2) that handles all incoming web requests.

Besides the domain of that web server there are domains for each shop like shop.example that must point to the same IP (here 192.0.2.2).

Certificates

Each domain (for shops and web server) needs its own SSL certificate if SSL/https shall be used.

SSL Web Servers

SSL web servers require following files installed in /etc/apache2-epages/ on the web server host:

extra/httpd-vhosts_default.conf

Apache configuration file for web server domain

ssl.crt/server.crt

SSLCertificateFile

ssl.key/server.key

SSLCertificateKeyFile

ssl.crt/ca.crt

SSLCACertificateFile

SSL Shops

SSL shops require following files installed in /etc/apache2-epages/ on the web server host:

extra/httpd-vhosts_additional.d/DOMAIN.conf

Apache configuration file for shop domain (for each shop, DOMAIN varies)

certs/DOMAIN/server.crt

SSLCertificateFile

certs/DOMAIN/server.key

SSLCertificateKeyFile

certs/DOMAIN/ca.crt

SSLCACertificateFile

Apache configuration files httpd-vhosts_default.conf and httpd-vhosts_additional.d/DOMAIN.conf define name and place of the certificate files. If you want to install certificate files in different places, then change the Apache configuration files accordingly.

Load Balancer

Normally, an ePages installation doesn’t have just one web server exposed to the public but a load balancer web server that forwards web requests to various web servers behind the firewall.

Then, each web server behind the firewall must be configured as described above. The load balancer must enable SSL for the web server domain.

Enable SSL

An ePages installation enables SSL in three steps:

  1. Configure Apache and store certificate files

  2. Reload Apache configuration

  3. Enable SSL for shop domain

Prerequisites

Package openssl must be installed. Install it either on Debian by:

apt-get install openssl

or on Redhat by:

yum install openssl

Dummy Certificate for the Web Server Domain

An ePages standard installation as described in ePages Installation Guide installs a dummy certificate for the web server domain so that SSL works instantly.

However, it is a) a self-signed certificate that no browser will accept and b) only a certificate for the web server domain, not for shop domains.

Replace the Certificate for the Web Server Domain

Install New Certificate

A certificate consists of 3 files:

Certificate file for the web server domain

store this in /etc/apache2-epages/ssl.crt/server.crt

Certificate chain for the certification authority (CA)

store this in /etc/apache2-epages/ssl.crt/ca.crt

Certificate key file for the web server domain

store this in /etc/apache2-epages/ssl.key/server.key

Correct the access rights (as user root on each web server):

chmod 644 /etc/apache2-epages/ssl.crt/*.crt
chmod 600 /etc/apache2-epages/ssl.key/*.key
chown root:root /etc/apache2-epages/ssl.*/*.*

Note that the certificate key file mustn’t be password secured. Remove the password by executing (you are asked for the password):

cd /etc/apache2-epages/ssl.key
openssl rsa -in server.key -out server.key

Test New Certificate

Check the certificate key file and check if .key belongs to .crt:

KEYFILE=/etc/apache2-epages/ssl.key/server.key
CRTFILE=/etc/apache2-epages/ssl.crt/server.crt
openssl rsa -in $KEYFILE -check
KEY=$(openssl rsa -in $KEYFILE -noout -modulus)
[[ -n $KEY ]] || echo "ERROR: $KEYFILE: getting modulus failed"
CRT=$(openssl x509 -in $CRTFILE -noout -modulus)
[[ -n $CRT ]] || echo "ERROR: $CRTFILE: getting modulus failed"
[[ $KEY = $CRT ]] || echo "ERROR: $KEYFILE does not belong to $CRTFILE"

Check that the certificate chain is complete:

CRTFILE=/etc/apache2-epages/ssl.crt/server.crt
CAFILE=/etc/apache2-epages/ssl.crt/ca.crt
CNT=0
while read i ; do
  [[ $i = ${i#*-BEGIN\ CERTIFICATE-} ]] || CNT=$((CNT + 1))
  echo $i >> /tmp/$$.$CNT.crt
done < $CAFILE
for i in /tmp/$$.*.crt ; do
  openssl x509 -noout -text < $i > /tmp/${i##*/}.txt
done
ISSUER=$(openssl x509 -noout -text < $CRTFILE | grep 'Issuer:' | sed -r 's,.*Issuer:\s*,,;s,\s+$,,')
SUBJECT=
while [[ $SUBJECT != $ISSUER ]] ; do
  grep -lPZ "Subject:\s*\Q$ISSUER\E\s*$" /tmp/$$.*.crt.txt > /tmp/$$.found
  [[ -s /tmp/$$.found ]] || { echo  "ERROR: issuer cert missing: $ISSUER"; break; }
  CERT_TXT=$(cat /tmp/$$.found | xargs -0 ls -t | head -1)
  [[ -n "$CERT_TXT" ]] || { echo  "ERROR: issuer cert missing: $ISSUER"; break; }
  SUBJECT=$ISSUER
  ISSUER=$(grep 'Issuer:' "$CERT_TXT" | sed -r 's,.*Issuer:\s*,,;s,\s+$,,')
done
rm -f /tmp/$$.*

Reload Apache Configuration

Run following commands as user root on each web server.

Check that the Apache configuration is correct:

source /etc/default/epages6
/usr/sbin/apache2ctl-epages -f httpd.conf -S $HTTPD_OPTS

If so, reload the Apache configuration:

/etc/init.d/epages6 start_httpd reload

Finally check log files for reload errors:

cat /var/log/apache2-epages/apache2-epages-startup.log
tail /var/log/apache2-epages/error_log

Add Certificate for a Shop Domain

Shops with own domain name are handled by VirtualHost entries of the Apache configuration, therefore add define -DVHOSTS_NAME to HTTPD_OPTS in /etc/default/epages6 like:

HTTPD_OPTS="-DSSL -DVHOSTS_NAME"

Install New Shop Certificate

Store the three certificate files into /etc/apache2-epages/certs.

In following commands, replace DOMAIN by the real shop domain name.

First create the directory

mkdir -m 755 -p /etc/apache2-epages/certs/DOMAIN

Store the certificate file for the shop in

/etc/apache2-epages/certs/DOMAIN/server.crt

Store the certificate chain for the certification authority (CA) in

/etc/apache2-epages/certs/DOMAIN/ca.crt

Store the certificate key file for the shop in

/etc/apache2-epages/certs/DOMAIN/server.key

Correct the access rights (as user root on each web server, replace DOMAIN):

DOM=DOMAIN
chmod 644 /etc/apache2-epages/certs/$DOM/*.crt
chmod 600 /etc/apache2-epages/certs/$DOM/*.key
chown root:root /etc/apache2-epages/certs/$DOM/*.*

Note that the certificate key file mustn’t be password secured. Remove the password by executing (you are asked for the password):

cd /etc/apache2-epages/certs/$DOM
openssl rsa -in server.key -out server.key

Test New Shop Certificate

Test new shop certificates the same way as described in section Test New Certificate.

Just replace following variables (don’t forget to replace DOMAIN):

DOM=DOMAIN
KEYFILE=/etc/apache2-epages/certs/$DOM/server.key
CRTFILE=/etc/apache2-epages/certs/$DOM/server.crt
CAFILE=/etc/apache2-epages/certs/$DOM/ca.crt

Create Apache Configuration for Shop

Create the Apache configuration DOMAIN.conf from template file host.conf.example in /etc/apache2-epages/extra/httpd-vhosts_additional.d (replace DOMAIN):

DOM=DOMAIN
CRTFILE=/etc/apache2-epages/certs/$DOM/server.crt
declare -A ALIAS
name=$(openssl x509 -noout -text < $CRTFILE | sed -rn '/Subject:/{s,.*\sCN=,,;s,(/|\s)+.*,,;p}')
ALIAS["$name"]=1
echo "Subject: $name"
[[ -n "$name" ]] || echo "ERROR: $CRTFILE: no Subject found"
while IFS=: read dns name ; do
  echo "Alias: $name"
  ALIAS["$name"]=1
done < <(openssl x509 -noout -text < $CRTFILE | egrep '^\s*DNS:' | tr ',' '\n')
unset ALIAS["$DOM"]
cd /etc/apache2-epages/extra/httpd-vhosts_additional.d
EX=host.example.com
sed "s,ssl\..../$EX,certs/$DOM/,;s,/\.,/server.,;s,/-ca,/ca,;s,$EX,$DOM,g" host.conf.example > $DOM.conf
[[ -z "${!ALIAS[@]}" ]] || sed -i "/ServerName/a\  ServerAlias $ALIAS" $DOM.conf

Reload Apache Configuration for Shop

Reload the Apache configuration the same way as described in section Reload Apache Configuration.

Set the DomainName for Shop

A SSL shop has a primary domain name and optionally secondary domain names. Get the primary domain name (replace Store and Shop by your store name and shop name):

source /etc/default/epages6
$PERL $EPAGES_CARTRIDGES/DE_EPAGES/Object/Scripts/get.pl -storename Store -path /Shops/Shop DomainName

If the DomainName= shown is empty or wrong then set the right domainname (replace Store, Shop and DOMAIN accordingly):

$PERL $EPAGES_CARTRIDGES/DE_EPAGES/Object/Scripts/set.pl -storename Store -path /Shops/Shop DomainName=DOMAIN

If the shop has more than one domain name (mentioned as ServerAlias in Apache DOMAIN.conf, see above) then add the other domainname(s) as secondary domain (replace Store, Shop and each DOMAIN accordingly):

$PERL $EPAGES_CARTRIDGES/DE_EPAGES/Object/Scripts/addSecondaryDomain.pl -storename Store -path /Shops/Shop -domain DOMAIN

Enable SSL for Shop

After setting the domain name, first enable SSL for the store (replace Store accordingly):

$PERL $EPAGES_CARTRIDGES/DE_EPAGES/Object/Scripts/set.pl -storename Store -path / HasSSLCertificate=1

then enable SSL for the shop (replace Store and Shop accordingly):

$PERL $EPAGES_CARTRIDGES/DE_EPAGES/Object/Scripts/set.pl -storename Store -path /Shops/Shop HasSSLCertificate=1

Test SSL Shop

After successfully executed all tasks as described above, following URL must work (replace DOMAIN and Shop accordingly):