Overview

Introduzione

Nota: questa documentazione è ancora in fase di sviluppo. Aspettati 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 dell'API è stata migliorata per aumentare la flessibilità e l'efficienza e ridurre il gonfiore. Inoltre, Google Navigazione sicura v5 è progettata per facilitare la migrazione dalla versione 4.

Al momento, Google offre le versioni 4 e 5 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, daremo un preavviso minimo di un anno. In questa pagina vengono descritte le versioni v5 e una guida alla migrazione dalla versione 4 alla versione 5. La documentazione completa relativa alla versione 4 rimane disponibile.

Aggiornamento dei dati

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

Nella versione 5, introduciamo una modalità di funzionamento nota come protezione in tempo reale. In questo modo è possibile aggirare il problema di inattività dei dati indicato sopra. Nella versione v4, i client dovrebbero scaricare e gestire un database locale, eseguire controlli sugli elenchi di minacce scaricati localmente e quindi, in presenza di una corrispondenza parziale del prefisso, eseguire una richiesta per scaricare l'hash completo. Nella versione 5, anche se i client dovrebbero continuare a scaricare e mantenere un database locale di elenchi di minacce, ora i client dovrebbero anche scaricare un elenco di siti probabilmente benigni (chiamato Global Cache), eseguire sia un controllo locale per questa Cache globale sia un controllo dell’elenco delle minacce locali e, infine, quando c’è una corrispondenza del prefisso parziale per gli elenchi di minacce o un’assenza di corrispondenza nella cache globale, eseguire una richiesta per scaricare gli hash completi. Per informazioni dettagliate sul trattamento locale richiesto dal cliente, consulta la procedura indicata di seguito. Ciò rappresenta un passaggio dall’impostazione predefinita a quella predefinita, 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 offrire una protezione quasi in tempo reale: il nostro obiettivo è far sì che i clienti usufruiscano di dati più aggiornati di Google Navigazione sicura.

Privacy IP

