DNS-01 Challenge: CNAME Delegation Explained

✅ How It Works (Simple!)

End users add ONE CNAME record (one-time setup):

Name:   _acme-challenge.example.com
Type:   CNAME
Target: <public-id>.acme.cjj365.cc

That's it! After this one-time setup:

cert-ctrl manages TXT records automatically on <public-id>.acme.cjj365.cc
No DNS provider API keys needed by end users
Automatic certificate issuance and renewal
Zero manual DNS work

🔄 The Complete Flow

One-Time Setup (End User)

Step 1: Get your public-id from cert-ctrl dashboard

When you add a certificate, cert-ctrl generates a unique public-id
Example: abc123def

Step 2: Add CNAME record in your DNS provider:

Name:   _acme-challenge.example.com
Type:   CNAME
Target: abc123def.acme.cjj365.cc
       └──────┬──────┘
         public-id (from cert-ctrl dashboard)
TTL:    3600 (or any value)

Automatic Process (cert-ctrl Backend)

When cert-ctrl requests a certificate from Let's Encrypt:

Let's Encrypt generates a challenge token
- Example: aBcD1234eFgH5678
cert-ctrl creates TXT record on its own domain
```
Name:  abc123def.acme.cjj365.cc
Type:  TXT
Value: aBcD1234eFgH5678
TTL:   120 (2 minutes)
```
This happens on cert-ctrl's DNS (cjj365.cc zone) using cert-ctrl's own API credentials

Let's Encrypt follows the CNAME and verifies

# Let's Encrypt queries:
dig TXT _acme-challenge.example.com

# DNS returns CNAME:
_acme-challenge.example.com. → CNAME → abc123def.acme.cjj365.cc

# Then queries the target:
abc123def.acme.cjj365.cc. 120 IN TXT "aBcD1234eFgH5678" ✅

cert-ctrl removes TXT record after validation
- Keeps DNS clean
- CNAME stays for future renewals (never changes)

📋 Comparison Table

Method	Manual TXT	acme.sh DNS API	cert-ctrl CNAME
User Setup	Every 90 days ❌	One-time API keys ⚠️	One CNAME only ✅
API Keys	Not needed ⚠️	User must provide ❌	Not needed ✅
DNS Provider	Any	Must support API	Any (CNAME only) ✅
Security Risk	Low but manual ⚠️	High (API keys) ❌	Low (no keys) ✅
Renewal	Manual every 90d ❌	Automatic ✅	Automatic ✅
DNS Cleanup	Manual (forget) ❌	Automatic ✅	Automatic ✅
Setup Difficulty	Easy but repetitive	Complex (API setup)	Easy (one CNAME) ✅

🎯 Why CNAME Delegation is Perfect

cert-ctrl uses CNAME delegation, and it's brilliant:

# User's DNS (one-time setup, never changes):
_acme-challenge.example.com → CNAME → abc123def.acme.cjj365.cc

# cert-ctrl's DNS (automatic, created/deleted as needed):
abc123def.acme.cjj365.cc → TXT → "challenge_token"

✅ Advantages

No API keys from users - Users never share DNS credentials
Works with any DNS provider - Just needs CNAME support (all have it)
One-time setup - CNAME never needs to change
Secure - Users only delegate _acme-challenge subdomain, not full zone
Automatic renewals - cert-ctrl updates its own TXT records
Clean DNS - TXT records removed immediately after validation

📊 Security Comparison

❌ Other ACME tools requiring DNS API keys:

Your DNS Provider API Key → Given to ACME service
Risk: 
- Service can modify ANY DNS record in your zone
- API key can be leaked/stolen
- Must trust service with full DNS control
- Cannot easily revoke (would break automation)

✅ cert-ctrl CNAME delegation:

Your DNS: Only CNAME record (read-only delegation)
cert-ctrl DNS: Manages TXT records on cjj365.cc zone
Risk:
- cert-ctrl can only prove domain ownership for challenges
- Cannot modify your other DNS records
- Easy to revoke (delete CNAME)
- No credentials shared

🎯 User Experience Comparison

Traditional DNS API Method (acme.sh, certbot-dns-*)

Step 1: Sign up for ACME service
Step 2: Create DNS provider API credentials
Step 3: Configure API keys in ACME tool
Step 4: Worry about API key security
Step 5: Request certificate
Step 6: Hope API integration works
Step 7: Manually deploy certificate
Step 8: Automatic renewal (but API keys remain a risk)

Problems:

❌ Must expose DNS API keys to third-party tool
❌ Complex API setup (different per provider)
❌ Security risk if keys are leaked
❌ Must manually deploy certificates

cert-ctrl CNAME Method

Step 1: Sign up for cert-ctrl
Step 2: Add certificate → get public-id
Step 3: Add CNAME record (one-time)
Step 4: Done! ✅
Step 5: Automatic renewal every 60 days
Step 6: Automatic deployment to all agents

Benefits:

✅ No API keys to manage
✅ Works with any DNS provider
✅ One CNAME, done forever
✅ Automatic deployment

🔐 Security Note

Why CNAME Delegation is More Secure

Limited Scope: Only affects _acme-challenge.* subdomain
Read-Only Delegation: cert-ctrl can only prove ownership, not change your records
No Credentials: Your DNS login/API keys stay with you
Easy Revocation: Just delete the CNAME record
Audit Trail: All actions logged on cert-ctrl side
Temporary TXT Records: Exist only during validation (30-60 seconds)

What Users CANNOT Do (By Design)

