RFC: Kommende XML-API CCU Addon 2.0 Version

[jmaus]

Hallo Zusammen,

in den letzten Tagen habe ich mich nun endlich einmal an das XML-API Addon wieder herangewagt um einige Verbesserungen umzusetzen die mir schon länger durch den Hinterkopf gegangen sind. Wie vielleicht bereits bekannt ist/war, bietet das XML-API Addon eine recht simple Art&Weise um nicht nur Werte einer CCU/RaspberryMatic abzufragen und die Antworten im XML Format zurück zu erhalten, es erlaubt auch gewisse Operationen oder Änderungen an Geräten, Systemvariablen, etc. hierüber vorzunehmen ähnlich wie das mit der internen JSONRPC API oder anderen APIs möglich ist.

Ein großes Problem dieses XML-API Addons ist/war es bisher jedoch, das alle diese Abfragen und Operationen völlig ohne Authentifizierungsprüfung stattgefunden haben. Und da dieses Addon jedoch einen recht hohen Verbreitungsgrad besitzt ist dies gerade nach Installation dieses Addons mitunter recht problematisch. Und auch wenn das Einrichten eines einfachen Port Forwardings weiterhin ein absolutes NoGo ist im Bezug auf eine CCU/RaspberryMatic, so ist es wirklich bisher für jemanden ein Leichtes bei einem installierten XML-API Addon beliebige Operationen bis hin zum kompletten Löschen oder anlegen von Admin Accounts vorzunehmen. Und da eben dieses Addon recht weit verbreitet ist, so ist es nicht verwunderlich das einige CCU-Zentralen die fälscherlicherweise via Port Forwarding freigegeben wurden von Fremden übernommen wurde. Genau deshalb existieren im XML-API Addon Projekt auch schon seit längerem Tickets und auch PullRequests die diesem Umstand versuchen Rechnung zu tragen (siehe https://github.com/homematic-community/ ... /issues/29, https://github.com/homematic-community/XML-API/pull/31).

Da es sich bei diesen Sicherheitsanpassungen jedoch leider nicht um einfach Anpassungen handelt wie diese bei anderen Addons bereits umgesetzt wurden, sondern es sich beim XML-API Addon eben um ein Addon handelt bei dem man eben eine API für die Abfragen/Nutzung erhält muss man hier eben etwas anders vorgehen damit bestehende Applikationen/Nutzungsfälle die diese API nutzen nicht komplett aufgeschmissen sind.

Und so gibt es nun inzwischen schon eine erste beta-version einer XML-API CCU Addon 2.0 Version die ich heute im GitHub Projekt als Pre-Release Version freigegeben habe. Siehe:

https://github.com/homematic-community/ ... /tag/2.0b4

Hier sei jedoch explizit davor gewarnt diese einfach in einem produktivem System über eine alte XML-API Addon Version drüberzuinstallieren, da durch das einführen von Authentifizierungsfunktionen (login + logout) es nun notwendig ist bestehende Applikationen zu anzupassen, das diese mittels Nutzername+Passwort sich erst eine valide Session ID generieren lassen die man dann für die weitere Aufrufe der API Funktionen nutzen muss.

Und da mir aktuell nicht alle Nutzungsszenarien bzw. Use-Cases bzgl. XML-API Addon bekannt sind, habe ich mich eben dazu entschieden erst diesen Pre-Release herauszubringen um dazu einzuladen sich bei der Finalisierung der kommenden 2.0 Version entsprechend zu beteiligen. Gerade Entwickler oder Nutzer die bereits auf die alte XML-API 1.x Version setzen sind hier explizit angesprochen und dazu aufgerufen entsprechende Tests der neuen 2.0 Version zu machen um gerade die neuen Authentifizierungsfunktionen auf Herz+Nieren zu testen und auch Feedback zu geben wo vielleicht das Eine oder Andere noch fehlt.

In diesem Sinne würde ich mich freuen wenn hier Interessierte bzgl. XML-API Addon sich zusammenführen würden damit die finale 2.0 Version hoffentlich noch in Q1/2023 so erscheinen kann das diese dann auf die Allgemeinheit losgelassen werden kann.

[deimos]

Hi,

warum Login/Logout mit SessionID und nicht Stateless Auth mit Token, wie es bei solchen APIs Standard ist?

Viele Grüße
Alex

[jmaus]

warum Login/Logout mit SessionID und nicht Stateless Auth mit Token, wie es bei solchen APIs Standard ist?

Weil ich mir das kurzerhand einfach abgeschaut habe wie das die ganzen anderen Addons inkl. CUxD so machen und weil die tcl Funktionen dafür einfach da waren. Wenn du aber da was parat hast wo ich mir das schnell abschauen kann dann können wir das gerne auch einfach auf eine token basierte Authentifizierung umstellen.

[deimos]

Hi,

die anderen Addons sind aber vermutlich keine APIs, zumindest ist das bei CuXD nicht der Fall. Bei APIs hat man dagegen aber normalerweise keinen menschlichen Nutzer und da hat es sich u.A. aus Sicherheits- und Resourcengründen eingebürgert, dass man Token basierte Authentifizierung nutzt. Ich bin halt mit der Überzeugung unterwegs, dass man Sachen gescheit neu machen sollte und nicht mit irgendwelchen Schnellschüssen.

Viele Grüße
Alex

[jmaus]

Bei APIs hat man dagegen aber normalerweise keinen menschlichen Nutzer und da hat es sich u.A. aus Sicherheits- und Resourcengründen eingebürgert, dass man Token basierte Authentifizierung nutzt. Ich bin halt mit der Überzeugung unterwegs, dass man Sachen gescheit neu machen sollte und nicht mit irgendwelchen Schnellschüssen.

Ich bin da prinzipiell vollkommen bei dir und die Überlegung hatte ich auch erst. Allerdings habe ich eben den Aufwand bisher gescheut jetzt die ganze Infrastruktur bzgl. API Token Generierung/Verwaltung via WebUI erst entwickeln bzw. bereitstellen zu müssen weil man müsste da ja eine Verwaltungsoberfläche für diese API Tokens zur Verfügung stellen usw. und das am besten in der Haupt WebUI der CCU/RaspberryMatic und dann wären wir wieder gleich bei der Frage der Inkompatibilität zu den anderen CCU Linien. Und wenn man da jetzt ne API Token Oberfläche nur für das XMLAPI Addon wieder baut geht man auch wieder einen Sonderweg und das würde es schwer machen die WebUI in Zukunft vllt. etwas mehr z.B. vom Webserver her zu verriegeln, d.h. da direkt eine SessionID überprüfung einzubauen und erst gar nicht zuzulassen das es Addons ohne Authentifizierung gibt (wenn man das denn umsetzen will).

Aber wenn du da konkrete Ideen oder Tools/Frameworks zur Hand hast immer gerne her damit, dann können wir da gerne konkreter drüber reden und das gerne auch in der XML-API 2.0 noch umsetzen. Bis jetzt ist es ja "nur" eine RFC bzw. Betaversion die prinzipiell noch ergebnisoffen ist...

[rentier-s]

Aus dieser Diskussion zu HTTP Auth im lighttpd möchte ich dann hier meine Laienhafte Meinung dazu kund tun.

Mein Anwendungsfall für die XML-API ist TinyMatic. Konkret habe ich Apache2 als ReverseProxy auf dem Raspberry Pi laufen, der als Host für PivCCU3 dient. Der ReverseProxy ist selbst mit HTTPS Zwang, HTTP Basic Authentifizierung und Fail2Ban ausgerüstet.

Zusätzlich habe ich die Authentifizierung für XML-API im lighttpd aktiviert, damit die CCU im lokalen Netz nicht komplett offen steht.

Die Anmeldedaten für die XML-API sind in der Konstellation in der Apache Konfig hinterlegt. In TinyMatic werden die Daten für die Authentifizierung am Apache eingetragen. So kann ich meiner Meinung nach doch relativ gut gesichert unterwegs vom Handy aus meine Anlage bedienen.

Wenn die XML-API jetzt eine wie auch immer geartete Anmeldung verlangt, um an eine Session ID zu kommen, funktioniert nach meinem Verständnis mein ganzes Konstrukt nicht mehr. Stattdessen müsste dieses Anmelde Prozedere in TinyMatic integriert werden, was aber dann bedeutet, dass man keinen ReverseProxy mit Vor-Authorisierung mehr verwenden kann, sondern dann ja eigentlich gezwungen ist, die XML-API direkt aus dem Internet zugänglich zu stellen. Es sei denn der Entwickler bietet eine Kombi aus HTTP Authentifizierung und Session Login.

[jmaus]

Wenn die XML-API jetzt eine wie auch immer geartete Anmeldung verlangt, um an eine Session ID zu kommen, funktioniert nach meinem Verständnis mein ganzes Konstrukt nicht mehr. Stattdessen müsste dieses Anmelde Prozedere in TinyMatic integriert werden, ...

Nun, Sicherheit hat nunmal ihren Preis. Und es ist einfach nicht mehr zeitgemäß, dass solch eine API bzw. Addon vollkommen ungeschützt es erlaubt sämtlich Dinge zu erledigen für die man über die WebUI normalerweise Admin-Rechte braucht. Viel zu oft ist/war die XML-API ein einfallstor, gerade bei Nutzer unachtsam einfach ein Port-Forwarding von Port 80 oder 443 eingestellt hatten um konfortabler auf ihre CCU WebUI zuzugreifen. Wenn dann noch das XML-API Addon installiert war, dann war/ist es für jemand außenstehenden ein Leichtes die gesamte Zentrale zu übernehmen weil eben die API des XML-API Addons vollkommen ungeschützt zugänglich ist. Deshalb ist es unabdingbar eine zwingende Authentifizierung zu haben, sodass nur berechtigte Anwendungen/Personen auch Zugriff auf die XML-API Methoden erlangen.

Und wenn das bedeutet das dann in TinyMatic eben die notwendigen Änderungen eingepflegt werden müssten um dieses Session Login/Logout durchzuführen, dann ist das eben so. Seit einiger Zeit ist TinyMatic ja selbst OpenSource und so steht es jedem frei es dann entsprechend an die kommende XML-API v2 anzupassen.

[ultrah]

Hi. Hab mir die neue Version über Weihnachten mal angesehen. Wird nicht ganz einfach das in TinyMatic einzubauen weil der Netzwerkcode etwas in die Jahre gekommen ist, aber hey, was muss das muss.

Könnte die API bei Auth-Fehlern einen entsprechenden HTTP Statuscode zurückgeben? Das würde transparente Reauthentication erleichtern.

[jmaus]

Hi. Hab mir die neue Version über Weihnachten mal angesehen. Wird nicht ganz einfach das in TinyMatic einzubauen weil der Netzwerkcode etwas in die Jahre gekommen ist, aber hey, was muss das muss.

Könnte die API bei Auth-Fehlern einen entsprechenden HTTP Statuscode zurückgeben? Das würde transparente Reauthentication erleichtern.

Direkte HTTP Statuscodes zurückzugeben wird schwierig. Das liefert ja der Webserver aus. Aber schon jetzt gibt die Login() Funktion usw. ja nen fehler zurück wenn die sid bzw. nutzername+passwort nicht passt.

[rentier-s]

Und es ist einfach nicht mehr zeitgemäß, dass solch eine API bzw. Addon vollkommen ungeschützt es erlaubt sämtlich Dinge zu erledigen für die man über die WebUI normalerweise Admin-Rechte braucht.

Unbestritten. Ich bin da aber ganz bei Alex, dass APIs halt normalerweise anders arbeiten.

Eine verpflichtende Authentifizierung könnte man auch per digest auth, challenge response oder Token machen. Dazu HTTPS bevorzugen oder erzwingen.

Nach der Installation des Addons zum Beispiel einmalig über das WebUI die Addon Config aufrufen, damit ein zufälliger Key erzeugt wird, der dann im Client für die Authentifizierung verwendet wird.

Gerade im Hinblick auf TinyMatic auf dem Handy bedeutet die Umstellung für mich, dass ich die API ohne weitere vorgelagerte Sicherheitsmechanismus ins Internet öffnen müsste.