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.
CATATAN: Google Safe Browsing V4 API tidak dapat diakses melalui layanan ini.
Protokol HTTP Oblivious Safe Browsing
Protokol RFC
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.
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.
// OAuth Authorization scope:
https://www.googleapis.com/auth/3p-relay-safe-browsing
Endpoint API
Kunci Publik OHTTP
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.
quiche::BinaryHttpRequest::ControlData bhttp_ctrl_data{
.method = "POST",
.scheme = "https",
.authority = "safebrowsing.googleapis.com",
.path = "/v5/hashes:search?key=<API key>&hashPrefixes=<HASH prefix 1>&hashPrefixes=<HASH prefix 2>",
};
quiche::BinaryHttpRequest bhttp_request(bhttp_ctrl_data);
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();
}