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:
-
Configure Apache and store certificate files
-
Reload Apache configuration
-
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):
-
store front: https://DOMAIN/
-
back office: https://DOMAIN/epages/Shop.admin