Sync DNS2 production changes - removed obsolete test suite and refactored structure
This commit is contained in:
Krystie
281
dashcaddy-api/ca/README.md
Normal file
281
dashcaddy-api/ca/README.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```powershell
|
||||
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:**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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):
|
||||
```powershell
|
||||
$ExpectedFingerprint = "NEW:FIN:GER:PRINT:HERE"
|
||||
```
|
||||
|
||||
**install.sh** (line 13):
|
||||
```bash
|
||||
EXPECTED_FP="NEW:FIN:GER:PRINT:HERE"
|
||||
```
|
||||
|
||||
### 3. Deploy to Production
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
Reference in New Issue
Block a user