Google Navigazione sicura (v4 o v5) non elabora informazioni associate all'identità dell'utente nel corso della pubblicazione delle richieste. I cookie, se inviati, vengono ignorati. Gli indirizzi IP di origine delle richieste sono noti a Google, ma Google li utilizza soltanto per esigenze di networking essenziali (ovvero per l'invio di risposte) e per scopi anti-DoS.

Contemporaneamente alla versione 5, introduciamo un'API complementare, nota come API Navigazione sicura Oblivious HTTP Gateway. In questo modo viene utilizzato il protocollo Oblivious HTTP per nascondere gli indirizzi IP degli utenti finali a Google. Questa operazione prevede la gestione di una versione criptata della richiesta dell'utente da parte di una terza parte che non applica restrizioni e la inoltra 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 Oblivious HTTP. Questa è un'API Companion facoltativa. Quando la funzionalità viene utilizzata insieme a Google Navigazione sicura, gli indirizzi IP degli utenti finali non vengono più inviati a Google.

Utilizzo appropriato

Uso consentito

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

Prezzi

Tutte le API di Google Navigazione sicura sono senza costi.

Quote

Agli sviluppatori viene assegnata una quota di utilizzo predefinita al momento dell'attivazione dell'API Navigazione sicura. L'allocazione e l'utilizzo attuali possono essere visualizzati in Google Developer Console. Se prevedi di utilizzare una quota superiore a quella attualmente allocata, puoi richiedere una quota aggiuntiva dall'interfaccia Quota di Play Console. Esaminiamo queste richieste e richiediamo un contatto quando richiediamo 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 intervenire sugli URL visualizzati nella barra degli indirizzi di un browser. Non è progettato per essere utilizzato per il confronto con 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 Google Navigazione sicura.

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

Avvisi per gli utenti

Se utilizzi Google Navigazione sicura per avvisare gli utenti dei rischi derivanti da pagine web specifiche, vengono applicate le seguenti linee guida.

Queste linee guida aiutano a proteggere te e Google da malintesi, poiché indicano chiaramente che la pagina non è nota con una certezza del 100% come risorsa web non sicura e che gli avvisi si limitano a identificare un possibile rischio.

• Nell'avviso visibile per l'utente 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 sospetta, potenzialmente, possibile, probabile.
• L'avviso deve consentire all'utente di ottenere maggiori informazioni esaminando la definizione di varie minacce di Google. Vengono suggeriti i seguenti link:
  • Social Engineering: 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 fornire l'attribuzione a Google includendo la riga "Avviso fornito da Google" con un link all'avvertenza di Navigazione sicura. Se il tuo prodotto mostra anche avvisi basati su altre fonti, non devi includere l'attribuzione Google negli avvisi derivanti da dati non Google.

• Nella documentazione del prodotto, devi inserire un avviso per informare gli utenti che la protezione offerta da Google Navigazione sicura non è perfetta. Deve comunicare all'utente 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 la seguente lingua:

  Google si impegna per fornire le informazioni più accurate e aggiornate in merito alle 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 altri 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 clienti scelgono di utilizzare Google Navigazione sicura v5 in modalità in tempo reale, i client manterranno nel loro database locale: (i) una cache globale di siti probabili benefici, formattata come hash SHA256 di espressioni URL su suffisso host/prefisso percorso, (ii) un insieme di elenchi di minacce, formattate come prefissi hash SHA256 di espressioni URL prefisso-suffisso/percorso host. L'idea generale è che ogni volta che il cliente desidera controllare un particolare URL, venga eseguito un controllo locale utilizzando la cache globale. Se questo controllo viene superato, viene eseguito un controllo degli elenchi di minacce locali. In caso contrario, il client continua con il controllo degli hash in tempo reale, come descritto di seguito.

Oltre al database locale, il client manterrà una cache locale. Questa cache locale non deve necessariamente trovarsi in uno spazio di archiviazione permanente e può essere cancellata in caso di utilizzo della memoria.

Di seguito è riportata una descrizione dettagliata della procedura.

Modalità elenco locale

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

Come nel caso precedente, il client gestirà anche una cache locale che non deve trovarsi in uno spazio di 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 permanente. Tuttavia, il client continuerà a mantenere una cache locale. Questa cache locale non deve necessariamente trovarsi in uno spazio di archiviazione permanente e può essere cancellata in caso di utilizzo della memoria.

Ogni volta che il client desidera verificare un particolare URL, si connette sempre al server per eseguire un controllo. Questa modalità è simile a quella implementata dai client dell'API v4 Lookup.

Rispetto alla modalità in tempo reale, questa modalità può utilizzare una maggiore larghezza di banda di rete, ma è più adatta se non consente al client di mantenere uno stato locale permanente.

Controllo degli URL in corso...

Questa sezione contiene specifiche dettagliate su come i clienti controllano gli URL.

Canonicalizzazione degli URL

Prima di controllare gli URL, è previsto che il client ne esegua una parte della canonicalizzazione.

Per iniziare, supponiamo che il client abbia analizzato l'URL e lo abbia reso valido in base allo standard RFC 2396. Se l'URL utilizza un nome di dominio internazionalizzato (IDN), il client deve convertire l'URL 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).

In primo luogo, 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, rimuovilo se l'URL termina con un frammento. Ad esempio, abbrevia http://google.com/#frag in http://google.com/.

In terzo luogo, elimina ripetutamente caratteri di escape percentuali dell'URL finché non sono presenti più caratteri di escape percentuali. Ciò potrebbe rendere l'URL non valido.

Per canonicalizzare il nome host:

Estrai il nome host dall'URL e poi:

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, normalizzalo in modo da utilizzare valori decimali separati da 4 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 nei componenti e comprimendo 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, ad esempio [::ffff:1.2.3.4], che deve 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 dovrebbe essere trasformato in 1.2.3.4.
5. Scrivi l'intera stringa in minuscolo.

Per canonicalizzare 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 singola barra.

Non applicare queste canonicalizzazioni dei percorsi ai parametri di query.

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

Espressioni prefisso-percorso host-suffisso

Dopo aver canonicalizzato l'URL, il passaggio successivo consiste nel creare le espressioni suffisso/prefisso. Ogni espressione di suffisso/prefisso è composta da un suffisso host (o host completo) e da un prefisso di percorso (o percorso completo).

Il client formerà fino a 30 diverse combinazioni possibili di suffisso host e prefisso del percorso. Queste combinazioni utilizzano solo i componenti host e il percorso dell'URL. Lo schema, il nome utente, la password e la 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 deve basarsi sull'elenco dei suffissi pubblici. Ad esempio, a.b.example.com determina il dominio eTLD+1 example.com nonché l'host con un componente host aggiuntivo b.example.com.
• Il nome host esatto nell'URL. Secondo l'esempio precedente, verrà selezionato 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, inclusa una barra finale.

I seguenti esempi illustrano il comportamento del 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é verranno utilizzati solo gli ultimi cinque componenti del 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 indicate.

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

• Quando utilizzi il metodo hashes.search, al momento richiediamo che gli hash nella richiesta vengano troncati a esattamente 4 byte. 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 termini di 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 prende 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 devono essere intraprese azioni appropriate, ad esempio 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, occorre utilizzare la seguente procedura di controllo locale.

1. Consenti a expressions di essere un elenco di espressioni di suffisso/prefisso generate dall'URL u.
2. Sia expressionHashes un elenco, in cui gli elementi sono hash SHA256 di ogni espressione in expressions.
3. Per ogni elemento hash di expressionHashes:
   1. Se hash può essere trovato nella cache globale, restituisce UNSURE.
4. Sia expressionHashPrefixes un elenco, in cui gli elementi sono i primi 4 byte di ogni hash in expressionHashes.
5. Per ogni elemento expressionHashPrefix di expressionHashPrefixes:
   1. Cerca expressionHashPrefix nella cache locale.
   2. Se viene trovata la voce memorizzata nella cache:
      1. Determina se l'ora corrente è superiore alla data di scadenza.
      2. Se è maggiore:
         1. Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
         2. Continua con il loop.
      3. Se non è superiore:
         1. Rimuovi questo particolare expressionHashPrefix da expressionHashPrefixes.
         2. Controlla se l'hash completo corrispondente in expressionHashes si trova 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 RPC SearchHashes o il metodo REST hashes.search. Se si è verificato un errore (compresi errori di rete, errori HTTP e così via), restituisce UNSURE. Altrimenti, 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.), nonché il tempo di scadenza della cache expiration.
7. Per ogni elemento fullHash di response:
   1. Inserisci fullHash nella cache locale insieme a expiration.
8. Per ogni elemento fullHash di response:
   1. Sia isFound il risultato dell'individuazione di fullHash in expressionHashes.
   2. Se isFound è False, continua con il loop.
   3. Se isFound è True, restituisce UNSAFE.
9. Restituisci SAFE.

Questo protocollo specifica quando il client invia expressionHashPrefixes al server, ma non specifica intenzionalmente come inviarli. Ad esempio, è accettabile che il client invii tutti i expressionHashPrefixes in un'unica richiesta ed è anche accettabile che il client invii ogni singolo prefisso di expressionHashPrefixes al server in richieste separate (magari procedendo in parallelo). Il client può anche inviare prefissi hash non correlati o generati in modo casuale insieme ai prefissi hash in expressionHashPrefixes, purché il numero di prefissi hash inviati in una singola richiesta non sia superiore a 30.

Procedura di controllo degli URL dell'elenco LocalThreat

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

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

1. Consenti a expressions di essere un elenco di espressioni di suffisso/prefisso generate dall'URL u.
2. Sia expressionHashes un elenco, in cui gli elementi sono hash SHA256 di ogni espressione in expressions.
3. Sia expressionHashPrefixes un elenco, in cui gli elementi sono i primi 4 byte di ogni hash in expressionHashes.
4. Per ogni elemento expressionHashPrefix di expressionHashPrefixes:
   1. Cerca expressionHashPrefix nella cache locale.
   2. Se viene trovata la voce memorizzata nella cache:
      1. Determina se l'ora corrente è superiore alla data di scadenza.
      2. Se è maggiore:
         1. Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
         2. Continua con il loop.
      3. Se non è superiore:
         1. Rimuovi questo particolare expressionHashPrefix da expressionHashPrefixes.
         2. Controlla se l'hash completo corrispondente in expressionHashes si trova 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 elemento expressionHashPrefix di expressionHashPrefixes:
   1. Cerca expressionHashPrefix nel database dell'elenco delle minacce locali.
   2. Se non è possibile trovare expressionHashPrefix nel database locale dell'elenco delle minacce, rimuovilo da expressionHashPrefixes.
6. Invia expressionHashPrefixes al server Google Navigazione sicura v5 utilizzando RPC SearchHashes o il metodo REST hashes.search. Se si è verificato un errore (compresi errori di rete, errori HTTP e così via), restituisce SAFE. Altrimenti, 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.), nonché il tempo di scadenza della cache expiration.
7. Per ogni elemento fullHash di response:
   1. Inserisci fullHash nella cache locale insieme a expiration.
