Awesome

uacme-gandi-hook

DNS-01 challenge hook script of uacme for gandi.net LiveDNS API

The gandi_nsupdate.sh hook script included in the distribution allows DNS gandi.net users to manage RFC8555 ACMEv2 protocol DNS-01 challenges using gandi.net LiveDNS API and uacme project ACMEv2 lightweight client .

Explanations

The ACMEv2 protocol allows a Certificate Authority (Let's Encrypt is a popular one) and an applicant to automate the process of verification and certificate issuance.

The DNS-01 challenge is a challenge type which is used to prove that you control the DNS for your domain name by putting a specific value in a TXT record under that domain name. This challenge must be used to allow Let's Encrypt to issue wildcard certificates as specified on Let's Encrypt Challenge Types documentation page.

The uacme github project is a lightweight client for the RFC8555 ACMEv2 protocol, written in plain C with minimal dependencies; for instance, an uacme package is available for OpenWrt Linux operating system targeting embedded devices.

Installation

Refer to uacme manual and README.md for hook script usage with uacme.

gandi_nsupdate.sh and gandi_api_functions.inc files have to be placed in the same folder as other uacme scripts as uacme.ash or nsupdate.sh, for instance /usr/share/uacme folder or /usr/local/share/uacme folder depending of the Linux distribution; README.md file may be copy in the same folder, renaming it to gandi_api_readme for instance.

gandi_api_key is expected to be copy in folder defined by GANDI_API_KEY_FILE variable of gandi_nsupdate.sh script (default /root folder); if this variable is not defined, gandi_api_key is expected to be copy in the same folder gandi_nsupdate.sh.

gandi_api_key - API key file

This file must contain gandi.net API key of your user account.

Refer to Gandi documentation to obtain your API key from your gandi.net account parameters, then replace "replace-me-by-your-gandi-livedns-api-key" first line with this Gandi API key.

For security reason, make gandi_api_key file permission rights to "rw------- root root" using following command :

chmod 600 gandi_api_key

gandi_nsupdate.sh - Hook script

This hook script must be must be made executable, using following command :

chmod +x gandi_nsupdate.sh

Note : gandi_api_functions.inc file contains specific gandi.net functions; it is sourced by the hook script gandi_nsupdate.sh and some gandi specific variables may have to be changed if necessary, such as __GANDI_DNS_SERVERS which defines gandi DNS or __ENDPOINT which defines gandi API base url.

gandi_nsupdate.sh hook script is designed to be used as nsupdate.sh script described in uacme manual and README.md.

Example of uacme command line used for test purpose (--staging option, using Let's Encrypt staging URL instead of production URL) to automate Let'Encrypt certficate updates using DNS-01 challenge for site1.example.com DNS Common Name with DNS Alternative Names site2.example.com and site3.example.com.

uacme --staging -v -c /etc/config/uacme.d \
      -h /usr/share/uacme/gandi_nsupdate.sh \
      issue site1.example.com site2.example.com site3.example.com

Example of uacme command line used for production purpose to automate Let'Encrypt certficate updates using DNS-01 challenge for DNS Common Name www.your.domain.com

uacme -v -c /etc/config/uacme.d \
      -h /usr/share/uacme/gandi_nsupdate.sh \
      issue www.your.domain.com