Overview

Introduzione

Nota: questa documentazione è attualmente in fase di sviluppo. Aspettati dei miglioramenti nel prossimo futuro.

Google Navigazione sicura v5 è un'evoluzione di Google Navigazione sicura v4. Le due modifiche principali apportate nella versione 5 sono l'aggiornamento dei dati e la privacy degli IP. Inoltre, la superficie API è stata migliorata per aumentare la flessibilità, l'efficienza e ridurre il gonfiore. Inoltre, Google Navigazione sicura v5 è progettata per facilitare la migrazione dalla versione 4.

Al momento, Google offre sia v4 che v5 ed entrambe sono considerate pronte per la produzione. Puoi utilizzare la versione 4 o 5. Non abbiamo annunciato una data per il ritiro della versione 4; in caso affermativo, ti invieremo un preavviso di almeno un anno. In questa pagina vengono descritte le versioni v5 e la guida alla migrazione da v4 a v5; la documentazione completa per la versione 4 rimane disponibile.

Aggiornamento dei dati

Un miglioramento significativo della versione 5 di Google Navigazione sicura rispetto alla versione 4 (in particolare, l'API v4 Update) riguarda l'aggiornamento dei dati e la copertura. Poiché la protezione dipende in gran parte dal database locale gestito dal client, il ritardo e la dimensione dell'aggiornamento del database locale sono il fattore principale della mancata protezione. Nella versione 4, un client tipico impiega da 20 a 50 minuti per ottenere la versione più aggiornata degli elenchi di minacce. Purtroppo, gli attacchi di phishing si sono diffusi rapidamente: nel 2021, il 60% dei siti che inviano attacchi vive in meno di 10 minuti. La nostra analisi mostra che circa il 25-30% della mancata protezione contro il phishing è dovuta a tale obsolescenza dei dati. Inoltre, alcuni dispositivi non sono in grado di gestire tutti gli elenchi di minacce di Google Navigazione sicura, che continuano a crescere nel tempo.

Nella versione 5 viene introdotta una modalità di funzionamento nota come protezione in tempo reale. Questa operazione elude il problema di inattività dei dati di cui sopra. Nella versione 4, i client devono scaricare e gestire un database locale, eseguire controlli sugli elenchi di minacce scaricati localmente e, in caso di corrispondenza parziale del prefisso, eseguire una richiesta per scaricare l'hash completo. Nella versione v5, sebbene i client debbano continuare a scaricare e gestire un database locale di elenchi di minacce, ora i client sono tenuti a scaricare un elenco di siti probabili (chiamati Cache globale), a eseguire un controllo locale di questa cache globale e un controllo dell’elenco delle minacce locali. Infine, se è presente una corrispondenza parziale con prefisso per gli elenchi di minacce o una mancata corrispondenza nella Cache globale, eseguire una richiesta per scaricare gli hash completi. Per i dettagli sull'elaborazione locale richiesta dal client, consulta la procedura indicata di seguito. Ciò rappresenta uno spostamento da allow-by-default al check-by-default, che può migliorare la protezione alla luce di una propagazione più rapida delle minacce sul web. In altre parole, si tratta di un protocollo progettato per fornire una protezione quasi in tempo reale: il nostro obiettivo è far sì che i clienti traggano vantaggio dai dati di Google Navigazione sicura più aggiornati.

Privacy relativa all'IP

Google Navigazione sicura (v4 o v5) non elabora nulla associato all'identità di un utente nel corso delle richieste di pubblicazione. I cookie, se inviati, vengono ignorati. Gli indirizzi IP di origine delle richieste sono noti a Google, ma utilizza gli indirizzi IP solo per esigenze di networking essenziali (ad esempio per l'invio di risposte) e per scopi anti-DoS.

In concomitanza con la versione 5, introduciamo un'API complementare nota come API Safe Browsing Oblivious HTTP Gateway. In questo modo viene utilizzato il protocollo Oblivious HTTP per nascondere gli indirizzi IP degli utenti finali a Google. Il suo funzionamento prevede che una terza parte non coinvolta possa gestire una versione criptata della richiesta dell'utente e inoltrarla a Google. Di conseguenza, la terza parte ha accesso solo agli indirizzi IP e Google ha accesso solo ai contenuti della richiesta. La terza parte gestisce un inoltro HTTP Oblivious (come questo servizio di Fastly) e Google gestisce il gateway HTTP Oblivious. Si tratta di un'API complementare facoltativa. Quando viene utilizzato insieme a Google Navigazione sicura, gli indirizzi IP degli utenti finali non vengono più inviati a Google.

