diff --git a/README.md b/README.md index 0115b39..9508f71 100644 --- a/README.md +++ b/README.md @@ -1,37 +1,87 @@ # Certificate Management Tools -Automated certificate generation and signing tools for UCS CA. +Automated certificate generation and signing tools for UCS CA with intelligent system detection and deployment. + +## Features + +- 🔍 **Automatic System Detection** - Detects target system type (Proxmox, pfSense, TrueNAS, UCS) +- 🤖 **Automated Deployment** - Fully automated certificate installation for supported systems +- 💾 **Configuration Persistence** - Remembers your settings between runs +- 🔐 **Proper Certificate Extensions** - Generates certificates with correct serverAuth extensions +- 🎯 **Interactive & Scriptable** - Works both interactively and in automation scripts + +## Supported Systems + +| System | Detection | Deployment | Status | +|--------|-----------|------------|--------| +| **Proxmox VE** | ✅ Automatic | ✅ Fully Automated | Production Ready | +| **pfSense** | ✅ Automatic | ⚠️ Manual (Web UI) | Detected | +| **TrueNAS** | ✅ Automatic | ⚠️ Manual (Web UI) | Detected | +| **UCS** | ✅ Automatic | ⚠️ Manual | Detected | +| **Other/Unknown** | ⚠️ Generic | ⚠️ Manual | Basic Support | + +### Proxmox VE - Full Automation ✅ + +For Proxmox systems, the tool provides complete automation: +- Generates CSR on the Proxmox host +- Signs with UCS CA +- Automatically installs to `/etc/pve/local/pveproxy-ssl.{pem,key}` +- Creates timestamped backups of existing certificates +- Restarts `pveproxy` service +- Fully automated, zero manual steps required + +### Other Systems - Manual Deployment ⚠️ + +For pfSense, TrueNAS, and other systems: +- System type is detected automatically +- CSR is generated on the target host +- Certificate is signed with UCS CA +- Certificate and key are copied to `/tmp/` +- Manual installation required through web interface ## Tools -### 1. cert-manager.py (Interactive Mode) -The main interactive tool that handles the entire certificate lifecycle. +### 1. cert-manager.py (Interactive Mode) - **RECOMMENDED** +The main interactive tool that handles the entire certificate lifecycle with system detection. **Usage:** ```bash ./cert-manager.py ``` +**Workflow:** +1. Detects target system type automatically +2. Prompts for certificate details with smart defaults +3. Generates CSR on remote host with proper extensions +4. Signs certificate with UCS CA +5. Deploys automatically (Proxmox) or copies to target (others) + **Features:** -- Interactive prompts with default values -- Remembers last used values -- Generates CSR on remote host -- Signs certificate with UCS CA -- Optionally deploys certificate back to target host +- Interactive prompts with default values from previous runs +- Automatic system type detection +- Intelligent deployment based on system capabilities +- Configurable key length (default: 4096 bits) +- Remembers last used values for quick reuse ### 2. generate-csr.sh (Standalone) Generates a certificate signing request on a remote host. **Usage:** ```bash -./generate-csr.sh [country] [state] [locality] [org] [ou] +./generate-csr.sh [country] [state] [locality] [org] [ou] [key-bits] ``` **Example:** ```bash -./generate-csr.sh 192.168.1.100 server.example.com DE berlin berlin egonetix it +./generate-csr.sh 192.168.1.100 server.example.com DE berlin berlin egonetix it 4096 ``` +**Features:** +- Generates CSR with proper server authentication extensions +- Configurable RSA key length (2048, 4096, 8192 bits) +- Automatic Subject Alternative Names (SANs) +- Private key stays on target host (secure) + ### 3. sign-cert.sh (Standalone) Signs a certificate request with the UCS CA. @@ -45,30 +95,109 @@ Signs a certificate request with the UCS CA. ./sign-cert.sh server.req server 3650 ``` +### 4. detect-system.sh (Utility) +Detects the type of system on a remote host. + +**Usage:** +```bash +./detect-system.sh +``` + +**Returns:** `proxmox`, `pfsense`, `truenas`, `ucs`, or `unknown` + +### 5. deploy-proxmox.sh (Proxmox Deployment) +Automated certificate deployment for Proxmox VE. + +**Usage:** +```bash +./deploy-proxmox.sh +``` + +**What it does:** +- Backs up existing certificates with timestamp +- Installs new certificate and key +- Sets correct permissions (640) +- Restarts pveproxy service +- Provides access URL + ## Configuration The interactive tool stores default values in `~/.cert-manager-config.json`. -Default values: -- Country: DE -- State: berlin -- Locality: berlin -- Organization: egonetix -- Organizational Unit: it -- CA Server: 10.0.0.21 -- Validity: 3650 days (10 years) +**Default values:** +- Country: `DE` +- State: `berlin` +- Locality: `berlin` +- Organization: `egonetix` +- Organizational Unit: `it` +- CA Server: `10.0.0.21` +- Validity: `3650` days (10 years) +- Key Length: `4096` bits -## Workflow +**Modifying defaults:** +Run `./cert-manager.py` and answer "yes" when asked to modify default values. -1. Run `./cert-manager.py` -2. Enter target host (IP or hostname where certificate will be used) -3. Enter common name (FQDN for the certificate) -4. Review/modify certificate subject fields -5. Confirm and proceed -6. The tool will: - - Generate CSR on target host - - Sign it with UCS CA - - Optionally copy certificate back to target +## Interactive Workflow Example + +```bash +$ ./cert-manager.py + +============================================================ +Interactive Certificate Manager +============================================================ + +--- Certificate Details --- +Target Host (IP or hostname) [srv-wmw-host01]: 10.0.0.50 + +Detecting system type on 10.0.0.50... +✓ Detected: Proxmox VE + +Common Name (FQDN) [srv-wmw-host01.egonetix.lan]: pve-host02.egonetix.lan + +--- Certificate Subject (press Enter to use defaults) --- +Country (C) [DE]: +State/Province (ST) [berlin]: +Locality (L) [berlin]: +Organization (O) [egonetix]: +Organizational Unit (OU) [it]: +Validity (days) [3650]: +Key Length (bits) [4096]: + +============================================================ +Summary: +============================================================ +System Type: Proxmox VE +Target Host: 10.0.0.50 +Common Name: pve-host02.egonetix.lan +Country: DE +State: berlin +Locality: berlin +Organization: egonetix +Org Unit: it +Key Length: 4096 bits +Validity: 3650 days +CA Server: 10.0.0.21 +Output files: pve-host02.req, pve-host02-cert.pem +============================================================ + +Proceed with certificate generation? [Y/n]: + +[Generates CSR, signs, deploys automatically for Proxmox] + +✓ Access Proxmox at: https://10.0.0.50:8006 +``` + +## Certificate Details + +**Generated certificates include:** +- RSA keys (configurable: 2048, 4096, or 8192 bits) +- SHA-256 signature algorithm +- Subject Alternative Names (SANs) for all hostname variants +- Proper key usage extensions: + - `digitalSignature` + - `keyEncipherment` +- Extended key usage: + - `serverAuth` (TLS Web Server Authentication) ## Requirements @@ -76,9 +205,91 @@ Default values: - SSH access to UCS CA server (10.0.0.21) as root - OpenSSL on target host - Python 3.6+ for interactive tool +- Bash for shell scripts -## Notes +## Security Notes -- Private keys are generated and remain on the target host -- Certificate requests (.req) and signed certificates (-cert.pem) are stored locally -- The interactive tool remembers your last target host and common name for convenience +1. **Private keys remain on target hosts** - Never transmitted or stored locally +2. **Certificate backups** - Proxmox deployment creates timestamped backups +3. **Proper permissions** - Certificates are installed with correct file permissions +4. **CA access** - Only the signing operation requires CA access +5. **SSH security** - Uses BatchMode and secure connection options + +## Troubleshooting + +### System not detected correctly +```bash +# Manually check what system it is +./detect-system.sh + +# Verify SSH access +ssh root@ "uname -a" +``` + +### Certificate not trusted in browser +```bash +# Verify system CA is installed +ls -la /usr/local/share/ca-certificates/ucs-root-ca.crt + +# Update system CA certificates +sudo update-ca-certificates + +# For browsers using NSS (Firefox, Brave, Chrome): +certutil -d sql:$HOME/.pki/nssdb -L | grep -i ucs +``` + +### Proxmox deployment failed +```bash +# Check Proxmox certificate directory +ssh root@ "ls -la /etc/pve/local/pveproxy-ssl.*" + +# View pveproxy logs +ssh root@ "journalctl -u pveproxy -n 50" + +# Manually restart pveproxy +ssh root@ "systemctl restart pveproxy" +``` + +### Certificate expired +Certificates are valid for 10 years by default. To renew: +```bash +# Simply run the tool again with the same hostname +./cert-manager.py +# It will generate a new certificate with a fresh validity period +``` + +## File Locations + +**On local machine:** +- Certificate requests: `./.req` +- Signed certificates: `./-cert.pem` +- Configuration: `~/.cert-manager-config.json` + +**On target host:** +- Private keys: `/tmp/.key` +- Certificates: `/tmp/.crt` + +**On Proxmox hosts:** +- Certificate: `/etc/pve/local/pveproxy-ssl.pem` +- Private key: `/etc/pve/local/pveproxy-ssl.key` +- Backups: `/etc/pve/local/pveproxy-ssl.{pem,key}.bak.YYYYMMDD-HHMMSS` + +## Adding Support for New Systems + +To add automated deployment for a new system type: + +1. Update `detect-system.sh` with detection logic +2. Create `deploy-.sh` script +3. Add system to `SYSTEM_TYPES` in `cert-manager.py` +4. Test thoroughly +5. Update this README + +## Additional Resources + +- UCS Manual: https://docs.software-univention.de/ +- Certificate Management: https://docs.software-univention.de/manual.html#domain:certificates +- OpenSSL Documentation: https://www.openssl.org/docs/ + +## License + +Internal tool for egonetix infrastructure management.