Overview

Pengantar

Catatan: Dokumentasi ini saat ini masih dalam pengembangan. Diperkirakan 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, tampilan API telah ditingkatkan untuk meningkatkan fleksibilitas dan efisiensi, serta mengurangi ukuran API. Selain itu, Google Safe Browsing v5 dirancang untuk mempermudah migrasi dari v4.

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

Keaktualan Data

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

Di v5, kami memperkenalkan mode operasi yang dikenal sebagai perlindungan real-time. Hal ini menghindar dari masalah data yang sudah usang 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 parsial, jalankan permintaan untuk mendownload hash lengkap. Di v5, meskipun klien harus terus mendownload dan mempertahankan database lokal dari daftar ancaman, klien kini juga diharapkan mendownload daftar situs yang kemungkinan tidak berbahaya (disebut Global Cache), melakukan pemeriksaan lokal untuk Global Cache ini serta pemeriksaan daftar ancaman lokal, dan terakhir saat ada kecocokan sebagian awalan untuk daftar ancaman atau tidak ada kecocokan di Global Cache, lakukan permintaan untuk mendownload hash lengkap. (Untuk detail tentang pemrosesan lokal yang diminta oleh klien, harap lihat prosedur yang disediakan di bawah ini.) Hal ini mewakili peralihan dari izinkan secara default menjadi check-by-default, yang dapat meningkatkan perlindungan seiring penyebaran ancaman yang lebih cepat di web. Dengan kata lain, ini adalah protokol yang dirancang untuk memberikan perlindungan yang mendekati 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 melayani permintaan. Cookie, jika dikirim, 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. Perintah ini menggunakan HTTP Oblivious untuk menyembunyikan alamat IP dari Google. Cara kerjanya adalah dengan meminta pihak ketiga yang tidak berkonflik 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 dari Fastly), dan Google mengoperasikan Gateway HTTP Oblivious. Ini adalah API pendamping opsional. Saat menggunakannya bersama dengan Google Safe Browsing, Alamat IP tidak lagi dikirim ke Google.

Penggunaan yang Sesuai

Penggunaan yang Diizinkan

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

Harga

Semua API Google Safe Browsing tanpa 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 dari kuota yang dialokasikan saat ini, Anda dapat meminta kuota tambahan dari antarmuka Kuota Konsol Play. Kami meninjau permintaan tersebut dan memerlukan kontak saat mengajukan permohonan penambahan kuota untuk memastikan ketersediaan layanan kami memenuhi kebutuhan semua pengguna.

URL yang sesuai

Google Safe Browsing dirancang untuk bertindak pada URL yang akan ditampilkan di kolom URL browser. URL ini tidak dirancang untuk digunakan guna memeriksa 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), URL yang dialihkan akan diperiksa dengan Google Safe Browsing. Manipulasi URL sisi klien seperti History.pushState tidak menghasilkan URL baru untuk diperiksa dengan Google Safe Browsing.

Peringatan Pengguna

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

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

  • Dalam peringatan yang terlihat oleh pengguna, Anda tidak boleh mengarahkan pengguna untuk meyakini bahwa halaman yang dipermasalahkan adalah aset web yang tidak aman. Saat merujuk ke halaman yang diidentifikasi atau potensi risiko yang dapat ditimbulkannya kepada pengguna, Anda harus menentukan syarat peringatan dengan menggunakan istilah seperti: dicurigai, berpotensi, mungkin, mungkin.
  • Peringatan Anda harus memungkinkan pengguna mempelajari lebih lanjut dengan meninjau definisi Google tentang berbagai ancaman. Berikut link yang disarankan:
  • Saat Anda menampilkan peringatan untuk halaman yang diidentifikasi berisiko oleh Layanan Safe Browsing, Anda harus memberikan atribusi kepada Google dengan menyertakan baris "Saran dari 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. Google harus memberi tahu pengguna 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 yang paling akurat dan terbaru tentang referensi web yang tidak aman. Namun, Google tidak dapat menjamin bahwa informasinya lengkap dan bebas dari error: beberapa situs berisiko mungkin tidak dapat teridentifikasi, dan beberapa situs aman mungkin salah teridentifikasi.

