Charon/docs/features/dns-providers.md

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
• 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

---

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

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