SlapOS Home SlapOS

    How To Request and Setup A Wildcard SSL Certificate

    FINAL - Document showing how to add a wildcard SSL certificate created by Letsencrypt.
    • Last Update:2020-05-25
    • Version:001
    • Language:en

    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

    Image Nexedi Office
    • Nexedi SA
    • 147 Rue du Ballon
    • 59110 La Madeleine
    • France