Overview

Pengantar

Catatan: Dokumentasi 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 ukuran yang berlebihan. Selain itu, Google Safe Browsing v5 didesain untuk mempermudah 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 sudah melakukannya, kami akan memberikan pemberitahuan minimal selama satu tahun. Halaman ini akan menjelaskan v5 serta panduan migrasi dari v4 ke v5; dokumentasi v4 lengkap tetap tersedia.

Keaktualan Data

Satu peningkatan signifikan pada Google Safe Browsing v5 dibandingkan v4 (khususnya, API Pembaruan v4) adalah keaktualan dan cakupan data. Karena perlindungan sangat bergantung pada database lokal yang dikelola klien, penundaan dan ukuran update database lokal adalah kontributor utama dari perlindungan yang terlewat. Di v4, klien biasa membutuhkan waktu 20 hingga 50 menit untuk mendapatkan daftar ancaman versi terbaru. Sayangnya, serangan phishing menyebar dengan cepat: per tahun 2021, 60% situs yang melakukan serangan hanya berdurasi kurang dari 10 menit. Analisis kami menunjukkan bahwa sekitar 25-30% hilangnya perlindungan terhadap phishing disebabkan oleh data yang sudah tidak berlaku. Selain itu, beberapa perangkat tidak dilengkapi untuk mengelola keseluruhan daftar ancaman Google Safe Browsing, yang terus bertambah dari waktu ke waktu.

Di v5, kami memperkenalkan mode operasi yang dikenal sebagai perlindungan real-time. Hal ini akan menghindari masalah penghentian data di atas. Di v4, klien diharapkan mendownload dan mengelola database lokal, melakukan pemeriksaan terhadap daftar ancaman yang didownload secara lokal, lalu jika ada kecocokan awalan sebagian, jalankan permintaan untuk mendownload hash lengkap. Di v5, meskipun klien harus terus mendownload dan mengelola database lokal daftar ancaman, klien kini juga diharapkan 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 jika tidak ada kecocokan di Cache Global, lakukan permintaan untuk mendownload hash lengkapnya. (Untuk detail tentang pemrosesan lokal yang diperlukan oleh klien, lihat prosedur yang diberikan di bawah.) Hal ini menunjukkan pergeseran dari izinkan secara default ke pemeriksaan secara default, yang dapat meningkatkan perlindungan karena penyebaran ancaman yang lebih cepat di web. Dengan kata lain, protokol ini dirancang untuk memberikan perlindungan hampir secara 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 saat melayani permintaan. Cookie, jika terkirim, akan diabaikan. Alamat IP asal permintaan diketahui oleh Google, tetapi Google hanya menggunakan alamat IP tersebut untuk kebutuhan jaringan 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. Tindakan ini menggunakan HTTP Oblivious untuk menyembunyikan alamat IP pengguna akhir dari Google. Solusi ini memiliki pihak ketiga yang tidak berhubungan untuk menangani versi terenkripsi dari permintaan pengguna, lalu meneruskannya ke Google. Jadi, pihak ketiga hanya memiliki akses ke alamat IP tersebut, dan Google hanya memiliki akses ke konten permintaan. Pihak ketiga mengoperasikan Oblivious HTTP Relay (seperti layanan dari Fastly ini), dan Google mengoperasikan Oblivious HTTP Gateway. Ini adalah API pendamping opsional. Jika menggunakannya bersama dengan Google Safe Browsing, alamat IP pengguna akhir tidak lagi dikirim ke Google.

Penggunaan yang Sesuai

Penggunaan yang Diizinkan

Safe Browsing API hanya ditujukan untuk penggunaan non-komersial (artinya “tidak untuk tujuan penjualan atau pendapatan”). Jika Anda memerlukan solusi untuk tujuan komersial, lihat Web Risk.

Harga

Semua Google Safe Browsing API tidak dikenai biaya.

Kuota

Developer diberi kuota penggunaan default setelah mengaktifkan Safe Browsing API. Alokasi dan penggunaan saat ini dapat dilihat di Google Developers Console. Jika ingin menggunakan lebih banyak dari kuota yang dialokasikan saat ini, Anda dapat meminta kuota tambahan dari antarmuka Kuota Konsol Developer. Kami meninjau permintaan ini dan meminta Anda menghubungi kontak saat mengajukan permohonan peningkatan kuota untuk memastikan ketersediaan layanan kami memenuhi kebutuhan semua pengguna.