Mode Operasi

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

Mode {i>Real-Time<i}

Jika klien memilih untuk menggunakan Google Safe Browsing v5 dalam mode real-time, klien akan mempertahankan database lokal mereka: (i) Cache Global dari situs yang kemungkinan tidak berbahaya, diformat sebagai hash SHA256 dari ekspresi URL awalan jalur/akhiran host, (ii) sekumpulan daftar ancaman, yang diformat sebagai awalan SHA256 dari ekspresi hash URL host-akhiran/awalan jalur. Garis besarnya adalah kapan pun 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 {i>database<i} lokal, klien akan mempertahankan {i>cache<i} lokal. Cache lokal tersebut tidak perlu berada dalam penyimpanan persisten dan dapat dibersihkan jika terjadi tekanan memori.

Spesifikasi prosedurnya tersedia di bawah.

Mode Daftar Lokal

Jika 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 telah ditingkatkan. Klien akan mempertahankan serangkaian daftar ancaman yang diformat sebagai awalan hash SHA256 dari ekspresi URL host-akhiran/awalan jalur di database lokal mereka. Setiap kali klien ingin memeriksa URL tertentu, pemeriksaan akan dilakukan menggunakan daftar ancaman lokal. Jika dan hanya jika terdapat kecocokan, klien akan terhubung ke server untuk melanjutkan pemeriksaan.

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

Mode Real-Time Tanpa Penyimpanan

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

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

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

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, kita asumsikan bahwa klien telah menguraikan URL dan membuatnya valid sesuai dengan RFC 2396. Jika URL menggunakan nama domain internasional (IDN), klien harus mengonversi URL ke representasi Punycode ASCII. URL harus menyertakan komponen jalur; artinya, nama 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 menggunakan persen-unescape URL hingga tidak ada lagi escape persen. (Ini dapat membuat URL menjadi tidak valid.)

Untuk melakukan kanonikalisasi nama host:

Ekstrak nama host dari URL, lalu:

  1. Hapus semua titik di bagian awal dan 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 setiap encoding alamat IP resmi, termasuk oktal, heksadesimal, dan kurang dari empat komponen.
  4. Jika nama host dapat diuraikan sebagai alamat IPv6 dalam tanda kurung, normalkan dengan menghapus angka nol di depan yang tidak perlu dalam komponen dan menciutkan komponen nol menggunakan sintaksis titik dua. Misalnya, [2001:0db8:0000::1] harus diubah menjadi [2001:db8::1]. Jika nama {i>host<i} adalah salah satu dari dua jenis alamat IPv6 khusus berikut, ubahlah ke dalam IPv4:
    • Alamat IPv6 yang dipetakan IPv4, seperti [::ffff:1.2.3.4], yang harus diubah menjadi 1.2.3.4;
    • Alamat NAT64 menggunakan awalan 64:ff9b::/96 yang dikenal, seperti [64:ff9b::1.2.3.4], yang harus diubah menjadi 1.2.3.4.
  5. Gunakan huruf kecil untuk seluruh string.

Untuk melakukan kanonikalisasi jalur:

  1. Selesaikan urutan /../ dan /./ di jalur dengan mengganti /./ dengan /, dan menghapus /../ bersama komponen jalur sebelumnya.
  2. Ganti garis miring yang berurutan dengan satu karakter garis miring.

Jangan terapkan kanonikalisasi jalur ini ke parameter kueri.

Di URL, gunakan persen-escape semua karakter yang merupakan <= ASCII 32, >= 127, #, atau %. Escape harus menggunakan karakter heksadesimal huruf besar.

Ekspresi Awalan Jalur Host-Akhiran

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

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

