Sign inGet started

Verschlüsselte Channels

Ein Channel, dessen Name mit private-encrypted- beginnt, ist Ende-zu-Ende-verschlüsselt. Ihr Server versiegelt jede Payload vor dem Veröffentlichen, und autorisierte Browser-Clients entschlüsseln sie mit einem Schlüssel von Ihrem Autorisierungsendpunkt. Die Realtime-Edge und Netzwerk-Zwischenstationen sehen nur Chiffretext.
Erzeugen und speichern Sie einen 32-Byte-Masterschlüssel. Der Masterschlüssel erscheint nie in einer Realtime-API-Anfrage, und das Channel-Namenspräfix aktiviert die Funktion. Bird kann einen verlorenen Schlüssel nicht wiederherstellen, und Payloads, die mit diesem Schlüssel versiegelt wurden, bleiben nach dem Ersetzen unlesbar.
Verschlüsselte Channels verwenden denselben Endpunkt und dieselbe Signatur wie private Channels. Die Autorisierungsantwort enthält außerdem den abgeleiteten Entschlüsselungsschlüssel des Channels als shared_secret. Wird eine Subscription abgelehnt, erhält der Client den Schlüssel nicht.

Masterschlüssel erzeugen

Erzeugen Sie 32 zufällige Bytes, codieren Sie sie als Base64 und speichern Sie den Wert wie das App-Secret:
Codebeispiel
openssl rand -base64 32
Übergeben Sie ihn Ihrem Server-SDK als Teil der Realtime-Konfiguration, neben App-Key und -Secret.

Ein verschlüsseltes Event veröffentlichen

Das Server-SDK erkennt das Channel-Präfix, leitet seinen Schlüssel vom Masterschlüssel ab und versiegelt die JSON-Payload lokal. Die Publish-Anfrage enthält das versiegelte Envelope.
import { BirdClient } from "@messagebird/sdk";

const bird = new BirdClient({
  apiKey: process.env.BIRD_API_KEY,
  realtime: {
    key: process.env.BIRD_REALTIME_KEY,
    secret: process.env.BIRD_REALTIME_SECRET,
    encryptionMasterKey: process.env.BIRD_REALTIME_MASTER_KEY,
  },
});

await bird.realtime.publish("rap_01krdgeqcxet5s7t44vh8rt9mg", {
  event: "order.updated",
  channels: ["private-encrypted-orders"],
  data: { order_id: "ord_123", status: "shipped" },
});
Ein verschlüsselter Channel muss der einzige Channel in einem einzelnen Publish sein. Jeder verschlüsselte Channel leitet einen anderen Schlüssel ab, sodass andere Channels dieselbe versiegelte Payload nicht entschlüsseln können. Die SDKs weisen diesen Fan-out lokal ab, und das API gibt E23000 zurück, wenn es einen empfängt. Um an mehrere verschlüsselte Channels zu veröffentlichen, verwenden Sie einen Batch mit einem Channel pro Event.

Das Shared Secret vom Auth-Endpunkt zurückgeben

Ihr Auth-Endpunkt genehmigt verschlüsselte Subscriptions genauso wie private. Verwenden Sie den authorizeChannel-Helper des SDK, und die Antwort erhält das shared_secret automatisch, sobald der Channel-Name das verschlüsselte Präfix trägt:
app.post("/bird/auth", async (req, res) => {
  const { connection_id, channel_name } = req.body;

  const user = getUserFromSession(req);
  if (!user || !mayJoin(user, channel_name)) return res.sendStatus(403);

  res.json(
    await bird.realtime.authorizeChannel({
      connectionId: connection_id,
      channelName: channel_name,
    }),
  );
});
Das SDK leitet für jeden Channel ein separates shared_secret ab. Eine Autorisierung für private-encrypted-orders entschlüsselt daher nicht private-encrypted-invoices. Das Secret wird in Ihrer Autorisierungsantwort übertragen und ist nicht im Subscription-Frame enthalten, der an die Edge gesendet wird.

Im Browser abonnieren und entschlüsseln

Die Verschlüsselung verwendet den separaten @messagebird/realtime/encrypted-Einstiegspunkt. Importieren Sie ihn und übergeben Sie ihn als encryption-Option des Clients:
Codebeispiel
import { BirdRealtime } from "@messagebird/realtime";
import { encryption } from "@messagebird/realtime/encrypted";

const bird = new BirdRealtime({
  appKey: "your-app-key",
  region: "us1",
  authEndpoint: "/bird/auth",
  encryption,
});

const orders = bird.subscribe("private-encrypted-orders");
orders.bind("order.updated", (data) => {
  console.log(data); // decrypted: { order_id: "ord_123", status: "shipped" }
});
Bindings empfangen Klartext. Ein Abonnement ohne die encryption-Option wirft sofort einen Fehler, und eine Autorisierungsantwort ohne shared_secret lässt die Subscription fehlschlagen.
Nur der Browser-Client empfängt derzeit verschlüsselte Channels. Die Swift- und Kotlin-Clients lehnen private-encrypted--Subscriptions ab, weil sie keine Entschlüsselung implementieren.

Masterschlüssel rotieren

Verteilen Sie den neuen Schlüssel gleichzeitig an alle Publisher und Autorisierungsendpunkte. Während der Rotation:
  1. Neue Publishes versiegeln unter dem neuen Schlüssel.
  2. Ein abonnierter Browser-Client, der ein Event nicht entschlüsseln kann, autorisiert sich einmalig neu und ruft das neue shared_secret ab.
  3. Instanzen mit unterschiedlichen Masterschlüsseln können kurzzeitig Events veröffentlichen, die manche Clients nicht entschlüsseln können. Koordinieren Sie den Rollout über alle Instanzen hinweg.
Rotieren Sie einen kompromittierten oder verlorenen Schlüssel. Die Rotation schützt zukünftige Payloads, kann aber frühere Events nicht neu versiegeln und Kopien des alten Schlüssels nicht widerrufen.

Was verschlüsselte Channels nicht leisten

  • Offizielle Clients unterstützen keine Client-Events. Browser-trigger() wirft bei verschlüsselten Channels einen Fehler, weil der Client Client-zu-Client-Payloads nicht versiegelt. Senden Sie keine Klartext-Client-Events von einem eigenen Client.
  • Presence und Verschlüsselung lassen sich nicht kombinieren. Das presence-encrypted--Präfix wird nicht unterstützt. Cache und Verschlüsselung funktionieren zusammen: private-encrypted-cache--Channels speichern das gecachte Event versiegelt, wobei nach einer Schlüsselrotation die gecachte Kopie unter dem alten Schlüssel versiegelt bleibt, bis der nächste Publish sie ersetzt.
  • Channel-Namen und Event-Namen werden nicht verschlüsselt. Nur die Payload wird verschlüsselt. Wählen Sie Channel-Namen, die nicht verraten, was Sie schützen.
  • Die Realtime-Edge kann Payloads nicht inspizieren. Channel- und Event-Namen bleiben sichtbar, während die Payload verschlüsselt bleibt.

Nächste Schritte