Overview

Nota: questa documentazione è attualmente in fase di sviluppo. Prevediamo di apportare miglioramenti nel prossimo futuro.

La versione 5 di Google Navigazione sicura è un'evoluzione della versione 4. Le due modifiche principali apportate nella versione 5 sono l'aggiornamento dei dati e la privacy IP. Inoltre, l'interfaccia API è stata migliorata per aumentare la flessibilità e l'efficienza e ridurre il bloat. Inoltre, la versione 5 di Navigazione sicura di Google è progettata per semplificare la migrazione dalla versione 4.

Al momento, Google offre sia la versione 4 che la 5 e entrambe sono considerate pronte per la produzione. Puoi utilizzare la versione 4 o 5. Non abbiamo annunciato una data di ritiro della versione 4. In caso contrario, daremo un preavviso minimo di un anno. Questa pagina descrive la versione 5 e una guida alla migrazione dalla versione 4 alla versione 5. La documentazione completa della versione 4 rimane disponibile.

Aggiornamento dei dati

Nella versione 5, abbiamo introdotto una modalità di funzionamento nota come protezione in tempo reale. In questo modo, viene aggirato il problema dell'obsolescenza dei dati riportato sopra. Nella versione 4, i client devono scaricare e gestire un database locale, eseguire controlli in base agli elenchi di minacce scaricati localmente e, in caso di corrispondenza parziale del prefisso, eseguire una richiesta per scaricare l'hash completo. Nella versione 5, anche se i client devono continuare a scaricare e gestire un database locale di elenchi di minacce, ora devono anche scaricare un elenco di siti probabilmente innocui (chiamato cache globale), eseguire sia un controllo locale per questo cache globale sia un controllo locale degli elenchi di minacce e infine, in caso di corrispondenza parziale del prefisso per gli elenchi di minacce o di mancata corrispondenza nella cache globale, eseguire una richiesta per scaricare gli hash completi. Per informazioni dettagliate sull'elaborazione locale richiesta dal cliente, consulta la procedura riportata di seguito. Si tratta di un passaggio dal permesso per impostazione predefinita al controllo per impostazione predefinita, che può migliorare la protezione alla luce della propagazione più rapida delle minacce sul web. In altre parole, si tratta di un protocollo progettato per fornire protezione quasi in tempo reale: il nostro obiettivo è far sì che i clienti possano usufruire di dati più recenti di Google Navigazione sicura.

Privacy IP

