saltcorn-samba 0.3.10 → 0.3.11

package/CHANGELOG.md

@@ -4,6 +4,64 @@ All notable changes to `saltcorn-samba` are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.3.11] – 2026-07-05
+
+### Fixed – **Worker-Crash / 502 durch DES-ECB auf Node 17+ / OpenSSL 3**
+
+Symptom nach dem 0.3.10-Update:
+
+```
+node:internal/crypto/cipher:117
+Error: error:0308010C:digital envelope routines::unsupported
+    at Cipheriv.createCipherBase ...
+    at .../@marsaud/smb2/node_modules/ntlm/lib/smbhash.js:46
+code: 'ERR_OSSL_EVP_UNSUPPORTED'
+worker died
+```
+
+Auf der Config-Seite dann: **„Antwort war kein JSON (HTTP 502)“**.
+
+**Ursache:** `@marsaud/smb2` benutzt über das transitive Paket `ntlm` den
+Cipher **DES-ECB** zur Berechnung der LM/NTLM-Hashes. Node.js ab Version 17
+ist gegen OpenSSL 3 gebaut, das DES-ECB standardmäßig blockiert. Der
+`createCipheriv("des-ecb", ...)`-Aufruf wirft dann synchron
+`ERR_OSSL_EVP_UNSUPPORTED`. Weil der Fehler synchron aus tiefen Callback-
+Aufrufen kommt, tötet er den Saltcorn-Worker-Prozess → der Reverse-Proxy
+liefert 502 → die Route liefert kein JSON.
+
+**Fixes in diesem Release:**
+
+1. **Präventiver Check in `smb-client.js`:** Beim ersten Aufbau eines
+   SMB-Clients wird geprüft, ob `crypto.createCipheriv("des-ecb", ...)`
+   funktioniert. Wenn nicht, wird eine saubere, ausführliche deutsche
+   Fehlermeldung mit Lieferanleitung geworfen (`E_LEGACY_CRYPTO`) — der
+   fehlerhafte NTLM-Code wird gar nicht erst betreten, der Worker überlebt.
+2. **`/sambatest`-Route:** Der Check läuft zusätzlich explizit **vor**
+   dem `withClient`-Aufruf und liefert JSON mit `code: "E_LEGACY_CRYPTO"`,
+   `error`, `hint`, `node_version` und `openssl_version` — damit steht der
+   Diagnose-Grund direkt in der UI, nicht im Server-Log.
+3. **Fehler-Mapping erweitert:** Falls der Crash doch mal aus einem
+   anderen Pfad kommt (z. B. spätere Reconnect-Versuche), erkennt die
+   Catch-Logik jetzt auch `ERR_OSSL_EVP_UNSUPPORTED`,
+   `digital envelope routines` und `unsupported` und liefert einen
+   verständlichen Hinweis.
+4. **README:** Neuer Abschnitt „Troubleshooting“ mit Setup-Rezepten für
+   `NODE_OPTIONS=--openssl-legacy-provider` (Umgebungsvariable, systemd,
+   Docker/Compose, PM2, direkter Aufruf) plus Tabelle mit den häufigsten
+   Verbindungsfehlern und Diagnose-Kommandos.
+
+### Notes
+- Das Plugin ändert keinen Node-Startparameter selbst — das können wir aus
+  Sicherheits- und Prozessgründen nicht (Node-Flags müssen beim Prozess-
+  Start gesetzt werden). Der Fix ist eine saubere Fehlererkennung mit
+  Lösungsanleitung.
+- Sobald Saltcorn mit `NODE_OPTIONS=--openssl-legacy-provider` läuft,
+  funktionieren Verbindungstest und alle SMB-Operationen ohne weitere
+  Anpassung.
+- **Roadmap:** Migration weg von `@marsaud/smb2` (letzter Release 2020) hin
+  zu einer aktiv gepflegten SMB-Client-Bibliothek, damit das
+  Legacy-Provider-Flag nicht mehr nötig ist.
+
 ## [0.3.10] – 2026-07-05
 
 ### Fixed – **DNS-Fehler: `getaddrinfo ENOTFOUND "host:445"`**

