dashcaddy/dashcaddy-api/ca/README.md

DashCA - Certificate Authority Distribution

A self-hosted landing page for distributing your root CA certificate with one-click installation across all major platforms.

Quick Start

Regenerate All Certificate Formats

cd scripts
bash generate-all.sh

This will:

1. Copy root.crt and intermediate.crt from Caddy PKI
2. Generate root.der (DER format for Windows)
3. Generate root.mobileconfig (Apple profile for iOS/macOS)
4. Extract certificate metadata to cert-info.json

Deploy to Production

# Copy all files to production directory
cp -r e:/CaddyCerts/sites/ca/* C:/caddy/sites/ca/

Or deploy via the dashboard app selector (preferred method).

File Structure

ca/
├── index.html                    # Landing page with OS detection
├── root.crt                      # Root CA certificate (PEM format)
├── root.der                      # Root CA certificate (DER format)
├── root.mobileconfig             # Apple configuration profile
├── intermediate.crt              # Intermediate CA certificate
├── cert-info.json                # Certificate metadata (auto-generated)
├── scripts/
│   ├── install.ps1               # Windows PowerShell installer
│   ├── install.sh                # Linux/macOS shell installer
│   ├── generate-cert-info.js     # Extract certificate metadata
│   ├── generate-mobileconfig.js  # Generate Apple profile
│   └── generate-all.sh           # Wrapper script to regenerate all
└── assets/
    └── (icons, logos, etc.)

Certificate Information

Source: Caddy's built-in PKI at C:/caddy/certs/pki/authorities/local/

• Name: Sami Home Network Root CA
• Algorithm: ECDSA P-256 with SHA-256
• Valid Until: Dec 22, 2034
• Fingerprint: 08:98:A5:63:F5:A1:A2:58:5F:02:D7:A8:A2:54:87:E6:BC:33:96:21:29:0E

Installation Scripts

Windows (install.ps1)

Features:

• Requires Administrator privileges
• Downloads certificate from ca.sami
• Verifies SHA-256 fingerprint
• Installs to LocalMachine\Root store
• Checks for existing installation

One-liner:

irm https://ca.sami/install.ps1 | iex

Linux/macOS (install.sh)

Features:

• Requires sudo/root
• Auto-detects OS (Debian, RedHat, Arch, macOS)
• Platform-specific installation commands
• Fingerprint verification with OpenSSL
• Checks for existing installation

One-liner:

curl -fsSL https://ca.sami/install.sh | sudo bash

Apple Devices (root.mobileconfig)

Features:

• Works on both iOS and macOS
• XML configuration profile format
• Contains base64-encoded certificate
• Unique UUIDs per generation
• User must manually trust after installation (iOS)

Installation:

1. Download root.mobileconfig
2. iOS: Settings prompts automatically
3. macOS: System Settings → Profiles → Install
4. iOS: Enable trust in Certificate Trust Settings

Landing Page Features

The landing page (index.html) includes:

• OS Detection: Automatically detects Windows, macOS, Linux, iOS, Android
• Certificate Info Display: Shows name, fingerprint, expiration, algorithm
• QR Code: For easy mobile access (powered by qrcodejs library)
• Download Links: All certificate formats and installation scripts
• Platform Tabs: Detailed instructions for each operating system
• Copy-to-Clipboard: For fingerprint and command-line scripts
• DashCaddy Theme: Dark mode with Sami Grotesk font

API Integration:

• Loads certificate info from /api/ca/info endpoint
• Falls back to static info if API unavailable

Development Workflow

1. Edit Files: Make changes in e:/CaddyCerts/sites/ca/
2. Test Locally: Open index.html in browser (file:// protocol works)
3. Regenerate Certificates: Run scripts/generate-all.sh if CA renewed
4. Deploy: Copy to production or use dashboard deployment
5. Verify: Visit https://ca.sami and test on target platforms

Updating After CA Renewal

When Caddy regenerates its CA certificate (every ~10 years):

1. Regenerate Certificate Formats

cd e:/CaddyCerts/sites/ca/scripts
bash generate-all.sh

2. Update Fingerprints in Scripts

The new fingerprint will be in cert-info.json. Update these files:

install.ps1 (line 17):

$ExpectedFingerprint = "NEW:FIN:GER:PRINT:HERE"

install.sh (line 13):

EXPECTED_FP="NEW:FIN:GER:PRINT:HERE"

3. Deploy to Production

cp -r e:/CaddyCerts/sites/ca/* C:/caddy/sites/ca/

4. Notify Users

• Add banner to dashboard
• Send notification via configured channels
• Update documentation with new expiration date

API Endpoints

DashCA integrates with DashCaddy API:

GET /api/ca/info

Returns certificate metadata:

{
  "success": true,
  "certificate": {
    "name": "Sami Home Network Root CA",
    "fingerprint": "08:98:A5:...",
    "validFrom": "Feb 12 07:44:51 2025 GMT",
    "validUntil": "Dec 22 07:44:51 2034 GMT",
    "daysUntilExpiration": 3235,
    "algorithm": "ECDSA P-256 with SHA-256",
    "serialNumber": "c1:dc:48:...",
    "downloadUrl": "https://ca.sami/root.crt"
  }
}

GET /api/health/ca

Returns CA expiration health status:

{
  "status": "healthy",
  "message": "CA certificate valid for 3235 days",
  "daysUntilExpiration": 3235,
  "expiresAt": "Dec 22 07:44:51 2034 GMT"
}

Status values:

• healthy: >90 days remaining
• warning: 30-90 days
• critical: <30 days or expired
• error: Certificate not found or error reading

Troubleshooting

Certificate Not Found Error

Symptom: Scripts fail with "certificate not found" Cause: Caddy hasn't generated the local CA yet Solution: Visit any *.sami domain to trigger CA generation

Fingerprint Mismatch

Symptom: Install scripts reject certificate with fingerprint mismatch Cause: CA was renewed but scripts not updated Solution: Run generate-all.sh and update fingerprints in install scripts

iOS Profile Won't Install

Symptom: .mobileconfig shows error when installing Cause: Invalid XML or missing UUIDs Solution: Regenerate with node generate-mobileconfig.js

Android Shows "Not Trusted"

Symptom: Certificate installs but sites still show warnings Cause: Android installs as "user" certificate; some apps don't trust user CAs Solution: This is by design. System CA installation requires root access.

Landing Page Shows "Loading..."

Symptom: Certificate info stuck on loading state Cause: API endpoint not accessible Solution: Check that dashcaddy-api server is running and /api/ca/info responds

Testing Checklist

Before deploying to production:

• All certificate formats generated successfully
• Landing page loads correctly in browser
• OS detection works (test multiple user agents)
• QR code renders and scans correctly
• Download links work for all file types
• API endpoint returns valid certificate info
• Copy-to-clipboard buttons work
• Platform instruction tabs function correctly
• Responsive design works on mobile viewport
• HTTPS access works after deployment

Security Notes

• Private Key: NEVER serve the CA private key (root.key). Only public certificates are safe to distribute.
• Fingerprint Verification: Install scripts verify fingerprint to prevent MITM attacks
• Access Control: ca.sami should only be accessible on your Tailnet/internal network
• HTTPS Enforcement: The page itself uses HTTPS (via Caddy's internal CA) to protect the distribution
• No Auto-Execution: All installation methods require explicit user action

Contributing

When adding features to DashCA:

1. Test on multiple platforms before committing
2. Update this README with new features
3. Add relevant sections to troubleshooting guide
4. Update CLAUDE.md if deployment process changes
5. Ensure backward compatibility with existing certificates

Resources

• Caddy PKI Documentation: https://caddyserver.com/docs/caddyfile/directives/tls#pki
• mobileconfig Format: https://developer.apple.com/documentation/devicemanagement
• OpenSSL Certificate Commands: https://www.openssl.org/docs/man1.1.1/man1/x509.html
• QR Code Library: https://github.com/davidshimjs/qrcodejs

---

Part of the DashCaddy project - Unified management for Docker + Caddy + DNS