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 Root CA certificate used by the local soundtouch-service.

1. Automated Migration (Hosts Method)

The soundtouch-service can automatically configure a device to use the /etc/hosts method:

curl -X POST "http://localhost:8000/setup/migrate/{deviceIP}?method=hosts"

This command will:

Connect to the device via SSH.
Update /etc/hosts to point Bose domains to the service IP.
Inject the auto-generated Root CA into the device's trust store (/etc/pki/tls/certs/ca-bundle.crt).
Reboot the device.

2. Managing the Root CA

The soundtouch-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 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:

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.
Capabilities: Grant the binary permission to bind to low ports: sudo setcap 'cap_net_bind_service=+ep' ./soundtouch-service.
Reverse Proxy: Use Nginx or Caddy as described below.

4. Reverse Proxy (Optional)

Generate a certificate for the Bose domains signed by your Root CA.
Configure Nginx to use this certificate and proxy requests to soundtouch-service.

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:

Copy ca.crt to the device:

scp data/certs/ca.crt root@{deviceIP}:/tmp/

Append it to the trust store on the device:
```
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.

4.6 KiB Raw Blame History