Skip to content

DNS Provider Types

This document describes the DNS provider types available in Charon for DNS-01 challenge validation during SSL certificate issuance.

Overview

Charon supports multiple DNS provider types to accommodate different deployment scenarios:

Provider Type Use Case Security Level
API-Based Cloudflare, Route53, DigitalOcean, etc. ✅ Recommended
RFC 2136 Self-hosted BIND9, PowerDNS, Knot DNS ✅ Recommended
Webhook Custom DNS APIs, automation platforms ⚠️ Moderate
Script Legacy tools, custom integrations ⚠️ High Risk

RFC 2136 (Dynamic DNS)

RFC 2136 Dynamic DNS Update allows Charon to directly update DNS records on authoritative DNS servers that support the protocol, using TSIG authentication for security.

Use Cases

  • Self-hosted BIND9, PowerDNS, or Knot DNS servers
  • Enterprise environments with existing DNS infrastructure
  • Air-gapped networks without external API access
  • ISP or hosting provider managed DNS with RFC 2136 support

Configuration

Field Required Default Description
nameserver ✅ — DNS server hostname or IP address
tsig_key_name ✅ — TSIG key name (e.g., acme-update.)
tsig_key_secret ✅ — Base64-encoded TSIG key secret
port ❌ 53 DNS server port
tsig_algorithm ❌ hmac-sha256 TSIG algorithm (see below)
zone ❌ — DNS zone override (auto-detected if not set)

TSIG Algorithms

Algorithm Recommendation
hmac-sha256 ✅ Recommended — Good balance of security and compatibility
hmac-sha384 ✅ Secure — Higher security, wider key
hmac-sha512 ✅ Secure — Maximum security
hmac-sha1 ⚠️ Legacy — Use only if required by older systems
hmac-md5 ❌ Deprecated — Avoid; cryptographically weak

Example Configuration

{
  "type": "rfc2136",
  "nameserver": "ns1.example.com",
  "port": 53,
  "tsig_key_name": "acme-update.",
  "tsig_key_secret": "base64EncodedSecretKey==",
  "tsig_algorithm": "hmac-sha256",
  "zone": "example.com"
}

Generating a TSIG Key (BIND9)

# Generate a new TSIG key
tsig-keygen -a hmac-sha256 acme-update > /etc/bind/acme-update.key

# Contents of generated key file:
# key "acme-update" {
#     algorithm hmac-sha256;
#     secret "base64EncodedSecretKey==";
# };

Security Notes

  • Network Security: Ensure the DNS server is reachable from Charon (firewall rules, VPN)
  • Key Permissions: TSIG keys should have minimal permissions (only _acme-challenge records)
  • Key Rotation: Rotate TSIG keys periodically (recommended: every 90 days)
  • TLS Not Supported: RFC 2136 uses UDP/TCP without encryption; use network-level security

Webhook Provider

The Webhook provider enables integration with custom DNS APIs or automation platforms by sending HTTP requests to user-defined endpoints.

Use Cases

  • Custom internal DNS management APIs
  • Integration with automation platforms (Ansible AWX, Rundeck, etc.)
  • DNS providers without native Charon support
  • Multi-system orchestration workflows

Configuration

Field Required Default Description
create_url ✅ — URL to call when creating TXT records
delete_url ✅ — URL to call when deleting TXT records
auth_header ❌ — HTTP header name for authentication (e.g., Authorization)
auth_value ❌ — HTTP header value (e.g., Bearer token123)
timeout_seconds ❌ 30 Request timeout in seconds
retry_count ❌ 3 Number of retry attempts on failure
insecure_skip_verify ❌ false Skip TLS verification (⚠️ dev only)

URL Template Variables

The following variables are available in create_url and delete_url:

Variable Description Example
{{fqdn}} Full record name _acme-challenge.example.com
{{domain}} Base domain example.com
{{value}} TXT record value dGVzdC12YWx1ZQ==
{{ttl}} Record TTL 120

Example Configuration

{
  "type": "webhook",
  "create_url": "https://dns-api.example.com/records?action=create&fqdn={{fqdn}}&value={{value}}",
  "delete_url": "https://dns-api.example.com/records?action=delete&fqdn={{fqdn}}",
  "auth_header": "Authorization",
  "auth_value": "Bearer your-api-token",
  "timeout_seconds": 30,
  "retry_count": 3
}

Webhook Request Format

Create Request:

POST {{create_url}}
Content-Type: application/json
{{auth_header}}: {{auth_value}}

{
  "fqdn": "_acme-challenge.example.com",
  "domain": "example.com",
  "value": "challenge-token-value",
  "ttl": 120
}

Delete Request:

POST {{delete_url}}
Content-Type: application/json
{{auth_header}}: {{auth_value}}

{
  "fqdn": "_acme-challenge.example.com",
  "domain": "example.com"
}

Expected Responses

Status Code Meaning
200, 201, 204 Success
4xx Client error — check configuration
5xx Server error — will retry based on retry_count