8. Per ogni elemento fullHash di response:
   1. Sia isFound il risultato dell'individuazione di fullHash in expressionHashes.
   2. Se isFound è False, continua con il loop.
   3. Se isFound è True, restituisce UNSAFE.
9. Restituisci 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 spazio di archiviazione.

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

1. Consenti a expressions di essere un elenco di espressioni di suffisso/prefisso generate dall'URL u.
2. Sia expressionHashes un elenco, in cui gli elementi sono hash SHA256 di ogni espressione in expressions.
3. Sia expressionHashPrefixes un elenco, in cui gli elementi sono i primi 4 byte di ogni hash in expressionHashes.
4. Per ogni elemento expressionHashPrefix di expressionHashPrefixes:
   1. Cerca expressionHashPrefix nella cache locale.
   2. Se viene trovata la voce memorizzata nella cache:
      1. Determina se l'ora corrente è superiore alla data di scadenza.
      2. Se è maggiore:
         1. Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
         2. Continua con il loop.
      3. Se non è superiore:
         1. Rimuovi questo particolare expressionHashPrefix da expressionHashPrefixes.
         2. Controlla se l'hash completo corrispondente in expressionHashes si trova 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 RPC SearchHashes o il metodo REST hashes.search. Se si è verificato un errore (compresi errori di rete, errori HTTP e così via), restituisce SAFE. Altrimenti, 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.), nonché il tempo di scadenza della cache expiration.
