Zum Inhalt springen

OBS/Kostenpflichtige Module/REST-Server/Zugangscode und Zertifikats-Pin

Aus OBS Wiki
Version vom 17. November 2026, 07:14 Uhr von MINERVA-Rademacker (Diskussion | Beiträge) (MINERVA-Rademacker verschob die Seite OBS/Kostenpflichtige Module/RESTServer/Zugangscode und Zertifikats-Pin nach OBS/Kostenpflichtige Module/REST-Server/Zugangscode und Zertifikats-Pin: Titel an Überschrift angeglichen (REST-Server, Umlaute, sprechende Beispieltitel))

Zugangscode und Zertifikats-Pin

Der Zugangscode bringt ein Gerät mit einem Scan an den REST-Server: Er enthält Adresse, App-Kennung, API-Key und bei Bedarf den Zertifikats-Pin in einer einzigen Zeile. Diese Seite beschreibt Format, QR-Vorgaben, Prüfregeln und Pin-Berechnung – für Entwickler der OBS-Smart-Apps und eigener Apps sowie für Betreuer, die Zugangscodes ausgeben.

Aufruf

Der Zugangscode ist eine Zeile mit genau einer URI (Formatversion 1). Angaben in eckigen Klammern sind optional.

obssmart://zugang?v=1&app=<app>&url=<basis-url>&key=<api-key>[&name=<anzeigename>][&pin=<pins>]

Parameter

Parameter Typ Pflicht Standard Bedeutung
obssmart://zugang Schema und Pfad ✓ – Kennzeichnet den Text als Zugangscode. Immer genau so.
v Zahl ✓ – Formatversion, hier 1. Eine höhere Zahl lehnt die App ab und verlangt ein App-Update.
app Text ✓ – App-Kennung. Das ist das erste Segment des Endpunkt-Pfades, z. B. service.
url URL ✓ – Basis-URL der Instanz in der Form https://host[:port]. Ohne App-Kennung, ohne Pfad, ohne / am Ende.
key Text ✓ – API-Key, so wie ihn die App im Header apikey sendet. Für die App undurchsichtig: nicht leer, höchstens 128 Zeichen.
name Text – leer Anzeigename. Er erscheint in der App als Bezeichnung der Verbindung.
pin Text – leer Ein bis drei Zertifikats-Pins, durch Komma getrennt. Siehe Zertifikats-Pin.

Für alle Felder gilt:

  • Jeder Wert ist prozentkodiert nach RFC 3986. Nur die unreservierten Zeichen A–Z a–z 0–9 - . _ ~ bleiben stehen. Alle anderen Zeichen werden als UTF-8-Bytes kodiert, aus ü wird also %C3%BC. Der ganze Code ist damit reines ASCII.
  • Die Reihenfolge der Felder ist frei.
  • Unbekannte Felder ignoriert die App.
  • Jedes Feld kommt höchstens einmal vor.
  • Release-Builds der App nehmen nur https an. http gilt nur in Entwicklungs-Builds.
  • Der Standardport entfällt: https ohne :443, http ohne :80.

Rückgabe

Der Zugangscode selbst liefert nichts zurück. Die OBS-Smart-Apps testen nach dem Einlesen die Verbindung mit GET /{app}/app/settings ohne Token. Der Endpunkt app/settings gehört zu den OBS-Smart-Apps; eine eigene App braucht ihn nicht.

Antwort Bedeutung in den OBS-Smart-Apps
401 mit AUTH_REQUIRED Server erreichbar, API-Key angenommen. Es fehlt nur noch die Anmeldung.
401 mit API_KEY_INVALID API-Key falsch oder gesperrt.

Beispiel

Ein Code ohne Pin, für eine Instanz mit öffentlichem Zertifikat:

obssmart://zugang?v=1&app=service&url=https%3A%2F%2Fobs.example.com%3A8443&key=abcdef-ghij-klmn-opqr-stuvwx&name=Kundendienst%20Nord

