Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang
Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.
Safe Browsing Oblivious HTTP Gateway API
Lưu ý: Tài liệu này hiện vẫn đang trong quá trình phát triển. Chúng tôi dự kiến sẽ cải thiện tính năng này trong thời gian sắp tới.
Safe Browsing Oblivious HTTP Gateway API là một API bảo đảm quyền riêng tư, được xây dựng dựa trên giao thức RFC của IETF có tên là Oblivious HTTP, RFC 9458.
Tổng quan
Safe Browsing Oblivious HTTP Gateway API là một dịch vụ của Google cho phép các ứng dụng khách kiểm tra URL dựa trên danh sách các tài nguyên web không an toàn được cập nhật liên tục của Google có các biện pháp bảo vệ quyền riêng tư bổ sung được áp dụng.
Việc này được thực hiện thông qua một giao thức gọn nhẹ có tên là Oblivious HTTP (HTTP Oblivious HTTP) hoặc gọi tắt là OHTTP. Đây là giao thức phi trạng thái mà các ứng dụng Duyệt web an toàn có thể sử dụng để truy cập vào Google Safe Browsing V5 API, nhằm có được các biện pháp bảo vệ mạnh mẽ và mở rộng phạm vi bảo vệ mà không ảnh hưởng đến người dùng quyền riêng tư.
Giao thức HTTP Oblivious của tính năng Duyệt web an toàn
Giao thức RFC
Oblivious HTTP là một giao thức nhẹ được xác định trong RFC 9458, dùng để mã hoá và gửi thông báo HTTP từ máy khách đến máy chủ đích. Tính năng này sử dụng dịch vụ chuyển tiếp đáng tin cậy theo cách giảm thiểu việc máy chủ đích sử dụng siêu dữ liệu, chẳng hạn như địa chỉ IP và thông tin kết nối để nhận dạng ứng dụng khách, đảm bảo quyền riêng tư và tính bảo mật so với giao thức HTTP/S thuần tuý. Giao thức sử dụng HTTP nhị phân, được xác định trong RFC 9292, để mã hoá/giải mã các yêu cầu/phản hồi HTTP.
Ở cấp độ cao, Relay đứng giữa tài nguyên Ứng dụng và Cổng vào để proxy lưu lượng truy cập ứng dụng khách bằng cách xoá tất cả giá trị nhận dạng ứng dụng khách, bao gồm cả các thuộc tính nhạy cảm về quyền riêng tư như địa chỉ IP, ẩn danh hiệu quả các yêu cầu HTTP gửi đến dịch vụ Cổng vào. Lợi ích bổ sung của OHTTP là tất cả các yêu cầu đều được mã hoá hai đầu, có nghĩa là yêu cầu của khách hàng Truy vấn Duyệt web an toàn (tức là hàm băm bị cắt bớt của biểu thức URL) không hiển thị với Relay. Tham khảo blogpost này để xem ví dụ về cách triển khai trong Chrome.
Hình: Quy trình OHTTP.
Khách hàng có thể chọn bất kỳ nhà cung cấp dịch vụ Chuyển tiếp nào (ví dụ: Fastly) để tích hợp với dịch vụ. Trình chuyển tiếp phải sử dụng phương thức xác thực Oauth 2.0 với phạm vi cấp phép sau để truy cập dịch vụ.
GET https://safebrowsingohttpgateway.googleapis.com/v1/ohttp/hpkekeyconfig?key=<API key>
Khoá API ở trên không hoàn toàn cần thiết; máy chủ không thay đổi Khoá công khai OHTTP dựa trên khoá API đã cung cấp. Ứng dụng được phép thăm dò thực tế này bằng cách sử dụng nhiều khoá API hợp lệ để truy cập vào điểm cuối này hoặc không sử dụng hoàn toàn khoá API nào, đồng thời kiểm tra để đảm bảo phản hồi thực sự chứa cùng một khoá công khai OHTTP. Tuy nhiên, để dễ dàng gỡ lỗi, bạn nên dùng khoá API; việc này cho phép khách hàng xem số liệu thống kê, chẳng hạn như số lượng yêu cầu trên Google Cloud Console. Nếu ứng dụng khách định cung cấp khoá API, hãy tham khảo tài liệu này về cách thiết lập khoá API.
Như đã nêu trong phần đề xuất về quyền riêng tư, để đáp ứng các mục tiêu về tính nhất quán của khoá, nhà cung cấp khách hàng nên thiết lập cơ sở hạ tầng phân phối khoá tập trung để tìm nạp khoá từ điểm cuối này rồi phân phối khoá cho các ứng dụng khách.
Theo hướng dẫn quản lý khoá, các khoá được xoay vòng thường xuyên trên máy chủ. Ứng dụng nên làm mới khoá (tức là tìm nạp và cập nhật bản sao cục bộ của khoá thường xuyên) để tránh lỗi giải mã.
Ứng dụng nên làm mới (tìm nạp và cập nhật) khoá công khai mỗi ngày một lần. Nếu bạn đang sử dụng cơ chế phân phối tập trung, thì cơ chế này phải đảm bảo tìm nạp và phân phối khoá một lần mỗi ngày.
Yêu cầu OHTTP được đóng gói
Điểm cuối này sẽ phân phát yêu cầu OHTTP có trong phần nội dung HTTP của yêu cầu POST, bằng cách giải mã yêu cầu, sau đó mã hoá phản hồi OHTTP để được chuyển tiếp trở lại Chuyển tiếp trong phản hồi HTTP. Ứng dụng phải bao gồm tiêu đề yêu cầu Content-Type dưới dạng message/ohttp-req trong yêu cầu POST qua HTTP.
POST https://safebrowsingohttpgateway.googleapis.com/v1/ohttp:handleOhttpEncapsulatedRequest?key=<API key>
LƯU Ý: Theo hướng dẫn về RFC, hãy mã hoá yêu cầu bên trong (tham khảo tài liệu phiên bản V5 về cách xây dựng yêu cầu Duyệt web an toàn) bằng giao thức HTTP nhị phân, RFC 9292.
Thư viện ứng dụng
Google Quiche có các biện pháp triển khai phía máy khách cho cả giao thức OHTTP và BHTTP. Ứng dụng nên sử dụng các thư viện này. Hãy tham khảo đoạn mã giả dưới đây để biết cách xây dựng các yêu cầu OHTTP để truy cập API.
Triển khai phía máy khách mẫu
Các ứng dụng tìm nạp khoá công khai HTTP Oblivious từ điểm cuối khoá công khai. Sau đó, hãy khởi chạy cấu hình khoá OHTTP quiche như vậy và khởi chạy ứng dụng OHTTP 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);
Ứng dụng khách sẽ sử dụng phương thức mã hoá HTTP nhị phân để tạo Yêu cầu BHTTP làm bước đầu tiên trước khi mã hoá.
Sau đó, Ứng dụng sẽ mã hoá yêu cầu HTTP nhị phân được tạo ở bước trên.
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();
Sau khi nhận được phản hồi từ Relay, ứng dụng sẽ giải mã phản hồi đó. Phản hồi sẽ bao gồm tiêu đề phản hồi Content-Type dưới dạng ohttp-res.
auto ctx = std::move(ohttp_request).ReleaseContext();
auto ohttp_response = ohttp_client.DecryptObliviousHttpResponse("data included in body of http_response", ctx);
Sau khi giải mã phản hồi OHTTP thành công, hãy giải mã đầu ra bằng HTTP nhị phân như vậy.
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,["Cập nhật lần gần đây nhất: 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 }"]]
