Using the Private State Token API

berblick auf hoher Ebene

Der Prozess, wie private Zustands-Token verwendet werden, kann in drei Phasen unterteilt werden:

1. Ausgabe von Tokens
2. Einlsen von Tokens
3. Nutzung von Einlsungsaufzeichnungen

Dieser Abschnitt fasst diese Phasen zusammen. Wir werden diese in den folgenden Abschnitten detaillierter betrachten.

Private Zustands-Token verwenden das Privacy Pass Protokoll im Hintergrund, um die Ausgabe und den Transport von Tokens usw. zu verwalten.

Ausgabe von Tokens

1. Angenommen, ein Benutzer besucht eine Website, issuer.example.
2. issuer.example kann Schritte unternehmen, um Vertrauen in den Benutzer zu etablieren. Dies kann durch Methoden wie ein CAPTCHA, die berprfung ihrer E-Mail-Adresse, das Fhren eines Protokolls der legitimen Kufe des Benutzers oder eine Kombination mehrerer solcher Methoden geschehen.

   Hinweis: Private Zustandstokens sind kein Ersatz fr CAPTCHAs oder andere Mechanismen zur Vertrauensetablierung. Private Zustandstokens bieten eine Mglichkeit, Vertrauen in einen Benutzer zu bermitteln, nicht zu etablieren.

3. Sobald das Vertrauen etabliert ist, kann issuer.example eine Anfrage an einen Server senden, um ein Private State Token auszustellen ein kryptografisches Token, das Vertrauen in den verifizierten Benutzer darstellt. In diesem Kontext wird issuer.example als Issuer bezeichnet. Der Server wird als Issuer Server bezeichnet.
4. Wenn die Anfrage erfolgreich ist, wird das Token dann sicher im Browser des Benutzers gespeichert.

Einlsen von Tokens

Wenn eine andere Website das Vertrauen in denselben Benutzer herstellen mchte, kann sie dies tun, indem sie ein private Zustands-Token einlst, das vom Browser des Benutzers von einer anderen Website ausgestellt wurde, anstatt den Prozess der Vertrauensetablierung von Grund auf neu durchzufhren.

1. Angenommen, der Benutzer besucht eine andere Website, redeemer.example.
2. redeemer.example kann eine Anfrage an einen Server stellen, um ein Token fr diesen bestimmten Benutzer und sein Gert einzulsen.
3. Der Browser berprft, ob er ein Token fr diesen Benutzer und das Gert gespeichert hat. Wenn ja, und das Token verwendbar ist (es wurde noch nicht eingelst und ist nicht abgelaufen), sendet es das Token an einen Server zur Einlsung. In diesem Kontext wird redeemer.example als Redeemer bezeichnet. Der Server wird als Redeemer Server bezeichnet.
4. Wenn das Token erfolgreich eingelst wird, sendet der Redeemer-Server eine Einlsungsaufzeichnung an den Browser, um das Benutzervetrauen zu besttigen.

Nutzung von Einlsungsaufzeichnungen

Sobald der Browser die Einlsungsaufzeichnung erhalten hat, kann er sie als Vertrauenssignal fr den aktuellen Benutzer in verschiedenen Kontexten verwenden, z. B. wenn er ihnen erlaubt, eine sensible Aktion wie das Anmelden, den Kauf eines Produkts oder das Posten eines Kommentars durchzufhren. Dieses Vertrauenssignal kann auch an andere Parteien weitergegeben werden, um Vertrauen zu bertragen.

Beispielimplementierung

Sie knnen eine Beispielimplementierung von private Zustandstokens bei Private State Token Demo Issuer finden (sehen Sie sich den Quellcode an).

Token-Ausgabe

Dieser Abschnitt fhrt Sie durch den Prozess des Aufsetzens eines Issuer-Servers und der Ausgabe von Tokens ber die Issuer-Website.

Anmeldung als Issuer

