Files

Krystie d76644d948 Sync DNS2 production changes - removed obsolete test suite and refactored structure

2026-03-23 10:47:15 +01:00

8.2 KiB

Raw Blame History

DashCA Certificate Generation API

Overview

DashCA now provides automatic SSL certificate generation for services on your network. This allows services like Technitium DNS to automatically obtain valid SSL certificates signed by your internal CA.

Features

Automatic Certificate Generation: Generate SSL certificates for any domain on demand
Multiple Formats: PFX, PEM, CRT, KEY, and full chain certificates
Certificate Caching: Certificates are cached and reused if still valid (>30 days remaining)
No Authentication Required: Public API endpoints for easy automation
Automatic Renewal: Certificates are regenerated when they expire in less than 30 days

API Endpoints

1. Generate/Download Certificate

GET /api/ca/cert/:domain

Generate and download an SSL certificate for the specified domain.

Parameters:

:domain (required) - The domain name (e.g., dns1.sami, dns2.sami)
format (optional) - Certificate format: pfx, pem, crt, key, or fullchain (default: pfx)
password (optional) - Password for PFX files (default: dashcaddy)

Examples:

# Download PFX certificate for dns1.sami
curl -O "https://ca.sami/api/ca/cert/dns1.sami?format=pfx&password=dashcaddy"

# Download PEM bundle (private key + certificate + chain)
curl -O "https://ca.sami/api/ca/cert/dns1.sami?format=pem"

# Download certificate only
curl -O "https://ca.sami/api/ca/cert/dns1.sami?format=crt"

# Download private key only
curl -O "https://ca.sami/api/ca/cert/dns1.sami?format=key"

# Download full certificate chain (cert + intermediate + root)
curl -O "https://ca.sami/api/ca/cert/dns1.sami?format=fullchain"

PowerShell:

Invoke-WebRequest -Uri "https://ca.sami/api/ca/cert/dns1.sami?format=pfx" -OutFile "dns1.pfx"

2. List Generated Certificates

GET /api/ca/certs

List all generated certificates with their status and expiration information.

Example:

curl https://ca.sami/api/ca/certs

Response:

{
  "success": true,
  "certificates": [
    {
      "domain": "dns1.sami",
      "subject": "CN=dns1.sami",
      "validFrom": "Feb 11 21:37:02 2026 GMT",
      "validUntil": "Feb 11 21:37:02 2027 GMT",
      "daysUntilExpiration": 364,
      "fingerprint": "4E:74:F8:49:...",
      "status": "valid"
    }
  ]
}

Status values:

valid - Certificate is valid and has >30 days remaining
expiring-soon - Certificate expires in less than 30 days
expired - Certificate has expired

Certificate Details

Validity: 365 days (1 year)
Algorithm: RSA 2048-bit (for broad compatibility)
Signature: SHA-256
Key Usage: Key Encipherment, Data Encipherment, Digital Signature
Extended Key Usage: Server Authentication
Subject Alternative Names: Primary domain + wildcard subdomain (if applicable)

Example: A certificate for dns1.sami includes both dns1.sami and *.dns1.sami.

Automation Scripts

PowerShell - Update Technitium DNS Certificate

Located at: C:\caddy\scripts\update-technitium-cert.ps1