Users cannot (and don't need to):

❌ Access cert-ctrl's DNS provider API
❌ See or manage TXT records on *.acme.cjj365.cc
❌ Modify challenge tokens
❌ Create/delete TXT records manually

This is perfect! Users get automation without security risks.

📝 Example: Real Certificate Request

Step-by-Step Visual Flow

1. User adds certificate in dashboard:

Domain: example.com
SANs: example.com, www.example.com

2. cert-ctrl generates public-id:

public-id: f8e3c2b9a1d4

3. Dashboard shows CNAME instruction:

┌─────────────────────────────────────────────────┐
│ Add this CNAME record to your DNS:             │
│                                                 │
│ Name:   _acme-challenge.example.com             │
│ Type:   CNAME                                   │
│ Target: f8e3c2b9a1d4.acme.cjj365.cc            │
│                                                 │
│ [Copy CNAME] [Mark as Done]                    │
└─────────────────────────────────────────────────┘

4. User adds CNAME (in their DNS provider's web interface):

Cloudflare/Route53/Aliyun/Any DNS Provider:
Name:   _acme-challenge.example.com
Type:   CNAME
Target: f8e3c2b9a1d4.acme.cjj365.cc
TTL:    3600

5. User clicks "Issue Certificate" in cert-ctrl dashboard

6. Behind the scenes (automatic):

cert-ctrl → Cloudflare API (cjj365.cc zone) → Create TXT f8e3c2b9a1d4.acme.cjj365.cc
Let's Encrypt → DNS Query → _acme-challenge.example.com
                         → Follow CNAME → f8e3c2b9a1d4.acme.cjj365.cc
                         → Get TXT record → Verify ✅
cert-ctrl → Cloudflare API (cjj365.cc zone) → Delete TXT f8e3c2b9a1d4.acme.cjj365.cc
cert-ctrl → Deploy certificate to all agents automatically

7. User sees:

✅ Certificate issued successfully!
- Deployed to 3 agents
- Next renewal: 60 days
- CNAME record can stay forever (never needs to change)

🌐 Multi-Domain Example

When requesting a certificate with multiple SANs:

Domain: example.com
SANs: example.com, www.example.com, api.example.com

User needs CNAMEs for each subdomain:

_acme-challenge.example.com     → f8e3c2b9a1d4.acme.cjj365.cc
_acme-challenge.www.example.com → f8e3c2b9a1d4.acme.cjj365.cc
_acme-challenge.api.example.com → f8e3c2b9a1d4.acme.cjj365.cc

All use the same public-id, cert-ctrl manages different TXT records automatically.

🚀 Summary

✅ What IS True

CNAME delegation is used (one-time setup by users)
TXT records are managed automatically (by cert-ctrl on its own domain)
No DNS API keys needed from users
Works with any DNS provider (all support CNAME)
Secure (limited delegation scope)
Automatic renewals (CNAME never changes)
Clean DNS (TXT records removed after validation)

❌ What is NOT True

❌ Users do NOT create TXT records manually
❌ Users do NOT provide DNS API keys to cert-ctrl
❌ Users do NOT need DNS provider with API support
❌ CNAME does NOT need to change for renewals
❌ Users do NOT see or manage TXT records on *.acme.cjj365.cc

🎯 The Key Insight

CNAME delegation splits the responsibility:

User's responsibility: Add one CNAME record (one-time, never changes)
cert-ctrl's responsibility: Manage TXT records automatically (using its own DNS API credentials)

Result: Users get full automation without security risks! 🎉

🤔 FAQ

Q: What if I don't have API access to my DNS provider?
A: No problem! CNAME records can be added through any DNS provider's web interface. You don't need API access.

Q: Can I use multiple DNS providers?
A: Yes! Each domain can use a different DNS provider. Just add the CNAME in each provider.

Q: What if I delete the CNAME after certificate issuance?
A: The current certificate will work, but renewals will fail. Keep the CNAME forever for automatic renewals.

Q: Can cert-ctrl modify my other DNS records?
A: No! cert-ctrl can only create/delete TXT records on its own domain (*.acme.cjj365.cc), not yours.

Q: What happens if cert-ctrl is compromised?
A: Attacker can only create/delete TXT records on *.acme.cjj365.cc, not modify your DNS zone. Delete the CNAME to revoke access.

Q: How is this different from acme.sh alias mode?
A: acme.sh alias mode still requires YOU to manage TXT records (or provide API keys). cert-ctrl manages everything for you.

Q: Can I see the TXT records cert-ctrl creates?
A: Yes! During validation, query: dig TXT f8e3c2b9a1d4.acme.cjj365.cc (replace with your public-id)

Q: Why 60-day renewal instead of 90?
A: Safety margin. Let's Encrypt certificates are valid for 90 days; we renew at 60 days to avoid expiration risks.

Still confused? Think of it like this:

🏠 Your house (DNS zone): You own it, full control
📬 Mailbox delegation (CNAME): You put a sign saying "ACME mail goes to cert-ctrl's office"
🏢 cert-ctrl's office: We receive the mail, process it, never touch your house
✅ Result: You get certificates automatically without giving us house keys (DNS API credentials)

✅ How It Works (Simple!)​

🔄 The Complete Flow​

One-Time Setup (End User)​

Automatic Process (cert-ctrl Backend)​

📋 Comparison Table​

🎯 Why CNAME Delegation is Perfect​

✅ Advantages​

📊 Security Comparison​

🎯 User Experience Comparison​

Traditional DNS API Method (acme.sh, certbot-dns-*)​

cert-ctrl CNAME Method​

🔐 Security Note​

Why CNAME Delegation is More Secure​

What Users CANNOT Do (By Design)​

📝 Example: Real Certificate Request​

Step-by-Step Visual Flow​

🌐 Multi-Domain Example​

🚀 Summary​

✅ What IS True​

❌ What is NOT True​

🎯 The Key Insight​

🤔 FAQ​