Merge wip/236-tls-server: TLS for the central server — https data server (8443) and MQTT over TLS (8883), pinned or CA trust, no plain network listener with TLS on, ecce-remote-setup --tls (#236)

Includes the TLS client socket (wip/236-tls-client). Verified on the merged
tree: tls_client, tls_server (23 checks), filedsi, csh2sh, session_end.py
(three deployment modes, 0 failures), tests/teaching (0 failing, 1582 s).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01PFPK14wBcLD1s4dYUowpP4

Author: andy

CMakeLists.txt

@@ -226,6 +226,8 @@ ecce_library(eccetdat
 # --- src/dsm -> 5 separate libraries, matching the old per-subdir mapping ---
 ecce_library(eccexml    src/dsm/chemistry src/dsm/xml)
 ecce_library(eccecipc   src/dsm/cipc)
+find_package(OpenSSL REQUIRED)
+target_link_libraries(eccecipc PUBLIC OpenSSL::SSL OpenSSL::Crypto)
 ecce_library(eccedav    src/dsm/dav)
 ecce_library(eccedsi    src/dsm/edsiimpl)
 ecce_library(eccefaces  src/dsm/faces)
@@ -1350,9 +1352,12 @@ set(CPACK_DEBIAN_PACKAGE_SHLIBDEPS ON)
 # perl: the whole job pipeline (ai.<code>, *.expt, gensub,
 # eccejobmonitor, processmachine) is Perl, and Getopt::Std and
 # Sys::Hostname are in perl-modules, which perl-base alone lacks.
+# openssl: ecce-remote-setup --tls makes and checks certificates with the
+# command line tool (#236); the libraries come from shlibdeps. Apache's
+# mod_ssl is in the apache2 package on Debian but its own package on RPM.
 # xterm: editing an input file with the default editor (vi) opens it in
 # an xterm (UserEditor.C).
-set(CPACK_DEBIAN_PACKAGE_DEPENDS "apache2, apache2-utils, python3-wxgtk4.0, mosquitto, libaprutil1, perl, xterm")
+set(CPACK_DEBIAN_PACKAGE_DEPENDS "apache2, apache2-utils, python3-wxgtk4.0, mosquitto, libaprutil1, perl, xterm, openssl")
 # NWChem is a real Debian package (confirmed working: /usr/bin/nwchem,
 # symlinked to nwchem.openmpi by the package itself) and the auto-register-
 # this-machine flow (RunMgmt::registerLocalMachine()) defaults new machine
@@ -1407,7 +1412,7 @@ if(RPMBUILD_EXECUTABLE)
   set(CPACK_RPM_PACKAGE_LICENSE "ECL-2.0")
   set(CPACK_RPM_PACKAGE_GROUP "Applications/Engineering")
   set(CPACK_RPM_PACKAGE_URL "https://github.com/FriendsofECCE/ECCE")
-  set(CPACK_RPM_PACKAGE_REQUIRES "httpd, httpd-tools, python3-wxpython4, perl, xterm, mosquitto, apr-util${_coin_rpm}")
+  set(CPACK_RPM_PACKAGE_REQUIRES "httpd, httpd-tools, mod_ssl, openssl, python3-wxpython4, perl, xterm, mosquitto, apr-util${_coin_rpm}")
   set(CPACK_RPM_PACKAGE_SUGGESTS "nwchem, openssh-clients, firefox")
   set(CPACK_RPM_FILE_NAME RPM-DEFAULT)
   #  /opt/ecce is ours, but /opt itself is owned by filesystem(5).  Without
@@ -1551,7 +1556,7 @@ if(ECCE_SPLIT_PACKAGES)
   # -remote client only needs the library, and the package's own system
   # service is of no use to it.
   set(CPACK_DEBIAN_CLIENT_PACKAGE_DEPENDS
-      "python3-wxgtk4.0, perl, xterm, libmosquitto1, curl")
+      "python3-wxgtk4.0, perl, xterm, libmosquitto1, curl, openssl")
   # A client on the SAME machine as a server benefits from it (the
   # default "everything on one box" case this project still ships), but
   # a client of an already-central server (#167/#138 -- the teaching
@@ -1574,7 +1579,7 @@ if(ECCE_SPLIT_PACKAGES)
   # (launchjob, eccejobmaster, eccejobstore) ship in ecce-client, and a server
   # needs them, so the server brings the client -- GUI libraries included,
   # unused on a headless box. Accepted rather than a third package.
-  set(CPACK_DEBIAN_SERVER_PACKAGE_DEPENDS "apache2, apache2-utils, mosquitto, libaprutil1, ecce-client (= ${_ecce_deb_version})")
+  set(CPACK_DEBIAN_SERVER_PACKAGE_DEPENDS "apache2, apache2-utils, mosquitto, libaprutil1, openssl, ecce-client (= ${_ecce_deb_version})")
   set(CPACK_DEBIAN_SERVER_PACKAGE_BREAKS "ecce (<< ${ECCE_MONOLITHIC_BREAK_VERSION})")
   set(CPACK_DEBIAN_SERVER_PACKAGE_REPLACES "ecce (<< ${ECCE_MONOLITHIC_BREAK_VERSION})")
 
@@ -1587,7 +1592,7 @@ if(ECCE_SPLIT_PACKAGES)
     set(CPACK_RPM_CLIENT_FILE_NAME RPM-DEFAULT)
     # mosquitto provides both the library and the broker on RPM distros.
     set(CPACK_RPM_CLIENT_PACKAGE_REQUIRES
-        "python3-wxpython4, perl, xterm, mosquitto, curl${_coin_rpm}")
+        "python3-wxpython4, perl, xterm, mosquitto, curl, openssl${_coin_rpm}")
     set(CPACK_RPM_CLIENT_PACKAGE_SUGGESTS
         "ecce-server, nwchem, openssh-clients, firefox")
     # RPM has no direct Breaks/Replaces pair; Obsoletes+Provides is the