# Update certificate for a single DNS server
.\update-technitium-cert.ps1 `
    -Domain "dns1.sami" `
    -TechnitiumUrl "http://192.168.254.204:5380" `
    -CertPath "C:\ProgramData\Technitium\DnsServer\cert.pfx"

# Update all DNS servers at once
.\update-all-dns-certs.ps1

Schedule Automatic Updates

Create a Windows scheduled task to update certificates monthly:

# Create scheduled task for monthly certificate updates
schtasks /create `
    /tn "Update DNS Certificates" `
    /tr "powershell -ExecutionPolicy Bypass -File C:\caddy\scripts\update-all-dns-certs.ps1" `
    /sc monthly `
    /d 1 `
    /st 03:00 `
    /ru SYSTEM

Manual Certificate Installation

Technitium DNS

Download PFX certificate:

curl -k -O "https://ca.sami/api/ca/cert/dns1.sami?format=pfx&password=dashcaddy"

Copy to Technitium directory:

Copy dns1.sami.pfx to C:\ProgramData\Technitium\DnsServer\cert.pfx

Restart Technitium DNS Server service:

Restart-Service "Technitium DNS Server"

Access Technitium DNS web interface via HTTPS:
```
https://dns1.sami:5380
```

Other Services

For other services requiring SSL certificates, use the appropriate format:

PFX: Windows services, .NET applications, IIS
PEM: Most Linux services (Apache, Nginx, HAProxy)
CRT + KEY: Separate certificate and key files (Nginx, Apache)
Fullchain: Full certificate chain for maximum compatibility

Security Considerations

Root CA Protection: The root CA private key is mounted read-only in the API container
Serial Number Tracking: Each certificate gets a unique serial number stored per domain
Password Protection: PFX files are password-protected (default: dashcaddy)
Network Access: Certificate API is available on your Tailscale network only
No Revocation: Certificates cannot be revoked; wait for expiration or delete manually

Troubleshooting

Certificate Generation Fails

Check if the PKI directory is accessible:

docker exec dashcaddy-api ls -la /app/pki/

Should show: root.crt, root.key, intermediate.crt, intermediate.key

Certificate Not Trusted by Browser

Install the root CA certificate on your device:

curl -O https://ca.sami/root.crt

Follow platform-specific installation instructions on the DashCA homepage.

Certificate Expired

Request a new certificate - it will automatically regenerate:

curl -O "https://ca.sami/api/ca/cert/dns1.sami?format=pfx"

Generated Certificates Location

On the host system:

C:\caddy\generated-certs\
  ├── dns1.sami\
  │   ├── server.key
  │   ├── server.csr
  │   ├── server.crt
  │   ├── server.pfx
  │   ├── server.pem
  │   └── fullchain.pem
  ├── dns2.sami\
  └── dns3.sami\

Integration Examples

curl

# Simple download
curl -O https://ca.sami/api/ca/cert/myservice.sami?format=pfx

# With custom password
curl -O "https://ca.sami/api/ca/cert/myservice.sami?format=pfx&password=mypassword"

PowerShell

# Download and install
$certPath = "C:\certs\myservice.pfx"
Invoke-WebRequest -Uri "https://ca.sami/api/ca/cert/myservice.sami?format=pfx" -OutFile $certPath

# Verify certificate
$cert = New-Object System.Security.Cryptography.X509Certificates.X509Certificate2($certPath, "dashcaddy")
Write-Host "Certificate valid until: $($cert.NotAfter)"

Bash/Linux

#!/bin/bash
# Download and extract PEM files
curl -k "https://ca.sami/api/ca/cert/myservice.sami?format=pem" -o myservice.pem

# Extract key and cert
openssl pkey -in myservice.pem -out myservice.key
openssl x509 -in myservice.pem -out myservice.crt

Docker Compose

services:
  myservice:
    image: myimage
    volumes:
      - ./certs:/certs
    environment:
      SSL_CERT_FILE: /certs/myservice.crt
      SSL_KEY_FILE: /certs/myservice.key
    command: |
      sh -c "
        curl -k https://ca.sami/api/ca/cert/myservice.sami?format=crt -o /certs/myservice.crt &&
        curl -k https://ca.sami/api/ca/cert/myservice.sami?format=key -o /certs/myservice.key &&
        exec myservice
      "

DNS Server Configuration

DNS1 (Primary)

IP: 192.168.254.204
Domain: dns1.sami
Certificate: https://ca.sami/api/ca/cert/dns1.sami?format=pfx

DNS2 (Secondary)

IP: 100.74.102.61 (Tailscale)
Domain: dns2.sami
Certificate: https://ca.sami/api/ca/cert/dns2.sami?format=pfx

DNS3 (Tertiary)

IP: 100.89.216.23 (Tailscale)
Domain: dns3.sami
Certificate: https://ca.sami/api/ca/cert/dns3.sami?format=pfx

Future Enhancements

Potential features for future versions:

Certificate revocation lists (CRL)
OCSP responder
Certificate renewal webhooks
Email notifications for expiring certificates
Web UI for certificate management
Custom certificate validity periods
Certificate templates for different service types
Automatic DNS record validation

Support

For issues or questions, check:

DashCA homepage: https://ca.sami
Certificate list: https://ca.sami/api/ca/certs
Server logs: docker logs dashcaddy-api

8.2 KiB Raw Blame History