package/README.md

@@ -331,6 +331,95 @@ Ab dann taucht das Plugin im Plugins-Store jeder Saltcorn-Instanz auf.
 
 ---
 
+## Troubleshooting
+
+### `ERR_OSSL_EVP_UNSUPPORTED` / `digital envelope routines::unsupported` / Worker stirbt / 502 Bad Gateway
+
+Die Bibliothek `@marsaud/smb2` benutzt intern (im transitiven Paket `ntlm`)
+den Cipher **DES-ECB**, um die NTLM/LM-Hashes zu berechnen. Ab **Node.js 17**
+mit **OpenSSL 3** ist DES-ECB standardmäßig deaktiviert. Der Aufruf wirft
+dann synchron:
+
+```
+Error: error:0308010C:digital envelope routines::unsupported
+code: 'ERR_OSSL_EVP_UNSUPPORTED'
+```
+
+Weil der Fehler synchron aus dem NTLM-Modul kommt, **tötet er den
+Saltcorn-Worker-Prozess**. Der davor sitzende Reverse-Proxy meldet dann
+`502 Bad Gateway` und die Antwort ist kein JSON — was auf der Config-Seite
+als "Antwort war kein JSON (HTTP 502)" erscheint.
+
+**Lösung:** Saltcorn mit dem Node-Flag `--openssl-legacy-provider` starten.
+Je nach Setup:
+
+**(a) Umgebungsvariable (empfohlen, wirkt auf jeden Node-Aufruf)**
+
+```bash
+export NODE_OPTIONS="--openssl-legacy-provider"
+saltcorn serve
+```
+
+**(b) systemd-Unit** (`/etc/systemd/system/saltcorn.service`)
+
+```ini
+[Service]
+Environment=NODE_OPTIONS=--openssl-legacy-provider
+ExecStart=/usr/bin/saltcorn serve
+```
+
+Danach:
+```bash
+sudo systemctl daemon-reload
+sudo systemctl restart saltcorn
+```
+
+**(c) Docker / docker-compose**
+
+```yaml
+services:
+  saltcorn:
+    image: saltcorn/saltcorn:latest
+    environment:
+      NODE_OPTIONS: "--openssl-legacy-provider"
+```
+
+**(d) PM2**
+
+```bash
+pm2 delete saltcorn
+NODE_OPTIONS="--openssl-legacy-provider" pm2 start saltcorn -- serve
+pm2 save
+```
+
+**(e) Direkter Aufruf**
+
+```bash
+node --openssl-legacy-provider $(which saltcorn) serve
+```
+
+Nach dem Neustart im Config-Dialog erneut auf „Verbindung jetzt testen“
+klicken — die Fehlermeldung sollte weg sein.
+
+> **Hinweis zur Sicherheit:** `--openssl-legacy-provider` reaktiviert die
+> alten Cipher für den gesamten Node-Prozess. Das ist für NTLM-Auth gegen
+> Samba akzeptabel (der Cipher wird nur zur Hash-Berechnung genutzt, nicht
+> für den Transport), aber ein Grund, mittelfristig auf eine gepflegte
+> SMB-Client-Bibliothek zu wechseln — siehe Roadmap.
+
+### Weitere häufige Fehler
+
+| Symptom | Ursache | Lösung |
+|---|---|---|
+| `getaddrinfo ENOTFOUND host:445` | Bis v0.3.9 wurde der Port in den UNC-Pfad geschrieben | Update auf **v0.3.10+** |
+| `ECONNREFUSED :445` | SMB-Dienst läuft nicht oder Firewall blockt Port 445 | `nc -vz <server> 445` vom Saltcorn-Host testen |
+| `ETIMEDOUT` | Kein Netzwerkpfad (VLAN/Docker-Bridge/VPN) | Vom Saltcorn-Container aus `ping` + `nc -vz` prüfen |
+| `STATUS_LOGON_FAILURE` | User/Passwort/Domain falsch | Zugangsdaten prüfen. Moderne Samba-Server erlauben keine leeren Passwörter |
+| `STATUS_BAD_NETWORK_NAME` | Share existiert nicht oder Schreibweise falsch | `smbclient -L //server -U user` zur Kontrolle |
+| Nur SMBv1 verfügbar | Server bietet SMB2/3 nicht an | In `smb.conf`: `min protocol = SMB2` |
+
+---
+
 ## Bekannte Grenzen
 
 - Dateien werden komplett gepuffert (`readFile` / `writeFile`). Für

