Sami
f61e85d9a7
Full codebase including API server (32 modules + routes), dashboard frontend, DashCA certificate distribution, installer script, and deployment skills.
282 lines
8.2 KiB
Markdown
282 lines
8.2 KiB
Markdown
# 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
|