Utilizzo appropriato

Utilizzo consentito

L'API Navigazione sicura è destinata esclusivamente a un uso non commerciale (ovvero "non per la vendita o per la generazione di entrate"). Se hai bisogno di una soluzione a fini commerciali, consulta l'articolo Rischio Web.

Prezzi

Tutte le API di Google Navigazione sicura sono senza costi aggiuntivi.

Quote

Agli sviluppatori viene assegnata una quota di utilizzo predefinita durante l'attivazione dell'API Navigazione sicura. L'allocazione e l'utilizzo attuali possono essere visualizzati in Google Developer Console. Se prevedi di utilizzare più quota di quella attualmente allocata, puoi richiedere una quota aggiuntiva dall'interfaccia Quota di Developer Console. Esaminiamo queste richieste e richiediamo un contatto quando richiedi un aumento della quota per garantire che la disponibilità del nostro servizio soddisfi le esigenze di tutti gli utenti.

URL appropriati

Google Navigazione sicura è progettata per funzionare sugli URL che potrebbero essere visualizzati nella barra degli indirizzi di un browser. Non è progettato per essere utilizzato per eseguire il confronto con le risorse secondarie (ad esempio un codice JavaScript o un'immagine a cui fa riferimento un file HTML oppure un URL WebSocket avviato da JavaScript). Gli URL delle sottorisorse non devono essere verificati con quelli di Google Navigazione sicura.

Se la visita di un URL genera un reindirizzamento (ad esempio HTTP 301), è opportuno che l'URL reindirizzato venga verificato con Google Navigazione sicura. La manipolazione degli URL lato client come History.pushState non comporta il controllo dei nuovi URL rispetto a Google Navigazione sicura.

Avvisi per l'utente

Se utilizzi Google Navigazione sicura per avvisare gli utenti dei rischi associati a determinate pagine web, vengono applicate le seguenti linee guida.

Queste linee guida contribuiscono a proteggere sia tu che Google dai malintesi, chiarendo che la pagina non è nota con certezza al 100% come risorsa web non sicura e che gli avvisi identificano semplicemente i possibili rischi.

• Nell'avviso visibile agli utenti non devi indurre gli utenti a credere che la pagina in questione sia, senza dubbio, una risorsa web non sicura. Quando fai riferimento alla pagina identificata o ai potenziali rischi che questa potrebbe comportare per gli utenti, devi qualificare l'avviso utilizzando termini quali sospetto, potenzialmente, possibile, probabile.
• L'avviso deve consentire all'utente di ottenere ulteriori informazioni esaminando la definizione di Google di varie minacce. Ti consigliamo di utilizzare i seguenti link:
  • Ingegneria sociale: https://developers.google.com/search/docs/monitor-debug/security/social-engineering
  • Malware e software indesiderato: https://developers.google.com/search/docs/monitor-debug/security/malware
  • Applicazioni potenzialmente dannose (solo Android): https://developers.google.com/android/play-protect/potentially-harmful-applications
• Quando mostri avvisi per le pagine identificate come rischiose dal servizio Navigazione sicura, devi attribuire a Google la riga "Consulenza fornita da Google" e un link all'avviso relativo alla Navigazione sicura. Se il tuo prodotto mostra avvisi basati su altre origini, non devi includere l'attribuzione Google negli avvisi derivati da dati non Google.

• Nella documentazione del prodotto, devi fornire un avviso per comunicare agli utenti che la protezione offerta da Google Navigazione sicura non è perfetta. Deve comunicare loro che esiste la possibilità sia di falsi positivi (siti sicuri segnalati come rischiosi) sia di falsi negativi (siti pericolosi non segnalati). Ti consigliamo di utilizzare il seguente linguaggio:

  Google si impegna per fornire le informazioni più accurate e aggiornate sulle risorse web non sicure. Tuttavia, Google non può garantire che le sue informazioni siano complete e prive di errori: alcuni siti rischiosi potrebbero non essere identificati, mentre alcuni siti sicuri potrebbero essere identificati per errore.

Modalità di funzionamento

Google Navigazione sicura v5 consente ai client di scegliere fra tre modalità di funzionamento.

Modalità In tempo reale

Quando i client scelgono di utilizzare Google Navigazione sicura v5 in modalità in tempo reale, manterranno nel proprio database locale: (i) una cache globale di siti probabili benefici, formattati come hash SHA256 di espressioni URL del suffisso host/prefisso percorso, (ii) un insieme di elenchi di minacce, formattati come prefissi hash SHA256 di espressioni URL del suffisso host/prefisso percorso. L'idea generale è che ogni volta che il cliente vuole controllare un particolare URL, viene eseguito un controllo locale utilizzando la cache globale. Se questo controllo ha esito positivo, viene eseguito un controllo degli elenchi di minacce locali. In caso contrario, il cliente continua con il controllo hash in tempo reale, come descritto di seguito.

Oltre al database locale, il client manterrà una cache locale. Una cache locale di questo tipo non deve necessariamente trovarsi in un'archiviazione permanente e potrebbe essere cancellata in caso di pressione della memoria.

Una specifica dettagliata della procedura è disponibile di seguito.

Modalità elenco locale

Se i client scelgono di utilizzare Google Navigazione sicura v5 in questa modalità, il comportamento del client è simile a quello dell'API v4 Update, ad eccezione dell'utilizzo della piattaforma API migliorata v5. I client manterranno nel loro database locale una serie di elenchi di minacce formattate come prefissi hash SHA256 di espressioni URL del suffisso host/prefisso percorso. Ogni volta che il cliente desidera controllare un particolare URL, viene eseguito un controllo utilizzando l’elenco locale delle minacce. Se e solo se c'è una corrispondenza, il client si connette al server per continuare il controllo.

Come nel caso precedente, il client manterrà anche una cache locale che non deve necessariamente trovarsi in un'archiviazione permanente.

Modalità In tempo reale senza spazio di archiviazione

Quando i client scelgono di utilizzare Google Navigazione sicura v5 in modalità in tempo reale senza spazio di archiviazione, non devono gestire alcun database locale. Ogni volta che un client desidera verificare un determinato URL, si connette sempre al server per eseguire un controllo. Questa modalità è simile a quella che potrebbero essere implementate dai client dell'API v4 Lookup.

Controllo degli URL

Questa sezione contiene specifiche dettagliate sulle modalità con cui i clienti controllano gli URL.

Canonicalizzazione degli URL

Prima del controllo degli URL, il client è tenuto a eseguire una qualche canonicalizzazione sull'URL in questione.

Per iniziare, supponiamo che il client abbia analizzato l'URL e lo abbia reso valido in base a RFC 2396. Se l'URL utilizza un nome di dominio internazionalizzato (IDN), il client deve convertirlo nella rappresentazione Punycode ASCII. L'URL deve includere un componente del percorso, ovvero deve avere almeno una barra che segue il dominio (http://google.com/ anziché http://google.com).

Innanzitutto, rimuovi i caratteri Tab (0x09), CR (0x0d) e LF (0x0a) dall'URL. Non rimuovere le sequenze di escape per questi caratteri (ad es. %0a).

In secondo luogo, se l'URL termina con un frammento, rimuovi quest'ultimo. Ad esempio, accorcia http://google.com/#frag in http://google.com/.

In terzo luogo, elimina ripetutamente la percentuale di escape dell'URL fino a quando non contiene più valori di escape percentuale. Questo potrebbe rendere l'URL non valido.

Per canonizzare il nome host:

Estrai il nome host dall'URL, quindi:

1. Rimuovi tutti i punti iniziali e finali.
2. Sostituisci i punti consecutivi con un unico punto.
3. Se il nome host può essere analizzato come indirizzo IPv4, normalizzato in 4 valori decimali separati da punti. Il client deve gestire qualsiasi codifica legale di indirizzi IP, inclusi ottale, esadecimale e meno di quattro componenti.
4. Se il nome host può essere analizzato come indirizzo IPv6 tra parentesi, normalizzalo rimuovendo gli zeri iniziali non necessari dai componenti e comprimi i componenti di zero utilizzando la sintassi dei due punti. Ad esempio, [2001:0db8:0000::1] deve essere trasformato in [2001:db8::1]. Se il nome host è uno dei due seguenti tipi di indirizzi IPv6 speciali, trasformali in IPv4:
   • Un indirizzo IPv6 mappato a IPv4, come [::ffff:1.2.3.4], che dovrebbe essere trasformato in 1.2.3.4.
   • Un indirizzo NAT64 che utilizza il noto prefisso 64:ff9b::/96, ad esempio [64:ff9b::1.2.3.4], che deve essere trasformato in 1.2.3.4.
5. Scrivi l'intera stringa in minuscolo.

Per canonizzare il percorso:

1. Risolvi le sequenze /../ e /./ nel percorso sostituendo /./ con / e rimuovendo /../ insieme al componente del percorso precedente.
2. Sostituisci le esecuzioni di barre consecutive con una barra singola.

Non applicare queste canonicalizzazioni dei percorsi ai parametri di query.

Nell'URL, utilizza l'escape di tutti i caratteri <= ASCII 32, >= 127, # o %. Le sequenze di escape devono utilizzare caratteri esadecimali maiuscoli.

Espressioni prefisso percorso host-suffisso

Dopo la canonicalizzazione dell'URL, il passaggio successivo consiste nella creazione delle espressioni di suffisso/prefisso. Ogni espressione prefisso/suffisso è composta da un suffisso host (o host completo) e da un prefisso di percorso (o percorso completo).

Il client può creare fino a 30 combinazioni possibili di suffisso host e prefisso percorso. Queste combinazioni utilizzano solo i componenti host e percorso dell'URL. Schema, nome utente, password e porta vengono ignorati. Se l'URL include parametri di query, almeno una combinazione includerà il percorso completo e i parametri di query.

Per l'host, il client proverà al massimo cinque stringhe diverse. Questi sono:

• Se il nome host non è un valore letterale IPv4 o IPv6, vengono formati fino a quattro nomi host iniziando con il dominio eTLD+1 e aggiungendo i componenti principali successivi. La determinazione di eTLD+1 dovrebbe basarsi sull'elenco dei suffissi pubblici. Ad esempio, a.b.example.com darebbe come risultato il dominio eTLD+1 di example.com e l'host con un componente host aggiuntivo b.example.com.
• Il nome host esatto nell'URL. Secondo l'esempio precedente, verrà controllato a.b.example.com.

Per il percorso, il client proverà al massimo sei stringhe diverse. Questi sono:

• Il percorso esatto dell'URL, inclusi i parametri di ricerca.
• Il percorso esatto dell'URL, senza parametri di query.
• I quattro percorsi formati iniziando dalla radice (/) e aggiungendo successivamente i componenti del percorso, tra cui una barra finale.

I seguenti esempi illustrano il comportamento di controllo:

Per l'URL http://a.b.com/1/2.html?param=1, il client proverà queste possibili stringhe:

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/

Per l'URL http://a.b.c.d.e.f.com/1.html, il client proverà queste possibili stringhe:

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/

Nota: ignora b.c.d.e.f.com, poiché prenderemo solo gli ultimi cinque componenti nome host e il nome host completo.

Per l'URL http://1.2.3.4/1/, il client proverà queste possibili stringhe:

1.2.3.4/1/
1.2.3.4/

Per l'URL http://example.co.uk/1, il client proverà queste possibili stringhe:

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

Hashing

Google Navigazione sicura utilizza esclusivamente SHA256 come funzione hash. Questa funzione hash deve essere applicata alle espressioni sopra riportate.

L'hash completo da 32 byte, a seconda delle circostanze, verrà troncato a 4 byte, 8 byte o 16 byte:

• Al momento, quando utilizzi il metodo hashes.search, gli hash della richiesta devono essere troncati a 4 byte esatti. L'invio di byte aggiuntivi in questa richiesta comprometterà la privacy dell'utente.

• Quando scarichi gli elenchi per il database locale utilizzando il metodo hashList.get o il metodo hashLists.batchGet, la lunghezza degli hash inviati dal server è influenzata sia dalla natura dell'elenco sia dalla preferenza del client in merito alla lunghezza dell'hash, comunicata dal parametro desired_hash_length.

Procedura di controllo degli URL in tempo reale

Questa procedura viene utilizzata quando il client sceglie la modalità operativa in tempo reale.

Questa procedura richiede un singolo URL u e restituisce SAFE, UNSAFE o UNSURE. Se restituisce SAFE, l'URL è considerato sicuro da Google Navigazione sicura. Se restituisce UNSAFE, l'URL è considerato potenzialmente non sicuro da Google Navigazione sicura e dovrebbero essere intraprese azioni appropriate: mostrare un avviso all'utente finale, spostare un messaggio ricevuto nella cartella Spam o richiedere un'ulteriore conferma da parte dell'utente prima di procedere. Se restituisce UNSURE, dovrai utilizzare in seguito la seguente procedura di controllo locale.

1. Consenti a expressions di essere un elenco di espressioni di suffissi/prefissi generati dall'URL u.
2. Sia expressionHashes un elenco, dove gli elementi sono hash SHA256 di ogni espressione in expressions.
3. Per ogni hash di expressionHashes:
   1. Se hash è presente nella cache globale, restituisci UNSURE.
4. Sia expressionHashPrefixes un elenco, dove gli elementi sono i primi 4 byte di ogni hash in expressionHashes.
5. Per ogni expressionHashPrefix di expressionHashPrefixes:
   1. Cerca expressionHashPrefix nella cache locale.
   2. Se viene trovata la voce memorizzata nella cache:
      1. Determina se l'ora attuale è successiva alla data di scadenza.
      2. Se è superiore:
         1. Rimuovi dalla cache locale la voce memorizzata nella cache.
         2. Continua con il laccetto.
      3. Se non è maggiore:
         1. Rimuovi questo expressionHashPrefix specifico da expressionHashPrefixes.
         2. Controlla se l'hash completo corrispondente all'interno di expressionHashes è presente nella voce memorizzata nella cache.
         3. Se lo trovi, restituisci UNSAFE.
         4. Se non lo trovi, continua con il loop.
   3. Se la voce memorizzata nella cache non viene trovata, continua con il loop.
6. Invia expressionHashPrefixes al server Google Navigazione sicura v5 utilizzando SearchHash RPC o il metodo REST hashes.search. Se si è verificato un errore (inclusi errori di rete, errori HTTP e così via), restituisci UNSURE. In caso contrario, lascia che la risposta sia il response ricevuto dal server SB, che è un elenco di hash completi insieme ad alcune informazioni ausiliarie che identificano la natura della minaccia (ingegneria sociale, malware, ecc.), così come la scadenza della cache expiration.
7. Per ogni fullHash di response:
   1. Inserisci fullHash nella cache locale, insieme a expiration.
8. Per ogni fullHash di response:
   1. Consenti a isFound di essere il risultato della ricerca di fullHash in expressionHashes.
   2. Se isFound è False, continua con il loop.
   3. Se isFound è True, restituisci UNSAFE.
9. Restituisci il giorno SAFE.

Procedura di controllo dell'URL dell'elenco di minacce locali

Questa procedura viene utilizzata quando il client sceglie la modalità operativa dell'elenco locale. Viene utilizzato anche quando il client la procedura RealTimeCheck sopra riportata restituisce il valore UNSURE.

Questa procedura richiede un singolo URL u e restituisce SAFE o UNSAFE.

1. Consenti a expressions di essere un elenco di espressioni di suffissi/prefissi generati dall'URL u.
2. Sia expressionHashes un elenco, dove gli elementi sono hash SHA256 di ogni espressione in expressions.
3. Sia expressionHashPrefixes un elenco, dove gli elementi sono i primi 4 byte di ogni hash in expressionHashes.
4. Per ogni expressionHashPrefix di expressionHashPrefixes:
   1. Cerca expressionHashPrefix nella cache locale.
   2. Se viene trovata la voce memorizzata nella cache:
      1. Determina se l'ora attuale è successiva alla data di scadenza.
      2. Se è superiore:
         1. Rimuovi dalla cache locale la voce memorizzata nella cache.
         2. Continua con il laccetto.
      3. Se non è maggiore:
         1. Rimuovi questo expressionHashPrefix specifico da expressionHashPrefixes.
         2. Controlla se l'hash completo corrispondente all'interno di expressionHashes è presente nella voce memorizzata nella cache.
         3. Se lo trovi, restituisci UNSAFE.
         4. Se non lo trovi, continua con il loop.
   3. Se la voce memorizzata nella cache non viene trovata, continua con il loop.
5. Per ogni expressionHashPrefix di expressionHashPrefixes:
   1. Cerca expressionHashPrefix nel database dell'elenco locale delle minacce.
   2. Se non è possibile trovare expressionHashPrefix nel database dell'elenco delle minacce locale, rimuovilo da expressionHashPrefixes.
6. Invia expressionHashPrefixes al server Google Navigazione sicura v5 utilizzando SearchHash RPC o il metodo REST hashes.search. Se si è verificato un errore (inclusi errori di rete, errori HTTP e così via), restituisci SAFE. In caso contrario, lascia che la risposta sia il response ricevuto dal server SB, che è un elenco di hash completi insieme ad alcune informazioni ausiliarie che identificano la natura della minaccia (ingegneria sociale, malware, ecc.), così come la scadenza della cache expiration.
7. Per ogni fullHash di response:
   1. Inserisci fullHash nella cache locale, insieme a expiration.
8. Per ogni fullHash di response:
   1. Consenti a isFound di essere il risultato della ricerca di fullHash in expressionHashes.
   2. Se isFound è False, continua con il loop.
   3. Se isFound è True, restituisci UNSAFE.
9. Restituisci il giorno SAFE.

La procedura di controllo degli URL in tempo reale senza un database locale

Questa procedura viene utilizzata quando il client sceglie la modalità operativa in tempo reale senza archiviazione.

Questa procedura richiede un singolo URL u e restituisce SAFE o UNSAFE.

1. Consenti a expressions di essere un elenco di espressioni di suffissi/prefissi generati dall'URL u.
2. Sia expressionHashes un elenco, dove gli elementi sono hash SHA256 di ogni espressione in expressions.
3. Sia expressionHashPrefixes un elenco, dove gli elementi sono i primi 4 byte di ogni hash in expressionHashes.
4. Per ogni expressionHashPrefix di expressionHashPrefixes:
   1. Cerca expressionHashPrefix nella cache locale.
   2. Se viene trovata la voce memorizzata nella cache:
      1. Determina se l'ora attuale è successiva alla data di scadenza.
      2. Se è superiore:
         1. Rimuovi dalla cache locale la voce memorizzata nella cache.
         2. Continua con il laccetto.
      3. Se non è maggiore:
         1. Rimuovi questo expressionHashPrefix specifico da expressionHashPrefixes.
         2. Controlla se l'hash completo corrispondente all'interno di expressionHashes è presente nella voce memorizzata nella cache.
         3. Se lo trovi, restituisci UNSAFE.
         4. Se non lo trovi, continua con il loop.
   3. Se la voce memorizzata nella cache non viene trovata, continua con il loop.
5. Invia expressionHashPrefixes al server Google Navigazione sicura v5 utilizzando SearchHash RPC o il metodo REST hashes.search. Se si è verificato un errore (inclusi errori di rete, errori HTTP e così via), restituisci SAFE. In caso contrario, lascia che la risposta sia il response ricevuto dal server SB, che è un elenco di hash completi insieme ad alcune informazioni ausiliarie che identificano la natura della minaccia (ingegneria sociale, malware, ecc.), così come la scadenza della cache expiration.
6. Per ogni fullHash di response:
   1. Inserisci fullHash nella cache locale, insieme a expiration.
7. Per ogni fullHash di response:
   1. Consenti a isFound di essere il risultato della ricerca di fullHash in expressionHashes.
   2. Se isFound è False, continua con il loop.
   3. Se isFound è True, restituisci UNSAFE.
8. Restituisci il giorno SAFE.

Manutenzione dei database locali

Google Navigazione sicura v5 si aspetta che il client mantenga un database locale, tranne quando sceglie la modalità in tempo reale senza spazio di archiviazione. La formattazione e l'archiviazione del database locale dipendono dal client. Il contenuto di questo database locale può essere concettualmente considerato come una cartella contenente vari elenchi come file, e il contenuto di questi file è hash SHA256 o prefissi hash.

Aggiornamenti del database

Il client chiama regolarmente il metodo hashList.get o il metodo hashLists.batchGet per aggiornare il database. Poiché un client tipico vuole aggiornare più elenchi alla volta, si consiglia di utilizzare il metodo hashLists.batchGet.

Gli elenchi sono identificati da nomi distinti. I nomi sono brevi stringhe ASCII brevi, lunghe pochi caratteri.

A differenza della versione V4, in cui gli elenchi sono identificati dalla tupla del tipo di minaccia, dal tipo di piattaforma e dal tipo di voce della minaccia, negli elenchi v5 sono semplicemente identificati per nome. Ciò fornisce flessibilità quando più elenchi v5 possono condividere lo stesso tipo di minaccia. I tipi di piattaforma e di voce delle minacce sono stati rimossi nella versione 5.

Una volta scelto un nome per un elenco, non verrà mai rinominato. Inoltre, una volta che un elenco è stato visualizzato, non verrà mai rimosso (se l'elenco non è più utile, diventerà vuoto, ma continuerà a esistere). Pertanto, è opportuno codificare questi nomi nel codice client di Google Navigazione sicura.

Sia il metodo hashList.get che il metodo hashLists.batchGet supportano gli aggiornamenti incrementali. L'utilizzo di aggiornamenti incrementali consente di risparmiare larghezza di banda e migliorare le prestazioni. Gli aggiornamenti incrementali funzionano mediante una pubblicazione di un delta tra la versione dell'elenco del client e la versione più recente dell'elenco. (se è stato appena eseguito il deployment di un client e non sono disponibili versioni, è disponibile un aggiornamento completo). L'aggiornamento incrementale contiene indici di rimozione e aggiunte. Il client deve prima rimuovere dal database locale le voci degli indici specificati e poi applicare le aggiunte.

Infine, per evitare il danneggiamento, il client deve controllare i dati archiviati rispetto al checksum fornito dal server. Ogni volta che il checksum non corrisponde, il client deve eseguire un aggiornamento completo.

Decodifica del contenuto dell'elenco

Tutti gli elenchi vengono pubblicati utilizzando una codifica speciale per ridurne le dimensioni. Questa codifica funziona riconoscendo che gli elenchi di Google Navigazione sicura contengono, concettualmente, un insieme di hash o prefissi hash, che non sono statisticamente indistinguibili dai numeri interi casuali. Se dovessimo ordinare questi numeri interi e prendere la loro differenza adiacente, la differenza adiacente dovrebbe essere "piccola". La codifica Golomb-Rice sfrutta quindi questa piccolezza.

Google Navigazione sicura v5 prevede quattro tipi distinti per la gestione dei dati a 4 byte, a 8 byte, a 16 byte e a 32 byte. Esaminiamo un esempio in cui vengono codificati tre numeri interi di 4 byte numericamente consecutivi. Lascia che il parametro Riso, indicato con k, sia 3. La parte del quoziente nella codifica è semplicemente il valore della differenza adiacente spostato a destra di k bit. Poiché i numeri interi dati sono consecutivi, la loro differenza adiacente è 1, e dopo lo spostamento di 3 bit la parte del quoziente è zero. I k bit meno significativi sono 001. Il quoziente zero è codificato come un singolo bit a 0. Il resto è 1 e codificato come 100. Questo viene ripetuto per formare il bitstream 01000100. Il bitstream risultante è codificato utilizzando small endian come 00100010. Pertanto, corrisponde ai seguenti dati:

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

Dopo il passaggio di decodifica di cui sopra per i numeri interi a 32 bit, i risultati sono utilizzabili direttamente come indici di rimozione o aggiunte. A differenza della versione 4, non è necessario eseguire uno scambio di byte in un secondo momento.

Elenchi disponibili

Si consiglia di utilizzare i seguenti elenchi in v5alpha1:

Nome elenco	Enum ThreatType v4 corrispondente	Descrizione
gc	Nessuno	Questo è un elenco di cache globali. Si tratta di un elenco speciale utilizzato soltanto nella modalità operativa In tempo reale.
se	SOCIAL_ENGINEERING	Questo elenco contiene minacce del tipo SOCIAL_ENGINEERING.
mw	MALWARE	Questo elenco contiene minacce del tipo di minaccia MALWARE per le piattaforme desktop.
uws	UNWANTED_SOFTWARE	Questo elenco contiene minacce del tipo di minaccia UNWANTED_SOFTWARE per le piattaforme desktop.
uwsa	UNWANTED_SOFTWARE	Questo elenco contiene minacce del tipo di minaccia UNWANTED_SOFTWARE per le piattaforme Android.
pha	POTENTIALLY_HARMFUL_APPLICATION	Questo elenco contiene minacce del tipo di minaccia POTENTIALLY_HARMFUL_APPLICATION per le piattaforme Android.

Ulteriori elenchi saranno disponibili in un secondo momento, quando la tabella sopra riportata verrà espansa.

Frequenza degli aggiornamenti

Il client deve controllare il valore restituito dal server nel campo minimum_wait_duration e utilizzarlo per pianificare il successivo aggiornamento del database. Questo valore potrebbe essere pari a zero e in questo caso il client dovrebbe eseguire immediatamente un altro aggiornamento.

Richieste di esempio

Questa sezione documenta alcuni esempi di utilizzo diretto dell'API HTTP per accedere a Google Navigazione sicura. In genere si consiglia di utilizzare un'associazione di lingua generata poiché gestirà automaticamente la codifica e la decodifica in modo pratico. Fai riferimento alla documentazione per quell'associazione.

Ecco un esempio di richiesta HTTP in cui viene utilizzato il metodo hashes.search:

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

Il corpo della risposta è un payload in formato buffer di protocollo che potrai decodificare.

Ecco un esempio di richiesta HTTP che utilizza il metodo hashLists.batchGet:

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

Il corpo della risposta è, ancora una volta, un payload formattato per il buffer di protocollo che puoi quindi decodificare.

Guida alla migrazione

Se attualmente utilizzi l'API v4 Update, puoi usufruire di un percorso di migrazione senza interruzioni da v4 a v5 senza dover reimpostare o cancellare il database locale. Questa sezione spiega come fare.

Conversione degli aggiornamenti dell'elenco in corso...

Nella versione 4, si utilizzava il metodothreatListUpdates.fetch per scaricare gli elenchi. Nella versione 5, si passa al metodo hashLists.batchGet.

Devi apportare le seguenti modifiche alla richiesta:

1. Rimuovi completamente l'oggetto ClientInfo v4. Anziché fornire l'identificazione di un client utilizzando un campo dedicato, utilizza semplicemente la nota intestazione User-Agent. Sebbene non esista un formato obbligatorio per fornire l'identificazione del client in questa intestazione, ti consigliamo di includere semplicemente l'ID client originale e la versione del client separati da uno spazio o da una barra.
2. Per ogni oggetto ListUpdateRequest v4:
   • Cerca il nome dell'elenco v5 corrispondente nella tabella precedente e fornisci questo nome nella richiesta v5.
   • Rimuovi i campi non necessari, come threat_entry_type o platform_type.
   • Il campo state nella versione 4 è compatibile direttamente con il campo versions nella versione 5. La stessa stringa di byte che verrebbe inviata al server utilizzando il campo state nella v4 può essere semplicemente inviata nella versione 5 utilizzando il campo versions.
   • Per i vincoli della versione 4, la versione 5 utilizza una versione semplificata denominata SizeConstraints. I campi aggiuntivi come region devono essere eliminati.

Devi apportare le seguenti modifiche alla risposta:

1. La v4 enum ResponseType viene semplicemente sostituita da un campo booleano denominato partial_update.
2. Il campo minimum_wait_duration ora può essere zero o omesso. In questo caso, il client deve effettuare immediatamente un'altra richiesta. Questo si verifica solo quando il client specifica in SizeConstraints un vincolo più piccolo relativo alla dimensione massima dell'aggiornamento rispetto alla dimensione massima del database.
3. L'algoritmo di decodifica Rice per i numeri interi a 32 bit dovrà essere modificato. La differenza è che i dati codificati sono codificati con un'estremità diversa. Sia nella versione 4 che nella versione 5, i prefissi hash a 32 bit sono ordinati lessicograficamente. Nella versione 4, invece, i prefissi vengono trattati come small endian se ordinati, mentre nella versione v5 vengono trattati come big-endian al momento dell'ordinamento. Ciò significa che il cliente non deve eseguire alcun ordinamento, poiché l'ordinamento lessicografico è identico a quello numerico per big endian. Un esempio di questo tipo nell'implementazione della versione 4 di Chromium è disponibile qui. Questo ordinamento può essere rimosso.
4. L'algoritmo di decodifica Rice dovrà essere implementato per altre lunghezze di hash.

Conversione delle ricerche di hash

Nella versione 4, si utilizzava il metodo fullHashes.find per ottenere hash completi. Il metodo equivalente nella versione v5 è il metodo hashes.search.

Devi apportare le seguenti modifiche alla richiesta:

1. Struttura il codice in modo che invii solo prefissi hash di lunghezza esatta di 4 byte.
2. Rimuovi del tutto gli oggetti ClientInfo v4. Anziché fornire l'identificazione di un client utilizzando un campo dedicato, utilizza semplicemente la nota intestazione User-Agent. Sebbene non esista un formato obbligatorio per fornire l'identificazione del client in questa intestazione, ti consigliamo di includere semplicemente l'ID client originale e la versione del client separati da uno spazio o da una barra.
3. Rimuovi il campo client_states. Non è più necessario.
4. Non è più necessario includere threat_types e campi simili.

Devi apportare le seguenti modifiche alla risposta:

1. Il campo minimum_wait_duration è stato rimosso. Il cliente può sempre inviare una nuova richiesta in base alle necessità.
2. L'oggetto ThreatMatch v4 è stato semplificato nell'oggetto FullHash.
3. La memorizzazione nella cache è stata semplificata in un'unica durata. Consulta le procedure precedenti per l'interazione con la cache.