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-challengerecords) - 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?queryor a#fragmentare refused, including forlocalhost. Put secrets in theauth_headerandauth_valuefields instead. - Checked when saved: Charon checks each address when you save the provider. If you saved a provider earlier with a
?queryin 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_headerandauth_valuefor 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.1or0x7f000001. 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
httpsif the connection crosses a network you do not fully trust, because your API key is sent with every request. Plainhttpis 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_secondsto 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 |
Related Documentation¶
- DNS Provider Auto-Detection — Automatic provider identification
- Multi-Credential DNS Support — Managing multiple credentials per provider
- Key Rotation — Credential rotation best practices
- Audit Logging — Tracking DNS operations
Last Updated: January 2026 Version: 1.4.0