Halaman ini diterjemahkan oleh Cloud Translation API.

Overview

Catatan: Dokumentasi ini saat ini masih dalam pengembangan. Nantikan peningkatan dalam waktu dekat.

Google Safe Browsing v5 adalah evolusi dari Google Safe Browsing v4. Dua perubahan utama yang dilakukan di v5 adalah keaktualan data dan privasi IP. Selain itu, platform API telah ditingkatkan untuk meningkatkan fleksibilitas, efisiensi, dan mengurangi pemborosan. Selain itu, Google Safe Browsing v5 dirancang untuk memudahkan migrasi dari v4.

Saat ini, Google menawarkan v4 dan v5 dan keduanya dianggap siap produksi. Anda dapat menggunakan v4 atau v5. Kami belum mengumumkan tanggal penghentian v4; jika kami melakukannya, kami akan memberikan pemberitahuan minimum satu tahun. Halaman ini akan menjelaskan v5 serta panduan migrasi dari v4 ke v5; dokumentasi v4 lengkap tetap tersedia.

Keaktualan Data

Di v5, kami memperkenalkan mode operasi yang dikenal sebagai perlindungan real-time. Hal ini akan menghindari masalah data yang sudah tidak berlaku di atas. Di v4, klien diharapkan untuk mendownload dan mengelola database lokal, melakukan pemeriksaan terhadap daftar ancaman yang didownload secara lokal, lalu jika ada kecocokan awalan sebagian, lakukan permintaan untuk mendownload hash lengkap. Di v5, meskipun klien harus terus mendownload dan mengelola database lokal daftar ancaman, klien kini juga diharapkan untuk mendownload daftar situs yang kemungkinan tidak berbahaya (disebut Cache Global), melakukan pemeriksaan lokal untuk Cache Global ini serta pemeriksaan daftar ancaman lokal, dan terakhir, jika ada kecocokan awalan sebagian untuk daftar ancaman atau tidak ada kecocokan di Cache Global, lakukan permintaan untuk mendownload hash lengkap. (Untuk mengetahui detail tentang pemrosesan lokal yang diperlukan oleh klien, lihat prosedur yang diberikan di bawah.) Hal ini menunjukkan pergeseran dari izinkan secara default menjadi periksa secara default, yang dapat meningkatkan perlindungan mengingat penyebaran ancaman yang lebih cepat di web. Dengan kata lain, ini adalah protokol yang dirancang untuk memberikan perlindungan hampir real-time: kami ingin klien mendapatkan manfaat dari data Google Safe Browsing yang lebih baru.

Privasi IP

Google Safe Browsing (v4 atau v5) tidak memproses apa pun yang terkait dengan identitas pengguna selama proses penayangan permintaan. Cookie, jika dikirim, akan diabaikan. Alamat IP asal permintaan diketahui oleh Google, tetapi Google hanya menggunakan alamat IP untuk kebutuhan jaringan yang penting (yaitu untuk mengirim respons) dan untuk tujuan anti-DoS.

Bersamaan dengan v5, kami memperkenalkan API pendamping yang dikenal sebagai Safe Browsing Oblivious HTTP Gateway API. Hal ini menggunakan Oblivious HTTP untuk menyembunyikan alamat IP pengguna akhir dari Google. Cara kerjanya adalah dengan meminta pihak ketiga yang tidak berkolusi untuk menangani versi terenkripsi permintaan pengguna, lalu meneruskannya ke Google. Jadi, pihak ketiga hanya memiliki akses ke alamat IP, dan Google hanya memiliki akses ke konten permintaan. Pihak ketiga mengoperasikan Oblivious HTTP Relay (seperti layanan ini oleh Fastly), dan Google mengoperasikan Oblivious HTTP Gateway. Ini adalah API pengiring opsional. Jika digunakan bersama dengan Safe Browsing Google, alamat IP pengguna akhir tidak lagi dikirim ke Google.

Mode Operasi

Google Safe Browsing v5 memungkinkan klien memilih dari tiga mode operasi.

Mode Real-Time

