setup_https.txt

################################################################################
#
#  Configuration Guide for moOde HTTPS mode
#
#  Version: 1.0 2024-01-11
#
#  (C) Tim Curtis 2023 http://moodeaudio.org
#
################################################################################

OVERVIEW

HTTPS mode is an experimental feature in moOde that enables secure communication
between the Browser and moOde/NGINX web server. This is achieved through use of
an automatically or manually generated security certificate (cert).

AUTOMATICALLY GENERATED (SELF_SIGNED)

This type of cert is automatically created and installed into NGINX web server
when HTTPS mode is turned on. The cert can be downloaded via the DOWNLOAD button
or Browser Export option and then a manual procedure is required to import the
cert into the Operating System (OS) certificate store. After this is done the
Browser will be able to establish secure HTTPS communication with moOde.

MANUALLY GENERATED

This type of cert is manually created and can be self-signed or signed by a
local Certificate Authority (CA) then manually installed into NGINX web server
via the UPLOAD and INSTALL buttons. A second manual procedure is used to import
the cert into the Operating System (OS) certificate Store. After this is done
the Browser will be able to establish secure HTTPS communication with moOde.

BASIC PROCEDURE (Desktop OS)

Below is a basic procedure for configuring HTTPS mode. The detailed steps for
importing the cert into the OS certificate store vary depending on the OS.

1. HTTPS mode on

a. Open System Config and scroll to the Security section
b. Set the Certificate type to "Automatic"
c. Turn HTTPS mode on
d. DOWNLOAD the cert
e. Install the downloaded cert into the OS certificate store and set its trust
   policy to "Always trust"
f. Reboot moOde
g. Refresh the Browser and a secure HTTPS connection should be established

2. HTTPS mode off

a. Open System Config and scroll to the Security section
b. Turn HTTPS mode OFF
c. Reboot
d. Open http://moode
e. A non-secure HTTP connection should be established

3. Changing the host name

If the host name is changed via System Config while HTTPS mode is on and the
Certificate type was set to "Automatic" a new self-signed cert will be generated
automatically and installed into NGINX web server during startup after reboot.

a. Refresh the Browser
b. Click the browser "Security warning" badge to view the cert
c. Navigate to an option that offers an "Export" button
d. Click the Export button
e. Select DER encoding format
f. Export/Download the cert
g. Install the downloaded cert into the OS certificate store and set its Trust
   policy to "Always trust"

BASIC PROCEDURE (Mobile OS)

*** Content TBD ***

DEVELOPER INFORMATION

The software components for the HTTPS mode feature are listed below.

PHP SESSION VARS

nginx_https_only
nginx_cert_type
nginx_hsts_policy

NGINX FILES

/etc/nginx/ssl.conf
/etc/nginx/dhparams.pem
/etc/nginx/sites/available/moode-http.conf
/etc/nginx/sites/available/moode-https.conf

MOODE FILES

/var/www/sys-config.php
/var/www/templates/sys-config.html
/var/www/daemon/worker.php
/var/www/util/gen-cert.sh
/var/www/setup_https.txt

AUTOMATICALLY GENERATED CERTIFICATE (SELF_SIGNED)

Generated by:
/var/www/util/gen-cert.sh

Certificate files:
/etc/ssl/certs/moode.crt
/etc/ssl/private/moode.key

Certificate attribute summary:
Bits            = 2048
Common name     = $HOSTNAME.local
Key usage       = digitalSignature, keyEncipherment, nonRepudiation
Key usage ext   = clientAuth, serverAuth
DNS.1           = $HOSTNAME.local
DNS.2           = $HOSTNAME
IP.1            = 172.24.1.1 (Access point mode)

################################################################################
#  Post questions regarding this guide to http://moodeaudio.org/forum
################################################################################