ACME DNS-01 Resolver

[Slyke]

Hello, trying to setup wildcard issuance with cert-manager and LetsEncrypt on a bare-metal Kubernetes cluster.

It seems that when trying to use wildcards, DNS-01 challenge is enforced. Luckily, cert-manager provides a generic webhook feature so that we can use our own API to add and remove records.

I also found a blog post on the Technitium blog which gives examples on how to use the API for adding and removing DNS-01 TXT challenge entries:

#!/bin/bash
API_TOKEN="your-api-token"

# Create challenge TXT record
curl "http://dns-server:5380/api/zones/records/add?token=$API_TOKEN&domain=_acme-challenge.$CERTBOT_DOMAIN&type=TXT&ttl=60&text=$CERTBOT_VALIDATION"

# Sleep to make sure the change has time to propagate from primary to secondary name servers
sleep 25

# Delete challenge TXT record
curl "http://dns-server:5380/api/zones/records/delete?token=$API_TOKEN&domain=_acme-challenge.$CERTBOT_DOMAIN&type=TXT&text=$CERTBOT_VALIDATION"

Kubernetes Issuer:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-prod
  namespace: cert-manager
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
    - http01:
        ingress:
          class: nginx
    - dns01:
        webhook:
          groupName: dns.webhook.cert-manager.io
          solverName: technitium
          config:
            url: http://technitium-dns-webhook.cert-manager

Cert-manager sends a JSON payload to the URL specified and that payload contains the data for adding/removing the TXT record. I couldn't find any details on what exactly is in this payload.

Before I go down a rabbit hole making some webhook middleman to do the translation between cert-manager and Technitium DNS, I was wondering if anyone had already done this before? There doesn't seem to be an App in the Technitium App Store for this.

[ShreyasZare]

Thanks for asking. I am not aware about cert manager but I guess they should be supporting Dynamic Updates (RFC 2136) which you can then use with the DNS server. The blog post explains how to use it with certbot. I would suggest that you explore if that is supported and try it.

[madson7]

@Slyke, how's your progress? I want to use the same approach.

[madson7]

@Slyke I ended up doing it this way because I'm in a controlled environment and on a separate subnet in my home lab.

$ORIGIN ramos.intra.net.
@                     900       IN  SOA           technitiumdns. madsonmar 38 900 300 604800 900
@                     3600      IN  NS            technitiumdns.
*                     3600      IN  CNAME         keepalive
dns                   3600      IN  A             9.0.0.2
keepalive             3600      IN  A             9.0.0.3

[Slyke]

Haven't started yet. Life's been in the way. I'm thinking to create a docker image with NodeJS and have it as a separate server and use Technitium API. I'm not a C# developer, so it probably wouldn't be good if I wrote a plugin.

[Slyke]

So I'm trying to write this as an application within TechnitiumDNS, but I'm not a C# guy and this is the first time I'm touching the language:

using Microsoft.AspNetCore.Builder;
using Microsoft.AspNetCore.Http;
using System.Text.Json;
using System.Threading.Tasks;
using DnsServerCore.ApplicationCommon;

namespace Dns01Handler
{
    public sealed class Dns01HandlerApp : IDnsApplication
    {
        private IDnsServer _dnsServer;
        private DnsTxtHandler _dnsHandler;

        public Task InitializeAsync(IDnsServer dnsServer, string config)
        {
            _dnsServer = dnsServer;

            _dnsHandler = new DnsTxtHandler(_dnsServer);

            _dnsServer.WriteLog("DNS-01 Challenge API is initialized successfully.");
            return Task.CompletedTask;
        }