Jika klien memilih untuk menggunakan Google Safe Browsing v5 dalam mode real-time, klien akan mempertahankan di database lokalnya: (i) Cache Global situs yang kemungkinan tidak berbahaya, yang diformat sebagai hash SHA256 dari ekspresi URL host-suffix/path-prefix, (ii) kumpulan daftar ancaman, yang diformat sebagai awalan hash SHA256 dari ekspresi URL host-suffix/path-prefix. Ide tingkat tinggi adalah setiap kali klien ingin memeriksa URL tertentu, pemeriksaan lokal akan dilakukan menggunakan Cache Global. Jika pemeriksaan tersebut lulus, pemeriksaan daftar ancaman lokal akan dilakukan. Jika tidak, klien akan melanjutkan dengan pemeriksaan hash real-time seperti yang dijelaskan di bawah.

Selain database lokal, klien akan mempertahankan cache lokal. Cache lokal tersebut tidak perlu berada dalam penyimpanan persisten dan dapat dihapus jika terjadi tekanan memori.

Spesifikasi mendetail tentang prosedur ini tersedia di bawah.

Mode Daftar Lokal

Saat klien memilih untuk menggunakan Google Safe Browsing v5 dalam mode ini, perilaku klien akan mirip dengan Update API v4, kecuali menggunakan platform API v5 yang ditingkatkan. Klien akan menyimpan kumpulan daftar ancaman yang diformat sebagai awalan hash SHA256 dari ekspresi URL awalan host/jalur di database lokal mereka. Setiap kali klien ingin memeriksa URL tertentu, pemeriksaan akan dilakukan menggunakan daftar ancaman lokal. Jika dan hanya jika ada kecocokan, klien akan terhubung ke server untuk melanjutkan pemeriksaan.

Seperti di atas, klien juga akan mempertahankan cache lokal yang tidak perlu berada dalam penyimpanan persisten.

Mode Real-Time Tanpa Penyimpanan

Jika klien memilih untuk menggunakan Google Safe Browsing v5 dalam mode real-time tanpa penyimpanan, klien tidak perlu mempertahankan database lokal persisten apa pun. Namun, klien masih diharapkan untuk mempertahankan cache lokal. Cache lokal tersebut tidak perlu berada dalam penyimpanan persisten dan dapat dihapus jika terjadi tekanan memori.

Setiap kali klien ingin memeriksa URL tertentu, klien selalu terhubung ke server untuk melakukan pemeriksaan. Mode ini mirip dengan yang dapat diterapkan klien Lookup API v4.

Dibandingkan dengan Mode Real-Time, mode ini mungkin menggunakan lebih banyak bandwidth jaringan, tetapi mungkin lebih cocok jika klien tidak dapat mempertahankan status lokal yang persisten.

Prosedur Pemeriksaan URL Real-Time

Prosedur ini digunakan saat klien memilih mode operasi real-time.

Prosedur ini menggunakan satu URL u dan menampilkan SAFE, UNSAFE, atau UNSURE. Jika menampilkan SAFE, URL dianggap aman oleh Google Safe Browsing. Jika menampilkan UNSAFE, URL dianggap berpotensi tidak aman oleh Google Safe Browsing dan tindakan yang sesuai harus dilakukan: seperti menampilkan peringatan kepada pengguna akhir, memindahkan pesan yang diterima ke folder spam, atau mewajibkan konfirmasi tambahan oleh pengguna sebelum melanjutkan. Jika menampilkan UNSURE, prosedur pemeriksaan lokal berikut harus digunakan setelahnya.

Anggap expressions adalah daftar ekspresi akhiran/awalan yang dihasilkan oleh URL u.
Anggap expressionHashes adalah daftar, dengan elemen berupa hash SHA256 dari setiap ekspresi di expressions.
Untuk setiap hash dari expressionHashes:
1. Jika hash dapat ditemukan di cache global, tampilkan UNSURE.
Anggap expressionHashPrefixes adalah daftar, dengan elemen adalah 4 byte pertama dari setiap hash di expressionHashes.
Untuk setiap expressionHashPrefix dari expressionHashPrefixes:
1. Cari expressionHashPrefix di cache lokal.
2. Jika entri yang di-cache ditemukan:
  1. Menentukan apakah waktu saat ini lebih besar dari waktu habis masa berlakunya.
  2. Jika lebih besar:
    1. Hapus entri yang di-cache yang ditemukan dari cache lokal.
    2. Lanjutkan dengan loop.
  3. Jika tidak lebih besar:
    1. Hapus expressionHashPrefix tertentu ini dari expressionHashPrefixes.
    2. Periksa apakah hash lengkap yang sesuai dalam expressionHashes ditemukan di entri yang di-cache.
    3. Jika ditemukan, tampilkan UNSAFE.
    4. Jika tidak ditemukan, lanjutkan dengan loop.