Untuk host, klien akan mencoba maksimal lima string yang berbeda. Bagian-bagian tersebut adalah:

  • Jika nama {i>host<i} bukan literal IPv4 atau IPv6, hingga empat nama {i>host<i} yang dibentuk dengan dimulai dengan domain eTLD+1 dan menambahkan komponen di depan secara berurutan. Penentuan eTLD+1 harus didasarkan pada Daftar Suffix 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. Bagian-bagian tersebut adalah:

  • Jalur persis URL, termasuk parameter kueri.
  • Jalur persis URL, tanpa parameter kueri.
  • Keempat jalur yang dibentuk dengan memulai dari akar (/) 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 kemungkinan 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 kemungkinan 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 kemungkinan string berikut:

1.2.3.4/1/
1.2.3.4/

Untuk URL http://example.co.uk/1, klien akan mencoba kemungkinan 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 situasinya, akan 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 menampilkan SAFE, URL dianggap aman oleh Google Safe Browsing. Jika menampilkan UNSAFE, URL tersebut 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 dari pengguna sebelum melanjutkan. Jika metode tersebut menampilkan UNSURE, prosedur pemeriksaan lokal berikut harus digunakan setelahnya.

  1. Misalkan expressions adalah daftar ekspresi akhiran/awalan yang dibuat oleh u URL.
  2. expressionHashes berupa daftar, dengan elemennya adalah 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 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. Tentukan 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 dengan loop.
      3. Jika tidak lebih besar:
        1. Hapus expressionHashPrefix 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 dalam cache lokal, bersama dengan expiration.
  8. Untuk setiap fullHash dari response:
    1. Misalkan isFound adalah hasil dari pencarian fullHash di expressionHashes.
    2. Jika isFound Salah, lanjutkan dengan loop.
    3. Jika isFound adalah Benar, tampilkan UNSAFE.
  9. Kembalikan SAFE.

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

Prosedur Pemeriksaan URL Daftar Ancaman Lokal

Prosedur ini digunakan saat klien memilih mode operasi daftar lokal. Metode 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 adalah daftar ekspresi akhiran/awalan yang dibuat oleh u URL.
  2. expressionHashes berupa daftar, dengan elemennya adalah hash SHA256 dari setiap ekspresi di expressions.
  3. Misalkan expressionHashPrefixes berupa daftar, dengan 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. Tentukan 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 dengan loop.
      3. Jika tidak lebih besar:
        1. Hapus expressionHashPrefix 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 dalam cache lokal, bersama dengan expiration.
  8. Untuk setiap fullHash dari response:
    1. Misalkan isFound adalah hasil dari pencarian fullHash di expressionHashes.
    2. Jika isFound Salah, lanjutkan dengan loop.
    3. Jika isFound adalah 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 adalah daftar ekspresi akhiran/awalan yang dibuat oleh u URL.
  2. expressionHashes berupa daftar, dengan elemennya adalah hash SHA256 dari setiap ekspresi di expressions.
  3. Misalkan expressionHashPrefixes berupa daftar, dengan 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. Tentukan 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 dengan loop.
      3. Jika tidak lebih besar:
        1. Hapus expressionHashPrefix 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 dalam cache lokal, bersama dengan expiration.
  7. Untuk setiap fullHash dari response:
    1. Misalkan isFound adalah hasil dari pencarian fullHash di expressionHashes.
    2. Jika isFound Salah, lanjutkan dengan loop.
    3. Jika isFound adalah Benar, tampilkan UNSAFE.
  8. Kembalikan SAFE.

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

Pemeliharaan Database Lokal

Google Safe Browsing v5 mengharapkan klien mengelola database lokal, kecuali jika klien memilih Mode Real-Time Tanpa Penyimpanan. Format dan penyimpanan database lokal ini bergantung pada klien. 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 secara rutin memanggil metode hashList.get atau metode hashLists.batchGet untuk memperbarui database. Karena klien standar ingin memperbarui beberapa daftar sekaligus, sebaiknya gunakan metode hashLists.batchGet.

Daftar diidentifikasi berdasarkan nama yang berbeda. Nama-nama tersebut adalah {i>string<i} ASCII pendek yang panjangnya beberapa karakter.

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

Setelah nama dipilih untuk daftar, nama tersebut 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, adalah tepat untuk melakukan hard code nama-nama ini dalam kode klien Google Safe Browsing.

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

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