package/index.js

@@ -47,6 +47,8 @@ const {
   mimeFromName,
   sanitizeRelativePath,
   sanitizeFilename,
+  checkLegacyCryptoAvailable,
+  legacyCryptoErrorMessage,
 } = require("./smb-client");
 const treeView = require("./tree-view");
 const fileManagerView = require("./filemanager-view");
@@ -747,6 +749,33 @@ code{background:#f4f4f4;padding:2px 6px;border-radius:3px;word-break:break-all}<
       if (!testCfg.server) return jsonError(res, 400, "Please enter a Server (hostname or IP).");
       if (!testCfg.share) return jsonError(res, 400, "Please enter a Share name.");
 
+      // Vor jedem echten SMB-Aufruf: Node/OpenSSL-Legacy-Cipher-Check.
+      // Falls DES-ECB nicht verfügbar ist (Node 17+ / OpenSSL 3 ohne
+      // --openssl-legacy-provider), übergeben wir gar nicht erst an ntlm,
+      // sonst crasht der Worker synchron und der Proxy meldet 502.
+      const cc = checkLegacyCryptoAvailable();
+      if (!cc.ok) {
+        return res.status(200).json({
+          ok: false,
+          error: legacyCryptoErrorMessage(cc.message),
+          code: "E_LEGACY_CRYPTO",
+          hint:
+            "Saltcorn mit --openssl-legacy-provider starten. " +
+            "Am einfachsten: die Umgebungsvariable NODE_OPTIONS=--openssl-legacy-provider setzen und Saltcorn neu starten. " +
+            "Details und Beispiele für systemd / Docker / PM2 stehen in der README des Plugins.",
+          attempted: {
+            server: testCfg.server,
+            share: testCfg.share,
+            port: testCfg.port,
+            domain: testCfg.domain,
+            username: testCfg.username || "(anonymous)",
+            base_path: testCfg.base_path || "(share root)",
+          },
+          node_version: process.version,
+          openssl_version: (process.versions && process.versions.openssl) || null,
+        });
+      }
+
       const started = Date.now();
       try {
         const listing = await withClient(testCfg, async (client) => {
@@ -798,6 +827,8 @@ code{background:#f4f4f4;padding:2px 6px;border-radius:3px;word-break:break-all}<
           hint = "The server may be offering only SMBv1 which this plugin does not support. Enable SMB2 / SMB3 on the Samba server (min protocol = SMB2 in smb.conf).";
         else if (m.includes("traversal") || m.includes("path"))
           hint = "The Base path could not be validated. It must be a relative sub-directory (e.g. 'projects/2026'), never start with / or \\, and must not contain '..'.";
+        else if (code === "ERR_OSSL_EVP_UNSUPPORTED" || code === "E_LEGACY_CRYPTO" || m.includes("digital envelope routines") || m.includes("unsupported"))
+          hint = "Node blockiert die Legacy-Cipher (DES-ECB), die @marsaud/smb2 für NTLM benötigt. Saltcorn mit NODE_OPTIONS=--openssl-legacy-provider neu starten. Details in der README.";
 
         return res.status(200).json({
           ok: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "saltcorn-samba",
-  "version": "0.3.10",
+  "version": "0.3.11",
   "description": "Saltcorn plugin: browse, upload, rename and delete files on a Samba/CIFS share. File-manager view, directory tree, inline PDF viewer, external-app open (smb://).",
   "main": "index.js",
   "scripts": {

package/smb-client.js

@@ -7,6 +7,7 @@
  */
 
 const path = require("path");
+const crypto = require("crypto");
 
 // @marsaud/smb2 is loaded lazily so the pure sanitizer helpers exported by
 // this module can be required (e.g. from unit tests) without needing the
@@ -18,6 +19,57 @@ function getSMB2() {
   return _SMB2;
 }
 
+// ---------------------------------------------------------------------------
+// OpenSSL 3 / Node 17+ compatibility check
+// ---------------------------------------------------------------------------
+//
+// @marsaud/smb2 -> ntlm -> smbhash.js benutzt DES-ECB für die LM/NTLM-Hashes.
+// Node 17+ mit OpenSSL 3 blockiert DES-ECB standardmäßig; der Aufruf wirft
+// dann `error:0308010C:digital envelope routines::unsupported`
+// (ERR_OSSL_EVP_UNSUPPORTED). Der Fehler fliegt synchron und tötet den
+// Saltcorn-Worker → der Reverse-Proxy meldet 502 Bad Gateway.
+//
+// Hier fangen wir das VOR dem eigentlichen SMB-Aufruf ab und liefern eine
+// verständliche Fehlermeldung mit Lösungsanleitung.
+let _cryptoOK = null;
+function checkLegacyCryptoAvailable() {
+  if (_cryptoOK !== null) return _cryptoOK;
+  try {
+    // DES-ECB genau so aufrufen, wie es ntlm intern tut.
+    // Wenn OpenSSL 3 ohne Legacy-Provider läuft, wirft das hier.
+    const key = Buffer.alloc(8, 0);
+    const c = crypto.createCipheriv("des-ecb", key, null);
+    c.setAutoPadding(false);
+    c.update(Buffer.alloc(8, 0));
+    c.final();
+    _cryptoOK = { ok: true };
+  } catch (e) {
+    _cryptoOK = {
+      ok: false,
+      code: e && e.code,
+      message: (e && e.message) || String(e),
+    };
+  }
+  return _cryptoOK;
+}
+
+/** Baut eine deutsche Erklärung für den Legacy-Provider-Fehler. */
+function legacyCryptoErrorMessage(detail) {
+  return (
+    "NTLM-Authentifizierung nicht möglich: Node.js blockiert die von " +
+    "@marsaud/smb2 benötigten Legacy-Cipher (DES-ECB). Das ist ab Node 17 " +
+    "mit OpenSSL 3 der Standard. " +
+    "Lösung: Saltcorn mit dem Flag --openssl-legacy-provider starten. " +
+    "Beispiele: " +
+    "(1) direkt: `node --openssl-legacy-provider node_modules/.bin/saltcorn serve`  " +
+    "(2) per Umgebungsvariable: `NODE_OPTIONS=--openssl-legacy-provider saltcorn serve`  " +
+    "(3) systemd-Unit: `Environment=NODE_OPTIONS=--openssl-legacy-provider`  " +
+    "(4) Docker: im Compose-File `environment: NODE_OPTIONS: --openssl-legacy-provider`. " +
+    "Danach Saltcorn neu starten. Details siehe README des Plugins. " +
+    (detail ? "[Original: " + detail + "]" : "")
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Path helpers
 // ---------------------------------------------------------------------------
@@ -116,6 +168,15 @@ function buildClient(config) {
   if (!share) throw new Error("Samba: share missing");
   if (/[\\/]/.test(share)) throw new Error("Samba: share must not contain slashes");
 
+  // WICHTIG: OpenSSL-Legacy-Check VOR jedem SMB2-Aufruf. Sonst crasht
+  // ntlm/smbhash.js synchron und tötet den Worker (→ 502 am Proxy).
+  const cc = checkLegacyCryptoAvailable();
+  if (!cc.ok) {
+    const err = new Error(legacyCryptoErrorMessage(cc.message));
+    err.code = "E_LEGACY_CRYPTO";
+    throw err;
+  }
+
   // Host und Port sauber trennen. Der Server-String darf NICHT im share-UNC-
   // Pfad landen, sonst versucht Node's DNS "host:port" als Hostnamen aufzulösen
   // (getaddrinfo ENOTFOUND "1.2.3.4:445"). @marsaud/smb2 nimmt den Port über
@@ -314,4 +375,6 @@ module.exports = {
   toSmbPath,
   toSmbUrl,
   mimeFromName,
+  checkLegacyCryptoAvailable,
+  legacyCryptoErrorMessage,
 };