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

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

Overview​

RFC 2136 (Dynamic DNS)​

Use Cases​

Configuration​

TSIG Algorithms​

Example Configuration​

Generating a TSIG Key (BIND9)​

Security Notes​

Webhook Provider​

Use Cases​

Configuration​

URL Template Variables​

Example Configuration​

Webhook Request Format​

Expected Responses​

Security Notes​

Script Provider​

⚠️ HIGH-RISK PROVIDER​

Use Cases​

Configuration​

Script Interface​

Example Configuration​

Example Script​

Security Requirements​

Security Notes​

Provider Comparison​

Related Documentation​

Overview

RFC 2136 (Dynamic DNS)

Use Cases

Configuration

TSIG Algorithms

Example Configuration

Generating a TSIG Key (BIND9)

Security Notes

Webhook Provider

Use Cases

Configuration

URL Template Variables

Example Configuration

Webhook Request Format

Expected Responses

Security Notes

Script Provider

⚠️ HIGH-RISK PROVIDER

Use Cases

Configuration

Script Interface

Example Configuration

Example Script

Security Requirements

Security Notes

Provider Comparison

Related Documentation