        public async Task StartAsync()
        {
            var builder = WebApplication.CreateBuilder();
            var app = builder.Build();

            _dnsServer.WriteLog("DNS-01 Challenge API Server is starting...");
            _dnsServer.WriteLog("Listening on http://0.0.0.0:3000");

            app.MapPost("/dns-01/{action}", async (HttpContext context, string action) =>
            {
                _dnsServer.WriteLog($"Incoming request: POST {context.Request.Path}");

                if (action != "create" && action != "delete")
                {
                    _dnsServer.WriteLog("Invalid endpoint accessed.");
                    context.Response.StatusCode = 404;
                    await context.Response.WriteAsJsonAsync(new { error = "Not Found" });
                    return;
                }

                try
                {
                    var requestBody = await JsonSerializer.DeserializeAsync<RequestBody>(context.Request.Body);
                    if (string.IsNullOrEmpty(requestBody.Domain) || string.IsNullOrEmpty(requestBody.Validation))
                    {
                        _dnsServer.WriteLog("Invalid request body: Missing domain or validation.");
                        context.Response.StatusCode = 400;
                        await context.Response.WriteAsJsonAsync(new { error = "Missing domain or validation" });
                        return;
                    }

                    string zoneName = requestBody.Domain;
                    string recordName = $"_acme-challenge.{requestBody.Domain}";
                    string txtValue = requestBody.Validation;

                    _dnsServer.WriteLog($"Action: {action.ToUpper()}, Domain: {zoneName}, TXT Value: {txtValue}");

                    if (action == "create")
                    {
                        _dnsServer.WriteLog("Adding TXT record...");
                        await _dnsHandler.AddTxtRecordAsync(zoneName, recordName, txtValue);
                        _dnsServer.WriteLog("TXT record added successfully.");
                    }
                    else if (action == "delete")
                    {
                        _dnsServer.WriteLog("Removing TXT record...");
                        await _dnsHandler.RemoveTxtRecordAsync(zoneName, recordName, txtValue);
                        _dnsServer.WriteLog("TXT record removed successfully.");
                    }

                    await context.Response.WriteAsJsonAsync(new { message = $"TXT record {action}d successfully" });
                }
                catch (Exception ex)
                {
                    _dnsServer.WriteLog($"Error: {ex.Message}");
                    context.Response.StatusCode = 500;
                    await context.Response.WriteAsJsonAsync(new { error = ex.Message });
                }
            });

            await app.RunAsync("http://0.0.0.0:3000");
        }

        public void Dispose()
        {
            _dnsServer.WriteLog("DNS-01 Challenge API Server is shutting down.");
        }

        private class RequestBody
        {
            public string Domain { get; set; }
            public string Validation { get; set; }
        }
    }
}

When I load this app or update the settings, I can see in the logs:

[2024-12-15 19:30:29 UTC] [10.7.1.171:64342] [admin] DNS application 'testdns01handler' was updated successfully.
[2024-12-15 19:30:46 UTC] [10.7.1.171:64342] [admin] DNS application 'testdns01handler' app config was saved successfully.

But I don't see any of my logs in there. When I try to curl the URL, I get connection refused. This hints that the application is not running. I'm not sure what I'm doing wrong.

I'm using a few examples from the github. EG: https://github.com/TechnitiumSoftware/DnsServer/blob/master/Apps/AdvancedBlockingApp/App.cs

[ShreyasZare]

Since there is no DnsTxtHandler code, I am not sure how the app works. The DNS server already has an HTTP API which you can use directly so such an app is really not needed.

The issue with the code is that the StartAsync() method is never called. You need to call it in the InitializeAsync() method.

[Slyke]

The DNS server already has an HTTP API which you can use directly so such an app is really not needed.

Yes, but this is not compatible with LetsEncrypt/JetStack's nginx ingress DNS01 challenges, so this app is meant to act as a middleware between the APIs.

You need to call it in the InitializeAsync() method.

I also don't see "DNS-01 Challenge API is initialized successfully." in the log (or any errors), so I don't even think InitializeAsync() is being called.

I have recreated this in NodeJS and have it creating and deleting TXT entries. If I get time today, I will test it with the ingress using DNS01 challenges to see if it's correctly adding and removing the TXT entries. If it works, I'll abandoned the C# app, and just publish a Docker image, along with the source code for it.

[Slyke]

Here's my solution. I've tested it out and confirmed that it is working on LetsEncrypt staging (Dockerhub link below). No need to run npm install, as these requires are all native to NodeJS:

const http = require('http');
const crypto = require('crypto');
const { URL } = require('url');

const PORT = process.env.PORT || 3000;
const DNS_SERVER = process.env.DNS_SERVER || 'http://dns-server:5380';
const API_TOKEN = process.env.API_TOKEN || 'your-api-token';
const LOG_TXT_VALUES = process.env.LOG_TXT_VALUES === 'true';
const LOG_REQ_BODY = process.env.LOG_REQ_BODY === 'true';
const LOG_TECHREQ_URL = process.env.LOG_TECHREQ_URL === 'true';

const logWithTimestamp = (message) => {
  const timestamp = new Date().toISOString().replace('T', ' ').replace('Z', '');
  console.log(`[${timestamp}]: ${message}`);
};

