Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
API Gateway HTTP Oblivious Safe Browsing
Catatan: Dokumentasi ini saat ini masih dalam pengembangan. Diperkirakan peningkatan dalam waktu dekat.
Safe Browsing Oblivious HTTP Gateway API adalah API perlindungan privasi yang dibuat berdasarkan protokol RFC IETF bernama Oblivious HTTP, RFC 9458.
Ringkasan
Safe Browsing Oblivious HTTP Gateway API adalah layanan Google yang memungkinkan aplikasi klien memeriksa URL berdasarkan daftar resource web tidak aman yang terus diperbarui Google dengan perlindungan privasi tambahan.
Hal ini dilakukan melalui protokol ringan yang disebut Oblivious HTTP, atau disingkat OHTTP. Ini adalah protokol stateless yang dapat digunakan oleh klien Safe Browsing untuk mengakses API Google Safe Browsing V5 guna mendapatkan perlindungan yang tangguh dan cakupan yang lebih baik tanpa mengorbankan privasi.
Oblivious HTTP adalah protokol ringan yang didefinisikan dalam RFC 9458, yang digunakan untuk mengenkripsi dan mengirim pesan HTTP dari klien ke server target. Hal ini menggunakan layanan relai tepercaya dengan cara yang mengurangi penggunaan metadata server target seperti alamat IP dan informasi koneksi untuk identifikasi klien, sehingga memberikan privasi dan keamanan selain protokol HTTP/S biasa. Protokol ini menggunakan Binary HTTP, yang didefinisikan dalam RFC 9292, untuk mengenkode/mendekode permintaan/respons HTTP.
Pada tingkat yang tinggi, Relay berada di antara resource Klien dan Gateway yang melakukan proxy pada traffic klien dengan menghapus semua ID klien, termasuk atribut sensitif privasi seperti alamat IP, yang secara efektif menganonimkan permintaan HTTP yang masuk ke layanan Gateway. Manfaat tambahan dari OHTTP adalah semua permintaan
dienkripsi end-to-end, yang berarti klien Kueri Safe Browsing (yaitu hash ekspresi URL yang terpotong) tidak terlihat oleh Relay. Lihat blogpost untuk mengetahui contoh implementasi di Chrome.
Fig: Alur OHTTP.
Klien dapat memilih penyedia Relay (misalnya, Fastly) untuk berintegrasi dengan layanan. Relay harus menggunakan autentikasi Oauth 2.0 dengan cakupan otorisasi berikut untuk mengakses layanan.
Endpoint ini akan menyediakan konfigurasi kunci publik OHTTP seperti yang ditentukan dalam RFC 9458, yang akan digunakan oleh klien untuk mengenkripsi permintaan OHTTP.
GET https://safebrowsingohttpgateway.googleapis.com/v1/ohttp/hpkekeyconfig?key=<API key>
Kunci API di atas tidak sepenuhnya diperlukan; server tidak memvariasikan Kunci Publik OHTTP berdasarkan kunci API yang diberikan. Klien diizinkan untuk menyelidiki fakta ini dengan menggunakan kunci API valid yang berbeda untuk mengakses endpoint ini atau tidak menggunakan kunci API sama sekali, dan memeriksa apakah respons memang berisi kunci publik OHTTP yang sama. Namun, untuk memudahkan proses debug, sebaiknya gunakan kunci API; Dengan demikian, klien dapat melihat statistik seperti jumlah permintaan pada Konsol Google Cloud. Jika klien ingin memberikan kunci API, lihat dokumentasi ini tentang cara menyiapkan kunci API.
Seperti yang dinyatakan di bagian rekomendasi privasi, untuk memenuhi sasaran konsistensi kunci, vendor Klien sebaiknya menyiapkan infrastruktur distribusi kunci terpusat untuk mengambil kunci dari endpoint ini, lalu mendistribusikannya ke aplikasi klien mereka.
Sesuai dengan panduan pengelolaan kunci, kunci dirotasi secara berkala di server. Klien harus selalu me-refresh kunci, yaitu sesekali mengambil dan mengupdate salinan lokal kunci untuk menghindari kegagalan dekripsi.
Klien harus memuat ulang (mengambil dan memperbarui) kunci publik sekali sehari. Jika mekanisme distribusi terpusat digunakan, mekanisme ini harus memastikan untuk mengambil dan mendistribusikan kunci sekali sehari.
Permintaan Enkapsulasi OHTTP
Endpoint ini akan menyalurkan permintaan OHTTP yang disertakan dalam isi HTTP permintaan POST, dengan melakukan dekripsi permintaan, lalu mengenkripsi respons OHTTP untuk diteruskan kembali ke Relay dalam respons HTTP. Klien harus menyertakan header permintaan Content-Type sebagai message/ohttp-req dalam permintaan HTTP POST.
POST https://safebrowsingohttpgateway.googleapis.com/v1/ohttp:handleOhttpEncapsulatedRequest?key=<API key>
CATATAN: Sesuai dengan panduan di RFC, enkode permintaan internal (lihat dokumentasi V5 tentang cara membuat permintaan Safe Browsing) menggunakan protokol HTTP Biner, RFC 9292.
Library Klien
Google Quiche memiliki implementasi sisi klien untuk protokol OHTTP dan BHTTP. Klien direkomendasikan untuk menggunakan library ini. Lihat kode semu di bawah tentang cara membangun permintaan OHTTP untuk mengakses API.
Contoh implementasi sisi klien
Klien mengambil kunci publik HTTP Oblivious dari endpoint public key. Selanjutnya, lakukan inisialisasi konfigurasi kunci OHTTP quiche seperti itu, dan lakukan inisialisasi klien 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);
Klien akan menggunakan encoding HTTP Biner untuk membuat Permintaan BHTTP sebagai langkah pertama sebelum mengenkripsi.
Selanjutnya, klien akan mengenkripsi permintaan HTTP Biner yang dibuat pada langkah di atas.
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();
Setelah respons diterima dari Relay, klien akan mendekripsi respons tersebut. Respons akan menyertakan header respons Content-Type sebagai ohttp-res.
auto ctx = std::move(ohttp_request).ReleaseContext();
auto ohttp_response = ohttp_client.DecryptObliviousHttpResponse("data included in body of http_response", ctx);
Setelah berhasil mendekripsi respons OHTTP, lakukan dekode output menggunakan Binary HTTP seperti itu.
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,["Terakhir diperbarui pada 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 }"]]