@@ -1600,7 +1605,7 @@ if(ECCE_SPLIT_PACKAGES)
     set(CPACK_RPM_CLIENT_PACKAGE_CONFLICTS "ecce < ${ECCE_MONOLITHIC_BREAK_VERSION}")
     set(CPACK_RPM_SERVER_PACKAGE_NAME "ecce-server")
     set(CPACK_RPM_SERVER_FILE_NAME RPM-DEFAULT)
-    set(CPACK_RPM_SERVER_PACKAGE_REQUIRES "httpd, httpd-tools, mosquitto, apr-util, ecce-client = ${_ecce_deb_version}")
+    set(CPACK_RPM_SERVER_PACKAGE_REQUIRES "httpd, httpd-tools, mod_ssl, openssl, mosquitto, apr-util, ecce-client = ${_ecce_deb_version}")
     set(CPACK_RPM_SERVER_PACKAGE_OBSOLETES "ecce < ${ECCE_MONOLITHIC_BREAK_VERSION}")
     set(CPACK_RPM_SERVER_PACKAGE_CONFLICTS "ecce < ${ECCE_MONOLITHIC_BREAK_VERSION}")
     set(CPACK_RPM_EXCLUDE_FROM_AUTO_FILELIST_ADDITION "/opt")
@@ -1682,6 +1687,30 @@ if(TARGET ecce_users_auth)
   set_tests_properties(mqtt-auth-plugin PROPERTIES TIMEOUT 120 SKIP_RETURN_CODE 77)
 endif()
 set_tests_properties(mqtt mqtt-auth PROPERTIES TIMEOUT 120 SKIP_RETURN_CODE 77)