Google Navigazione sicura (versione 4 o 5) non elabora nulla associato all'identità di un utente durante l'elaborazione delle richieste. I cookie, se inviati, vengono ignorati. Gli indirizzi IP di origine delle richieste sono noti a Google, ma Google li utilizza solo per esigenze di networking essenziali (ad es. per l'invio di risposte) e per scopi anti-DoS.

Contemporaneamente alla versione 5, stiamo introducendo un'API complementare nota come API Safe Browsing Oblivious HTTP Gateway. Questo metodo utilizza HTTP anonimo per nascondere a Google gli indirizzi IP degli utenti finali. Funziona in modo che una terza parte non collusa gestisca una versione criptata della richiesta dell'utente e la inoltri a Google. Di conseguenza, la terza parte ha accesso solo agli indirizzi IP e Google solo ai contenuti della richiesta. La terza parte gestisce un relè HTTP anonimo (ad esempio questo servizio di Fastly) e Google gestisce il gateway HTTP anonimo. Questa è un'API companion facoltativa. Se lo utilizzi in combinazione con Navigazione sicura di Google, gli indirizzi IP degli utenti finali non vengono più inviati a Google.

Le modalità di funzionamento

La versione 5 di Navigazione sicura di Google consente ai client di scegliere tra tre modalità di funzionamento.

Modalità In tempo reale

Quando i clienti scelgono di utilizzare la versione 5 di Google Safe Browsing in modalità in tempo reale, gestiscono nel proprio database locale: (i) una cache globale di siti probabilmente innocui, formattata come hash SHA256 di espressioni URL con suffisso host/prefisso percorso, (ii) un insieme di elenchi di minacce, formattati come prefissi di hash SHA256 di espressioni URL con suffisso host/prefisso percorso. L'idea di alto livello è che ogni volta che il client vuole controllare un determinato URL, viene eseguito un controllo locale utilizzando la cache globale. Se il controllo va a buon fine, viene eseguito un controllo degli elenchi di minacce locali. In caso contrario, il client continua con il controllo dell'hash in tempo reale, come descritto di seguito.

Oltre al database locale, il client manterrà una cache locale. Questa cache locale non deve essere nello spazio di archiviazione permanente e può essere cancellata in caso di pressione sulla memoria.

Di seguito è disponibile una specifica dettagliata della procedura.

Modalità Elenco locale

Quando i client scelgono di utilizzare la versione 5 di Navigazione sicura di Google in questa modalità, il loro comportamento è simile a quello dell'API Update 4, tranne per l'utilizzo dell'interfaccia API migliorata della versione 5. I client manterranno nel proprio database locale un insieme di elenchi di minacce formattati come prefissi di hash SHA256 di espressioni URL con suffisso host/prefisso percorso. Ogni volta che il cliente vuole controllare un determinato URL, viene eseguito un controllo utilizzando l'elenco delle minacce locali. Se e solo se esiste una corrispondenza, il client si connette al server per continuare il controllo.

Come per quanto sopra, il client manterrà anche una cache locale che non deve essere in uno spazio di archiviazione permanente.

Modalità in tempo reale senza archiviazione

Quando i client scelgono di utilizzare la versione 5 di Navigazione sicura di Google nella modalità in tempo reale senza spazio di archiviazione, non devono gestire alcun database locale persistente. Tuttavia, il client deve comunque mantenere una cache locale. Questa cache locale non deve essere nello spazio di archiviazione permanente e può essere cancellata in caso di pressione sulla memoria.

Ogni volta che il client vuole controllare un determinato URL, si connette sempre al server per eseguire un controllo. Questa modalità è simile a quella che potrebbero implementare i client dell'API Lookup 4.

Rispetto alla modalità in tempo reale, questa modalità potrebbe utilizzare più larghezza di banda di rete, ma potrebbe essere più adatta se per il client è sconveniente mantenere uno stato locale persistente.

Procedura di verifica degli URL in tempo reale

Questa procedura viene utilizzata quando il client sceglie la modalità di funzionamento 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 Safe Browsing e devono essere intraprese le 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, successivamente deve essere utilizzata la seguente procedura di controllo locale.

  1. Sia expressions un elenco di espressioni di suffissi/prefissi generate dall'URL u.
  2. Sia expressionHashes un elenco, i cui 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, i cui 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 corrente è successiva all'ora di scadenza.
      2. Se è superiore:
        1. Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
        2. Continua con il loop.
      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 viene trovato, restituisci UNSAFE.
        4. Se non viene trovato, continua con il ciclo.
    3. Se la voce memorizzata nella cache non viene trovata, continua con il ciclo.
  6. Invia expressionHashPrefixes al server di Navigazione sicura di Google 5 utilizzando SearchHashes 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, la risposta è il response ricevuto dal server SB, ovvero un elenco di hash completi insieme ad alcune informazioni ausiliarie che identificano la natura della minaccia (ingegneria sociale, malware e così via), nonché la data e l'ora di 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. Sia isFound il risultato della ricerca di fullHash in expressionHashes.
    2. Se isFound è False, continua con il ciclo.
    3. Se isFound è True, restituisce UNSAFE.
  9. Ritorno: SAFE.

Sebbene questo protocollo specifichi quando il client invia expressionHashPrefixes al server, non specifica intenzionalmente come inviarli. Ad esempio, è accettabile che il client invii tutti i expressionHashPrefixes in una singola richiesta ed è anche accettabile che il client invii ogni singolo prefisso in expressionHashPrefixes al server in richieste separate (magari procedendo in parallelo). È inoltre accettabile che il client invii prefissi di hash non correlati o generati in modo casuale insieme ai prefissi di hash in expressionHashPrefixes, a condizione che il numero di prefissi di hash inviati in una singola richiesta non superi 30.

Procedura di controllo degli URL nell'elenco LocalThreat

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

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

  1. Sia expressions un elenco di espressioni di suffissi/prefissi generate dall'URL u.
  2. Sia expressionHashes un elenco, i cui elementi sono hash SHA256 di ogni espressione in expressions.
  3. Sia expressionHashPrefixes un elenco, i cui 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 corrente è successiva all'ora di scadenza.
      2. Se è superiore:
        1. Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
        2. Continua con il loop.
      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 viene trovato, restituisci UNSAFE.
        4. Se non viene trovato, continua con il ciclo.
    3. Se la voce memorizzata nella cache non viene trovata, continua con il ciclo.
  5. Per ogni expressionHashPrefix di expressionHashPrefixes:
    1. Cerca expressionHashPrefix nel database dell'elenco delle minacce locali.
    2. Se expressionHashPrefix non è presente nel database dell'elenco delle minacce locali, rimuovilo da expressionHashPrefixes.
  6. Invia expressionHashPrefixes al server di Navigazione sicura di Google 5 utilizzando SearchHashes 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, la risposta è il response ricevuto dal server SB, ovvero un elenco di hash completi insieme ad alcune informazioni ausiliarie che identificano la natura della minaccia (ingegneria sociale, malware e così via), nonché la data e l'ora di 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. Sia isFound il risultato della ricerca di fullHash in expressionHashes.
    2. Se isFound è False, continua con il ciclo.
    3. Se isFound è True, restituisce UNSAFE.
  9. Ritorno: SAFE.

Procedura di verifica degli URL in tempo reale senza un database locale

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

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

  1. Sia expressions un elenco di espressioni di suffissi/prefissi generate dall'URL u.
  2. Sia expressionHashes un elenco, i cui elementi sono hash SHA256 di ogni espressione in expressions.
  3. Sia expressionHashPrefixes un elenco, i cui 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 corrente è successiva all'ora di scadenza.
      2. Se è superiore:
        1. Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
        2. Continua con il loop.
      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 viene trovato, restituisci UNSAFE.
        4. Se non viene trovato, continua con il ciclo.
    3. Se la voce memorizzata nella cache non viene trovata, continua con il ciclo.
  5. Invia expressionHashPrefixes al server di Navigazione sicura di Google 5 utilizzando SearchHashes 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, la risposta è il response ricevuto dal server SB, ovvero un elenco di hash completi insieme ad alcune informazioni ausiliarie che identificano la natura della minaccia (ingegneria sociale, malware e così via), nonché la data e l'ora di 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. Sia isFound il risultato della ricerca di fullHash in expressionHashes.
    2. Se isFound è False, continua con il ciclo.
    3. Se isFound è True, restituisce UNSAFE.
  8. Ritorno: SAFE.

Come la procedura di controllo dell'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 una singola richiesta ed è anche accettabile che il client invii ogni singolo prefisso in expressionHashPrefixes al server in richieste separate (magari procedendo in parallelo). È inoltre accettabile che il client invii prefissi di hash non correlati o generati in modo casuale insieme ai prefissi di hash in expressionHashPrefixes, a condizione che il numero di prefissi di hash inviati in una singola richiesta non superi 30.

Richieste di esempio

Questa sezione illustra alcuni esempi di utilizzo diretto dell'API HTTP per accedere a Navigazione sicura di Google. In genere, è consigliabile utilizzare un'associazione di linguaggi generata perché gestisce automaticamente la codifica e la decodifica in modo pratico. Consulta la documentazione relativa alla specifica 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 del protocollo che puoi 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-4b

Il corpo della risposta è, ancora una volta, un payload in formato buffer di protocollo che puoi decodificare.