Setting Up Wildcard Subdomains with SSL on a Debian Application

This guide provides a step-by-step approach to setting up wildcard subdomains with SSL on a Debian-based application. Wildcard subdomains allow applications to dynamically support multiple subdomains (abc.example.com, xyz.example.com) under a single SSL certificate.

In this guide, the focus is on configuring a Debian package to handle wildcard subdomains primarily through updates to the debian/postinst file. The guide uses the kaboom-api app as an example, with staging-elearning.nl as the domain name on which we’re setting up wildcard subdomains.

If you do not need or prefer not to modify the application code itself, you can still follow the key steps and commands described in this guide directly from the terminal. This will allow you to set up SSL for wildcard subdomains without diving into the application’s Debian packaging configuration.

By the end of this guide, you will have a fully automated process for configuring and renewing SSL certificates for wildcard subdomains, leveraging tools like Certbot and DNS authentication.

Prerequisites

1. DNS Configuration for Wildcard Subdomains

Access your DNS repository and add the necessary A and AAAA records for the wildcard subdomain you plan to use. This typically involves adding entries like *.example.com pointing to your server’s IP address.

The following is an example of what has been done for the domain name staging-elearning.nl

staging-elearning.nl.zone

$ORIGIN staging-elearning.nl.
$TTL 3600
@	IN	3600	SOA	delftsolutions.ns1.signaldomain.nl.	info.signaldomain.nl. (
		<serial>	; don't modify, auto incremented
		86400		; secondary refresh
		7200		; secondary retry
		3600000		; secondary expiry
		600			; negative response ttl
	)

@	3600	IN	NS	ns2.signaldomain.net.
@	3600	IN	NS	delftsolutions.ns1.signaldomain.nl.

*   IN  3600 A     193.5.147.172
*   IN  3600 AAAA  2a0c:8187:0:201::196

2. Required Packages

• python3-certbot-dns-rfc2136
• openssl
• nginx
• dnsutils
• certbot

Configuring SSL and Wildcard Subdomains

1. Handling Environment Variables

We’ll first add three environment variables to capture essential information: DNS_AUTHENTICATION, CERTBOT_EMAIL, and ELEARNING_FQDN. These variables will be defined using Debconf, which allows us to prompt for values during installation and configuration.

DNS_AUTHENTICATION: This string is required for Certbot’s DNS-based challenge verification. The format includes a keyname, algorithm, and secret for authentication, followed by the authoritative DNS hostname. This string is currently obtained using the signal domain api package running the command : signaldomain-api key certbot create <domain_name>

The expected format is: dns://<key_name>:<key_algorithm>~<key_secret_base64>@<authoritive_nameserver_domainname>

example: dns://staging-elearning_nl__certbot._keys.delftsolutions.signaldomain._internal.usersignal.nl.:hmac-sha256~<key_secret>@ns1.signaldomain.nl/staging-elearning_nl__certbot._keys.delftsolutions.signaldomain._internal.usersignal.nl.

CERTBOT_EMAIL: This email address is used when registering an account with Let’s Encrypt. Important notifications about certificate issues will be sent to this address.

ELEARNING_FQDN: This is the fully qualified domain name (FQDN) of the primary domain for which wildcard SSL certificates will be issued. staging-elearning.nl for this guide example.

Here’s how to set these variables in debian/templates, define prompts in debian/config, and retrieve them in debian/postinst.

in debian/templates, add the following entries to create prompt templates for each variable:

…
Template: kaboom-api/DNS_AUTHENTICATION
Type: string
Default:
Description: DNS authentication string in the following format: dns://<key_name>:<key_algorithm>~<key_secret_base64>@<authoritative_nameserver_domainname>

Template: kaboom-api/CERTBOT_EMAIL
Type: string
Default:
Description: Enter the email that certificate issues should be reported to. Entering this will result in accepting the Let's Encrypt terms and conditions.

Template: kaboom-api/ELEARNING_FQDN
Type: string
Default:
Description: Enter the fully qualified domain name used for e-learnings
…

Add the following lines to your debian/config file to prompt for these variables during configuration: in debian/templates, add the following entries to create prompt templates for each variable:

…
db_input medium kaboom-api/CERTBOT_EMAIL || true
db_input medium kaboom-api/DNS_AUTHENTICATION || true
db_input medium kaboom-api/ELEARNING_FQDN || true
…