Wenn Sie ein Issuer werden mchten und Ihre Website private Zustandstokens ausgeben soll, mssen Sie sich zuerst registrieren, indem Sie den Issuer-Registrierungsprozess abschlieen. ffnen Sie ein neues Issue im Google private-tokens GitHub-Repository unter Verwendung der Vorlage "New PST Issuer". Folgen Sie den Anweisungen im Repository, um das Issue auszufllen. Sobald ein Endpunkt verifiziert wurde, wird er in dieses Repository integriert und die Chrome-Server-Infrastruktur beginnt, diese Schlssel abzurufen.

Erstellung eines Issuer-Servers

Um den Token-Issuer-Server zu implementieren, mssen Sie Ihre eigene serverseitige Anwendung erstellen, die HTTP-Endpunkte bereitstellt. Die Issuer-Komponente besteht aus zwei Hauptmodulen:

1. Die Issuer-App
2. Der Token-Issuer

[Die Hauptkomponenten des Issuer-Servers: Issuer-App gebaut mit zum Beispiel, Node.js, und Token-Issuer (kryptografische Komponente, die fr die Ausstellung von Tokens verantwortlich ist)]

In der Beispielimplementierung:

1. Die Issuer-App ist ein Node.js-Server, der das Express-Framework verwendet, um die HTTP-Endpunkte des Issuers zu hosten. Sehen Sie sich den Code der App-Beispiel an.
2. Die kryptografische Komponente des Token-Issuers erfordert keine spezielle Sprache, aber aufgrund der Leistungsanforderungen dieser Komponente stellen wir Ihnen eine C-Implementierung als Beispiel zur Verfgung, die die Boring SSL-Bibliothek verwendet, um Tokens zu verwalten. Sehen Sie sich das Beispiel des kryptografischen Komponenten-Codes und weitere Informationen zur Installation an.
3. Die Token-Issuer-Komponente verwendet benutzerdefinierte elliptische Kurven (EC)-Schlssel zur Verschlsselung von Tokens. Diese Schlssel mssen geschtzt und in einem sicheren Speicher aufbewahrt werden.

Technische Anforderungen an den Issuer-Server

Entsprechend dem Privacy Pass Protokoll mssen Sie mindestens zwei HTTP-Endpunkte in Ihrem Issuer-Server implementieren:

• Schlsselselbstverpflichtung: Dieser Endpunkt ist dort, wo Ihre Verschlsselungs-ffentliche-Schlssel-Details fr Browser verfgbar sind, um zu besttigen, dass Ihr Server legitim ist. Dieser Endpunkt muss sich in einem bekannten Verzeichnis befinden, das sich innerhalb der registrierbaren Domain des Issuer-Servers bei /.well-known/private-state-token/key-commitment befindet. Sehen Sie sich das Schlsselselbstverpflichtungs-Endpunkt Beispiel an.
• Token-Ausgabe: Der Token-Output-Endpunkt ist der, an dem alle Token-Anfragen bearbeitet werden. Dieser Endpunkt wird der Integrationspunkt fr die Token-Issuer-Komponente sein. Er muss sich auf dem Issuer-Server bei /.well-known/private-state-token/issuance befinden. Sehen Sie sich das Token-Output-Endpunkt Beispiel an.

Aufgrund des erwarteten hohen Verkehrsaufkommens auf einem solchen Server empfehlen wir, ihn unter Verwendung einer skalierbaren Infrastruktur bereitzustellen (z. B. in einer Cloud-Umgebung), um Ihr Backend je nach variabler Nachfrage anpassen zu knnen.

Ausgabe eines Tokens ber Ihren Server

Mit dem aufgesetzten Issuer-Server kann Ihre Issuer-Website nun ein neues Token ausgeben, indem eine Fetch-Anfrage an Ihren Token-Output-Endpunkt gestellt wird. Die Fetch-Anfrage muss ein privateToken-Objekt enthalten, dessen obligatorische Eigenschaften sind:

version

Die Version des kryptografischen Protokolls, die Sie bei der Generierung des Tokens verwenden mchten. Derzeit wird dies immer auf 1 gesetzt, was die einzige von der Spezifikation untersttzte Version ist.

operation

Die Token-Operation, die Sie ausfhren mchten. In diesem Fall setzen wir sie auf token-request.