Security Notes

  • HTTPS Required: Non-localhost URLs must use HTTPS
  • Keep secrets out of the address: Addresses containing a username and password (user:pass@), a ?query or a #fragment are refused, including for localhost. Put secrets in the auth_header and auth_value fields instead.
  • Checked when saved: Charon checks each address when you save the provider. If you saved a provider earlier with a ?query in its address, you will see the error the next time you edit and save it. Remove the query and move the secret into the auth fields.
  • Authentication: Always use auth_header and auth_value for production
  • Timeouts: Set appropriate timeouts to avoid blocking certificate issuance
  • insecure_skip_verify: Never enable in production; only for local development with self-signed certs

PowerDNS

PowerDNS is available as a plugin. Enter the address of your PowerDNS API and your API key.

Which Addresses Work

Address Allowed?
Your server's LAN address (like 192.168.1.20) or a Docker network address Yes
Tailscale-style addresses (100.64.x.x) Yes
localhost, 127.0.0.1, ::1 (the Charon host itself) No — use your server's LAN or Docker network address instead
Private IPv6 addresses (like fd00:: or fd7a::) No — use an IPv4 LAN or 100.64.x.x address
Cloud-internal addresses No
  • Charon checks the address when you create, update or test the provider.
  • Charon does not follow redirects.
  • When you press Test, Charon also refuses ports below 1024 other than 80 and 443 (for example :22). Saving a provider does not apply this port rule.
  • Charon also refuses unusual ways of writing an IP address, such as 127.1 or 0x7f000001. Use the normal form (192.168.1.20) or a hostname.
  • Providers you already saved keep issuing certificates as before. The check applies when you test or save.
  • Use https if the connection crosses a network you do not fully trust, because your API key is sent with every request. Plain http is still allowed.
  • Charon refuses connections to a few internal-only address ranges everywhere it makes outgoing connections.

Script Provider

The Script provider executes shell scripts to manage DNS records, enabling integration with legacy systems or tools without API access.

⚠️ HIGH-RISK PROVIDER

Warning: Scripts execute with container privileges. Only use when no other option is available. Thoroughly audit all scripts before deployment.

Use Cases

  • Legacy DNS management tools (nsupdate wrappers, custom CLIs)
  • Systems requiring SSH-based updates
  • Complex multi-step DNS workflows
  • Air-gapped environments with local tooling

Configuration

Field Required Default Description
script_path ✅ — Path to script (must be in /scripts/)
timeout_seconds ❌ 60 Maximum script execution time
env_vars ❌ — Environment variables (KEY=VALUE format)

Script Interface

Scripts receive DNS operation details via environment variables:

Variable Description Example
DNS_ACTION Operation type create or delete
DNS_FQDN Full record name _acme-challenge.example.com
DNS_DOMAIN Base domain example.com
DNS_VALUE TXT record value (create only) challenge-token
DNS_TTL Record TTL (create only) 120

Exit Codes:

Code Meaning
0 Success
1 Failure (generic)
2 Configuration error

Example Configuration

{
  "type": "script",
  "script_path": "/scripts/dns-update.sh",
  "timeout_seconds": 60,
  "env_vars": "DNS_SERVER=ns1.example.com,SSH_KEY_PATH=/secrets/dns-key"
}

Example Script

#!/bin/bash
# /scripts/dns-update.sh
set -euo pipefail

case "$DNS_ACTION" in
  create)
    echo "Creating TXT record: $DNS_FQDN = $DNS_VALUE"
    nsupdate -k /etc/bind/keys/update.key <<EOF
server $DNS_SERVER
update add $DNS_FQDN $DNS_TTL TXT "$DNS_VALUE"
send
EOF
    ;;
  delete)
    echo "Deleting TXT record: $DNS_FQDN"
    nsupdate -k /etc/bind/keys/update.key <<EOF
server $DNS_SERVER
update delete $DNS_FQDN TXT
send
EOF
    ;;
  *)
    echo "Unknown action: $DNS_ACTION" >&2
    exit 1
    ;;
esac

Security Requirements

Requirement Details
Script Location Must be in /scripts/ directory (enforced)
Permissions Script must be executable (chmod +x)
Audit Review all scripts before deployment
Secrets Use mounted secrets, never hardcode credentials
Timeouts Set appropriate timeouts to prevent hanging

Security Notes

  • Container Privileges: Scripts run with full container privileges
  • Path Restriction: Scripts must reside in /scripts/ to prevent arbitrary execution
  • No User Input: Script path cannot contain user-supplied data
  • Logging: All script executions are logged to audit trail
  • Resource Limits: Use timeout_seconds to prevent runaway scripts
  • Testing: Test scripts thoroughly in non-production before deployment

Provider Comparison

Feature RFC 2136 Webhook Script
Setup Complexity Medium Low High
Security High (TSIG) Medium (HTTPS) Low (shell)
Flexibility DNS servers only HTTP APIs Unlimited
Debugging DNS tools HTTP logs Script logs
Recommended For Self-hosted DNS Custom APIs Legacy only

Last Updated: January 2026 Version: 1.4.0