3. Jika entri yang di-cache tidak ditemukan, lanjutkan dengan loop.
Kirim expressionHashPrefixes ke server Google Safe Browsing v5 menggunakan SearchHashes RPC atau metode REST hashes.search. Jika terjadi error (termasuk error jaringan, error HTTP, dll.), tampilkan UNSURE. Jika tidak, biarkan respons menjadi response yang diterima dari server SB, yang merupakan daftar hash lengkap beserta beberapa informasi tambahan yang mengidentifikasi sifat ancaman (manipulasi psikologis, malware, dll.), serta waktu habis masa berlaku cache expiration.
Untuk setiap fullHash dari response:
1. Sisipkan fullHash ke dalam cache lokal, bersama dengan expiration.
Untuk setiap fullHash dari response:
1. Anggap isFound adalah hasil dari menemukan fullHash di expressionHashes.
2. Jika isFound bernilai Salah, lanjutkan dengan loop.
3. Jika isFound bernilai Benar, tampilkan UNSAFE.
Kembalikan SAFE.

Meskipun protokol ini menentukan kapan klien mengirim expressionHashPrefixes ke server, protokol ini sengaja tidak menentukan dengan tepat cara mengirimnya. Misalnya, klien dapat mengirim semua expressionHashPrefixes dalam satu permintaan, dan klien juga dapat mengirim setiap awalan di expressionHashPrefixes ke server dalam permintaan terpisah (mungkin dilanjutkan secara paralel). Klien juga dapat mengirim awalan hash yang tidak terkait atau dibuat secara acak bersama dengan awalan hash di expressionHashPrefixes, selama jumlah awalan hash yang dikirim dalam satu permintaan tidak melebihi 30.

Prosedur Pemeriksaan URL Daftar LocalThreat

Prosedur ini digunakan saat klien memilih mode operasi daftar lokal. Ini juga digunakan saat klien prosedur RealTimeCheck di atas menampilkan nilai UNSURE.

Prosedur ini menggunakan satu URL u dan menampilkan SAFE atau UNSAFE.

Anggap expressions adalah daftar ekspresi akhiran/awalan yang dihasilkan oleh URL u.
Anggap expressionHashes adalah daftar, dengan elemen berupa hash SHA256 dari setiap ekspresi di expressions.
Anggap expressionHashPrefixes adalah daftar, dengan elemen adalah 4 byte pertama dari setiap hash di expressionHashes.
Untuk setiap expressionHashPrefix dari expressionHashPrefixes:
1. Cari expressionHashPrefix di cache lokal.
2. Jika entri yang di-cache ditemukan:
  1. Menentukan apakah waktu saat ini lebih besar dari waktu habis masa berlakunya.
  2. Jika lebih besar:
    1. Hapus entri yang di-cache yang ditemukan dari cache lokal.
    2. Lanjutkan dengan loop.
  3. Jika tidak lebih besar:
    1. Hapus expressionHashPrefix tertentu ini dari expressionHashPrefixes.
    2. Periksa apakah hash lengkap yang sesuai dalam expressionHashes ditemukan di entri yang di-cache.
    3. Jika ditemukan, tampilkan UNSAFE.
    4. Jika tidak ditemukan, lanjutkan dengan loop.
3. Jika entri yang di-cache tidak ditemukan, lanjutkan dengan loop.
Untuk setiap expressionHashPrefix dari expressionHashPrefixes:
1. Cari expressionHashPrefix di database daftar ancaman lokal.
2. Jika expressionHashPrefix tidak dapat ditemukan di database daftar ancaman lokal, hapus dari expressionHashPrefixes.
Kirim expressionHashPrefixes ke server Google Safe Browsing v5 menggunakan SearchHashes RPC atau metode REST hashes.search. Jika terjadi error (termasuk error jaringan, error HTTP, dll.), tampilkan SAFE. Jika tidak, biarkan respons menjadi response yang diterima dari server SB, yang merupakan daftar hash lengkap beserta beberapa informasi tambahan yang mengidentifikasi sifat ancaman (manipulasi psikologis, malware, dll.), serta waktu habis masa berlaku cache expiration.
Untuk setiap fullHash dari response:
1. Sisipkan fullHash ke dalam cache lokal, bersama dengan expiration.
Untuk setiap fullHash dari response:
1. Anggap isFound adalah hasil dari menemukan fullHash di expressionHashes.
2. Jika isFound bernilai Salah, lanjutkan dengan loop.
3. Jika isFound bernilai Benar, tampilkan UNSAFE.
Kembalikan SAFE.