Sie knnen dies mit einem fetch()-Aufruf und mit der method auf POST festgelegt und einer privateToken-Option spezifiziert handhaben:

const hasToken = await Document.hasPrivateToken(`issuer.example`);
if (!hasToken) {
  await fetch(
    "https://issuer.example/.well-known/private-state-token/issuance",
    {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request",
      },
    },
  );
}

Im Hintergrund generiert der Browser eine Reihe von Nonces, die zur Generierung des Tokens bentigt werden, verschleiert sie und sendet sie im Rahmen der Fetch-Anfrage in einem Sec-Private-State-Token-Request-Header an den Issuer-Server. Zustzlich wird die Version des kryptografischen Protokolls, das zur Generierung der Nonces verwendet wird, in einem Sec-Private-State-Token-Crypto-Version-Request-Header an den Issuer-Server gesendet. Zum Zeitpunkt des Schreibens wird nur eine Version untersttzt, aber dieser Mechanismus ermglicht es, in Zukunft mehrere Versionen zu untersttzen.

Beachten Sie, wie Sie die Methode Document.hasPrivateToken() verwenden knnen, um zu berprfen, ob der Browser bereits ein Token von unserem Issuer gespeichert hat, bevor Sie versuchen, ein weiteres anzufordern.

Wenn die Token-Anfrage erfolgreich ist, wird die Antwort einen Sec-Private-State-Token-Response-Header mit blinden Signaturen enthalten. Der Browser hebt diese Verschleierung auf und speichert sie zusammen mit den ursprnglichen nicht verschleierten Nonces in einem sicheren Token-Store. Diese Paarung von Signaturen und Nonces stellt ein privates Zustandstoken dar, das spter eingelst werden kann. Die Rohtokens sind fr JavaScript nicht zugnglich.

Token-Ausgabelimitationen

Jedes Gert kann bis zu 500 Tokens pro Top-Level-Website und Issuer speichern. Die maximale Anzahl von Issuers pro Top-Level-Herkunft ist zwei.

Jedes Token hat Metadaten, die angeben, welchen Schlssel der Issuer zur Ausgabe verwendet hat. Diese Informationen knnen verwendet werden, um zu entscheiden, ob Tokens whrend des Einlsungsprozesses eingelst werden sollen (oder nicht). Jedes Token kann nur mit einem einzigen kryptografischen Schlssel ausgegeben werden und jeder Issuer kann maximal 6 Schlssel besitzen. Eine potenzielle Mglichkeit, dies zu nutzen, besteht darin, Ihren Tokens basierend auf Ihren kryptografischen Schlsseln einen Vertrauensbereich zu definieren (z. B. Schlssel 1: hohes Vertrauen; Schlssel 6: kein Vertrauen).

Der Browser kann die aktuelle Menge gltiger Schlssel des Issuers von dem Schlsselselbstverpflichtungs-Endpunkt erhalten. Schlssel sollten regelmig rotiert werden; dies kann mindestens alle 60 Tage erfolgen; jede Rotation, die schneller erfolgt, wird ignoriert. Alle Tokens, die mit ungltigen Schlsseln ausgegeben wurden, werden auch als ungltig angesehen.

Einlsung von Tokens

Dieser Abschnitt fhrt Sie durch den Prozess des Aufsetzens eines Redeemer-Servers, des Einlsens von Tokens und der Ausgabe von Einlsungsaufzeichnungen.

Erstellung eines Redeemer-Servers

Sie mssen einen Redeemer-Server erstellen, um die vom Issuer-Server ausgegebenen Tokens zu lesen. Die folgenden Schritte skizzieren, wie Tokens eingelst werden knnen sowie wie die Einlsungsaufzeichnungen, die mit diesen Tokens verbunden sind, gelesen werden.

Die Redeemer-Komponente besteht aus zwei Hauptmodulen:

1. Die Redeemer-App
2. Der Token-Redeemer

[Die Hauptkomponenten des Redeemer-Servers: Redeemer-App gebaut mit zum Beispiel, Node.js, und Token-Redeemer (kryptografische Komponente, die fr die berprfung von Signaturen und Tokens innerhalb des Einlsungsprozesses verantwortlich ist)]