6. Per ogni elemento fullHash di response:
   1. Inserisci fullHash nella cache locale insieme a expiration.
7. Per ogni elemento fullHash di response:
   1. Sia isFound il risultato dell'individuazione di fullHash in expressionHashes.
   2. Se isFound è False, continua con il loop.
   3. Se isFound è True, restituisce UNSAFE.
8. Restituisci SAFE.

Come la procedura di controllo degli URL in tempo reale, questa procedura non specifica esattamente come inviare i prefissi hash al server. Ad esempio, è accettabile che il client invii tutti i expressionHashPrefixes in un'unica richiesta ed è anche accettabile che il client invii ogni singolo prefisso di expressionHashPrefixes al server in richieste separate (magari procedendo in parallelo). Il client può anche inviare prefissi hash non correlati o generati in modo casuale insieme ai prefissi hash in expressionHashPrefixes, purché il numero di prefissi hash inviati in una singola richiesta non sia superiore a 30.

Manutenzione dei database locali

Google Navigazione sicura v5 prevede che il client mantenga un database locale, tranne quando sceglie la modalità in tempo reale senza spazio di archiviazione. Spetta al client il formato e l'archiviazione di questo database locale. Concettualmente, i contenuti di questo database locale possono essere considerati come una cartella contenente vari elenchi come file e i contenuti di questi file sono hash SHA256 o prefissi hash.

Aggiornamenti del database

Il client chiamerà regolarmente il metodo hashList.get o il metodo hashLists.batchGet per aggiornare il database. Poiché il client tipico vuole aggiornare più elenchi alla volta, ti consigliamo di utilizzare il metodo hashLists.batchGet.

Gli elenchi sono identificati da nomi distinti. I nomi sono stringhe ASCII brevi e lunghe alcuni caratteri.

A differenza di V4, dove gli elenchi sono identificati dalla tupla di tipo di minaccia, tipo di piattaforma e tipo di voce di minaccia, negli elenchi v5 vengono semplicemente identificati per nome. Questo fornisce flessibilità quando più elenchi v5 potrebbero condividere lo stesso tipo di minaccia. I tipi di piattaforma e di inserimento delle minacce sono stati rimossi nella versione 5.

Una volta scelto, un nome per un elenco non verrà mai rinominato. Inoltre, una volta visualizzato, un elenco non verrà mai rimosso (se non è più utile, diventerà vuoto ma continuerà a esistere). Pertanto, è opportuno codificare questi nomi come hardcoded 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 generando un delta tra la versione dell'elenco del cliente e la versione più recente dell'elenco. (se un client è stato appena eseguito il deployment e non ha versioni disponibili, è disponibile un aggiornamento completo.) L'aggiornamento incrementale contiene indici e aggiunte di rimozione. Il client deve prima rimuovere le voci negli indici specificati dal proprio database locale, quindi applicare le aggiunte.