const makeRequest = async (url, correlationId) => {
  logWithTimestamp(`{${correlationId}} Making request to: ${DNS_SERVER}`);
  if (LOG_TECHREQ_URL) {
    logWithTimestamp(`{${correlationId}} Request URL: ${url}`);
  }
  const response = await fetch(url);
  if (!response.ok) {
    logWithTimestamp(`{${correlationId}} Error:`);
    throw new Error(`HTTP error! Status: ${response.status}`);
  }
}

const server = http.createServer(async (req, res) => {
  const correlationId = crypto.randomUUID();
  logWithTimestamp(`{${correlationId}} Received request: ${req.method} ${req.url}`);

  if (req.method !== 'POST' || !['/present', '/cleanup'].includes(req.url)) {
    res.writeHead(404, { 'Content-Type': 'application/json' });
    res.end(JSON.stringify({ error: 'Not Found' }));
    logWithTimestamp(`{${correlationId}} Responded with: 404`);
    return;
  }

  let body = '';
  req.on('data', chunk => { body += chunk; });
  req.on('end', async () => {
    try {
      const { fqdn, value } = JSON.parse(body);
      if (LOG_TXT_VALUES) {
        logWithTimestamp(`{${correlationId}} Received request - FQDN: ${fqdn}, Value: ${value}`);
      } else {
        logWithTimestamp(`{${correlationId}} Received request - FQDN: ${fqdn}`);
      }

      if (LOG_REQ_BODY) {
        logWithTimestamp(`{${correlationId}} Received request - body: ${body}`);
      }

      if (!fqdn || !value) {
        res.writeHead(400, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify({ error: 'Missing fqdn or value' }));
        logWithTimestamp(`{${correlationId}} Responded with: 400 (Missing fqdn or value)`);
        return;
      }

      const action = req.url === '/present' ? 'add' : 'delete';
      const url = `${DNS_SERVER}/api/zones/records/${action}?token=${API_TOKEN}&domain=${fqdn}&type=TXT&text=${value}`;
      await makeRequest(url, correlationId);

      logWithTimestamp(`{${correlationId}} TXT record: ${action} successfully`);
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ message: `TXT record: ${action}` }));
    } catch (error) {
      logWithTimestamp(`{${correlationId}} Error handling request: ${error.message}`);
      res.writeHead(500, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ error: 'Failed to process request' }));
    }
  });
});

logWithTimestamp(`DNS-01 Challenge Handler init.`);

server.listen(PORT, () => {
  logWithTimestamp(`DNS-01 Challenge Handler running on port ${PORT}`);
});

You will also need to install this Solver to have the Kubernetes Issuer send a http request:

$ helm repo add cert-manager-webhook-httpreq https://saturncloud.github.io/cert-manager-webhook-httpreq/ --force-update
"cert-manager-webhook-httpreq" has been added to your repositories

$ helm install cert-manager-webhook-httpreq/httpreq-webhook --generate-name --namespace cert-manager --set groupName=dns01.acme.YOURDOMAIN.xyz
NAME: httpreq-webhook-1734433876
LAST DEPLOYED: Tue Dec 17 11:11:17 2024
NAMESPACE: cert-manager
STATUS: deployed
REVISION: 1
TEST SUITE: None

Issuer Yaml:

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-staging
  namespace: cert-manager
spec:
  acme:
    email: [email protected]
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    privateKeySecretRef:
      name: letsencrypt-staging
    solvers:
    - dns01:
        webhook:
          groupName: dns01.acme.YOURDOMAIN.xyz
          solverName: httpreq
          config:
            endpoint: http://FQDN-TO-NODEJS-HANDLER-SERVICE.:3000

Dockerhub link: https://hub.docker.com/repository/docker/slyke/dns01-challenge-handler/tags

@ShreyasZare it would be nice if TechnitiumDNS had native support for Let'sEncrypt DNS01 challenges, or at least an App for it. Basically it would work by pointing LetsEncrypt to TechnitiumDNS URL (with an API key) and it just works.

[ShreyasZare]

Thanks for the post here. Certbot is already capable to work with Technitium DNS using both the HTTP API and using RFC 2136. So any additional DNS app would be a duplicate effort and additional work to maintain.

[Slyke]

I found this blog post: https://blog.technitium.com/2023/03/how-to-auto-renew-ssl-certificates-with.html but it appears getting certbot to talk directly with Technitium (especially in Kubernetes) requires an extra pod using Python.

[ShreyasZare]

I just checked the cert-manager docs and it looks like they already support RFC 2136 method. So, you can just enable Dynamic Updates on your DNS zone and use rfc2156 provider in your config and make it work without need for any script. Does that work for you?