Sie knnen whlen, den Issuer und den Redeemer im selben Server (oder einer Gruppe von Servern) laufen zu lassen und gleiche kryptografische Komponenten zu verwenden. Tatschlich wurde dies in der Beispielimplementierung gemacht, um es einfacher nachzuvollziehen. Sehen Sie sich wieder den App-Beispielcode und das Beispiel des kryptografischen Komponenten-Codes und Informationen ber die Installation an.

Technische Anforderungen an den Redeemer-Server

Entsprechend dem Privacy Pass Protokoll mssen Sie mindestens einen HTTP-Endpunkt in Ihrem Redeemer-Server implementieren:

• Token-Einlsung: Hier werden alle Token-Einlsungen bearbeitet. Dieser Endpunkt wird der Integrationspunkt fr die Token-Redeemer-Komponente sein. Er muss sich auf dem Issuer-Server bei /.well-known/private-state-token/redemption befinden. Sehen Sie sich unser Token-Einlsungsendpunkt Beispiel an.

Einlsen eines Tokens ber Ihren Server

Mit dem aufgesetzten Redeemer-Server kann Ihre Redeemer-Website nun ein zuvor gespeichertes Token einlsen, indem eine Fetch-Anfrage an Ihren Token-Einlsungsendpunkt gestellt wird. Die Fetch-Anfrage muss ein privateToken-Objekt enthalten, genau wie in der Token-Ausgabeanfrage, auer dass die spezifizierte operation token-redemption sein sollte.

Sie knnen dies mit einem fetch()-Aufruf und mit der method auf POST festgelegt und einer privateToken-Option spezifiziert handhaben.

await fetch(
  "https://issuer.example/.well-known/private-state-token/redemption",
  {
    method: "POST",
    privateToken: {
      version: 1,
      operation: "token-redemption",
      refreshPolicy: "none",
    },
  },
);

Hier setzen wir auch die refreshPolicy-Eigenschaft auf none, was bedeutet, dass, wenn es eine zuvor gesetzte, nicht abgelaufene Einlsungsaufzeichnung fr diesen Benutzer und diese Website gibt, diese Einlsungsaufzeichnung verwendet werden sollte und keine neue erstellt werden sollte. Wenn wir refreshPolicy: "refresh" setzen, wrde immer eine neue Einlsungsaufzeichnung erstellt werden. Beachten Sie, dass none der Standardwert ist, da dies das Verhalten ist, das Sie in den meisten Fllen mchten, aber wir wollten darauf aufmerksam machen.

Im Hintergrund sendet der Browser das Token (zusammen mit relevanten Einlsungsmetadaten) in einem Sec-Private-State-Token-Request-Header. Der Redeemer sendet dann eine Einlsungsaufzeichnung in einem Sec-Private-State-Token-Response-Header, um eine Einlsungsbescheinigung zu geben, die verwendet werden kann, um Benutzervetrauen zu bermitteln. Die Einlsungsaufzeichnung wird in einem sicheren Datenspeicher gespeichert, der nicht direkt ber JavaScript zugnglich ist.

Zustzlich kann der Redeemer einen Sec-Private-State-Token-Lifetime-Header in die Antwort einfgen, um dem Browser anzuzeigen, wie lange (in Sekunden) die Einlsungsaufzeichnung zwischengespeichert werden soll. Wenn der Sec-Private-State-Token-Lifetime-Header weggelassen wird, wird die Lebensdauer der Einlsungsaufzeichnung an die Lebensdauer des Token-Verifikationsschlssels gekoppelt, der die Ausgabe des eingelsten Tokens besttigt hat.

Einschrnkungen bei Einlsungsaufzeichnungen

Zwei Tokens knnen alle 48 Stunden pro Gert, Seite und Issuer eingelst werden.

Die resultierenden Einlsungsaufzeichnungen gelten bis zum Ablauf (wie im Sec-Private-State-Token-Lifetime-Response-Header angegeben) als aktiv.

Nutzung der Einlsungsaufzeichnung