Infine, per evitare il danneggiamento, il client deve verificare 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

Decodifica di hash e prefissi hash

Tutti gli elenchi vengono inviati mediante una codifica speciale per ridurne le dimensioni. Questa codifica riconosce che gli elenchi di Google Navigazione sicura contengono concettualmente un insieme di hash o prefissi hash che sono statisticamente indistinguibili dai numeri interi casuali. Se ordinassimo questi numeri interi e prendessimo la loro differenza adiacente, questa differenza adiacente dovrebbe essere in un certo senso "piccola". La codifica Golomb-Rice sfrutta questa piccolezza.

Supponiamo che tre espressioni con prefisso percorso del suffisso host, a.example.com/, b.example.com/ e y.example.com/, vengano trasmesse usando prefissi hash da 4 byte. Inoltre, supponiamo che il parametro Riso, indicato con k, sia scelto su 30. Il server inizia calcolando l'hash completo per queste stringhe, che sono, rispettivamente:

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

Il server forma quindi prefissi hash da 4 byte per ciascuno degli elementi precedenti, che sono i primi 4 byte dell'hash completo da 32 byte, interpretati come numeri interi a 32 bit big-endian. La "big endianness" si riferisce al fatto che il primo byte dell'hash completo diventa il byte più significativo del numero intero a 32 bit. Questo passaggio restituisce i numeri interi 0x291bc542, 0x1d32c508 e 0xf7a502e5.

