Letsencrypt with Dehydrated using DNS-01 on CentOS v7
Notes on using Dehydrated to ussue x.509 public key certificates for non-web services (e.g. SMTP, IMAP, XMPP) using DNS-01
This describes using Dehydrated from EPEL to setup issuing of certificates from LetsEncrypt in a minimal simple way. The procedure needs to be simple and minimally invasive on machines so that each machine can independenly maintain it's own certificates.
This script and setup is in support of DNS-01 validation. The script supports a CNAME (alias) for DNS entries so that the DNS hosting domain for certificate validation doesn't have to be the same as certificate domain. By being able to put statically configured CNAME record in a high value domain (e.g. production domains), a less crticial and independent domain can be used for certificate issuing.
Procedure
- Install EPEL repository and packages
- Install dehydrated and jq (for processing JSON data in the hook script)
- Install the custom hook script
- Configure dehydrated domains (domains.txt)
- Register with lets encrypt
- Issue certificates
Install
Install the EPEL repository and install the required packages:
# yum install epel-release # yum install dehydrated jq bind-utils
Configure
Create a local config file
# cat >> /etc/dehydrated/conf.d/local.sh <<EOF CHALLENGETYPE="dns-01" HOOK="/usr/local/bin/dehydrated-dns01-luadns-hook" LOCKFILE="/var/lock/dehydrated/lock" CONTACT_EMAIL="user@example.com" EOF
Create a hook config:
# cat >> /etc/dehydrated/hook.conf <<EOF LUADNS_USERNAME=username@example.com LUADNS_TOKEN=<auth key for user> EOF
Copy the hook script:
# wget -P /usr/local/bin https://plone.lucidsolutions.co.nz/web/pki/letsencrypt/images/dehydrated-dns01-luadns-hook # chmod +x /usr/local/bin/dehydrated-dns01-luadns-hook
Create directories that the package didn't create:
# mkdir -p /var/lock/dehydrated /var/www/dehydrated
Register
Register an account with LetsEncrypt. This is a one off process.
# dehydrated --register --accept-terms
Add the certificate names to '/etc/dehydrated/domains.txt'.
Run dehydrated in cron mode.
# dehydrated -c
Residuals
Installation
Each certificate will need to be installed in a way that is specific to the application using the certificate.
CentOS v6
The dehydrated hook script requires jq version 1.5 or later. The EPEL 6 repository does not have jq v1.5. The EPEL 7 source RPM is recompiled for CentOS 6 - to install:
# yum install http://files.lucidsolutions.co.nz/linux/centos/jq/jq-1.5-1.el6.x86_64.rpm
Links
- Dehydrated
- https://github.com/lukas2511/dehydrated
- https://github.com/lukas2511/dehydrated/blob/master/docs/dns-verification.md
- https://github.com/lukas2511/dehydrated/wiki/Examples-for-DNS-01-hooks
- http://www.luadns.com/api.html
- https://stedolan.github.io/jq/manual/
- https://github.com/diafygi/acme-tiny
Appendices
Usage
Usage: ./dehydrated [-h] [command [argument]] [parameter [argument]] [parameter [argument]] ... Default command: help Commands: --version (-v) Print version information --register Register account key --account Update account contact information --cron (-c) Sign/renew non-existent/changed/expiring certificates. --signcsr (-s) path/to/csr.pem Sign a given CSR, output CRT on stdout (advanced usage) --revoke (-r) path/to/cert.pem Revoke specified certificate --cleanup (-gc) Move unused certificate files to archive directory --help (-h) Show help text --env (-e) Output configuration variables for use in other scripts Parameters: --accept-terms Accept CAs terms of service --full-chain (-fc) Print full chain when using --signcsr --ipv4 (-4) Resolve names to IPv4 addresses only --ipv6 (-6) Resolve names to IPv6 addresses only --domain (-d) domain.tld Use specified domain name(s) instead of domains.txt entry (one certificate!) --keep-going (-g) Keep going after encountering an error while creating/renewing multiple certificates in cron mode --force (-x) Force renew of certificate even if it is longer valid than value in RENEW_DAYS --no-lock (-n) Don't use lockfile (potentially dangerous!) --lock-suffix example.com Suffix lockfile name with a string (useful for with -d) --ocsp Sets option in CSR indicating OCSP stapling to be mandatory --privkey (-p) path/to/key.pem Use specified private key instead of account key (useful for revocation) --config (-f) path/to/config Use specified config file --hook (-k) path/to/hook.sh Use specified script for hooks --out (-o) certs/directory Output certificates into the specified directory --challenge (-t) http-01|dns-01 Which challenge should be used? Currently http-01 and dns-01 are supported --algo (-a) rsa|prime256v1|secp384r1 Which public key algorithm should be used? Supported: rsa, prime256v1 and secp384r1
Installed files
The following files are installed from the RPM (excluding docs and license):
/etc/cron.d/dehydrated /etc/dehydrated /etc/dehydrated/accounts /etc/dehydrated/archive /etc/dehydrated/certs /etc/dehydrated/conf.d /etc/dehydrated/conf.d/local.sh /etc/dehydrated/config /etc/dehydrated/domains.txt /etc/dehydrated/hook.sh /run/dehydrated /usr/bin/dehydrated /usr/lib/tmpfiles.d/dehydrated.conf
Install Hydrated
# yum install dehydrated Loaded plugins: fastestmirror Resolving Dependencies --> Running transaction check ---> Package dehydrated.noarch 0:0.4.0-5.el7 will be installed --> Finished Dependency Resolution Dependencies Resolved ================================================================================================================== Package Arch Version Repository Size ================================================================================================================== Installing: dehydrated noarch 0.4.0-5.el7 epel 74 k Transaction Summary ================================================================================================================== Install 1 Package Total download size: 74 k Installed size: 121 k Is this ok [y/d/N]: y Downloading packages: dehydrated-0.4.0-5.el7.noarch.rpm | 74 kB 00:00:00 Running transaction check Running transaction test Transaction test succeeded Running transaction Installing : dehydrated-0.4.0-5.el7.noarch 1/1 Verifying : dehydrated-0.4.0-5.el7.noarch 1/1 Installed: dehydrated.noarch 0:0.4.0-5.el7 Complete!
