Questo documento si applica ai seguenti metodi:
Informazioni sulla memorizzazione nella cache
Per ridurre l'utilizzo della larghezza di banda da parte dei client e proteggere Google dai picchi di traffico, sia i client delle API Search sia quelli dell'API Update devono creare e mantenere una cache locale dei dati sulle minacce.
Per l'API lookup, la cache viene utilizzata per ridurre il numero di richieste threatMatches
che i client inviano a Google. Per l'API Update, la cache viene utilizzata per ridurre il numero di richieste fullHashes inviate dai client a Google. Il protocollo di memorizzazione nella cache per ciascuna API è descritto di seguito.
API Lookup
I client dell'API lookup devono memorizzare nella cache ogni elemento ThreatMatch restituito per la durata definita
dal campo cacheDuration. I client devono quindi consultare la cache prima di inviare una richiesta threatMatches successiva al server. Se la durata della cache per un ThreatMatch restituito in precedenza non è ancora scaduta, il client deve presumere che l'elemento sia ancora non sicuro. La memorizzazione nella cache di ThreatMatch elementi potrebbe ridurre il numero di richieste API effettuate dal client.
Esempio: ThreatMatches.find
Fai clic sui link di richiesta e risposta nell'intestazione della tabella per consultare esempi completi.
| Verifica URL threatMatches Request |
URL con corrispondenza threatMatches Response |
Comportamento di memorizzazione nella cache |
|---|---|---|
"threatEntries": [
{"url": "http://www.urltocheck.org/"}
]
|
"matches": [{
"threat": {"url": "http://www.urltocheck.org/"},
"cacheDuration": "300.000s"
}]
|
Corrispondenza. Il client deve attendere 5 minuti prima di inviare una nuova richiesta threatMatches che includa l'URL http://www.urltocheck.org/.
|
API Update
Per ridurre il numero complessivo di richieste fullHashes inviate a Google utilizzando l'API Update, i client devono mantenere una cache locale. L'API stabilisce due tipi di memorizzazione nella cache: positiva e negativa.
Memorizzazione nella cache positiva
Per evitare che i client chiedano ripetutamente informazioni sullo stato di un determinato hash completo non sicuro, ogni ThreatMatch restituito contiene una durata positiva della cache (definita dal campo cacheDuration), che indica per quanto tempo l'hash completo deve essere considerato non sicuro.
Memorizzazione nella cache negativa
Per evitare che i client chiedano ripetutamente informazioni sullo stato di un determinato hash completo sicuro, ogni risposta fullHashes definisce una durata della cache negativa per il prefisso richiesto (definita dal campo negativeCacheDuration). Questa durata indica per quanto tempo tutti gli hash completi con il prefisso richiesto devono essere considerati sicuri per gli elenchi richiesti, ad eccezione di quelli non restituiti dal server. Questa memorizzazione nella cache è particolarmente importante perché impedisce il sovraccarico del traffico che potrebbe essere causato da una collisione del prefisso hash con un URL sicuro che riceve molto traffico.
Consulenza della cache
Quando il cliente vuole controllare lo stato di un URL, prima calcola l'hash completo. Se il prefisso completo dell'hash è presente nel database locale, il client deve consultare la sua cache prima di inviare una richiesta fullHashes al server.
Innanzitutto, i client devono cercare un hit dalla cache positivo. Se esiste una voce di cache positiva non scaduta per l'hash completo di interesse, deve essere considerata non sicura. Se la voce della cache positiva è scaduta, il client deve inviare una richiesta fullHashes per il prefisso locale associato. In base al protocollo, se il server restituisce l'hash completo è considerato non sicuro, altrimenti viene considerato sicuro.
Se non sono presenti voci di cache positive per l'hash completo, il client deve verificare la presenza di un hit da cache negativo. Se esiste una voce di una cache negativa non scaduta per il prefisso locale associato, l'hash completo è considerato sicuro. Se la voce della cache esclusa è scaduta o non esiste, il client deve inviare una richiesta fullHashes per il prefisso locale associato e interpretare la risposta come di consueto.
Aggiornamento della cache
La cache del client deve essere aggiornata ogni volta che viene ricevuta una risposta fullHashes. Devi creare o aggiornare una voce della cache positiva per l'hash completo nel campo cacheDuration. Anche la durata negativa della cache del prefisso hash deve essere creata o aggiornata in base al campo negativeCacheDuration della risposta.
Se una richiesta fullHashes successiva non restituisce un hash completo attualmente memorizzato nella cache, il client non è tenuto a rimuovere la voce della cache positiva. Questo non è motivo di preoccupazione, poiché le durate positive della cache sono in genere brevi (alcuni minuti) per consentire una rapida correzione dei falsi positivi.
Scenario di esempio
Nel seguente esempio, supponiamo che h(url) sia il prefisso hash dell'URL e H(url) l'hash a lunghezza intera dell'URL. In altre parole, h(url) = SHA256(url).substr(4), H(url) = SHA256(url).
Supponiamo ora che un client (con una cache vuota) visiti example.com/ e veda che h(example.com/) sia nel database locale. Il client richiede gli hash a lunghezza intera per il prefisso hash h(example.com/) e riceve l'hash a lunghezza intera H(example.com/) insieme a una durata della cache positiva di 5 minuti e una durata della cache negativa di 1 ora.
La durata positiva della cache di 5 minuti indica al client per quanto tempo l'hash di lunghezza intera(H.example.com/) deve essere considerato non sicuro senza inviare un'altra richiesta fullHashes. Dopo 5 minuti, il client deve inviare un'altra richiesta fullHashes per il prefisso h(example.com/) se il client visita di nuovo example.com/. Il client deve reimpostare la durata della cache negativa del prefisso hash in base alla nuova risposta.
La durata della cache negativa di 1 ora indica al client per quanto tempo tutti gli altri hash a lunghezza intera oltre a H(example.com/) che condividono lo stesso prefisso di h(example.com/) devono essere considerati sicuri. Per la durata di 1 ora, ogni URL tale che h(URL) = h(example.com/) deve essere considerato sicuro e, di conseguenza, non deve generare una richiesta fullHashes (supponendo che H(URL) != H(example.com/)).
Se la risposta fullHashes contiene zero corrispondenze e viene impostata una durata della cache negativa, il client non deve inviare richieste fullHashes per nessuno dei prefissi richiesti per la durata della cache esclusa specificata.
Se la risposta fullHashes contiene una o più corrispondenze, viene comunque impostata una durata negativa della cache per l'intera risposta. In questo caso, la durata della cache di un singolo hash completo indica per quanto tempo quel particolare hash deve essere considerato non sicuro dal client. Una volta trascorsa la durata della cache ThreatMatch, il client deve aggiornare l'hash a lunghezza intera inviando una richiesta fullHashes per il prefisso dell'hash se l'URL richiesto corrisponde all'hash a lunghezza intera esistente nella cache. In tal caso, la durata della cache negativa non è valida. La durata della cache negativa della risposta si applica solo agli hash a lunghezza intera che non erano presenti nella risposta fullHashes. Per gli hash a lunghezza intera che non sono presenti nella risposta, il client deve astenersi dall'inviare eventuali richieste fullHashes fino al termine della durata della cache negativa.
Esempio: fullHashes.find
Fai clic sui link di richiesta e risposta nell'intestazione della tabella per consultare esempi completi.
| Prefissi hash Richiesta FullHashes |
Corrispondenza hash completa Risposta FullHashes |
Comportamento di memorizzazione nella cache |
|---|---|---|
"threatEntries": [
{"hash": "0xaaaaaaaa"}
]
|
"matches": [], "negativeCacheDuration": "3600.000s" |
Nessuna corrispondenza. Il client non deve inviare richieste fullHashes per il prefisso hash 0xaaaaaaaa per almeno un'ora.
Qualsiasi hash con prefisso 0xaaaaaaaa è considerato sicuro per un'ora. |
"threatEntries": [
{"hash": "0xbbbbbbbb"}
]
|
"matches": [
"threat": {"hash": "0xbbbbbbbb0000..."}
"cacheDuration": "600.000s",
],
"negativeCacheDuration": "300.000s"
|
Eventuali corrispondenze. Il client deve considerare l'URL con l'hash completo 0xbbbbbb0000... non sicuro per 10 minuti. Il client deve prendere in considerazione tutti gli altri URL con prefisso hash 0xbbbbbbbb sicuro per 5 minuti. Dopo 5 minuti, la voce di cache negativa dei prefissi hash scadrà. Poiché la voce della cache positiva per 0xbbbbbb0000 non è ancora scaduta, il client deve inviare richieste fullHashes per tutti gli hash tranne questo. |
"threatEntries": [
{"hash": "0xcccccccc"}
]
|
"matches": [
"threat": {"hash": "0xccccccccdddd..."},
"cacheDuration": "600.000s"
],
"negativeCacheDuration": "3600.000s"
|
Eventuali corrispondenze. Il client non deve inviare nessuna richiesta fullHashes per il prefisso hash 0xrcexcccc per almeno 1 ora e presumere che questo prefisso sia sicuro, tranne se l'hash completo dell'URL corrisponde all'hash completo memorizzato nella cache 0xcseccccdddd.... In questo caso, il client deve considerare l'URL come non sicuro per 10 minuti.
Dopo 10 minuti, l'hash di durata estesa scade. Qualsiasi successiva ricerca per l'hash completo dovrebbe attivare una nuova richiesta fullHashes. |