URL yang sesuai

Google Safe Browsing didesain untuk bertindak pada URL yang akan ditampilkan di kolom URL browser. Ini tidak dirancang untuk digunakan terhadap subresource (seperti JavaScript atau gambar yang dirujuk oleh file HTML, atau URL WebSocket yang dimulai oleh JavaScript). URL subresource tersebut tidak boleh diperiksa dengan Google Safe Browsing.

Jika mengunjungi URL menghasilkan pengalihan (seperti HTTP 301), sebaiknya URL yang dialihkan diperiksa untuk Google Safe Browsing. Manipulasi URL sisi klien seperti History.pushState tidak mengakibatkan URL baru diperiksa dengan Google Safe Browsing.

Peringatan Pengguna

Jika Anda menggunakan Google Safe Browsing untuk memperingatkan pengguna tentang risiko dari halaman web tertentu, panduan berikut berlaku.

Pedoman ini membantu melindungi Anda dan Google dari kesalahpahaman dengan menjelaskan bahwa halaman tersebut tidak diketahui dengan 100% sebagai resource web yang tidak aman, dan peringatan tersebut hanya mengidentifikasi kemungkinan risiko.

• Dalam peringatan yang terlihat bagi pengguna, Anda tidak boleh membuat pengguna percaya bahwa halaman yang dipermasalahkan adalah, tanpa diragukan lagi, halaman web yang tidak aman. Saat Anda merujuk ke halaman yang diidentifikasi atau potensi risiko yang mungkin ditimbulkan kepada pengguna, Anda harus mengkualifikasikan peringatan menggunakan istilah seperti: dicurigai, berpotensi, mungkin, mungkin, bisa saja.
• Peringatan Anda harus memungkinkan pengguna mempelajari lebih lanjut dengan meninjau definisi Google tentang berbagai ancaman. Link berikut disarankan:
  • Manipulasi Psikologis: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
  • Malware dan Software yang Tidak Diinginkan: https://developers.google.com/search/docs/monitor-debug/security/malware
  • Aplikasi yang Berpotensi Berbahaya (khusus Android): https://developers.google.com/android/play-protect/potentially-harmful-applications
• Jika Anda menampilkan peringatan untuk halaman yang diidentifikasi berisiko oleh Layanan Safe Browsing, Anda harus memberikan atribusi kepada Google dengan menyertakan baris "Saran yang diberikan oleh Google" dengan link ke Saran Safe Browsing. Jika produk Anda juga menampilkan peringatan berdasarkan sumber lain, Anda tidak boleh menyertakan atribusi Google dalam peringatan yang berasal dari data non-Google.

• Dalam dokumentasi produk, Anda harus memberikan pemberitahuan untuk memberi tahu pengguna bahwa perlindungan yang ditawarkan oleh Google Safe Browsing tidak sempurna. Mereka harus memberi tahu mereka bahwa ada kemungkinan positif palsu (situs aman yang ditandai sebagai berisiko) dan negatif palsu (situs berisiko tidak ditandai). Sebaiknya gunakan bahasa berikut:

  Google berupaya memberikan informasi terbaru yang paling akurat tentang resource web yang tidak aman. Namun, Google tidak dapat menjamin bahwa informasinya komprehensif dan bebas dari kesalahan: beberapa situs berisiko mungkin tidak dapat diidentifikasi, dan beberapa situs aman mungkin salah diidentifikasi.

Mode Operasi

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

Mode Real-Time

Saat klien memilih untuk menggunakan Google Safe Browsing v5 dalam mode real-time, klien akan mempertahankannya di database lokal mereka: (i) Cache Global dari situs yang kemungkinan tidak berbahaya, yang diformat sebagai hash SHA256 dari ekspresi URL akhiran host/awalan jalur, (ii) sekumpulan daftar ancaman, yang diformat sebagai awalan hash SHA256 dari ekspresi URL host-suffix/awalan. Ide tingkat tingginya 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 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 memori terjadi.

Spesifikasi terperinci prosedur tersedia di bawah ini.

Mode Daftar Lokal

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

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

Mode Real-Time Tanpa Penyimpanan