Mendekode Konten Daftar

Decoding Hash dan Awalan Hash

Semua daftar dikirim menggunakan encoding khusus untuk mengurangi ukuran. Encoding ini bekerja dengan mengenali bahwa daftar Google Safe Browsing berisi, secara konseptual, serangkaian 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" diartikan. Encoding Golomb-Rice kemudian mengeksploitasi kecilnya ini.

Misalkan tiga ekspresi awalan jalur akhiran host, yaitu a.example.com/, b.example.com/, dan y.example.com/, akan dikirim menggunakan awalan hash 4 byte. Selanjutnya anggaplah parameter Rice, yang dilambangkan dengan k, dipilih menjadi 30. Server akan memulai dengan menghitung hash lengkap untuk string ini, yaitu, masing-masing:

291bc5421f1cd54d99afcc55d166e2b9fe42447025895bf09dd41b2110a687dc  a.example.com/
1d32c5084a360e58f1b87109637a6810acad97a861a7769e8f1841410d2a960c  b.example.com/
f7a502e56e8b01c6dc242b35122683c9d25d07fb1f532d9853eb0ef3ff334f03  y.example.com/

Server kemudian membentuk awalan hash 4-byte untuk masing-masing hal di atas, yang merupakan 4 byte pertama dari hash penuh 32-byte, yang ditafsirkan sebagai bilangan bulat 32-bit big-endian. Big endianness mengacu pada fakta bahwa byte pertama dari hash lengkap menjadi byte paling signifikan dari integer 32-bit. Langkah ini menghasilkan bilangan bulat 0x291bc542, 0x1d32c508, dan 0xf7a502e5.

Server perlu mengurutkan tiga awalan hash ini secara leksikografis (setara dengan penyortiran numerik dalam big endian), dan hasil penyortiran adalah 0x1d32c508, 0x291bc542, 0xf7a502e5. Awalan hash pertama disimpan tanpa perubahan di kolom first_value.

Server kemudian menghitung dua perbedaan yang berdekatan, yaitu 0xbe9003a dan 0xce893da3 masing-masing. Mengingat bahwa k dipilih menjadi 30, server membagi kedua angka ini menjadi bagian hasil bagi dan bagian sisanya yang masing-masing panjangnya 2 dan 30 bit. Untuk angka pertama, bagian hasil bagi adalah nol dan sisanya adalah 0xbe9003a; untuk angka kedua, bagian hasil bagi adalah 3 karena dua bit yang paling signifikan adalah 11 dalam biner dan sisanya adalah 0xe893da3. Untuk hasil bagi q, ini dienkode ke (1 << q) - 1 menggunakan 1 + q bit; sisanya dikodekan langsung menggunakan k bit. Bagian hasil bagi angka pertama dikodekan sebagai 0, dan bagian sisanya dalam biner 001011111010010000000000111010; bagian hasil bagi dari angka kedua dikodekan sebagai 0111, dan bagian sisanya adalah 001110100010010011110110100011.

Ketika angka-angka ini dibentuk menjadi {i>string<i} byte, {i>small endian<i} digunakan. Secara konseptual, mungkin lebih mudah untuk membayangkan bitstring panjang terbentuk mulai dari bit yang paling tidak signifikan: kita mengambil bagian hasil bagi angka pertama dan menambahkan bagian sisanya dari angka pertama; kita kemudian menambahkan bagian hasil bagi angka kedua dan menambahkan bagian sisanya. Hal ini akan menghasilkan jumlah yang besar berikut ini (jeda baris dan komentar ditambahkan agar lebih jelas):

001110100010010011110110100011 # Second number, remainder part
0111 # Second number, quotient part
001011111010010000000000111010 # First number, remainder part
0 # First number, quotient part

Ditulis dalam satu baris tentang

00111010001001001111011010001101110010111110100100000000001110100

Jelas jumlah ini jauh melebihi 8 bit yang tersedia dalam satu byte. Pengkodean {i>small endian<i} kemudian mengambil 8 bit yang paling tidak signifikan dalam angka itu, dan menghasilkannya sebagai byte pertama yaitu 01110100. Agar lebih jelas, kita dapat mengelompokkan bitstring di atas ke dalam kelompok yang berisi delapan, dimulai dari bit yang paling tidak signifikan:

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

