# 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

# Requesting SSL Certificate

Letsencrypt will be used for creating a wildcard SSL certificate (introduction to using Letsencrypt). There are different clients available. Both Certbot and Dehydrated support wildcard SSL certificate issuance at the time of writing. The following steps will be performed using Certbot as described in this blog post.

# 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

- nexedi.com/contact