In debian/postinst, retrieve the stored values with the following lines:

…
db_get kaboom-api/DNS_AUTHENTICATION
DNS_AUTHENTICATION="$RET"

db_get kaboom-api/CERTBOT_EMAIL
CERTBOT_EMAIL="$RET"

db_get kaboom-api/ELEARNING_FQDN
ELEARNING_FQDN="$RET"
…

These values shall be set or updated once the whole config is over, by running the following command: sudo dpkg-reconfigure <pkg-name>

2. Automating SSL and Wildcard Domain Setup in postinst

Here we will break down concern by concern how to configure the debian/postinst file.

a. Creating the dns-auth.conf File

The dns-auth.conf file will be generated from the DNS_AUTHENTICATION variable, which contains the details for Certbot’s DNS challenge configuration. Add the following to the debian/postinst file to create this file:

dns_hostname_path="$(cut -d'@' -f2- <<<"$DNS_AUTHENTICATION")"
dns_schema_auth="$(cut -d'@' -f1 <<<"$DNS_AUTHENTICATION")"

dns_hostname="$(cut -d'/' -f1 <<<"$dns_hostname_path")"
dns_auth="$(cut -d'/' -f3- <<<"$dns_schema_auth")"
dns_auth_keyname="$(cut -d':' -f1 <<<"$dns_auth")"
dns_auth_algorithm="$(cut -d':' -f2- <<<"$dns_auth" | cut -d'~' -f1 | tr '[:lower:]' '[:upper:]')"
dns_auth_secret="$(cut -d':' -f2- <<<"$dns_auth" | cut -d'~' -f2-)"

dns_host_aaaa="$(dig +short AAAA "$dns_hostname" | head -n1)"

[ -d <path-to-dns-conf-file> ] || mkdir -p <path-to-dns-conf-file>

umask 266
cat > <path-to-dns-conf-file>/dns-auth.conf <<CONF
# Managed by apt, please use dpkg-reconfigure <pkg-name> to modify
dns_rfc2136_server = $dns_host_aaaa
dns_rfc2136_port = 53
dns_rfc2136_name = $dns_auth_keyname
dns_rfc2136_secret = $dns_auth_secret
dns_rfc2136_algorithm = $dns_auth_algorithm
CONF
umask 022

This configuration file will be used by Certbot to authenticate and verify domain ownership via DNS challenges. In the case of our guide with the kaboom-api example, <path-to-dns-conf-file> is /etc/kaboom, it's up to you to select the right naming for your case.

Once the script has been executed The dns-auth.conf file should look something like this:

dns_rfc2136_server = 2a0c:8187::120
dns_rfc2136_port = 53
dns_rfc2136_name = staging-elearning_nl__certbot._keys.delftsolutions.signaldomain._internal.usersignal.nl.
dns_rfc2136_secret = <secret-key>
dns_rfc2136_algorithm = HMAC-SHA256 

Make sure that proper letter case is observed as this would cause the script to fail with unclear error messages.

b. Setting Up Certbot and Requesting Certificates

To handle SSL certificates, Certbot needs to register an account (if not already registered) and request a certificate for the primary domain and wildcard subdomain. Add the following to postinst to check and register Certbot, then request the certificate:

certbot_account_count="$(find /etc/letsencrypt/accounts/acme-v02.api.letsencrypt.org/directory/ -maxdepth 1 -mindepth 1 | wc -l)"
if [ "z$certbot_account_count" = "z0" ]; then
    certbot register --non-interactive --email "$CERTBOT_EMAIL" --no-eff-email --agree-tos
fi

[ ! -f "/etc/letsencrypt/live/<cert-name>/fullchain.pem" ] || certbot certonly --non-interactive --cert-name <cert-name> --dns-rfc2136 --dns-rfc2136-credentials <path-to-dns-conf-file>/dns-auth.conf --domain "$ELEARNING_FQDN" --domain "*.$ELEARNING_FQDN" --deploy-hook /usr/share/<pkg-name>/bin/cert-deploy

This block registers Certbot, checks for an existing certificate, and if none exists, requests a new certificate using DNS authentication with the specified dns-auth.conf file. The --deploy-hook option calls the cert-deploy file after each certificate issuance or renewal. We will create the cert-deploy in a further step.

In the case of our guide with the kaboom-api example, <cert-name> is kaboom-elearning, again it's up to you to select the right naming for your case.