Encoding sedikit endian kemudian mengambil setiap byte dari kanan dan memasukkannya ke dalam sebuah bytestring:

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

Dapat dilihat bahwa karena secara konseptual kita menambahkan bagian baru ke angka besar di sebelah kiri (yaitu menambahkan bit yang lebih signifikan), tetapi kita mengenkode dari kanan (yaitu bit yang paling tidak signifikan), encoding dan decoding dapat dilakukan secara bertahap.

Hal ini akhirnya menghasilkan

additions_four_bytes {
  first_value: 489866504
  rice_parameter: 30
  entries_count: 2
  encoded_data: "t\000\322\227\033\355It\000"
}

Klien cukup mengikuti langkah-langkah di atas secara terbalik untuk mendekode awalan hash. Tidak seperti v4, tidak perlu melakukan pertukaran byte di akhir karena fakta bahwa integer awalan hash ditafsirkan sebagai big endian.

Indeks Penghapusan Dekode

Indeks penghapusan dienkode menggunakan teknik yang sama persis seperti di atas menggunakan bilangan bulat 32-bit. Encoding dan decoding indeks penghapusan tidak berubah antara v4 dan v5.

Daftar yang Tersedia

Daftar berikut direkomendasikan untuk digunakan dalam v5alpha1:

Nama Daftar Enum ThreatType v4 yang sesuai Deskripsi
gc Tidak ada Daftar ini adalah daftar Cache Global. Ini adalah daftar khusus yang hanya digunakan dalam mode operasi {i>Real-Time<i}.
se SOCIAL_ENGINEERING Daftar ini berisi ancaman dari 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.

Klien diperbolehkan mengoperasikan server proxy {i>caching<i} untuk mengambil sebagian atau semua daftar di atas dan kemudian meminta klien menghubungi server proxy. Jika hal ini diterapkan, sebaiknya gunakan durasi cache yang singkat, misalnya lima menit; di masa mendatang, durasi cache ini dapat dikomunikasikan menggunakan header HTTP Cache-Control standar.

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 (kolom minimum_wait_duration benar-benar hilang), sehingga klien HARUS segera melakukan update lain.

Contoh Permintaan

Bagian ini mendokumentasikan beberapa contoh penggunaan langsung HTTP API 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 ini 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

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

Panduan Migrasi

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

Pembaruan Daftar Konversi

Di v4, seseorang akan menggunakan metodethreatListUpdates.fetch untuk mendownload daftar. Pada v5, seseorang 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 ditentukan untuk memberikan identifikasi klien di header ini, sebaiknya sertakan client ID asli dan versi klien yang dipisahkan oleh karakter spasi atau karakter garis miring.
  2. Untuk setiap objek ListUpdateRequest v4:
    • Cari nama daftar v5 yang sesuai pada 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 kompatibel secara langsung 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 yang disederhanakan yang disebut SizeConstraints. Kolom tambahan seperti region harus dihapus.

Perubahan berikut harus dilakukan pada respons:

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

Mengonversi Pencarian Hash

Di v4, seseorang akan 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 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 ditentukan untuk memberikan identifikasi klien di header ini, sebaiknya sertakan client ID asli dan versi klien yang dipisahkan oleh karakter spasi atau karakter garis miring.
  3. Hapus kolom client_states. Fungsi tersebut tidak diperlukan lagi.
  4. Tidak perlu lagi menyertakan threat_types dan kolom serupa.

Perubahan berikut harus dilakukan pada respons:

  1. Kolom minimum_wait_duration telah dihapus. Klien selalu dapat mengajukan permintaan baru sesuai kebutuhan.
  2. Objek ThreatMatch v4 telah disederhanakan menjadi objek FullHash.
  3. Penyimpanan dalam cache telah disederhanakan menjadi durasi cache tunggal. Lihat prosedur di atas untuk berinteraksi dengan cache.