mirror of
https://github.com/gesellix/Bose-SoundTouch.git
synced 2026-08-24 14:47:23 +00:00
103 lines
4.6 KiB
Markdown
103 lines
4.6 KiB
Markdown
# HTTPS Setup & Custom CA Certificate
|
|
|
|
To use the `/etc/hosts` redirection method safely, SoundTouch devices must communicate over HTTPS. This requires the device to trust the AfterTouch Root CA certificate used by the local service.
|
|
|
|
## 1. Automated Migration (Hosts Method)
|
|
|
|
The `soundtouch-service` can automatically configure a device to use the `/etc/hosts` method:
|
|
|
|
```bash
|
|
curl -X POST "http://localhost:8000/setup/migrate/{deviceIP}?method=hosts"
|
|
```
|
|
|
|
This command will:
|
|
1. Connect to the device via SSH.
|
|
2. Update `/etc/hosts` to point Bose domains to the service IP.
|
|
3. Inject the auto-generated AfterTouch Root CA into the device's trust store (`/etc/pki/tls/certs/ca-bundle.crt`).
|
|
4. Reboot the device.
|
|
|
|
## 2. Managing the Root CA
|
|
|
|
The AfterTouch service automatically generates a Root CA when it first starts.
|
|
|
|
- **CA Certificate**: `data/certs/ca.crt`
|
|
- **CA Private Key**: `data/certs/ca.key`
|
|
|
|
### Downloading the CA Certificate
|
|
You can download the CA certificate for manual installation on other devices (like your phone or PC) from:
|
|
`http://<server-ip>:8000/setup/ca.crt`
|
|
|
|
### 3. Built-in HTTPS Support
|
|
|
|
The `soundtouch-service` now includes a built-in HTTPS listener. This simplifies the `/etc/hosts` redirection method by automatically presenting the correct certificates for Bose domains.
|
|
|
|
- **HTTPS Port**: Configurable via `HTTPS_PORT` environment variable (defaults to `8443`).
|
|
- **HTTPS Server URL**: Configurable via `HTTPS_SERVER_URL` (e.g., `https://mysoundtouch.local:8443`). If not set, the service attempts to guess it using the system hostname.
|
|
- **Domain Coverage**: Automatically presents a certificate for `streaming.bose.com`, `updates.bose.com`, `stats.bose.com`, `bmx.bose.com`, and `content.api.bose.io`.
|
|
- **Automatic Setup**: On first start, it generates a server certificate signed by your AfterTouch local Root CA.
|
|
|
|
#### TLS Security
|
|
|
|
The built-in HTTPS listener is configured to use modern and secure TLS settings while maintaining compatibility with SoundTouch devices (which support up to TLS 1.2 with OpenSSL 1.0.2).
|
|
|
|
- **Minimum TLS Version**: TLS 1.2
|
|
- **Preferred Cipher Suites**:
|
|
- `ECDHE-RSA-AES128-GCM-SHA256`
|
|
- `ECDHE-RSA-AES256-GCM-SHA384`
|
|
- `ECDHE-RSA-CHACHA20-POLY1305`
|
|
- `RSA-AES128-GCM-SHA256` (Legacy support)
|
|
- `RSA-AES256-GCM-SHA384` (Legacy support)
|
|
|
|
#### Binding to Port 443
|
|
SoundTouch devices expect HTTPS on the default port 443. Since binding to port 443 usually requires root privileges, you have two options:
|
|
|
|
1. **Port Forwarding (Recommended)**: Run the service on a high port (e.g., 8443) and use `iptables` or your firewall to forward traffic from 443 to 8443.
|
|
2. **Capabilities**: Grant the binary permission to bind to low ports: `sudo setcap 'cap_net_bind_service=+ep' ./soundtouch-service`.
|
|
3. **Reverse Proxy**: Use Nginx or Caddy as described below.
|
|
|
|
### 4. Reverse Proxy (Optional)
|
|
|
|
1. **Generate a certificate** for the Bose domains signed by your Root CA.
|
|
2. **Configure Nginx** to use this certificate and proxy requests to `soundtouch-service`.
|
|
|
|
```nginx
|
|
server {
|
|
listen 443 ssl;
|
|
server_name streaming.bose.com bmx.bose.com stats.bose.com updates.bose.com;
|
|
|
|
ssl_certificate /path/to/generated-cert.crt;
|
|
ssl_certificate_key /path/to/generated-cert.key;
|
|
|
|
# Secure TLS configuration (matches soundtouch-service defaults)
|
|
ssl_protocols TLSv1.2;
|
|
ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-CHACHA20-POLY1305:AES128-GCM-SHA256:AES256-GCM-SHA384';
|
|
|
|
location / {
|
|
proxy_pass http://localhost:8000;
|
|
proxy_set_header Host $host;
|
|
proxy_set_header X-Real-IP $remote_addr;
|
|
}
|
|
}
|
|
```
|
|
|
|
## 5. Manual CA Injection (Legacy/Manual)
|
|
|
|
If you prefer to inject the CA certificate manually:
|
|
|
|
1. Copy `ca.crt` to the device:
|
|
```bash
|
|
scp data/certs/ca.crt root@{deviceIP}:/tmp/
|
|
```
|
|
2. Append it to the trust store on the device:
|
|
```bash
|
|
ssh root@{deviceIP} "(rw || mount -o remount,rw /) && cat /tmp/ca.crt >> /etc/pki/tls/certs/ca-bundle.crt"
|
|
```
|
|
|
|
## 6. Verifying Connectivity
|
|
|
|
You can verify that your device can correctly reach the `soundtouch-service` over HTTPS using the management web UI.
|
|
|
|
In the **Migration Summary** for a device, you will find an **HTTPS Connection Test** section:
|
|
- **Test with Explicit CA.crt**: Uploads a temporary copy of the Root CA to the device and uses `curl --cacert` to verify the connection. Use this to verify your HTTPS setup *before* modifying the device's shared trust store.
|
|
- **Test with Shared Trust Store**: Uses the device's default trust store. Use this to verify that your CA injection was successful and the device now natively trusts your local server.
|