Dekodiert gelesen:

Feld Wert
v 1
app service
url https://obs.example.com:8443
key abcdef-ghij-klmn-opqr-stuvwx
name Kundendienst Nord

Derselbe Zugang mit eigenem Zertifikat und Pin. Der Pin steht als letztes Feld; / wird zu %2F, = zu %3D:

obssmart://zugang?v=1&app=service&url=https%3A%2F%2Fobs.example.com%3A8443&key=abcdef-ghij-klmn-opqr-stuvwx&name=Kundendienst%20Nord&pin=sha256%2Fxmsy8bxKgajABQHMuf%2FU7s1MuQ3uhZ2JXoW8UPAZ3Oc%3D

Dekodiert lautet das Feld pin: sha256/xmsy8bxKgajABQHMuf/U7s1MuQ3uhZ2JXoW8UPAZ3Oc=. Schlüssel und Pin in beiden Beispielen sind Platzhalter.

Code in OBS ausgeben

Markieren Sie den Zugang in der Liste der Zugänge und drücken Sie F6. Der Dialog Zugangscode für OBS-Smart-App belegt alle Felder aus der Einrichtung vor. Jedes Feld können Sie überschreiben.

Feld Vorbelegung Wird zu
App Erstes Segment des Pfad-Templates der Endpunkte, die dem Zugang zugeordnet sind app
Host (FQDN) Zertifikatsname (FQDN) des Server-Profils. Hier gehört die Adresse hinein, unter der das Gerät den Server erreicht, nicht die Adresse, auf der der Dienst lauscht Host in url
Port Port der Bindung mit Standard, sonst der ersten aktiven Bindung Port in url
HTTPS Gesetzt, wenn am Server-Profil kein SSL (Plain-HTTP - nur für Debug!) aus ist Schema in url
Anzeigename Name des Zugangs name
API-Key API-Key des Zugangs key
Zertifikats-Pin Zertifikats-Pin des Server-Profils, nur wenn dort Eigenes Zertifikat (Pin) gesetzt ist pin
Alter Key noch Tage 14 nur für den Schlüsseltausch

Der fertige Code steht im Feld Zugangscode. Unter Hinweise meldet der Dialog, was fehlt oder fragwürdig ist.

Taste Funktion
F2 QR-Code anzeigen, zum Abfotografieren mit dem Gerät.
F3 Schlüssel tauschen, siehe API-Key tauschen.
F4 Zugangscode als Text in die Zwischenablage.
Esc Dialog schließen.

Kein Code entsteht, wenn

  • App, Host (FQDN) oder API-Key leer ist,
  • ein Zertifikats-Pin eingetragen ist, aber HTTPS aus ist,
  • der Zertifikats-Pin nicht das Format hat: höchstens drei Pins, jeder sha256/ plus 44 Zeichen Base64, also 51 Zeichen.

Nur als Hinweis, der Code entsteht trotzdem:

  • HTTPS ist aus. Release-Builds der App lehnen den Code dann ab.
  • Der Host ist localhost oder 127.0.0.1. Vom Gerät aus ist der Server so nicht erreichbar.
  • Port ist leer. Dann gilt der Standardport des Schemas.
  • Dem Zugang sind Endpunkte mehrerer Apps zugeordnet. Prüfen Sie dann App.
ACHTUNG: Der Zugangscode enthält den API-Key im Klartext – auch als QR-Code. Geben Sie ihn nur an das Gerät weiter, für das er bestimmt ist, und verschicken Sie ihn nicht über offene Kanäle.

QR-Code

Vorgabe Wert
Code-Typ QR (ISO/IEC 18004). Kein Data Matrix, kein Micro-QR
Modus Byte
Fehlerkorrektur Stufe M (15 %)
Ruhezone mindestens 4 Module, weiß
Farbe schwarz auf weiß, nicht invertiert
Größe am Bildschirm mindestens 5 cm bzw. 300 × 300 Pixel
Größe als Bild in einer Mail PNG, mindestens 600 × 600 Pixel
Logo keines in der Mitte