Bila klien memilih menggunakan Google Safe Browsing v5 dalam mode real-time tanpa penyimpanan, klien tidak perlu mengelola database lokal apa pun. Kapan pun klien ingin memeriksa URL tertentu, klien tersebut selalu terhubung ke server untuk melakukan pemeriksaan. Mode ini mirip dengan yang dapat diterapkan oleh klien v4 Lookup API.

Memeriksa URL

Bagian ini berisi spesifikasi mendetail tentang cara klien memeriksa URL.

Kanonikalisasi URL

Sebelum URL diperiksa, klien diharapkan melakukan beberapa kanonikalisasi pada URL tersebut.

Untuk memulai, kami berasumsi bahwa klien telah mengurai URL dan membuatnya valid sesuai dengan RFC 2396. Jika URL menggunakan nama domain (IDN) internasional, klien harus mengonversi URL menjadi representasi ASCII Punycode. URL harus menyertakan komponen jalur. Artinya, URL harus memiliki setidaknya satu garis miring setelah domain (http://google.com/, bukan http://google.com).

Pertama, hapus karakter tab (0x09), CR (0x0d), dan LF (0x0a) dari URL. Jangan hapus urutan escape untuk karakter ini (misalnya, %0a).

Kedua, jika URL berakhir dengan fragmen, hapus fragmen tersebut. Misalnya, persingkat http://google.com/#frag menjadi http://google.com/.

Ketiga, berulang kali membatalkan penggantian persentase pada URL hingga tidak ada lagi persentase escape pada URL. (Ini dapat membuat URL menjadi tidak valid.)

Untuk melakukan kanonikalisasi nama host:

Ekstrak nama host dari URL, lalu:

1. Hapus semua titik di awal dan di akhir.
2. Ganti titik yang berurutan dengan satu titik.
3. Jika nama host dapat diuraikan sebagai alamat IPv4, normalkan menjadi 4 nilai desimal yang dipisahkan titik. Klien harus menangani encoding alamat IP resmi, termasuk oktal, heksadesimal, dan komponen yang kurang dari empat.
4. Jika nama host dapat diuraikan sebagai alamat IPv6 dalam kurung, normalkan dengan menghapus angka nol di awal yang tidak perlu dalam komponen dan menciutkan komponen nol dengan menggunakan sintaksis titik dua. Misalnya, [2001:0db8:0000::1] harus diubah menjadi [2001:db8::1]. Jika nama host adalah salah satu dari dua jenis alamat IPv6 khusus berikut, ubah nama host menjadi IPv4:
   • Alamat IPv6 yang dipetakan IPv4, seperti [::ffff:1.2.3.4], yang harus diubah menjadi 1.2.3.4;
   • Alamat NAT64 yang menggunakan awalan 64:ff9b::/96 yang sudah dikenal, seperti [64:ff9b::1.2.3.4], yang harus diubah menjadi 1.2.3.4.
5. Membuat seluruh string menjadi huruf kecil.

Untuk melakukan kanonikalisasi jalur:

1. Selesaikan urutan /../ dan /./ di jalur dengan mengganti /./ dengan /, dan menghapus /../ beserta komponen jalur sebelumnya.
2. Mengganti garis miring berturut-turut dengan satu karakter garis miring.

Jangan terapkan kanonikalisasi jalur ini ke parameter kueri.

Pada URL, ganti persen dari semua karakter yang merupakan <= ASCII 32, >= 127, #, atau %. Escape harus menggunakan karakter heksadesimal huruf besar.

Ekspresi Awalan-Akhiran Host

Setelah URL dikanonikalisasi, langkah berikutnya adalah membuat akhiran/ekspresi awalan. Setiap ekspresi awalan/akhiran terdiri dari akhiran host (atau host lengkap) dan awalan jalur (atau jalur lengkap).

Klien akan membentuk hingga 30 kemungkinan kombinasi akhiran host dan awalan jalur yang berbeda. Kombinasi ini hanya menggunakan komponen host dan jalur URL. Skema, nama pengguna, sandi, dan porta akan dibuang. Jika URL menyertakan parameter kueri, setidaknya satu kombinasi akan menyertakan jalur lengkap dan parameter kueri.

Untuk host, klien akan mencoba maksimal lima string berbeda. Faktor-faktor tersebut adalah:

• Jika nama host bukan literal IPv4 atau IPv6, hingga empat nama host yang dibentuk dengan memulai dengan domain eTLD+1 dan menambahkan komponen utama berturut-turut. Penentuan eTLD+1 harus didasarkan pada Daftar Akhiran Publik. Misalnya, a.b.example.com akan menghasilkan domain eTLD+1 dari example.com serta host dengan satu komponen host tambahan b.example.com.
• Nama host yang tepat di URL. Dengan mengikuti contoh sebelumnya, a.b.example.com akan diperiksa.

Untuk jalur, klien akan mencoba maksimal enam string berbeda. Faktor-faktor tersebut adalah:

• Jalur URL persisnya, termasuk parameter kueri.
• Jalur URL persis, tanpa parameter kueri.
• Keempat jalur yang dibentuk dengan memulai dari root (/) dan menambahkan komponen jalur secara berurutan, termasuk garis miring.

Contoh berikut menggambarkan perilaku pemeriksaan:

Untuk URL http://a.b.com/1/2.html?param=1, klien akan mencoba string berikut:

a.b.com/1/2.html?param=1
a.b.com/1/2.html
a.b.com/
a.b.com/1/
b.com/1/2.html?param=1
b.com/1/2.html
b.com/
b.com/1/

Untuk URL http://a.b.c.d.e.f.com/1.html, klien akan mencoba string berikut:

a.b.c.d.e.f.com/1.html
a.b.c.d.e.f.com/
c.d.e.f.com/1.html
c.d.e.f.com/
d.e.f.com/1.html
d.e.f.com/
e.f.com/1.html
e.f.com/
f.com/1.html
f.com/

(Catatan: lewati b.c.d.e.f.com, karena kita hanya akan mengambil lima komponen nama host terakhir, dan nama host lengkap.)

Untuk URL http://1.2.3.4/1/, klien akan mencoba string berikut:

1.2.3.4/1/
1.2.3.4/

Untuk URL http://example.co.uk/1, klien akan mencoba string berikut:

example.co.uk/1
example.co.uk/

Hashing

Google Safe Browsing secara eksklusif menggunakan SHA256 sebagai fungsi hash. Fungsi hash ini harus diterapkan ke ekspresi di atas.

Hash 32-byte penuh akan, tergantung pada keadaan, dipotong menjadi 4 byte, 8 byte, atau 16 byte:

• Saat menggunakan metode hashes.search, saat ini kami mengharuskan hash dalam permintaan dipotong menjadi tepat 4 byte. Mengirim byte tambahan dalam permintaan ini akan membahayakan privasi pengguna.

• Saat mendownload daftar untuk database lokal menggunakan metode hashList.get atau metode hashLists.batchGet, panjang hash yang dikirim oleh server dipengaruhi oleh sifat daftar dan preferensi klien terhadap panjang hash, yang dikomunikasikan oleh parameter desired_hash_length.

Prosedur Pemeriksaan URL Real-Time

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

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

1. Misalkan expressions berupa daftar ekspresi awalan/awalan yang dibuat oleh URL u.
2. Misalkan expressionHashes berupa daftar, dengan elemen berupa hash SHA256 dari setiap ekspresi di expressions.
3. Untuk setiap hash dari expressionHashes:
   1. Jika hash dapat ditemukan di cache global, tampilkan UNSURE.
4. Misalkan expressionHashPrefixes berupa daftar, dengan elemen-elemennya adalah 4 byte pertama dari setiap hash di expressionHashes.
5. 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 cache yang ditemukan dari cache lokal.
         2. Lanjutkan 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.
6. Kirim expressionHashPrefixes ke server Google Safe Browsing v5 menggunakan RPC SearchHashes atau metode REST hashes.search. Jika terjadi error (termasuk error jaringan, error HTTP, dll.), tampilkan UNSURE. Jika tidak, respons berupa 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.
7. Untuk setiap fullHash dari response:
   1. Masukkan fullHash ke cache lokal, bersama dengan expiration.
8. Untuk setiap fullHash dari response:
   1. Anggaplah isFound sebagai hasil dari menemukan fullHash di expressionHashes.
   2. Jika isFound bernilai Salah, lanjutkan dengan loop.
   3. Jika isFound bernilai Benar, tampilkan UNSAFE.
9. Kembalikan SAFE.

Prosedur Pemeriksaan URL Daftar Ancaman Lokal

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

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

1. Misalkan expressions berupa daftar ekspresi awalan/awalan yang dibuat oleh URL u.
2. Misalkan expressionHashes berupa daftar, dengan elemen berupa hash SHA256 dari setiap ekspresi di expressions.
3. Misalkan expressionHashPrefixes berupa daftar, dengan elemen-elemennya adalah 4 byte pertama dari setiap hash di expressionHashes.
4. 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 cache yang ditemukan dari cache lokal.
         2. Lanjutkan 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.
5. Untuk setiap expressionHashPrefix dari expressionHashPrefixes:
   1. Cari expressionHashPrefix di database daftar ancaman lokal.
   2. Jika expressionHashPrefix tidak dapat ditemukan dalam database daftar ancaman lokal, hapus dari expressionHashPrefixes.
6. Kirim expressionHashPrefixes ke server Google Safe Browsing v5 menggunakan RPC SearchHashes atau metode REST hashes.search. Jika terjadi error (termasuk error jaringan, error HTTP, dll.), tampilkan SAFE. Jika tidak, respons berupa 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.
7. Untuk setiap fullHash dari response:
   1. Masukkan fullHash ke cache lokal, bersama dengan expiration.
8. Untuk setiap fullHash dari response:
   1. Anggaplah isFound sebagai hasil dari menemukan fullHash di expressionHashes.
   2. Jika isFound bernilai Salah, lanjutkan dengan loop.
   3. Jika isFound bernilai Benar, tampilkan UNSAFE.
9. 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.

1. Misalkan expressions berupa daftar ekspresi awalan/awalan yang dibuat oleh URL u.
2. Misalkan expressionHashes berupa daftar, dengan elemen berupa hash SHA256 dari setiap ekspresi di expressions.
3. Misalkan expressionHashPrefixes berupa daftar, dengan elemen-elemennya adalah 4 byte pertama dari setiap hash di expressionHashes.
4. 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 cache yang ditemukan dari cache lokal.
         2. Lanjutkan 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.
5. Kirim expressionHashPrefixes ke server Google Safe Browsing v5 menggunakan RPC SearchHashes atau metode REST hashes.search. Jika terjadi error (termasuk error jaringan, error HTTP, dll.), tampilkan SAFE. Jika tidak, respons berupa 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.
6. Untuk setiap fullHash dari response:
   1. Masukkan fullHash ke cache lokal, bersama dengan expiration.
7. Untuk setiap fullHash dari response:
   1. Anggaplah isFound sebagai hasil dari menemukan fullHash di expressionHashes.
   2. Jika isFound bernilai Salah, lanjutkan dengan loop.
   3. Jika isFound bernilai Benar, tampilkan UNSAFE.
8. Kembalikan SAFE.

Pemeliharaan Database Lokal

Google Safe Browsing v5 mengharapkan klien untuk mempertahankan database lokal, kecuali jika klien memilih Mode Real-Time Tanpa Penyimpanan. Klien dapat memilih format dan penyimpanan database lokal ini. Konten dari database lokal ini secara konseptual dapat dianggap sebagai folder yang berisi berbagai daftar sebagai file, dan isi file ini adalah hash SHA256 atau awalan hash.

Update Database

Klien akan memanggil metode hashList.get atau metode hashLists.batchGet secara berkala untuk memperbarui database. Karena klien umum ingin memperbarui beberapa daftar sekaligus, sebaiknya gunakan metode hashLists.batchGet.

Daftar diidentifikasi berdasarkan namanya yang berbeda. Namanya adalah {i>string<i} ASCII pendek yang panjangnya beberapa karakter.

Tidak seperti V4, ketika daftar diidentifikasi oleh tuple jenis ancaman, jenis platform, jenis entri ancaman, dalam daftar v5 hanya diidentifikasi berdasarkan nama. Hal ini memberikan fleksibilitas ketika beberapa daftar v5 dapat memiliki jenis ancaman yang sama. Jenis platform dan jenis entri ancaman dihapus di v5.

Setelah dipilih, nama untuk daftar tidak akan pernah diganti namanya. Selain itu, setelah muncul, daftar tidak akan dihapus (jika tidak lagi berguna, daftar akan menjadi kosong tetapi akan terus ada). Oleh karena itu, sebaiknya lakukan hard code untuk nama-nama ini dalam kode klien Google Safe Browsing.

Baik metode hashList.get maupun metode hashLists.batchGet mendukung update inkremental. Menggunakan update inkremental akan menghemat bandwidth dan meningkatkan performa. Update inkremental berfungsi dengan mengirimkan delta antara daftar versi klien dan versi terbaru daftar. (Jika klien baru di-deploy dan tidak memiliki versi apa pun yang tersedia, update lengkapnya tersedia.) Update inkremental berisi penambahan dan indeks penghapusan. Klien diharapkan menghapus entri pada indeks yang ditentukan dari database lokalnya terlebih dahulu, lalu menerapkan penambahan.

Akhirnya, untuk mencegah kerusakan, klien harus memeriksa data yang disimpan terhadap {i>checksum<i} yang disediakan oleh server. Setiap kali {i>checksum<i} tidak cocok, klien harus melakukan update penuh.

Mendekode Konten Daftar

Semua daftar dikirimkan menggunakan encoding khusus untuk mengurangi ukuran. Encoding ini berfungsi dengan mengenali bahwa daftar Google Safe Browsing berisi, secara konseptual, sekumpulan hash atau awalan hash, yang secara statistik tidak dapat dibedakan dari bilangan bulat acak. Jika kita mengurutkan bilangan bulat ini dan mengambil selisihnya yang berdekatan, perbedaan yang berdekatan tersebut diharapkan menjadi "kecil". Encoding Golomb-Rice kemudian mengeksploitasi ukuran kecil ini.

Google Safe Browsing v5 memiliki empat jenis berbeda untuk menangani data 4 byte, data 8 byte, data 16 byte, dan data 32 byte. Mari kita lihat contoh di mana tiga bilangan bulat 4-byte berturut-turut akan dienkode. Misalkan parameter Rice, dilambangkan dengan k, menjadi 3. Bagian hasil bagi dari pengkodean hanyalah nilai perbedaan yang berdekatan yang digeser ke kanan oleh k bit. Karena bilangan bulat yang diberikan berurutan, selisihnya yang berdekatan adalah 1, dan setelah bergeser 3 bit, bagian pembagiannya adalah nol. K bit yang paling tidak signifikan adalah 001. Hasil bagi nol dienkode sebagai bit 0 tunggal. Sisanya adalah 1, dan dienkode sebagai 100. Langkah ini diulangi untuk membentuk bitstream 01000100. Bitstream yang dihasilkan akan dienkode menggunakan {i>small endian<i} sebagai 00100010. Oleh karena itu, entri tersebut sesuai dengan data berikut:

rice_parameter: 3
entries_count: 2
encoded_data: "\x22"

Setelah langkah decoding di atas untuk bilangan bulat 32-bit, hasilnya langsung dapat digunakan sebagai indeks penghapusan atau penambahan. Tidak seperti v4, setelah itu Anda tidak perlu melakukan pertukaran byte.

Daftar yang Tersedia

Daftar berikut direkomendasikan untuk digunakan di v5alpha1:

Nama Daftar	Enum ThreatType v4 yang sesuai	Deskripsi
gc	Tidak ada	Daftar ini merupakan daftar Cache Global. Ini merupakan daftar khusus yang hanya digunakan dalam mode operasi Real-Time.
se	SOCIAL_ENGINEERING	Daftar ini berisi ancaman jenis ancaman SOCIAL_EngineERING.
mw	MALWARE	Daftar ini berisi ancaman jenis ancaman MALWARE untuk platform desktop.
uws	UNWANTED_SOFTWARE	Daftar ini berisi ancaman jenis ancaman UNWANTED_SOFTWARE untuk platform desktop.
uwsa	UNWANTED_SOFTWARE	Daftar ini berisi ancaman jenis ancaman UNWANTED_SOFTWARE untuk platform Android.
pha	POTENTIALLY_HARMFUL_APPLICATION	Daftar ini berisi ancaman jenis ancaman POTENTIALLY_HARMFUL_APPLICATION untuk platform Android.

Daftar tambahan akan tersedia di kemudian hari, dan pada saat itu tabel di atas akan diperluas.

Frekuensi Pembaruan

Klien harus memeriksa nilai server yang ditampilkan di kolom minimum_wait_duration dan menggunakannya untuk menjadwalkan update database berikutnya. Nilai ini mungkin nol, sehingga klien harus segera melakukan update lainnya.

Contoh Permintaan

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

Berikut adalah contoh permintaan HTTP yang menggunakan metode hash.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 yang menggunakan metode hashLists.batchGet:

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

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

Panduan Migrasi

Jika saat ini Anda menggunakan v4 Update API, ada jalur migrasi yang lancar dari v4 ke v5 tanpa harus mereset atau menghapus database lokal. Bagian ini mendokumentasikan cara melakukannya.

Mengonversi Pembaruan Daftar

Pada v4, seseorang akan menggunakan metode threatListUpdates.fetch untuk mendownload daftar. Di v5, satu model akan beralih ke metode hashLists.batchGet.

Perubahan berikut harus dilakukan pada permintaan:

1. Hapus objek ClientInfo v4 sepenuhnya. Daripada memberikan identifikasi klien menggunakan kolom khusus, cukup gunakan header Agen Pengguna yang sudah dikenal. Meskipun tidak ada format yang ditetapkan untuk memberikan identifikasi klien dalam {i>header<i} ini, sebaiknya Anda hanya menyertakan ID klien asli dan versi klien yang dipisahkan dengan karakter spasi atau karakter garis miring.
2. Untuk setiap objek ListUpdateRequest v4:
   • Cari nama daftar v5 yang sesuai dalam tabel di atas dan berikan nama tersebut dalam permintaan v5.
   • Hapus kolom yang tidak diperlukan seperti threat_entry_type atau platform_type.
   • Kolom state di v4 secara langsung kompatibel dengan kolom versions v5. String byte yang sama yang akan dikirim ke server menggunakan kolom state di v4 dapat dikirim di v5 menggunakan kolom versions.
   • Untuk batasan v4, v5 menggunakan versi sederhana yang disebut SizeConstraints. Kolom tambahan seperti region harus dihapus.

Perubahan berikut harus dilakukan pada respons:

1. ResponseType enum v4 hanya diganti dengan kolom boolean bernama partial_update.
2. Kolom minimum_wait_duration sekarang bisa nol atau dihilangkan. Jika ya, klien akan diminta untuk segera membuat permintaan lainnya. Hal ini hanya terjadi jika klien menentukan di SizeConstraints batasan yang lebih kecil pada ukuran update maksimum daripada ukuran database maksimum.
3. Algoritma decoding Rice untuk bilangan bulat 32-bit perlu disesuaikan. Perbedaannya adalah data yang dienkode dienkode dengan endianness yang berbeda. Pada v4 dan v5, awalan hash 32-bit diurutkan secara leksikografis. Namun pada v4, awalan tersebut diperlakukan sebagai endian kecil ketika diurutkan, sedangkan pada v5 awalan tersebut diperlakukan sebagai endian besar ketika diurutkan. Ini berarti bahwa klien tidak perlu melakukan penyortiran apa pun, karena penyortiran leksikografis identik dengan penyortiran numerik dengan endian besar. Contoh semacam ini dalam implementasi Chromium v4 dapat ditemukan di sini. Pengurutan semacam itu dapat dihapus.
4. Algoritma decoding Rice perlu diimplementasikan untuk panjang hash lainnya.

Mengonversi Penelusuran Hash

Pada v4, kita dapat menggunakan metode fullHashes.find untuk mendapatkan hash lengkap. Metode yang setara di v5 adalah metode hashes.search.

Perubahan berikut harus dilakukan pada permintaan:

1. Buat struktur kode agar hanya mengirim awalan hash yang panjangnya tepat tepat 4 byte.
2. Hapus objek ClientInfo v4 sepenuhnya. Daripada memberikan identifikasi klien menggunakan kolom khusus, cukup gunakan header Agen Pengguna yang sudah dikenal. Meskipun tidak ada format yang ditetapkan untuk memberikan identifikasi klien dalam {i>header<i} ini, sebaiknya Anda hanya menyertakan ID klien asli dan versi klien yang dipisahkan dengan karakter spasi atau karakter garis miring.
3. Hapus kolom client_states. Fungsi tersebut tidak diperlukan lagi.
4. Anda tidak perlu lagi menyertakan threat_types dan kolom serupa.

Perubahan berikut harus dilakukan pada respons:

1. Kolom minimum_wait_duration telah dihapus. Klien dapat mengajukan permintaan baru kapan saja sesuai kebutuhan.
2. Objek ThreatMatch v4 telah disederhanakan menjadi objek FullHash.
3. Menyimpan ke cache telah disederhanakan menjadi satu durasi cache. Lihat prosedur di atas untuk berinteraksi dengan cache.