Organiza tus páginas con colecciones
Guarda y categoriza el contenido según tus preferencias.
API de Safe Browsing de HTTP Gateway
Nota: Esta documentación aún está en desarrollo. Se esperan mejoras próximamente.
La API de Oblivious HTTP Gateway para la Navegación segura es una API que preserva la privacidad basada en el protocolo IETF RFC llamado Oblivious HTTP (HTTP Oblivious) de RFC 9458.
Descripción general
La API de Oblivious HTTP Gateway de la Navegación segura es un servicio de Google que permite que las aplicaciones cliente verifiquen las URLs con las listas de Google de recursos web no seguros, las cuales se actualizan constantemente y cuentan con protecciones de privacidad adicionales.
Esto se logra a través de un protocolo ligero llamado Oblivious HTTP (Oblivious HTTP) u OHTTP para abreviar. Este es un protocolo sin estado que los clientes de Navegación segura pueden usar para acceder a las APIs de Navegación segura de Google V5 para obtener protecciones sólidas y una mayor cobertura sin comprometer la seguridad de los usuarios. la privacidad.
HTTP obvia es un protocolo ligero definido en RFC 9458, que se usa para encriptar y enviar mensajes HTTP de un cliente a un servidor de destino. Utiliza un servicio de retransmisión confiable de una manera que mitiga el uso de metadatos del servidor de destino, como la dirección IP y la información de conexión, para la identificación del cliente, lo que proporciona privacidad y seguridad además del protocolo HTTP/S simple. El protocolo usa HTTP binario, definido en RFC 9292, para codificar y decodificar solicitudes o respuestas HTTP.
En un nivel alto, un Relay se interpone entre el cliente y el recurso de la puerta de enlace que actúa como proxy para el tráfico del cliente quitando todos los identificadores del cliente, incluidos los atributos sensibles a la privacidad, como las direcciones IP, y anonimiza de manera eficaz las solicitudes HTTP entrantes al servicio de la puerta de enlace. El beneficio adicional de OHTTP es que todas las solicitudes están encriptadas de extremo a extremo, lo que significa que las solicitudes Relay no puede ver las consultas de Navegación segura (es decir, hashes truncados de expresiones de URL). Consulta la blogpost para ver un ejemplo de implementación en Chrome.
Fig: Flujo de OHTTP.
Los clientes pueden elegir cualquier proveedor de Relay (p. ej., Fastly) para integrar el servicio. Para acceder al servicio, el Relay debe usar la autenticación Oauth 2.0 con el siguiente permiso de autorización.
GET https://safebrowsingohttpgateway.googleapis.com/v1/ohttp/hpkekeyconfig?key=<API key>
La clave de API anterior no es estrictamente necesaria. El servidor no modifica la clave pública de OHTTP en función de la clave de API proporcionada. Los clientes pueden comprobar esto usando diferentes claves de API válidas para acceder a este extremo o sin usar claves de API por completo, y verificando que la respuesta efectivamente contenga la misma clave pública de OHTTP. Sin embargo, para facilitar la depuración, se recomienda usar una clave de API. Esto permite a los clientes ver estadísticas, como la cantidad de solicitudes en la consola de Google Cloud. Si el cliente desea proporcionar una clave de API, consulta esta documentación sobre cómo configurarlas.
Como se indica en la sección de recomendaciones de privacidad, para cumplir con los objetivos de coherencia de claves, se recomienda a los proveedores de clientes que configuren una infraestructura de distribución de claves centralizada para recuperar la clave de este extremo y, luego, distribuirla a sus aplicaciones cliente.
Según la guía de administración de claves, las claves se rotan con regularidad en el servidor. Los clientes deben actualizar la clave, es decir, recuperar y actualizar la copia local de la clave de vez en cuando para evitar errores de desencriptación.
Los clientes deben actualizar (recuperar y actualizar) la clave pública una vez al día. Si se utiliza un mecanismo de distribución centralizada, este mecanismo debe asegurarse de recuperar y distribuir las claves una vez al día.
Solicitud encapsulada de OHTTP
Este extremo entregará la solicitud OHTTP que se incluye en el cuerpo HTTP de la solicitud POST mediante la desencriptación de la solicitud y, luego, encriptará la respuesta OHTTP para que se reenvíe a Relay en la respuesta HTTP. El cliente debe incluir el encabezado de la solicitud Content-Type como message/ohttp-req en la solicitud HTTP POST.
POST https://safebrowsingohttpgateway.googleapis.com/v1/ohttp:handleOhttpEncapsulatedRequest?key=<API key>
NOTA: Según la guía sobre RFC, codifica la solicitud interna (consulta la documentación de V5 sobre cómo crear una solicitud de Navegación segura) con el protocolo HTTP binario, RFC 9292.
Bibliotecas cliente
Google Quiche tiene implementaciones del lado del cliente para los protocolos OHTTP y BHTTP. Se recomienda que los clientes usen estas bibliotecas. Consulta el siguiente seudocódigo sobre cómo crear solicitudes OHTTP para acceder a la API.
Ejemplo de implementación del lado del cliente
Los clientes recuperan la clave pública HTTP Oblivious desde el extremo de clave pública. Luego, inicializa la configuración de la clave de OHTTP de quiche de esta manera y, luego, inicializa el cliente de OHTTP de 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);
El cliente usará la codificación HTTP binaria para crear una solicitud BHTTP como primer paso antes de la encriptación.
El Cliente encriptará luego la solicitud HTTP Binaria creada en el paso anterior.
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();
Una vez que se reciba la respuesta de Relay, el cliente la desencriptará. La respuesta incluirá el encabezado de respuesta Content-Type como ohttp-res.
auto ctx = std::move(ohttp_request).ReleaseContext();
auto ohttp_response = ohttp_client.DecryptObliviousHttpResponse("data included in body of http_response", ctx);
Después de desencriptar la respuesta de OHTTP correctamente, decodifica el resultado con HTTP binario de esta manera.
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,["Última actualización: 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 }"]]
