Mit Sammlungen den Überblick behalten
Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Safe Browsing Oblivious HTTP Gateway API
Hinweis: Diese Dokumentation befindet sich noch in der Entwicklungsphase. Verbesserungen sind schon in naher Zukunft zu erwarten.
Die Safe Browsing Oblivious HTTP Gateway API ist eine datenschutzfreundliche API, die auf dem IETF-RFC-Protokoll namens Oblivious HTTP, RFC 9458, aufbaut.
Übersicht
Die Safe Browsing Oblivious HTTP Gateway API ist ein Google-Dienst, mit dem Client-Anwendungen URLs mit den fortlaufend aktualisierten Google-Listen unsicherer Webressourcen abgleichen können, wobei zusätzliche Datenschutzmaßnahmen implementiert sind.
Dazu wird ein einfaches Protokoll namens Oblivious HTTP, kurz OHTTP, verwendet. Dies ist ein zustandsloses Protokoll, das von Safe Browsing-Clients verwendet werden kann, um auf Google Safe Browsing V5 APIs zuzugreifen, um robuste Schutzmaßnahmen und eine erhöhte Abdeckung zu erhalten, ohne die Nutzer zu gefährden. Datenschutz.
Oblivious HTTP ist ein in RFC 9458 definiertes einfaches Protokoll, das zum Verschlüsseln und Senden von HTTP-Nachrichten von einem Client an einen Zielserver verwendet wird. Dabei wird ein vertrauenswürdiger Relay-Dienst auf eine Weise verwendet, die die Verwendung von Metadaten wie IP-Adresse und Verbindungsinformationen durch den Zielserver zur Client-Identifizierung verringert und neben dem einfachen HTTP/S-Protokoll Datenschutz und Sicherheit bietet. Das Protokoll verwendet binäres HTTP (in RFC 9292 definiert), um HTTP-Anfragen/-Antworten zu codieren/decodieren.
Allgemein steht ein Relay zwischen der Client- und Gateway-Ressource, die den Clienttraffic weiterleitet. Dazu werden alle Clientkennungen entfernt, einschließlich datenschutzsensibler Attribute wie IP-Adressen, wodurch eingehende HTTP-Anfragen an den Gateway-Dienst effektiv anonymisiert werden. Der zusätzliche Vorteil von OHTTP ist, dass alle Anfragen Ende-zu-Ende-verschlüsselt sind. Das bedeutet, dass die Safe Browsing-Abfragen (d.h. abgeschnittene Hashes von URL-Ausdrücken) sind für das Relay nicht sichtbar. blogpost finden Sie ein Beispiel für eine Implementierung in Chrome.
Abbildung: OHTTP-Ablauf.
Kunden können einen beliebigen Relay-Anbieter auswählen (z. B. Fastly) in den Dienst integriert werden. Das Relay muss die Oauth 2.0-Authentifizierung mit dem folgenden Autorisierungsbereich verwenden, um auf den Dienst zugreifen zu können.
GET https://safebrowsingohttpgateway.googleapis.com/v1/ohttp/hpkekeyconfig?key=<API key>
Der obige API-Schlüssel ist nicht unbedingt erforderlich. Der Server variiert den öffentlichen OHTTP-Schlüssel nicht basierend auf dem bereitgestellten API-Schlüssel. Clients können dies überprüfen, indem sie verschiedene gültige API-Schlüssel für den Zugriff auf diesen Endpunkt verwenden oder vollständig keine API-Schlüssel verwenden und prüfen, ob die Antwort tatsächlich denselben öffentlichen OHTTP-Schlüssel enthält. Zur Vereinfachung der Fehlerbehebung wird jedoch ein API-Schlüssel empfohlen. So können sich Clients Statistiken wie die Anzahl der Anfragen in der Google Cloud Console ansehen. Wenn der Client einen API-Schlüssel bereitstellen möchte, finden Sie in dieser Dokumentation Informationen zum Einrichten von API-Schlüsseln.
Wie im Abschnitt Datenschutzempfehlungen beschrieben, wird den Kundenanbietern empfohlen, eine zentrale Infrastruktur für die Schlüsselverteilung einzurichten, um die Ziele für Schlüsselkonsistenz zu erreichen. So kann der Schlüssel von diesem Endpunkt abgerufen und anschließend an ihre Clientanwendungen verteilt werden.
Gemäß der Anleitung zur Schlüsselverwaltung werden die Schlüssel regelmäßig auf dem Server rotiert. Clients sollten den Schlüssel aktualisieren, d.h. die lokale Kopie des Schlüssels in regelmäßigen Abständen abrufen und aktualisieren, um Entschlüsselungsfehler zu vermeiden.
Clients sollten den öffentlichen Schlüssel einmal täglich aktualisieren (abrufen und aktualisieren). Wenn ein zentraler Verteilungsmechanismus verwendet wird, sollte mit diesem Mechanismus sichergestellt werden, dass die Schlüssel einmal pro Tag abgerufen und verteilt werden.
Gekapselte OHTTP-Anfrage
Dieser Endpunkt verarbeitet die OHTTP-Anfrage, die im HTTP-Text der POST-Anfrage enthalten ist, indem er die Anfrage entschlüsselt und anschließend die OHTTP-Antwort verschlüsselt, damit sie in der HTTP-Antwort an Relay zurückgesendet wird. Der Client muss den Anfrageheader Content-Type als message/ohttp-req in die HTTP-POST-Anfrage aufnehmen.
POST https://safebrowsingohttpgateway.googleapis.com/v1/ohttp:handleOhttpEncapsulatedRequest?key=<API key>
HINWEIS: Codieren Sie die innere Anfrage gemäß den RFC-Richtlinien mit dem Binär-HTTP-ProtokollRFC 9292. Informationen zum Erstellen einer Safe Browsing-Anfrage finden Sie in der V5-Dokumentation.
Clientbibliotheken
Google Quiche bietet clientseitige Implementierungen für OHTTP- und BHTTP-Protokolle. Es wird empfohlen, für Clients diese Bibliotheken zu verwenden. Unten finden Sie den Pseudocode zum Erstellen von OHTTP-Anfragen für den Zugriff auf die API.
Beispiel für eine clientseitige Implementierung
Clients rufen den öffentlichen HTTP-Schlüssel von Oblivious HTTP vom Endpunkt des öffentlichen Schlüssels ab. Initialisieren Sie anschließend die OHTTP-Schlüsselkonfiguration für die Quiche und dann den OHTTP-Client für die Quiche.
auto ohttp_key_cfgs = quiche::ObliviousHttpKeyConfigs::ParseConcatenatedKeys(std::string public_key);
auto key_config = ohttp_key_cfgs->PreferredConfig();
auto public_key = ohttp_key_cfgs->GetPublicKeyForId(key_config.GetKeyId())
auto ohttp_client = quiche::ObliviousHttpClient::Create(public_key, key_config);
Der Client verwendet als ersten Schritt vor der Verschlüsselung die HTTP-Binärcodierung, um die BHTTP-Anfrage zu erstellen.
Der Client verschlüsselt anschließend die im obigen Schritt erstellte binäre HTTP-Anfrage.
auto bhttp_serialized = bhttp_request.Serialize();
auto ohttp_request = ohttp_client.CreateObliviousHttpRequest(*bhttp_serialized);
// Client must include this in POST body, and add `Content-Type` header as "message/ohttp-req".
auto payload_include_in_post_body = ohttp_request.EncapsulateAndSerialize();
Sobald die Antwort von Relay eingegangen ist, entschlüsselt der Client sie. Die Antwort enthält den Antwortheader Content-Type im Format ohttp-res.
auto ctx = std::move(ohttp_request).ReleaseContext();
auto ohttp_response = ohttp_client.DecryptObliviousHttpResponse("data included in body of http_response", ctx);
Nachdem Sie die OHTTP-Antwort erfolgreich entschlüsselt haben, decodieren Sie die Ausgabe mit binärem HTTP wie hier gezeigt.
auto bhttp_response = BinaryHttpResponse::Create(ohttp_response.GetPlaintextData());
if (bhttp_response.status_code() == 200) {
auto http_response = bhttp_response.body();
auto response_headers = bhttp_response.GetHeaderFields();
}
[null,null,["Zuletzt aktualisiert: 2025-07-25 (UTC)."],[[["\u003cp\u003eSafe Browsing Oblivious HTTP Gateway API allows client applications to privately check URLs against Google's unsafe web resources lists using the Oblivious HTTP protocol.\u003c/p\u003e\n"],["\u003cp\u003eThis API leverages a Relay service to anonymize client requests to Google, enhancing privacy by hiding client identifiers like IP addresses.\u003c/p\u003e\n"],["\u003cp\u003eClients need to fetch and regularly update the OHTTP public key from a dedicated endpoint for encryption and decryption of requests and responses.\u003c/p\u003e\n"],["\u003cp\u003eThe API uses two endpoints: one for obtaining the OHTTP public key and another for handling encapsulated OHTTP requests.\u003c/p\u003e\n"],["\u003cp\u003eGoogle provides client libraries and sample code to facilitate integration with the API, recommending the use of Quiche for OHTTP and BHTTP functionalities.\u003c/p\u003e\n"]]],["\n\nI'm sorry, but I can't help you with this."],null,["# Overview\n\nSafe Browsing Oblivious HTTP Gateway API\n----------------------------------------\n\n**Note: This documentation is currently still under development. Expect improvements in the near future.**\n\nSafe Browsing Oblivious HTTP Gateway API is a privacy preserving API built on top of IETF RFC protocol named *Oblivious HTTP* , [RFC 9458](https://www.ietf.org/rfc/rfc9458.html).\n\n### Overview\n\nSafe Browsing Oblivious HTTP Gateway API is a Google service that lets client applications check URLs against Google's constantly updated lists of unsafe web resources with additional privacy protections in place.\n\nThis is achieved via a lightweight protocol called *Oblivious HTTP* , or [OHTTP](https://www.ietf.org/rfc/rfc9458.html) for short. This is a stateless protocol that can be used by Safe Browsing clients in order to access [*Google Safe Browsing V5* APIs](/safe-browsing/reference), to get robust protections and increased coverage without compromising users' privacy.\n\n**NOTE:** [Google Safe Browsing V4 APIs](https://developers.google.com/safe-browsing/v4) cannot be accessed via this service.\n\n#### Safe Browsing Oblivious HTTP protocol\n\n##### RFC Protocol\n\nOblivious HTTP is a lightweight protocol defined in [RFC 9458](https://www.ietf.org/rfc/rfc9458.html), used for encrypting and sending HTTP messages from a client to a target server. This uses a trusted relay service in a manner that mitigates the target server's use of metadata such as IP address and connection information for client identification, providing privacy and security on top of plain HTTP/S protocol. The protocol uses Binary HTTP, defined in RFC 9292, to encode/decode HTTP requests/responses.\n\nAt a high level, a Relay stands between the Client and Gateway resource that proxies client traffic by removing all client identifiers, including privacy sensitive attributes such as IP addresses, effectively anonymizing incoming HTTP requests to the Gateway service. The added benefit of OHTTP is all the requests are end-to-end encrypted, which means clients' Safe Browsing queries (i.e. truncated hashes of URL expressions) are not visible to the Relay. Refer to the [blogpost](https://security.googleblog.com/2024/03/blog-post.html) for an example implementation in Chrome.\n\n\u003cbr /\u003e\n\n**Fig**: OHTTP flow.\n\n\u003cbr /\u003e\n\nClients can choose any Relay provider (eg., [Fastly](https://docs.fastly.com/products/oblivious-http-relay)) to integrate with the service. The Relay must use [Oauth 2.0](https://developers.google.com/identity/protocols/oauth2/service-account#authorizingrequests) authentication with following *authorization scope* in order to access the service. \n\n\n // OAuth Authorization scope:\n https://www.googleapis.com/auth/3p-relay-safe-browsing\n\n##### API Endpoints\n\n###### OHTTP Public Key\n\nThis endpoint will provide [OHTTP public key configuration](https://www.ietf.org/rfc/rfc9458.html#name-key-configuration) as specified in [RFC 9458](https://www.ietf.org/rfc/rfc9458.html), which will be used by the client to encrypt OHTTP request. \n\n\n GET https://safebrowsingohttpgateway.googleapis.com/v1/ohttp/hpkekeyconfig?key=\u003cAPI key\u003e\n\nThe API key above is not strictly necessary; the server does *not* vary the OHTTP Public Key based on the supplied API key. It is allowed for clients to probe this fact by using different valid API keys to access this endpoint or using no API keys altogether, and checking that the response indeed contains the same OHTTP public key. However, for ease of debugging, an API key is recommended; this allows clients to view statistics such as number of requests on the Google Cloud Console. If the client intends to supply an API key, refer to this [documentation](https://cloud.google.com/docs/authentication/api-keys) on how to set up API keys.\n\nAs stated in the [privacy recommendations](https://www.ietf.org/rfc/rfc9458.html#name-privacy-considerations) section, in order to meet *key consistency* goals, Client vendors are recommended to set up a *centralized key distribution* infrastructure in order to fetch the key from this endpoint and subsequently distribute it to their client applications.\n\nAs per the [key management guidance](https://www.ietf.org/rfc/rfc9458.html#name-key-management), keys are rotated regularly on the server. Clients should refresh the key, i.e., fetch and update the local copy of the key every so often in order to avoid decryption failures.\n\nClients should refresh (fetch and update) the public key once per day. If a centralized distribution mechanism is in use, this mechanism should make sure to fetch and distribute the keys once per day.\n\n###### OHTTP Encapsulated Request\n\nThis endpoint will serve the OHTTP request that's included in HTTP body of the POST request, by performing request decryption, and subsequently encrypt the OHTTP response to be forwarded back to Relay in the HTTP response. The Client must include *Content-Type* request header as *message/ohttp-req* in the HTTP POST request. \n\n\n POST https://safebrowsingohttpgateway.googleapis.com/v1/ohttp:handleOhttpEncapsulatedRequest?key=\u003cAPI key\u003e\n\n**NOTE:** As per the guidance on RFC, encode the inner request (refer [V5 documentation](/safe-browsing/reference) on how to build Safe Browsing request) using *Binary HTTP* protocol, [RFC 9292](https://www.ietf.org/rfc/rfc9292.html).\n\n##### Client Libraries\n\n[Google Quiche](https://github.com/google/quiche) has client side implementations for both [OHTTP](https://github.com/google/quiche/tree/main/quiche/oblivious_http), and [BHTTP](https://github.com/google/quiche/tree/main/quiche/binary_http) protocols. Clients are recommended to use these libraries. Refer below pseudo-code on how to go about building OHTTP requests in order to access the API.\n\n###### Sample client side implementation\n\nClients fetch the Oblivious HTTP public key from the *public key* endpoint. Subsequently initialize the quiche OHTTP key config like so, and initialize quiche OHTTP client. \n\n\n auto ohttp_key_cfgs = quiche::ObliviousHttpKeyConfigs::ParseConcatenatedKeys(std::string public_key);\n auto key_config = ohttp_key_cfgs-\u003ePreferredConfig();\n auto public_key = ohttp_key_cfgs-\u003eGetPublicKeyForId(key_config.GetKeyId())\n auto ohttp_client = quiche::ObliviousHttpClient::Create(public_key, key_config);\n\nClient will use Binary HTTP encoding to create BHTTP Request as a first step before encrypting. \n\n\n quiche::BinaryHttpRequest::ControlData bhttp_ctrl_data{\n .method = \"POST\",\n .scheme = \"https\",\n .authority = \"safebrowsing.googleapis.com\",\n .path = \"/v5/hashes:search?key=\u003cAPI key\u003e&hashPrefixes=\u003cHASH prefix 1\u003e&hashPrefixes=\u003cHASH prefix 2\u003e\",\n };\n quiche::BinaryHttpRequest bhttp_request(bhttp_ctrl_data);\n\nClient will subsequently encrypt the Binary HTTP request created in the above step. \n\n\n auto bhttp_serialized = bhttp_request.Serialize();\n auto ohttp_request = ohttp_client.CreateObliviousHttpRequest(*bhttp_serialized);\n // Client must include this in POST body, and add `Content-Type` header as \"message/ohttp-req\".\n auto payload_include_in_post_body = ohttp_request.EncapsulateAndSerialize();\n\nOnce the response is received from Relay, client will decrypt the response. The response will include *Content-Type* response header as *ohttp-res*. \n\n\n auto ctx = std::move(ohttp_request).ReleaseContext();\n auto ohttp_response = ohttp_client.DecryptObliviousHttpResponse(\"data included in body of http_response\", ctx);\n\nAfter decrypting the OHTTP response successfully, decode the output using Binary HTTP like so. \n\n\n auto bhttp_response = BinaryHttpResponse::Create(ohttp_response.GetPlaintextData());\n if (bhttp_response.status_code() == 200) {\n auto http_response = bhttp_response.body();\n auto response_headers = bhttp_response.GetHeaderFields();\n }"]]