+
+# tests/tls -- https data-server client (#236): pinned certificate, CA mode
+# with host-name check, certificate rejection, no fallback to plain http.
+# Needs python3 and the openssl command line; SKIPs (77) without them.
+add_executable(tls_client_test tests/tls/tls_client_test.C)
+target_include_directories(tls_client_test PRIVATE ${XercesC_INCLUDE_DIRS})
+target_link_libraries(tls_client_test PRIVATE
+  eccedsi eccedav eccecipc eccefaces eccexml eccetdat ecceutil ${XercesC_LIBRARIES})
+add_test(NAME tls_client
+         COMMAND ${PYTHON3_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/tls/run_tests.py
+                 $<TARGET_FILE:tls_client_test> ${CMAKE_BINARY_DIR}/tls-test)
+set_tests_properties(tls_client PROPERTIES TIMEOUT 120 SKIP_RETURN_CODE 77)
+
+# The central server over TLS (#236): the real data server and broker scripts
+# on loopback with a fresh certificate, then the clients with and without
+# the right pin.
+add_executable(tls_broker_test tests/tls/tls_broker_test.C)
+target_include_directories(tls_broker_test PRIVATE ${XercesC_INCLUDE_DIRS})
+target_link_libraries(tls_broker_test PRIVATE ecceutil ${XercesC_LIBRARIES})
+add_test(NAME tls_server
+         COMMAND ${PYTHON3_EXECUTABLE} ${CMAKE_SOURCE_DIR}/tests/tls/server_tls.py
+                 $<TARGET_FILE:tls_client_test> $<TARGET_FILE:tls_broker_test>
+                 ${CMAKE_BINARY_DIR} ${CMAKE_BINARY_DIR}/tls-server-test)
+set_tests_properties(tls_server PROPERTIES TIMEOUT 300 SKIP_RETURN_CODE 77)
 if(PYTHON3_EXECUTABLE)
   add_test(NAME parsers
            COMMAND ${PYTHON3_EXECUTABLE}

GETTING_STARTED.md

@@ -407,10 +407,13 @@ On a TCP broker (modes 2 and 3) no anonymous client is accepted, and an
 account may publish and subscribe only below `ecce/<its name>/` (plus
 hearing that a machine registration changed). One user therefore cannot
 act in another's name, for example by cancelling that user's jobs. The
-rules are `server/mosquitto.acl`. The data server still speaks plain
-HTTP and the broker's password is sent unencrypted too (#138): keep both
-ports on a trusted network or firewall them. The accounts keep users
-apart; they are not a defence against an untrusted network.
+rules are `server/mosquitto.acl`. Unless TLS is switched on (mode 2,
+below) the data server speaks plain HTTP and the broker's password is
+sent unencrypted too (#138): keep both ports on a trusted network or
+firewall them. The accounts keep users apart; they are not a defence
+against an untrusted network, and neither is TLS here: it keeps
+passwords and data off the wire, and is no security product.
+Mode 3 has no TLS yet.
 
 A client stopping never stops a central or shared broker. Which broker a
 quit may stop is decided only by what the admin declared, never by
@@ -483,6 +486,43 @@ client after the admin changes that list (#188). It writes only the data server'
 client finds the broker on the same host, port 8088 (set `ECCE_BROKER_PORT`
 in the client's environment if the server uses another).
 
+##### TLS for the central server (optional)
+
+Off by default. On the server, as the account that runs it:
+
+```
+ecce-remote-setup --server all --tls     # makes a 10-year self-signed certificate
+ecce-dataserver-stop; ecce-gateway-stop; ecce-dataserver-start && ecce-gateway-start
+```
+
+The data server then serves HTTPS on port 8443
+(`ECCE_DATASERVER_TLS_PORT`) and the broker TLS on port 8883
+(`ECCE_BROKER_TLS_PORT`). The plain ports (8096, 8088) accept connections
+from the server machine itself only, so open 8443 and 8883 in the
+firewall, not those. The certificate and key are in `~/.ECCE/tls/`
+(`--new-cert` replaces them, `--cert F --key F` installs your own). Give
+every client installation `~/.ECCE/tls/server.pem`, and on each client, as
+root:
+
+```
+sudo ecce-remote-setup <server-host> --tls --pin server.pem
+```
+
+That client then accepts only this exact certificate and refuses any
+other; it never falls back to plain HTTP or an unencrypted broker, and
+reports a certificate that does not match. The installed copy is
+`/opt/ecce/siteconfig/RemoteServer/server.pem`; a per-user override does
+not exist. `--fetch-pin` takes the certificate from the running server
+instead and prints its fingerprint to compare with the one the server's
+administrator reads out (`ecce-remote-setup --server` shows it).
+
+A certificate from Let's Encrypt or the university's CA works too, but is
+only documented here: pass its full chain and key as `--cert` and `--key`
+on the server (renewed certificates need the same command and a restart),
+and set the clients up with `--tls --system-ca`, which checks the host
+name against the system's CA list and installs no pin. Reach the server by
+the name in the certificate.
+
 ##### Changing the site settings from a client
 
 An administrator can edit the server's site machine list from a client

data/client/config/EDSI

@@ -11,6 +11,7 @@ UNKNOWN: %s unrecognized error.
 # Client side status codes
 CLIENT_ERROR: The application is unable to access the data server
 SERVER_NOT_FOUND: Server or server port is not available. %s 
+CERTIFICATE_REJECTED: The data server's certificate was rejected. Contact the ECCE administrator. %s
 
 # Different implementations of AuthEventListener may choose to abort
 # after a certain number of authentication attempts.

docs/claude/services/https-data-server-client.md

@@ -0,0 +1,25 @@
+---
+type: rule
+title: "The data-server client speaks TLS only when the URL says https, and never falls back"
+area: services
+section: "Pitfalls"
+paths: ["src/dsm/cipc/CTLSSocket.C", "src/dsm/cipc/CHTTPConnection.C", "src/dsm/dav/EcceDAVClient.C", "tests/tls/run_tests.py"]
+issues: [236]
+---
+**`https://` selects `ipc::CTLSClientSocket` (OpenSSL); `http://` is the
+unchanged plain socket. There is no fallback from one to the other.**
+- Trust: if `$ECCE_HOME/siteconfig/RemoteServer/server.pem` exists it is the
+  only trust anchor and the presented certificate must be identical to it
+  (host name unchecked). A pin file that exists but cannot be read is an
+  error, not a reason to use the system store. Without the file the system
+  store and host-name verification apply (CA mode).
+- A rejected certificate gives `EcceDAVStatus::CERTIFICATE_REJECTED` (EDSI
+  message `CERTIFICATE_REJECTED`); other TLS failures are `UNABLE_TO_CONNECT`.
+- `poll()` must check `SSL_pending()` first, and a readable fd is confirmed
+  by a non-blocking `SSL_peek` (TLS 1.3 tickets make the fd readable with no
+  application data).
+- The TLS socket cannot be copied; a copied `CHTTPConnection` that held a TLS
+  session starts disconnected and re-verifies on `connect()`.
+- https defaults to port 443, and the `Host` header omits the port only for
+  the scheme's default.
+- `ctest -R tls_client` covers pinned, CA, mismatch and no-fallback cases.

docs/claude/services/index.md

@@ -40,6 +40,8 @@ what the deployment mode needs (GETTING_STARTED, "Deployment modes"):
 
 - [TCP broker accounts are the data server logins](broker-accounts-are-the-data-server-logins.md)
 - [`ecce_auth_changed` carries no password](auth-changed-carries-no-password.md)
+- [The data-server client speaks TLS only for https URLs, never falls back](https-data-server-client.md)
+- [Central-server TLS: ports, loopback, what must stay in step](tls-central-server.md)
 - [Per-session state is keyed by the session id, and the "is it already running?" checks must be too](per-user-service-state-is-keyed-by.md)
 - [A calculation can live in any local folder, not only in a data store](calculations-in-any-local-folder.md)
 - [Waiting for login: a lost monitor parks the job, session start catches it up](waiting-for-login.md)

docs/claude/services/tls-central-server.md

@@ -0,0 +1,33 @@
+---
+type: rule
+title: "Central-server TLS: ports, who is on loopback, and what must stay in step"
+area: services
+section: "Pitfalls"
+paths: ["packaging/dataserver/ecce-remote-setup", "packaging/dataserver/ecce-dataserver-start", "packaging/dataserver/httpd.conf.ecce", "packaging/gateway/ecce-gateway-start", "src/util/jms/MqttLink.C", "tests/tls/server_tls.py"]
+issues: [236]
+---
+**TLS is opt-in per server (`ecce-remote-setup --server --tls`) and per client
+(`--tls --pin|--fetch-pin|--system-ca`); nothing detects it and nothing falls back.**
+- Server state is `~/.ECCE/tls/{server.pem,server.key,enabled}`, shared by the
+  data server and the broker (not under `~/.ECCE/dataserver`, which is
+  Apache's ServerRoot). `enabled` is what both start scripts read.
+- With TLS on, the plain ports (8096, 8088) are bound to 127.0.0.1/::1 only
+  and the TLS ports (8443, 8883) go on the listen setting's addresses *and*
+  loopback. A wildcard `Listen 8443` cannot be combined with
+  `127.0.0.1:8443` (address in use), so `all` gets the wildcard alone.
+- The client learns TLS from the `https://` URL in `RemoteServer/DataServers`;
+  `ecce-gateway-start` takes the broker's port (8883) and the
+  `tls=1`/`cafile=`/`pinned=1` keys of the broker file from it. The pin is
+  `siteconfig/RemoteServer/server.pem`; without it the system CA directory
+  and host-name check apply.
+- Pinned mode checks the chain against the one certificate and ignores the
+  host name (`mosquitto_tls_insecure_set`, curl `--insecure
+  --pinnedpubkey`): never use curl `--insecure` without the pin.
+- A failed handshake reaches `MqttLink` only as a libmosquitto log line
+  (`onLog`), not a CONNACK; the refusal text starts with `TLS:`.
+- `ecce-remote-setup --tls` probes the server and writes nothing if the
+  certificate is not trusted (curl exit 90/60/35); only an unreachable
+  server (7/28) is a warning.
+- Mode 3 (`siteconfig/SharedBroker`) has no TLS.
+- `ctest -R tls_server` runs the whole thing on loopback; it needs
+  mod_ssl and, for the network-address checks, a non-loopback IPv4 address.

include/dsm/CHTTPConnection.H

@@ -45,7 +45,12 @@ public :
   virtual bool connect(
     const string_type& host,
     port_type          port  =  HTTPDefPort,
-    const string_type& proxy = "");
+    const string_type& proxy = "",
+    bool               secure = false);  // true: TLS (https), never plain
+
+  // After a failed connect(): was the server certificate rejected?
+  bool certificateRejected(void) const { return certRejected_; }
+  const string_type& connectError(void) const { return connectError_; }
 
   // Did the connection to the server die?
   virtual bool deadConnection(void) const
@@ -128,6 +133,9 @@ protected :
                   proxy_;             // proxy server ("" if no proxy)
   port_type       port_;              // server port
   socket_type     *server_;           // client socket to server
+  bool            secure_;            // TLS (https)
+  bool            certRejected_;      // last connect() failed on certificate
+  string_type     connectError_;      // last connect() failure text
 
 private :
 

include/dsm/CTLSSocket.H

@@ -0,0 +1,64 @@
+// CTLSSocket.H -- TLS client socket (OpenSSL) for the https data server.
+//
+// Trust: if $ECCE_HOME/siteconfig/RemoteServer/server.pem exists, that
+// certificate is the only trust anchor and the presented certificate must be
+// identical to it (host name is not checked, so IP addresses and aliases
+// work).  Otherwise the system store is used and the host name is verified.
+// There is no mode in which verification is skipped.
+
+#if !defined( __CTLSSOCKET_H )
+#define __CTLSSOCKET_H
+
+#include <string>
+#include "dsm/CSocket.H"
+
+typedef struct ssl_ctx_st SSL_CTX;
+typedef struct ssl_st     SSL;
+
+namespace ipc {
+
+class CTLSError : public CSocketError
+{
+public :
+  // certificate = true when the server's certificate was rejected
+  CTLSError(const std::string& msg, bool certificate)
+    : CSocketError(CreateError), msg_(msg), cert_(certificate) {}
+  virtual ~CTLSError(void) {}
+
+  bool certificateRejected(void) const { return cert_; }
+  virtual string_type message(void) const { return msg_; }
+
+private :
+  std::string msg_;
+  bool        cert_;
+};
+
+class CTLSClientSocket : public CClientSocket
+{
+public :
+
+  // Connect, handshake and verify.  Throws CSocketError (TCP) or CTLSError.
+  CTLSClientSocket(const string_type& host, port_type port);
+
+  // The SSL session belongs to exactly one socket.
+  CTLSClientSocket(const CTLSClientSocket&)              = delete;
+  CTLSClientSocket& operator = (const CTLSClientSocket&) = delete;
+
+  virtual ~CTLSClientSocket(void);
+
+  virtual bool poll(size_type seconds = 0, size_type microseconds = 0);
+  virtual size_type receive(void * buff, size_type nbytes, int flags = 0);
+  virtual size_type send(const string_type&);
+  virtual size_type send(const void * buff, size_type nbytes);
+
+  // Path of the pinned certificate, or "" when the system store applies.
+  static string_type pinnedCertPath(void);
+
+private :
+  SSL_CTX * ctx_;
+  SSL     * ssl_;
+};
+
+} // namespace ipc
+
+#endif

include/dsm/EcceDAVStatus.H

@@ -76,7 +76,8 @@ public:
     UNABLE_TO_COMPLETE_REQUEST,
     UNABLE_TO_SEND_REQUEST,
     UNABLE_TO_GET_RESPONSE,
-    INTERRUPTED
+    INTERRUPTED,
+    CERTIFICATE_REJECTED    // https: server certificate failed verification
   };
 
   static string text(int key);

include/util/MqttLink.H

@@ -57,6 +57,10 @@ struct MqttConfig {
   std::string socket;      // Unix-socket broker, or
   std::string host;        // host + port
   int port = 1883;
+  bool tls = false;        // tls=1: the broker speaks TLS on host:port
+  std::string cafile;      // trust anchor: the pinned server certificate, or
+  std::string capath;      // the system's CA directory (no pin)
+  bool pinned = false;     // pinned=1: the exact certificate is the anchor
   std::string user;        // topic user
   std::string sessionKey;  // Ecce::sessionKey(): <host>_<session id>
 
@@ -168,6 +172,7 @@ private:
   ~MqttLink();
   static void onConnect(mosquitto*, void*, int rc, int flags,
                         const mqtt5__property*);
+  static void onLog(mosquitto*, void*, int level, const char* str);
   static void onDisconnect(mosquitto*, void*, int rc, const mqtt5__property*);
   static void onMessage(mosquitto*, void*, const mosquitto_message*,
                         const mqtt5__property*);