Prosedur Pemeriksaan URL Real-Time Tanpa Database Lokal

Prosedur ini digunakan saat klien memilih mode operasi real-time tanpa penyimpanan.

Prosedur ini menggunakan satu URL u dan menampilkan SAFE atau UNSAFE.

Anggap expressions adalah daftar ekspresi akhiran/awalan yang dihasilkan oleh URL u.
Anggap expressionHashes adalah daftar, dengan elemen berupa hash SHA256 dari setiap ekspresi di expressions.
Anggap expressionHashPrefixes adalah daftar, dengan elemen adalah 4 byte pertama dari setiap hash di expressionHashes.
Untuk setiap expressionHashPrefix dari expressionHashPrefixes:
1. Cari expressionHashPrefix di cache lokal.
2. Jika entri yang di-cache ditemukan:
  1. Menentukan apakah waktu saat ini lebih besar dari waktu habis masa berlakunya.
  2. Jika lebih besar:
    1. Hapus entri yang di-cache yang ditemukan dari cache lokal.
    2. Lanjutkan dengan loop.
  3. Jika tidak lebih besar:
    1. Hapus expressionHashPrefix tertentu ini dari expressionHashPrefixes.
    2. Periksa apakah hash lengkap yang sesuai dalam expressionHashes ditemukan di entri yang di-cache.
    3. Jika ditemukan, tampilkan UNSAFE.
    4. Jika tidak ditemukan, lanjutkan dengan loop.
3. Jika entri yang di-cache tidak ditemukan, lanjutkan dengan loop.
Kirim expressionHashPrefixes ke server Google Safe Browsing v5 menggunakan SearchHashes RPC atau metode REST hashes.search. Jika terjadi error (termasuk error jaringan, error HTTP, dll.), tampilkan SAFE. Jika tidak, biarkan respons adalah response yang diterima dari server SB, yang merupakan daftar hash lengkap beserta beberapa informasi tambahan yang mengidentifikasi sifat ancaman (manipulasi psikologis, malware, dll.), serta waktu habis masa berlaku cache expiration.
Untuk setiap fullHash dari response:
1. Sisipkan fullHash ke dalam cache lokal, bersama dengan expiration.
Untuk setiap fullHash dari response:
1. Anggap isFound adalah hasil dari menemukan fullHash di expressionHashes.
2. Jika isFound bernilai Salah, lanjutkan dengan loop.
3. Jika isFound bernilai Benar, tampilkan UNSAFE.
Kembalikan SAFE.

Sama seperti Prosedur Pemeriksaan URL Real-Time, prosedur ini tidak menentukan secara tepat cara mengirim awalan hash ke server. Misalnya, klien dapat mengirim semua expressionHashPrefixes dalam satu permintaan, dan klien juga dapat mengirim setiap awalan di expressionHashPrefixes ke server dalam permintaan terpisah (mungkin dilanjutkan secara paralel). Klien juga dapat mengirim awalan hash yang tidak terkait atau dibuat secara acak bersama dengan awalan hash di expressionHashPrefixes, selama jumlah awalan hash yang dikirim dalam satu permintaan tidak melebihi 30.

Contoh Permintaan

Bagian ini mendokumentasikan beberapa contoh penggunaan HTTP API secara langsung untuk mengakses Google Safe Browsing. Sebaiknya gunakan binding bahasa yang dihasilkan karena akan otomatis menangani encoding dan decoding dengan cara yang mudah. Lihat dokumentasi untuk binding tersebut.

Berikut adalah contoh permintaan HTTP menggunakan metode hashes.search:

GET https://safebrowsing.googleapis.com/v5/hashes:search?key=INSERT_YOUR_API_KEY_HERE&hashPrefixes=WwuJdQ

Isi respons adalah payload berformat buffering protokol yang kemudian dapat Anda dekode.

Berikut adalah contoh permintaan HTTP menggunakan metode hashLists.batchGet:

GET https://safebrowsing.googleapis.com/v5alpha1/hashLists:batchGet?key=INSERT_YOUR_API_KEY_HERE&names=se&names=mw-4b

Sekali lagi, isi respons adalah payload berformat buffering protokol yang kemudian dapat Anda dekode.