Die QR-Version hängt von der Länge ab: Ein Code mit rund 130 Zeichen ohne Pin passt in Version 8 (49 × 49 Module). Mit einem Pin (rund 180 Zeichen) wird es Version 10, mit zwei Pins (rund 240 Zeichen) Version 11.

Weitergabe

Den Code geben Sie am Bildschirm weiter (das Gerät scannt mit der Kamera) oder per Mail. Die Mail schreiben Sie selbst: den Text holen Sie mit F4, das Bild aus dem Fenster des QR-Codes. Eine Mail enthält den Code am besten dreifach:

  1. als Bild, inline und als Anhang zugang-<app>.png,
  2. als Link mit demselben Inhalt; ein Tipp darauf öffnet die App,
  3. als Text zum Kopieren, für Code einfügen in der App.

Die App liest den Code damit auf vier Wegen: Kamera, Bild, Link und eingefügter Text.

Prüfung durch die App

Die App übernimmt einen Code nur, wenn alle Prüfungen bestehen.

Fall Meldung in der App
Text beginnt nicht mit obssmart://zugang „Das ist kein Zugangscode für OBS Smart.“
v größer als 1 „Dieser Code ist neuer als die App — bitte die App aktualisieren.“
app passt nicht zur App „Dieser Code gehört zur App ‚<app>‘ …“
url fehlt, enthält einen Pfad oder ist im Release-Build nicht https „Die Adresse im Code ist ungültig.“
key fehlt „Im Code fehlt der Zugangsschlüssel.“
pin zusammen mit einer http-Adresse „Die Adresse im Code ist ungültig.“
pin leer, fehlerhaft oder mit mehr als drei Pins „Das ist kein Zugangscode für OBS Smart.“
Server zeigt einen anderen Schlüssel als gepinnt „Zertifikat passt nicht zum Zugangscode“ bzw. Verbindungsfehler

Liest das Gerät einen neuen Code ein:

  • Gleiche url: Die App ersetzt nur Key und Pins. Anmeldung und lokale Daten bleiben.
  • Andere url: Das ist ein Serverwechsel. Die App fragt nach und weist auf den Verlust der lokalen Daten hin.

Zertifikats-Pin

Der Pin bindet die App an genau einen Schlüssel. Er ist für interne Netze ohne eigene Domain gedacht, in denen keine Zertifizierungsstelle erreichbar ist. Mit öffentlichem Zertifikat brauchen Sie keinen Pin.

Was gepinnt wird

Gepinnt wird der öffentliche Schlüssel des Serverzertifikats, nicht das Zertifikat. Erneuern Sie das Zertifikat mit demselben Schlüssel, bleibt der Pin gleich.

Ein Pin lautet sha256/ plus Base64 (mit =-Auffüllung) des SHA-256 über den DER-kodierten öffentlichen Schlüssel (SubjectPublicKeyInfo, kurz SPKI). Er ist 51 Zeichen lang. Andere Präfixe als sha256/ lehnt die App ab.

Pin selbst berechnen

Zur Gegenprobe oder für einen neuen Schlüssel berechnen Sie den Pin mit OpenSSL aus der Zertifikatsdatei:

openssl x509 -in server.crt -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64

Setzen Sie sha256/ vor das Ergebnis.

HINWEIS: Der Pin ist nicht der Zertifikats-Hash (Fingerabdruck über das ganze Zertifikat). Ein solcher Wert passt nie.

Was die App prüft

  • Mit Pin prüft die App bei jeder Verbindung, ob der Server den gepinnten Schlüssel zeigt.
  • Hostname und Ablaufdatum des Zertifikats prüft sie nicht.
  • Es gibt kein „Trotzdem verbinden“ und kein Vertrauen beim ersten Kontakt.
  • Eine App, die keinen Pin versteht, lehnt den Code ab. Sie fällt nicht auf das normale Vertrauen in Zertifizierungsstellen zurück.

