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.
- Sia
expressions
un elenco di espressioni di suffissi/prefissi generate dall'URLu
. - Sia
expressionHashes
un elenco, i cui elementi sono hash SHA256 di ogni espressione inexpressions
. - Per ogni
hash
diexpressionHashes
:- Se
hash
è presente nella cache globale, restituisciUNSURE
.
- Se
- Sia
expressionHashPrefixes
un elenco, i cui elementi sono i primi 4 byte di ogni hash inexpressionHashes
. - Per ogni
expressionHashPrefix
diexpressionHashPrefixes
:- Cerca
expressionHashPrefix
nella cache locale. - Se viene trovata la voce memorizzata nella cache:
- Determina se l'ora corrente è successiva all'ora di scadenza.
- Se è superiore:
- Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
- Continua con il loop.
- Se non è maggiore:
- Rimuovi questo
expressionHashPrefix
specifico daexpressionHashPrefixes
. - Controlla se l'hash completo corrispondente all'interno di
expressionHashes
è presente nella voce memorizzata nella cache. - Se viene trovato, restituisci
UNSAFE
. - Se non viene trovato, continua con il ciclo.
- Rimuovi questo
- Se la voce memorizzata nella cache non viene trovata, continua con il ciclo.
- Cerca
- 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), restituisciUNSURE
. In caso contrario, la risposta è ilresponse
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 cacheexpiration
. - Per ogni
fullHash
diresponse
:- Inserisci
fullHash
nella cache locale, insieme aexpiration
.
- Inserisci
- Per ogni
fullHash
diresponse
:- Sia
isFound
il risultato della ricerca difullHash
inexpressionHashes
. - Se
isFound
è False, continua con il ciclo. - Se
isFound
è True, restituisceUNSAFE
.
- Sia
- 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
.
- Sia
expressions
un elenco di espressioni di suffissi/prefissi generate dall'URLu
. - Sia
expressionHashes
un elenco, i cui elementi sono hash SHA256 di ogni espressione inexpressions
. - Sia
expressionHashPrefixes
un elenco, i cui elementi sono i primi 4 byte di ogni hash inexpressionHashes
. - Per ogni
expressionHashPrefix
diexpressionHashPrefixes
:- Cerca
expressionHashPrefix
nella cache locale. - Se viene trovata la voce memorizzata nella cache:
- Determina se l'ora corrente è successiva all'ora di scadenza.
- Se è superiore:
- Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
- Continua con il loop.
- Se non è maggiore:
- Rimuovi questo
expressionHashPrefix
specifico daexpressionHashPrefixes
. - Controlla se l'hash completo corrispondente all'interno di
expressionHashes
è presente nella voce memorizzata nella cache. - Se viene trovato, restituisci
UNSAFE
. - Se non viene trovato, continua con il ciclo.
- Rimuovi questo
- Se la voce memorizzata nella cache non viene trovata, continua con il ciclo.
- Cerca
- Per ogni
expressionHashPrefix
diexpressionHashPrefixes
:- Cerca
expressionHashPrefix
nel database dell'elenco delle minacce locali. - Se
expressionHashPrefix
non è presente nel database dell'elenco delle minacce locali, rimuovilo daexpressionHashPrefixes
.
- Cerca
- 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), restituisciSAFE
. In caso contrario, la risposta è ilresponse
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 cacheexpiration
. - Per ogni
fullHash
diresponse
:- Inserisci
fullHash
nella cache locale, insieme aexpiration
.
- Inserisci
- Per ogni
fullHash
diresponse
:- Sia
isFound
il risultato della ricerca difullHash
inexpressionHashes
. - Se
isFound
è False, continua con il ciclo. - Se
isFound
è True, restituisceUNSAFE
.
- Sia
- 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
.
- Sia
expressions
un elenco di espressioni di suffissi/prefissi generate dall'URLu
. - Sia
expressionHashes
un elenco, i cui elementi sono hash SHA256 di ogni espressione inexpressions
. - Sia
expressionHashPrefixes
un elenco, i cui elementi sono i primi 4 byte di ogni hash inexpressionHashes
. - Per ogni
expressionHashPrefix
diexpressionHashPrefixes
:- Cerca
expressionHashPrefix
nella cache locale. - Se viene trovata la voce memorizzata nella cache:
- Determina se l'ora corrente è successiva all'ora di scadenza.
- Se è superiore:
- Rimuovi la voce memorizzata nella cache trovata dalla cache locale.
- Continua con il loop.
- Se non è maggiore:
- Rimuovi questo
expressionHashPrefix
specifico daexpressionHashPrefixes
. - Controlla se l'hash completo corrispondente all'interno di
expressionHashes
è presente nella voce memorizzata nella cache. - Se viene trovato, restituisci
UNSAFE
. - Se non viene trovato, continua con il ciclo.
- Rimuovi questo
- Se la voce memorizzata nella cache non viene trovata, continua con il ciclo.
- Cerca
- 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), restituisciSAFE
. In caso contrario, la risposta è ilresponse
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 cacheexpiration
. - Per ogni
fullHash
diresponse
:- Inserisci
fullHash
nella cache locale, insieme aexpiration
.
- Inserisci
- Per ogni
fullHash
diresponse
:- Sia
isFound
il risultato della ricerca difullHash
inexpressionHashes
. - Se
isFound
è False, continua con il ciclo. - Se
isFound
è True, restituisceUNSAFE
.
- Sia
- 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.