HowTo Request and Setup a Wildcard SSL Certificate
This document explains how to add a wildcard SSL certificate to a server to enable SSL communication. It will be shown how to use Letsencrypt to create the certificate.
Note that the setup process will require access to a DNS server.
Table of Content
- DNS Update
- Requesting Wildcard SSL Certificate
- Requesting SSL Certificate
DNS Update
Setting/Updating DNS depends on the respective hosting domain/provider and is therefore not covered in detail in this tutorial.
Creating an A Record
# Add an A record to provider DNS settings:
*.[your_wildcard_domain] IN A [your_ip]
In order to get a SSL certificate, a domain pointing to the server that required the certificate is needed.
For this example, the domain *.slaptext.erp5.net will be used. It points to a sample server at 167.114.246.26. DNS Updates have to be made with the domain/hosting provider. In the present case, we need to add the following A record to the DNS settings on the provider's web dashboard:
*.slaptest.erp5.net CNAME IN A 167.114.246.26
DNS changes usually take up to 48h to propagate. To verify availability, it is possible ping the domain using the terminal:
$ ping a.slaptest.erp5.net
PING a.slaptest.erp5.net (167.114.246.26) 56(84) bytes of data.
64 bytes from ip-167-114-246.eu (167.114.246.26): icmp_seq=1 ttl=52 time=21.1 ms
64 bytes from ip-167-114-246.eu (167.114.246.26): icmp_seq=2 ttl=52 time=17.1 ms
64 bytes from ip-167-114-246.eu (167.114.246.26): icmp_seq=3 ttl=52 time=17.2 ms
^C
--- a.slaptest.erp5.net ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2001ms
rtt min/avg/max/mdev = 17.103/18.528/21.186/1.881 ms
Install Certbot
$ sudo su
# wget https://dl.eff.org/certbot-auto
(...)
# chmod a+x ./certbot-auto
# sudo ./certbot-auto
Start by installing Certbot using wget. Certbot will likely report an error at the end that it was not able to find the executable apache2ctl in PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin and that it doesn't know how to automatically configure the web server on this system. As we will be using just the certonly command in the next step, it is ok to continue.
Run Certbot
# sudo ./certbot-auto certonly \
--server https://acme-v02.api.letsencrypt.org/directory \
--manual --preferred-challenges dns \
-d *.slaptest.erp5.net
After installation has finished, try running certbot as shown above.
Note, that this command uses the https://acme-v02.api.letsencrypt.org/directory
production API endpoint. If you want to experiment and not run into the Letsencrypt production quotas while testing certificate generation, you could also use one of the staging access points described here.
Also note, there are two types of challenges for verifying that you have access to a domain - http-01 which will require setting up a webserver and providing a challenge file for every domain and dns-01 which is used here and requires a file to be set directly on the DNS server. For more information on how letsencrypt and dehydrated use hooks for DNS challenges, you can have a look at letsencrypt domain verification.
Provide an email address (optional) and fill out the questions until you receive a challenge.
DNS TXT Challenge Record
-------------------------------------------------------------------------------
Please deploy a DNS TXT record under the name
_acme-challenge.slaptest.erp5.net with the following value:
5GFgEqWd7AQrvHteRtfT5V-XXXXXXXXXXXXXX
Before continuing, verify the record is deployed.
-------------------------------------------------------------------------------
Press Enter to Continue
During the certificate generation you will eventually be presented with the above message. Head over to your DNS server and add the record in the zone file used by your domain (erp5.net in our case):
_acme-challenge.slaptest 10800 IN TXT "5GFgEqWd7AQrvHteRtfT5V-XXXXXXXXXXXXXX"
Make sure to only continue after the file has been created and is accessible.
Verify DNS Challenge
# try to request a token using dnsutils in another terminal
# sudo apt-get install dnsutils
(...)
# nslookup -type=TXT _acme-challenge.slaptest.erp5.net
Server: xxx.xxx.xx.xx
Address: xxx.xxx.xx.xx#xx
Non-authoritative answer:
*** Can't find _acme-challenge.slaptest.erp5.net: No answer
DNS changes need up to 48h to propagate. You can check whether you can request the token by installing dnsutils and calling nslookup. Once you receive a Non-authoritative answer: with the saved token, you can continue the certificate issuance.
Certificate Issued
IMPORTANT NOTES:
- Congratulations! Your certificate and chain have been saved at:
/etc/letsencrypt/live/slaptest.erp5.net/fullchain.pem
Your key file has been saved at:
/etc/letsencrypt/live/slaptest.erp5.net/privkey.pem
Your cert will expire on 2018-06-18. To obtain a new or tweaked
version of this certificate in the future, simply run certbot-auto
again. To non-interactively renew *all* of your certificates, run
"certbot-auto renew"
- If you like Certbot, please consider supporting our work by:
Donating to ISRG / Let's Encrypt: https://letsencrypt.org/donate
Donating to EFF: https://eff.org/donate-le
Once the process has completed you will receive the above message informing you that your certificate is available.
The files required to continue can be found in the directory mentioned.
# ls /etc/letsencrypt/live/slaptest.erp5.net/
cert.pem chain.pem fullchain.pem privkey.pem README
Check the Certbot documentation for more information on the location of certificate files and SO for info on the different formats.
Requesting SSL Certificate
For some use cases a regular SSL certificate may be required. This is an easier case as there is no need to access the DNS settings when using Dehydrated which is outlined in this section.
Setup Letsencrpyt and Dehydrated
$ mkdir letsencrypt
$ cd letsencrypt
/letsencrypt $ git clone https://github.com/lukas2511/dehydrated.git
/letsencrypt $ git clone https://lab.nexedi.com/nexedi/dehydrated-zope-hook.git
Start by creating a folder for letsencrpyt and inside, clone both the dehydrated and dehydrated-zope-hook repositories.
Zope Hook
# ~/.netrc
machine www.example.com
login zope_username
password zope_password
machine example.com
login zope_username
password zope_password
machine another.example.com
login zope_username
password zope_password
Afterwards you can follow the steps outlined in the zope-hook readme. Be sure to prepare the target Zope folder before so that http://example.com/.well-known/acme-challenge/xxx
works. For example you can create the target folder portal_skins/custom/.well-known/acme-challenge
and then provide zope username and password in ~/.netrc
. For example:
~/.netrc
machine www.example.com
login zope_username
password zope_password
machine example.com
login zope_username
password zope_password
machine another.example.com
login zope_username
password zope_password
Prepare Dehydrated Config
# We can use any local directory for storing challenge string temporarily.
WELLKNOWN="${BASEDIR}"
# We use a special hook script for zope.
HOOK="${BASEDIR}/zope-hook.sh"
You also need "domains.txt" like :
www.example.com example.com
another.example.com
Next prepare the configuration file as described in the dehydrated config.
# See https://github.com/lukas2511/dehydrated/blob/master/docs/examples/config for other parameters.
#
# We can use any local directory for storing challenge string temporarily.
WELLKNOWN="${BASEDIR}"
# We use a special hook script for zope.
HOOK="${BASEDIR}/zope-hook.sh"
You also need "domains.txt" like :
www.example.com example.com
another.example.com
Then invoke the script
../dehydrated/dehydrated -c
(not like currently written in the readme)
Note, you may need to run
../dehydrated/dehydrated --register --accept-terms
if this is the first time running letencrypt
Thank You
- Nexedi SA
- 147 Rue du Ballon
- 59110 La Madeleine
- France