Let’s Encrypt – How to Use Let’s Encrypt as a Free SSL Certificate Provider

apache-2.4debianlets-encryptssl

I have a few sites running with a StartSSL free certificate (CJSHayward.com, JobhuntTracker.com), and Firefox rejects StartSSL and displays an error page saying that my server is not properly configured (IIRC) because of the certificate chain. I asked for help and confirmed that my VirtualHost (available on request) was for the certificate chain and I had the intermediate certificate installed correctly. The sites are displayed without errors that I am aware of in Chrome, Safari, Edge, or Opera.

After some searching, Let's Encrypt! looked like an attractive offering, and before too long I had (AFAICT) a private key and a certificate for each domain under /etc/apache2/sites-enabled, minus of course any domains that are no longer mine. I thought I'd do a trial run and make an HTTPS connection to a site now available only under HTTP: JSH.name. I moved the "Let's Encrypt!" certificate and private key to my SSL directory and added:

<VirtualHost *:443>
        ServerAdmin cjshayward@pobox.com
        DocumentRoot /home/jonathan/stornge
        SSLEngine On
        SSLCertificateFile /etc/apache2/ssl/0000_csr-letsencrypt.pem
        SSLCertificateKeyFile /etc/apache2/ssl/0000_key-letsencrypt.pem
        ServerName jsh.name
        ServerAlias www.jsh.name
        LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" combined
        CustomLog /home/jonathan/logs/stornge.com combined
        <Directory /home/jonathan/stornge/>
            Options ExecCGI Indexes FollowSymLinks MultiViews
            AllowOverride None
            Order allow,deny
            allow from all
        </Directory>
</VirtualHost>

Then I rebooted to see my work, and every HTTP or HTTPS request I made simply hung. This included two domains on HTTPS with my StartSSL certificate, and the domain that should have been newly available on HTTPS accessed via both HTTP and HTTPS. I commented out the VirtualHost and bounced Apache, and all of the old functionality was back again in working order.

Have I used Let's "Encrypt!" correctly? I'm slightly suspicious as existing SSL configuration has private keys with an extension of .key, a certificate extension of .crt, and a certificate chain file with extension .pem.

I tried again after checking the SSL directory and finding that 0000_csr.letsencrypt.pem was mode 644; I changed all files in that directory to mode 600. When I tried a moment ago, I got a repeat of the old behavior: the website hangs on all requests and, in addition, an apachectl restart gets a statement (I forget the exact wording) that httpd is not running and the computer is trying to start it.

How can I get working free certitificates for "Let's Encrypt" or some other tool that hasn't alienated Firefox?

An apachectl -v gives:

Server version: Apache/2.4.10 (Debian)
Server built:   Nov 28 2015 14:05:48

A uname -a gives:

Linux www 4.4.0-x86_64-linode63 #2 SMP Tue Jan 19 12:43:53 EST 2016 x86_64 GNU/Linux

–UPDATE–

Contents deleted, 0000_key-letsencrypt.pem is bounded by:

-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----

A find on the directory heirarchy yields:

root@www:/etc/letsencrypt# find `pwd` -print
/etc/letsencrypt
/etc/letsencrypt/keys
/etc/letsencrypt/keys/0000_key-letsencrypt.pem
/etc/letsencrypt/accounts
/etc/letsencrypt/accounts/acme-v01.api.letsencrypt.org
/etc/letsencrypt/accounts/acme-v01.api.letsencrypt.org/directory
/etc/letsencrypt/accounts/acme-v01.api.letsencrypt.org/directory/1ef8dc9b994b9b68a4e9c7cedd003be3
/etc/letsencrypt/accounts/acme-v01.api.letsencrypt.org/directory/1ef8dc9b994b9b68a4e9c7cedd003be3/private_key.json
/etc/letsencrypt/accounts/acme-v01.api.letsencrypt.org/directory/1ef8dc9b994b9b68a4e9c7cedd003be3/meta.json
/etc/letsencrypt/accounts/acme-v01.api.letsencrypt.org/directory/1ef8dc9b994b9b68a4e9c7cedd003be3/regr.json
/etc/letsencrypt/renewal
/etc/letsencrypt/options-ssl-apache.conf
/etc/letsencrypt/csr
/etc/letsencrypt/csr/0000_csr-letsencrypt.pem

The directory /home/jonathan/stornge and its contents are world readable and world executable where that would make a difference.

–UPDATE–

Adding something substantive here:

The http://OrthodoxChurchFathers.com Apache conf file has two VirtualHosts, one to serve up http://OrthodoxChurchFathers.com and one to redirect http://www.OrthodoxChurchFathers.com requests to http://OrthodoxChurchFathers.com. The .conf file housing both VirtualHosts is:

<VirtualHost *:80> ServerAdmin webmaster@localhost ServerName orthodoxchurchfathers.com #ServerAlias www.orthodoxchurchfathers.com fathers.jonathanscorner.com DocumentRoot /home/cjsh/fathers/document_root <Directory /> Options FollowSymLinks AllowOverride None </Directory> <Directory /home/cjsh/fathers> Options ExecCGI FollowSymLinks Indexes MultiViews AllowOverride None Order allow,deny allow from all </Directory> DirectoryIndex index.cgi index.html ErrorLog ${APACHE_LOG_DIR}/error.log # Possible values include: debug, info, notice, warn, error, crit, # alert, emerg. LogLevel warn CustomLog ${APACHE_LOG_DIR}/access.log combined Alias /doc/ "/usr/share/doc/" <Directory "/usr/share/doc/"> Options Indexes MultiViews FollowSymLinks AllowOverride None Order deny,allow Deny from all Allow from 127.0.0.0/255.0.0.0 ::1/128 </Directory> </VirtualHost> <VirtualHost *:80> ServerAdmin CJSHayward@POBox.com ServerName www.orthodoxchurchfathers.com ServerAlias fathers.jonathanscorner.com DocumentRoot /home/cjsh/oldmirror RewriteEngine On RewriteRule ^(.*)$ http://orthodoxchurchfathers.com$1 [R=301,L] </VirtualHost></pre></code> When I try to run it and request orthodoxchurchfathers.com alone, I get: ┌───────── │ We were unable to │ orthodoxchurchfathers.com. │ Which virtual host │ (note: conf files │ ┌──────── │ │1 008-stornge.conf │ │2 014-paraskeva.conf │ │3 036-unixytalk.conf │ │4 038-proxy.conf │ │5 027-anna.conf │ │6 044-jobhunt-tracker.creation.c │ │7 049-jsh.conf │ │8 001-steampunk.conf │ │9 006-blajeny.conf │ │10 032-videos.conf │ └────↓(+)── ├───────── │ └───────── ─────────────────────────────────────────────────────────────┐ find a vhost with a ServerName or Address of │ │ would you like to choose? │ with multiple vhosts are not yet supported) │ ──────────────────────────────────────────────────────────┐ │ | Multiple Names | │ │ | paraskeva.jonathansco | │ │ | unixtalk.jsh.name | │ │ | Multiple Names | │ │ | Multiple Names | │ │ | Multiple Names | │ │ | Multiple Names | │ │ | | │ │ | Multiple Names | │ │ | Multiple Names | d│ │ ────────────────────────────────────────────────30%─────┘ │ ─────────────────────────────────────────────────────────────┤ │ ─────────────────────────────────────────────────────────────┘

The command I used was with ./letsencrypt-auto --debug certonly.

Best Answer

I have written a pair of how-tos for running Let's Encrypt SSL certs on CentOS: initial setup & cronning it.

And my per-domain (I use the file naming convention of z-<[sub-]domain-tld>.conf) Apache config files look like this:

<VirtualHost *:80>
ServerName domain.tld
Redirect permanent / https://domain.tld/
</VirtualHost>

<VirtualHost *:443>
    SSLCertificateFile /etc/letsencrypt/live/domain.tld/cert.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/domain.tld/privkey.pem
    SSLCertificateChainFile /etc/letsencrypt/live/domain.tld/fullchain.pem
    DocumentRoot /var/www/domain
    ServerName domain.tld
    ErrorLog logs/domain-error_log
    CustomLog logs/domain-access_log \
          "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
    ServerAdmin user@domain.tld

    SSLEngine on

<Files ~ "\.(cgi|shtml|phtml|php3?)$">
    SSLOptions +StdEnvVars
</Files>
<Directory "/var/www/cgi-bin">
    SSLOptions +StdEnvVars
</Directory>

SetEnvIf User-Agent ".*MSIE.*" \
         nokeepalive ssl-unclean-shutdown \
         downgrade-1.0 force-response-1.0

    <Directory "/var/www/domain">
         Options All +Indexes +FollowSymLinks
         AllowOverride All
         Order allow,deny
         Allow from all
    </Directory>

</VirtualHost>

And my ssl.conf looks like this:

#SSL options for all sites
Listen 443
SSLPassPhraseDialog  builtin
SSLSessionCache         shmcb:/var/cache/mod_ssl/scache(512000)
SSLSessionCacheTimeout  300
Mutex sysvsem default
SSLRandomSeed startup file:/dev/urandom  1024
SSLRandomSeed connect builtin
SSLCryptoDevice builtin
SSLCompression          off
SSLHonorCipherOrder     on
SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
SSLCipherSuite ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256

Using Let's Encrypt to get SSL certs (and get your site up to an "A" rating from SSL Labs) is pretty straight-forward - once you get past some of the arcana of the Apache configs and LE command-line arguments.

Manual plugin

You can either perform a manual verification - with the manual plugin.

certbot -d bristol3.pki.enigmabridge.com --manual --preferred-challenges dns certonly

Certbot will then provide you instructions to manually update a TXT record for the domain in order to proceed with the validation.

