Exchange data with partners

Wo

Admin-Panel, Reiter Datenaustausch

Zwei Schnittstellen

Blacklist (HyghCheck) und Telematik (HyghFleet), getrennt

Schutz

Ende-zu-Ende verschlüsselt, standardmäßig aus

Für wen

Partner oder Kunden mit eigenem Server

Zwei getrennte Schnittstellen#

Es ist kein gemeinsamer Zugang, sondern zwei voneinander unabhängige Schnittstellen. Sie teilen dasselbe Drahtformat, aber weder Partner noch Schlüssel noch Endpunkte. Wer beides nutzt, richtet zwei Partner ein, je einen pro Schnittstelle.

Was die Grenze überquert und was nicht#

• Blacklist: Es gehen nur geblendete Werte über die Leitung, keine E-Mail, keine Telefonnummer, kein Name im Klartext. Die Antwort nennt nur, *dass* und *warum* ein Treffer vorliegt, ohne Namen und Geburtsdatum. Grundlage ist der bereits geteilte Pool aus Kunde prüfen und Kunde sperren.
• Telematik: Es werden nur freigegebene Fahrzeuge und nur freigegebene Felder übertragen, zum Beispiel Tankfüllstand oder Kilometerstand. Die Position ist optional. Was nicht freigegeben ist, erscheint gar nicht. Die Daten stammen aus derselben Quelle wie die Live-Karte.

Sicherheitsmodell#

Der Transport ist HTTPS. Zusätzlich liegt darüber eine Ende-zu-Ende-Verschlüsselung des Nutzinhalts, damit selbst ein Proxy oder Load Balancer, der TLS auflöst, den Inhalt nicht lesen kann.

• Vertraulichkeit und Integrität über libsodium crypto_box (X25519 mit XSalsa20-Poly1305).
• Echtheit des Absenders über eine Ed25519-Signatur.
• Schlüsselhoheit: Jede Seite erzeugt ihre eigenen Schlüssel, ausgetauscht werden nur die öffentlichen. Der private Schlüssel verlässt nie den Server.
• Standardmäßig aus: Es fließt kein Datum, bevor der Partner scharfgeschaltet ist.

So richtest du einen Partner ein#

1. Partner anlegen

   Im Reiter Datenaustausch die passende Schnittstelle wählen, Blacklist-Austausch oder Telematik-Austausch, und einen neuen Partner mit Namen und Mandant anlegen.

2. Schlüssel tauschen

   Das Panel zeigt unsere öffentlichen Schlüssel an. Die öffentlichen Schlüssel der Gegenstelle trägst du dort ein. Gleiche die Fingerprints über einen zweiten Weg ab, etwa telefonisch.

3. API-Schlüssel vergeben

   Einen API-Schlüssel erzeugen. Er wird einmalig angezeigt, danach nicht wieder. Sicher an die Gegenstelle übergeben.

4. Freigabe festlegen

   Bei der Blacklist die Gründe einschränken oder alle zulassen. Bei der Telematik die Felder ankreuzen und die Fahrzeuge wählen, die geteilt werden dürfen.

5. Scharfschalten und testen

   Den Partner scharfschalten. Erst ab hier fließen echte Daten. Mit Verbindung testen einen Ping senden, danach eine Beispielabfrage von der Gegenstelle aus.

Der Envelope#

Jede Anfrage und jede Antwort ist ein signierter, verschlüsselter Umschlag in genau dieser Form. Das Format ist für beide Schnittstellen identisch, nur der type und der Endpunkt unterscheiden sich.

{
  "v": 1,
  "peer": "peer_abc123",
  "alg": "x25519-xsalsa20poly1305+ed25519",
  "type": "blacklist.query",
  "ts": 1737045600000,
  "nonce": "<base64url ohne Padding, 24 Byte>",
  "ciphertext": "<base64url ohne Padding>",
  "sig": "<base64url ohne Padding, Ed25519>"
}

Anleitung und Referenzclient für die Gegenstelle#

Für die technische Integration bekommt der Partner zwei Dateien direkt von uns, nicht über diese Wiki-Seite:

• datenaustausch-anleitung.md: die ausführliche Integrationsanleitung mit dem vollständigen Drahtprotokoll, beiden Endpunkten und durchgerechneten Beispielen.
• datenaustausch-referenzclient.py: ein lauffähiger Referenzclient (PyNaCl), der das Format byteweise umsetzt und beide Schnittstellen bedient.