Sign inGet started

Canais criptografados

Um canal cujo nome começa com private-encrypted- possui criptografia de ponta a ponta. Seu servidor sela cada payload antes de publicá-lo, e clientes de navegador autorizados o descriptografam com uma chave do seu endpoint de autorização. O edge do Realtime e intermediários de rede veem apenas texto cifrado.
Gere e armazene uma chave mestra de 32 bytes. A chave mestra nunca aparece em uma solicitação API do Realtime, e o prefixo do nome do canal habilita o recurso. Bird não consegue recuperar uma chave perdida, e payloads selados com essa chave permanecem ilegíveis após você substituí-la.
Canais criptografados usam o mesmo endpoint e assinatura que os canais privados. A resposta de autorização também inclui a chave de descriptografia derivada do canal como shared_secret. Rejeitar uma inscrição impede que o cliente receba a chave.

Gerar uma chave mestra

Gere 32 bytes aleatórios, codifique-os como base64 e armazene o valor como o app secret:
Exemplo de código
openssl rand -base64 32
Forneça-a ao SDK do seu servidor como parte da configuração do realtime, junto com a app key e o secret.

Publicar um evento criptografado

O SDK do servidor detecta o prefixo do canal, deriva a chave a partir da chave mestra e sela o payload JSON localmente. A solicitação de publicação contém o envelope selado.
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" },
});
Um canal criptografado deve ser o único canal em uma única publicação. Cada canal criptografado deriva uma chave diferente, então outros canais não conseguiriam descriptografar o mesmo payload selado. Os SDKs rejeitam esse fan-out localmente, e o API retorna E23000 se receber um. Para publicar em vários canais criptografados, use um batch com um canal por evento.

Retornar o segredo compartilhado do seu endpoint de autenticação

Seu endpoint de autenticação aprova inscrições criptografadas da mesma forma que aprova inscrições privadas. Use o helper authorizeChannel do SDK e a resposta ganha o shared_secret automaticamente sempre que o nome do canal tiver o prefixo criptografado:
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,
    }),
  );
});
O SDK deriva um shared_secret separado para cada canal. A autorização para private-encrypted-orders, portanto, não descriptografa private-encrypted-invoices. O segredo trafega na sua resposta de autorização e não é incluído no frame de inscrição enviado ao edge.

Inscrever-se e descriptografar no navegador

O cifrador usa o ponto de entrada @messagebird/realtime/encrypted separado. Importe-o e passe-o como a opção encryption do cliente:
Exemplo de código
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" }
});
Os bindings recebem texto plano. Inscrever-se sem a opção encryption lança um erro imediatamente, e uma resposta de autorização sem shared_secret falha na inscrição.
Apenas o cliente de navegador recebe canais criptografados atualmente. Os clientes Swift e Kotlin rejeitam inscrições private-encrypted- porque não implementam a descriptografia.

Rotacionar a chave mestra

Implante a nova chave em todos os publicadores e endpoints de autorização ao mesmo tempo. Durante a rotação:
  1. Novas publicações selam sob a nova chave.
  2. Um cliente de navegador inscrito que não conseguir descriptografar um evento se reautoriza uma vez e obtém o novo shared_secret.
  3. Instâncias usando chaves mestras diferentes podem publicar brevemente eventos que alguns clientes não conseguem descriptografar; coordene o rollout entre as instâncias.
Rotacione uma chave vazada ou perdida. A rotação protege payloads futuros, mas não consegue selar novamente eventos anteriores nem revogar cópias da chave antiga.

O que canais criptografados não fazem

  • Clientes oficiais não suportam eventos de cliente. O trigger() do navegador lança um erro em canais criptografados porque o cliente não sela payloads de cliente para cliente. Não envie eventos de cliente em texto plano a partir de um cliente customizado.
  • Presença e criptografia não podem ser combinadas. O prefixo presence-encrypted- não é suportado. Cache e criptografia funcionam juntos: canais private-encrypted-cache- armazenam o evento em cache selado, mas após uma rotação de chave a cópia em cache permanece selada sob a chave antiga até que a próxima publicação a substitua.
  • Nomes de canal e nomes de evento não são criptografados. Apenas o payload é. Escolha nomes de canal que não revelem o que você está protegendo.
  • O edge do Realtime não consegue inspecionar payloads. Nomes de canal e de evento permanecem visíveis, enquanto o payload permanece criptografado.

Próximos passos