Einrichtung in OBS

  1. Setzen Sie im Server-Profil auf der Registerkarte 4 Zertifikaterneuerung den Haken Eigenes Zertifikat (Pin). Er ist anfangs aus.
  2. Tragen Sie unter Zertifikatsname (FQDN) die Adresse ein, unter der das Gerät den Server erreicht. Auch eine IP-Adresse ist zulässig.
  3. Lassen Sie Zertifikat (cert) und Schlüssel (key) leer und starten Sie den REST-Dienst neu.
  4. Der Dienst stellt ein Zertifikat aus: RSA 3072, gültig 3650 Tage, Name und alternativer Name aus Zertifikatsname (FQDN). Er berechnet den Pin und legt ihn im Feld Zertifikats-Pin ab.
  5. Geben Sie mit F6 in den Zugängen den Zugangscode aus. Der Pin ist vorbelegt.

Sind Zertifikat und Schlüssel beide hinterlegt, ändert der Dienst sie nie. Fehlt eines von beiden, stellt er beide neu aus.

Eigenes Zertifikat (Pin) schließt sich aus mit

  • Automatische Erneuerung: Jede Erneuerung brächte einen neuen Schlüssel und damit einen neuen Pin.
  • kein SSL (Plain-HTTP - nur für Debug!): Ohne TLS gibt es keinen Schlüssel.

OBS weist beide Kombinationen beim Speichern zurück.

Ändert sich der Pin eines Profils, schreibt der Dienst beim Start ins Protokoll:

Server [<Name>]: ACHTUNG, Zertifikats-Pin hat sich geändert: <neu> statt <alt>. Alle bisher ausgegebenen Zugangscodes sind damit ungültig.

Schlüsseltausch

API-Key tauschen

Mit F3 im Dialog Zugangscode für OBS-Smart-App erzeugt OBS nach Rückfrage einen neuen API-Key und speichert ihn sofort am Zugang. Der bisherige Key gilt so viele Tage weiter, wie unter Alter Key noch Tage steht (vorbelegt 14). In dieser Zeit lesen die Geräte den neuen Code ein, ohne dass der Betrieb steht. Mit 0 gilt der alte Key sofort nicht mehr.

Solange die Frist läuft, schreibt der Server bei jeder Nutzung des alten Keys eine Zeile ins Protokoll:

Vorheriger API-Key benutzt von <IP-Adresse> (gueltig bis …)

So sehen Sie, welche Geräte den neuen Code noch nicht haben.

Zertifikatsschlüssel wechseln

ACHTUNG: Ein neuer Zertifikatsschlüssel macht jeden bisher ausgegebenen Zugangscode mit Pin ungültig. Die Geräte kommen dann nicht mehr durch.

Damit kein Gerät ausfällt, wechseln Sie mit Überlappung:

  1. Erzeugen Sie den neuen Schlüssel samt Zertifikat. Bauen Sie ihn noch nicht ein.
  2. Berechnen Sie den Pin des neuen Schlüssels mit OpenSSL, siehe Pin selbst berechnen.
  3. Ergänzen Sie im Dialog das Feld Zertifikats-Pin von Hand zu <alter Pin>,<neuer Pin> und geben Sie die Codes an alle Geräte aus.
  4. Haben alle Geräte den neuen Code, bauen Sie das Zertifikat mit dem neuen Schlüssel im Server-Profil ein und starten den REST-Dienst neu. Der Dienst berechnet den Pin neu und meldet die Änderung im Protokoll, wie oben gezeigt. Die Meldung ist in diesem Fall erwartet.
  5. Geben Sie künftig nur noch Codes mit dem neuen Pin aus.

Siehe auch