Please deploy a DNS TXT record under the name
_acme-challenge.bristol3.pki.enigmabridge.com with the following value:

667drNmQL3vX6bu8YZlgy0wKNBlCny8yrjF1lSaUndc

Once this is deployed,
Press ENTER to continue

Once you have updated the DNS record, press Enter, certbot will continue and if the LetsEncrypt CA verifies the challenge, the certificate is issued as normally.

You may also use a command with more options to minimize interactivity and answering certbot questions. Note that the manual plugin does not yet support non-interactive mode.

certbot --text --agree-tos --email you@example.com -d bristol3.pki.enigmabridge.com --manual --preferred-challenges dns --expand --renew-by-default  --manual-public-ip-logging-ok certonly

Renewal does not work with the manual plugin as it runs in non-interactive mode. More info in the official certbot documentation.

Update: manual hooks

In the new certbot version you can use hooks, e.g., --manual-auth-hook, --manual-cleanup-hook. The hooks are external scripts executed by certbot to perform the task.

Information is passed in environment variables - e.g., domain to validate, challenge token. Vars: CERTBOT_DOMAIN, CERTBOT_VALIDATION, CERTBOT_TOKEN.

certbot certonly --manual --preferred-challenges=dns --manual-auth-hook /path/to/dns/authenticator.sh --manual-cleanup-hook /path/to/dns/cleanup.sh -d secure.example.com

You can write your own handler or use already existing ones. There are many available, e.g., for Cloudflare DNS.

More info on official certbot hooks documentation.

Automation, Renewal, Scripting

~~If you would like to automate DNS challenge validation it is not currently possible with vanilla certbot.~~ Update: some automation is possible with the certbot hooks.

We thus created a simple plugin that supports scripting with DNS automation. It's available as certbot-external-auth.

pip install certbot-external-auth

It supports the DNS, HTTP, TLS-SNI validation methods. You can either use it in handler mode or in JSON output mode.

Handler mode

In handler mode, the certbot + plugin calls external hooks (a program, shell script, Python, ...) to perform the validation and installation. In practice you write a simple handler/shell script which gets the input arguments - domain, token and makes the change in DNS. When the handler finishes, certbot proceeds with validation as usual.

This gives you extra flexibility, renewal is also possible.

Handler mode is also compatible with Dehydrated DNS hooks (former letsencrypt.sh). There are already many DNS hooks for common providers (e.g., CloudFlare, GoDaddy, AWS). In the repository there is a README with extensive examples and example handlers.

Example with Dehydrated DNS hook:

certbot \
    --text --agree-tos --email you@example.com \
    --expand --renew-by-default \
    --configurator certbot-external-auth:out \
    --certbot-external-auth:out-public-ip-logging-ok \
    -d "bristol3.pki.enigmabridge.com" \
    --preferred-challenges dns \
    --certbot-external-auth:out-handler ./dehydrated-example.sh \
    --certbot-external-auth:out-dehydrated-dns \
    run

JSON mode

Another plugin mode is JSON mode. It produces one JSON object per line. This enables a more complicated integration - e.g., when Ansible or some deployment manager is calling certbot. Communication is performed via STDOUT and STDIN. Cerbot produces JSON objects with data to perform the validation, for example:

certbot \
    --text --agree-tos --email you@example.com \
    --expand --renew-by-default \
    --configurator certbot-external-auth:out \
    --certbot-external-auth:out-public-ip-logging-ok \
    -d "bristol3.pki.enigmabridge.com" \
    --preferred-challenges dns \
    certonly 2>/dev/null

{"cmd": "perform_challenge", "type": "dns-01", "domain": "bs3.pki.enigmabridge.com", "token": "3gJ87yANDpmuuKVL2ktfQ0_qURQ3mN0IfqgbTU_AGS4", "validation": "ejEDZXYEeYHUxqBAiX4csh8GKkeVX7utK6BBOBshZ1Y", "txt_domain": "_acme-challenge.bs3.pki.enigmabridge.com", "key_auth": "3gJ87yANDpmuuKVL2ktfQ0_qURQ3mN0IfqgbTU_AGS4.tRQM98JsABZRm5-NiotcgD212RAUPPbyeDP30Ob_7-0"}

Once DNS is updated, the caller sends the new-line character to STDIN of certbot to signal it can continue with validation.

This enables automation and certificate management from the central management server. For installation you can deploy certificates over SSH.

For more info please refer to the readme and examples on certbot-external-auth GitHub.

EDIT: There is also a new blog post describing the DNS validation problem and the plugin usage.

EDIT: We currently work on Ansible 2-step validation, will be soon off.

Best Answer

Related Solutions

Ssl – setting up multiple ssl certificates on same server/ip on CENTOs with apache 2.2

Let’s Encrypt – How to Use DNS-01 Challenge Validation

Manual plugin

Update: manual hooks

Automation, Renewal, Scripting

Handler mode

JSON mode

Related Topic