Sobald der Browser die Einlsungsaufzeichnung erhalten hat, kann sie als Vertrauenssignal fr den aktuellen Benutzer in anderen Kontexten verwendet werden, beispielsweise wenn man ihm erlaubt, eine sensible Aktion wie das Anmelden, den Kauf eines Produkts oder das Posten eines Kommentars auszufhren.

Dieses Vertrauenssignal kann an andere Parteien weitergegeben werden, um Vertrauen weiterzugeben. Um dies zu tun, schlieen Sie eine privateToken-Option in Fetch-Aufrufe fr zuknftige Ressourcen ein, mit der operation auf send-redemption-record:

const hasRR = await Document.hasRedemptionRecord(`issuer.example`);
if (hasRR) {
  await fetch("some-resource.example", {
    method: "POST",
    privateToken: {
      version: 1,
      operation: "send-redemption-record",
      issuers: ["https://issuer.example"],
    },
  });
}

Die send-redemption-record-Token-Operation ist nur verfgbar bei fetch()-Aufrufen, die im Top-Level-Dokument gemacht werden.

Wir setzen auch die issuers-Eigenschaft auf [issuer.example], was spezifiziert, von welchem Issuer wir erwarten, dass die Einlsungsaufzeichnung stammt. Wenn keine Einlsungsaufzeichnungen fr die angegebenen Issuer verfgbar sind, wird der Anforderungs-Header leer sein. Beachten Sie, wie Sie die Methode Document.hasRedemptionRecord() verwenden knnen, um zu berprfen, ob der Browser eine Einlsungsaufzeichnung hat, die von einem bestimmten Issuer stammt, bevor Sie versuchen, sie weiterzugeben.

Im Hintergrund werden die Einlsungsaufzeichnungen in einem Sec-Redemption-Record-Anforderungs-Header enthalten sein. Der Header enthlt eine Liste von Issuer- und Einlsungsaufzeichnungspaaren, die jeder Einlsungsaufzeichnung entsprechen.

Integration in die Berechtigungsrichtlinie

token-request-Operationen werden durch die private-state-token-issuance-Permissions-Policy-Direktive kontrolliert, whrend token-redemption- und send-redemption-record-Operationen durch die private-state-token-redemption-Direktive kontrolliert werden. Die Allowlist fr diese Direktiven ist standardmig auf * (alle Herknfte) gesetzt. Das bedeutet, dass die Funktion fr die oberste Seite, gleichherkunftsbezogene <iframe>-Elemente und fremdherkunftsbezogene <iframe>-Elemente ohne explizite Delegation verfgbar ist.

Sie knnen die Token-Ausgabe oder -Einlsung fr bestimmte Seiten auf Ihrer Website ablehnen, indem Sie private-state-token-issuance=() und private-state-token-redemption=() in den Permissions-Policy-Header fr jede Seite einschlieen.

Sie knnen auch den Permissions-Policy-Header verwenden, um den Zugriff Dritter auf Token-Operationen zu steuern. Verwenden Sie als Parameter zur Kopfzeilen-Herkuftsliste self und alle Herknfte, denen Sie den Zugang zur API erlauben mchten. Zum Beispiel, um die Verwendung von privaten Zustandstokens in allen Browsing-Kontexten auer Ihrer eigenen Herkunft und https://example.com vollstndig zu deaktivieren, setzen Sie den folgenden HTTP-Response-Header:

Permissions-Policy: private-state-token-issuance=(self "https://example.com"), private-state-token-redemption=(self "https://example.com")

Um die API fr alle fremden Ressourcen zu aktivieren, setzen Sie die Herkuftsliste auf *.

Obwohl die Standard-Politik * ist, muss ein <iframe> dennoch die Direktiven private-state-token-issuance und private-state-token-redemption in seinem Allow-Attribut enthalten, um Zugriff auf die Funktion zu erhalten. Zum Beispiel, um beide Funktionen auf example.com zuzulassen:

<iframe
  src="https://example.com"
  allow="private-state-token-issuance 'self';
  private-state-token-redemption 'self'">
</iframe>