È necessario che il server ordini questi tre prefissi hash in modo grammaticale (equivalente all'ordinamento numerico in big endian) e il risultato dell'ordinamento è 0x1d32c508, 0x291bc542, 0xf7a502e5. Il primo prefisso hash viene memorizzato invariato nel campo first_value.

Il server quindi calcola le due differenze adiacenti, rispettivamente 0xbe9003a e 0xce893da3. Dato che k viene scelto come 30, il server suddivide questi due numeri nelle parti del quoziente e nelle parti di resto lunghe rispettivamente 2 e 30 bit. Per il primo numero, la parte del quoziente è zero e il resto è 0xbe9003a; per il secondo numero, la parte del quoziente è 3 perché i due bit più significativi sono 11 in binario e il resto è 0xe893da3. Per un dato quoziente q, questo viene codificato in (1 << q) - 1 utilizzando esattamente 1 + q bit; il resto è codificato direttamente utilizzando k bit. La parte del quoziente del primo numero è codificata come 0 e la parte restante è in codice binario 001011111010010000000000111010; la parte del quoziente del secondo numero è codificata come 0111 e la parte restante è 0011101000101010101010

Quando questi numeri vengono formati in una stringa di byte, si usa l'endpoint-endian. Concettualmente, può essere più facile immaginare che si forma una lunga bitstring a partire dai bit meno significativi: prendiamo la parte del quoziente del primo numero e anteponiamo la parte restante del primo numero; quindi anteponiamo ulteriormente la parte di quoziente del secondo numero e anteponiamo la parte restante. Ciò dovrebbe comportare il seguente numero elevato (linebreak e commenti aggiunti per chiarezza):

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

Scritto in una sola riga,

00111010001001001111011010001101110010111110100100000000001110100

Ovviamente questo numero supera di gran lunga gli 8 bit disponibili in un singolo byte. La piccola codifica endian prende quindi gli 8 bit meno significativi di quel numero e li restituisce come primo byte, ovvero 01110100. Per chiarezza, possiamo raggruppare la bitstring di cui sopra in gruppi di otto partendo dai bit meno significativi:

0 01110100 01001001 11101101 00011011 10010111 11010010 00000000 01110100

La piccola codifica endian prende quindi ogni byte da destra e lo inserisce in una bytestring:

01110100
00000000
11010010
10010111
00011011
11101101
01001001
01110100
00000000

Si può vedere che, poiché concettualmente prepend nuove parti al grande numero a sinistra (ovvero aggiungiamo bit più significativi), ma codifichiamo da destra (ovvero i bit meno significativi), la codifica e la decodifica possono essere eseguite in modo incrementale.

Il risultato finale

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

Il client segue invertiti i passaggi riportati sopra per decodificare i prefissi hash. A differenza della versione 4, non è necessario eseguire uno scambio di byte alla fine poiché i numeri interi con prefisso hash vengono interpretati come big endian.

Decodifica degli indici di rimozione

Gli indici di rimozione sono codificati utilizzando la stessa tecnica di cui sopra, utilizzando numeri interi a 32 bit. La codifica e la decodifica degli indici di rimozione non sono cambiate tra le versioni v4 e v5.

Elenchi disponibili

Nella versione v5alpha1 è consigliato l'uso dei seguenti elenchi:

Nome elenco	Enum v4 ThreatType corrispondente	Descrizione
gc	Nessun valore	Questo elenco è un elenco di Cache globale. Si tratta di un elenco speciale utilizzato soltanto nel funzionamento in tempo reale.
se	SOCIAL_ENGINEERING	Questo elenco contiene le minacce del tipo SOCIAL_ENGINEERING.
mw	MALWARE	Questo elenco contiene le minacce del tipo di minaccia MALWARE per le piattaforme desktop.
uws	UNWANTED_SOFTWARE	Questo elenco contiene le minacce del tipo di minaccia UNWANTED_SOFTWARE per piattaforme desktop.
uwsa	UNWANTED_SOFTWARE	Questo elenco contiene le minacce del tipo di minaccia UNWANTED_SOFTWARE per le piattaforme Android.
pha	POTENTIALLY_HARMFUL_APPLICATION	Questo elenco contiene le minacce del tipo di minaccia POTENTIALLY_HARMFUL_APPLICATION per le piattaforme Android.

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

Il client può gestire un server proxy di memorizzazione nella cache per recuperare alcuni o tutti gli elenchi riportati sopra e quindi fare in modo che il client contatti il server proxy. Se viene implementato, consigliamo una durata della cache breve, ad esempio cinque minuti; in futuro, la durata della cache potrebbe essere comunicata utilizzando l'intestazione HTTP Cache-Control standard.

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. Possibilmente questo valore è pari a zero (il campo minimum_wait_duration è completamente mancante), nel qual 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 consigliamo di utilizzare un'associazione di linguaggio generata perché gestirà automaticamente la codifica e la decodifica in modo pratico. Fai riferimento alla documentazione relativa all'associazione.

Ecco un esempio di richiesta HTTP che utilizza 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 puoi quindi decodificare.

Ecco un esempio di richiesta HTTP utilizzando 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 in formato buffer di protocollo che puoi quindi decodificare.

Guida alla migrazione

Se al momento utilizzi l'API di aggiornamento v4, il percorso di migrazione dalla versione 4 alla 5 può essere completato senza dover reimpostare o cancellare il database locale. Questa sezione spiega come fare.

Conversione aggiornamenti elenco in corso...

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

È necessario apportare le seguenti modifiche alla richiesta:

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

È necessario apportare le seguenti modifiche alla risposta:

1. La versione v4 enum ResponseType è 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 accade solo quando il client specifica in SizeConstraints un vincolo inferiore alla dimensione massima di aggiornamento rispetto alla dimensione massima del database.
3. Dovrai modificare l'algoritmo di decodifica di Rice per i numeri interi a 32 bit. La differenza è che i dati codificati sono codificati con un'endianità diversa. Sia nella versione 4 che nella versione 5, i prefissi hash a 32 bit sono ordinati in modo grammaticale. Tuttavia, nella versione 4 questi prefissi vengono trattati come piccoli endian al momento dell'ordinamento, mentre nella versione 5 vengono trattati come "big endian" al momento dell'ordinamento. Ciò significa che il client non deve eseguire alcun ordinamento, poiché l'ordinamento lessicografico è identico all'ordinamento numerico con big endian. Puoi trovare un esempio di questo tipo nell'implementazione della versione 4 di Chromium qui. Questo ordinamento può essere rimosso.
4. L'algoritmo di decodifica del riso dovrà essere implementato per altri hash.

Conversione delle ricerche con hash

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

È necessario apportare le seguenti modifiche alla richiesta:

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

È necessario 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 e ora ha una durata unica. Consulta le procedure precedenti per l'interazione con la cache.