Panoramica
L'API Update consente alle applicazioni client di scaricare versioni con hash degli elenchi di Navigazione sicura per l'archiviazione in un database locale. Gli URL possono quindi essere controllati localmente. Solo se viene trovata una corrispondenza nel database locale, il client deve inviare una richiesta ai server di Navigazione sicura per verificare se l'URL è incluso negli elenchi di Navigazione sicura.
Prima di utilizzare l'API Update, devi configurare un database locale. Navigazione sicura offre un pacchetto Go che puoi utilizzare per muoverti. Per maggiori dettagli, consulta la sezione Configurazione del database in Database locali.
Aggiornamento del database locale
Per rimanere aggiornati, i client devono aggiornare periodicamente gli elenchi di Navigazione sicura nel proprio database locale. Per risparmiare larghezza di banda, i client scaricano i prefissi hash degli URL anziché gli URL non elaborati. Ad esempio, se "www.badurl.com/" si trova in un elenco di Navigazione sicura, i client scaricano il prefisso hash SHA256 dell'URL anziché l'URL stesso. Nella maggior parte dei casi i prefissi hash sono lunghi 4 byte, il che significa che il costo medio della larghezza di banda per il download di una singola voce di elenco è di 4 byte prima della compressione.
Per aggiornare gli elenchi di Navigazione sicura nel database locale, invia una richiesta HTTP POST al metodo threatListUpdates.fetch:
- La richiesta HTTP
POSTinclude i nomi degli elenchi da aggiornare insieme a vari vincoli del client per tenere conto delle limitazioni di memoria e larghezza di banda. - La risposta HTTP
POSTrestituisce un aggiornamento completo o parziale. La risposta potrebbe restituire anche una durata di attesa minima.
Esempio: ThreatListUpdates.fetch
Richiesta POST HTTP
Nel seguente esempio, vengono richiesti gli aggiornamenti per un singolo elenco di Navigazione sicura.
Intestazione della richiesta
L'intestazione della richiesta include l'URL della richiesta e il tipo di contenuti. Ricordati di sostituire la chiave API con API_KEY nell'URL.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
Corpo della richiesta
Il corpo della richiesta include le informazioni sul client (ID e versione) e le informazioni di aggiornamento (nome dell'elenco, stato dell'elenco e vincoli del client). Per ulteriori dettagli, consulta il corpo della richiestathreatListUpdates.fetch e le spiegazioni che seguono l'esempio di codice.
{
"client": {
"clientId": "yourcompanyname",
"clientVersion": "1.5.2"
},
"listUpdateRequests": [{
"threatType": "MALWARE",
"platformType": "WINDOWS",
"threatEntryType": "URL",
"state": "Gg4IBBADIgYQgBAiAQEoAQ==",
"constraints": {
"maxUpdateEntries": 2048,
"maxDatabaseEntries": 4096,
"region": "US",
"supportedCompressions": ["RAW"]
}
}]
}
Dati cliente
I campi clientID e clientVersion devono identificare in modo univoco un'implementazione client, non un singolo utente. (Le informazioni sul client vengono utilizzate nel logging lato server. Puoi scegliere qualsiasi nome per l'ID client, ma ti suggeriamo di scegliere un nome che rappresenti l'identità reale del client, ad esempio il nome dell'azienda, presentato come un'unica parola, in lettere minuscole.
Elenchi di Navigazione sicura
I campi threatType, platformType e threatEntryType vengono combinati per identificare (nome) gli elenchi di Navigazione sicura. Nell'esempio è identificato un elenco:
MALWARE/WINDOWS/URL. Prima di inviare una richiesta, assicurati che le combinazioni di tipi specificate siano valide (consulta la sezione Elenchi di Navigazione sicura).
Stato client
Il campo state contiene lo stato client corrente dell'elenco di Navigazione sicura.
(Gli stati del client vengono restituiti nel campo newClientState della rispostathreatListUpdates.fetch.)
Per gli aggiornamenti iniziali, lascia vuoto il campo state.
Vincoli di dimensioni
Il campo maxUpdateEntries specifica il numero totale di aggiornamenti che il client può gestire (nell'esempio, 2048). Il campo maxDatabaseEntries specifica il numero totale di voci che il database locale può gestire (nell'esempio, 4096). I client dovrebbero impostare limiti di dimensioni per proteggere i limiti di memoria e larghezza di banda e per evitare la crescita degli elenchi. Per ulteriori informazioni,
(consulta la pagina relativa all'aggiornamento dei vincoli).
Compressione supportate
Nel campo supportedCompressions sono elencati i tipi di compressione supportati dal client. Nell'esempio, il client supporta solo dati non elaborati e non compressi. Navigazione sicura, tuttavia, supporta tipi di compressione aggiuntivi (vedi Compressione).
Risposta POST HTTP
In questo esempio, la risposta restituisce un aggiornamento parziale per l'elenco di Navigazione sicura utilizzando il tipo di compressione richiesto.
Intestazione della risposta
L'intestazione della risposta include il codice di stato HTTP e il tipo di contenuto. I client che ricevono un codice di stato diverso da HTTP/200 devono attivare la modalità di backoff (consulta Frequenza delle richieste).
HTTP/1.1 200 OK Content-Type: application/json
Corpo della risposta
Il corpo della risposta include le informazioni di aggiornamento (il nome dell'elenco, il tipo di risposta, le aggiunte e le rimozioni da applicare al database locale, il nuovo stato del client e un checksum). Nell'esempio, la risposta include anche un tempo di attesa minimo. Per ulteriori dettagli, consulta il corpo della rispostathreatListUpdates.fetch e le spiegazioni che seguono l'esempio di codice.
{
"listUpdateResponses": [{
"threatType": "MALWARE",
"threatEntryType": "URL",
"platformType": "WINDOWS",
"responseType" : "PARTIAL_UPDATE",
"additions": [{
"compressionType": "RAW",
"rawHashes": {
"prefixSize": 4,
"rawHashes": "rnGLoQ=="
}
}],
"removals": [{
"compressionType": "RAW",
"rawIndices": {
"indices": [0, 2, 4]
}
}],
"newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
"checksum": {
"sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
}
}],
"minimumWaitDuration": "593.440s"
}
Aggiornamenti del database
Il campo responseType indicherà un aggiornamento parziale o completo. Nell'esempio viene restituito un aggiornamento parziale, quindi la risposta include aggiunte e rimozioni. Potrebbero esserci più insiemi di aggiunte, ma un solo insieme di rimozioni (vedi Aggiornamenti dei database).
Stato nuovo client
Il campo newClientState contiene il nuovo stato client per l'elenco di Navigazione sicura appena aggiornato.
I client devono salvare il nuovo stato client per le successive richieste di aggiornamento (il campo state nella
richiestathreatListUpdates.fetch o il campo clientStates nella
richiesta fullHashes.find).
Checksum
Il checksum consente ai client di verificare che il database locale non abbia subito alcun danneggiamento. Se il checksum non corrisponde, il client deve cancellare il database ed emettere nuovamente un aggiornamento con un campo state vuoto. Tuttavia, in questa situazione i client devono comunque seguire gli intervalli di tempo per gli aggiornamenti (vedi Frequenza delle richieste).
Durate minime di attesa
Il campo minimumWaitDuration indica che il client deve attendere 593,44 secondi (9,89 minuti) prima di inviare un'altra richiesta di aggiornamento. Tieni presente che un periodo di attesa può essere incluso o meno nella risposta (vedi Frequenza delle richieste).
Verifica degli URL
Per verificare se un URL è in un elenco di Navigazione sicura, il client deve prima calcolare l'hash e il prefisso hash dell'URL (consulta la sezione URL e hashing). Il client quindi esegue una query al database locale per determinare se esiste una corrispondenza. Se il prefisso hash non è presente nel database locale, l'URL è considerato sicuro (non è presente negli elenchi di Navigazione sicura).
Se il prefisso hash è presente nel database locale (un conflitto con il prefisso hash), il client deve inviare il prefisso hash ai server di Navigazione sicura per la verifica. I server restituiranno tutti gli hash SHA 256 completi che contengono il prefisso hash specificato. Se uno di questi hash completi corrisponde all'hash completo dell'URL in questione, l'URL è considerato non sicuro. Se nessuno degli hash completi corrisponde all'hash completo dell'URL in questione, l'URL viene considerato sicuro.
Google non viene mai a conoscenza degli URL che stai esaminando. Google apprende i prefissi hash degli URL, ma questi non forniscono molte informazioni sugli URL effettivi.
Per verificare se un URL è presente in un elenco di Navigazione sicura, invia una richiesta HTTP POST al metodo
fullHashes.find:
- La richiesta HTTP
POSTpuò includere fino a 500 voci di minaccia. - La richiesta HTTP
POSTinclude i prefissi hash degli URL da controllare. Consigliamo ai client di raggruppare più voci di minacce in un'unica richiesta per ridurre l'utilizzo della larghezza di banda. - La risposta HTTP
POSTrestituisce gli hash completi corrispondenti insieme alle durate positive e negative della cache. La risposta potrebbe anche restituire una durata di attesa minima.
Esempio: fullHashes.find
Richiesta POST HTTP
Nell'esempio seguente, vengono inviati i nomi di due elenchi di Navigazione sicura e di tre prefissi hash per il confronto e la verifica.
Intestazione della richiesta
L'intestazione della richiesta include l'URL della richiesta e il tipo di contenuti. Ricordati di sostituire la tua chiave API con API_KEY nell'URL.
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Corpo della richiesta
Il corpo della richiesta include le informazioni sul client (ID e versione), gli stati del client e le informazioni sulla minaccia (i nomi degli elenchi e i prefissi hash). Per le richieste JSON, i prefissi hash devono essere inviati in formato con codifica Base64. Per ulteriori dettagli, consulta il corpo della richiesta fullHashes.find e le spiegazioni che seguono l'esempio di codice.
{
"client": {
"clientId": "yourcompanyname",
"clientVersion": "1.5.2"
},
"clientStates": [
"ChAIARABGAEiAzAwMSiAEDABEAE=",
"ChAIAhABGAEiAzAwMSiAEDABEOgH"
],
"threatInfo": {
"threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
"platformTypes": ["WINDOWS"],
"threatEntryTypes": ["URL"],
"threatEntries": [
{"hash": "WwuJdQ=="},
{"hash": "771MOg=="},
{"hash": "5eOrwQ=="}
]
}
}
Dati cliente
I campi clientID e clientVersion devono identificare in modo univoco un'implementazione client, non un singolo utente. (Le informazioni sul client vengono utilizzate nel logging lato server. Puoi scegliere un nome qualsiasi per l'ID client, ma ti suggeriamo di scegliere un nome che rappresenti l'identità reale del client, ad esempio il nome dell'azienda, presentato in un'unica parola e con lettere minuscole.
Tutti gli stati del client
Il campo clientStates contiene gli stati del client per tutti gli elenchi di Navigazione sicura nel database locale del client. (Gli stati del client vengono restituiti nel campo newClientState della rispostathreatListUpdates.fetch.)
Elenchi di Navigazione sicura
I campi threatTypes, platformTypes e threatEntryTypes
si combinano per identificare (assegnare un nome) agli elenchi di
Navigazione sicura. Nell'esempio sono identificati due elenchi: MALWARE/WINDOWS/URL e
SOCIAL_ENGINEERING/WINDOWS/URL. Prima di inviare una richiesta, assicurati che le combinazioni dei tipi specificate siano valide (consulta la sezione Elenchi di Navigazione sicura).
Prefissi hash di minaccia
L'array ThreatEntries contiene i prefissi hash degli URL che vuoi controllare.
Il campo hash deve contenere l'esatto prefisso dell'hash presente nel database locale. Ad esempio, se il prefisso hash locale è lungo 4 byte, la voce della minaccia deve avere una lunghezza di 4 byte. Se il prefisso hash locale è stato allungato a 7 byte, la voce di minaccia deve avere una lunghezza di 7 byte.
Nell'esempio, la richiesta include tre prefissi hash. Tutti e tre i prefissi vengono confrontati con ciascuno degli elenchi di Navigazione sicura per determinare se è presente un hash completo corrispondente.
Nota: l'API Update e il metodo fullHashes.find dovrebbero utilizzare sempre il campo hash, mai il campo URL (vedi ThreatEntry).
Risposta POST HTTP
Nell'esempio seguente, la risposta restituisce i dati corrispondenti, organizzati dall'elenco di Navigazione sicura, insieme alla cache e alle durate di attesa.
Intestazione della risposta
L'intestazione della risposta include il codice di stato HTTP e il tipo di contenuto. I client che ricevono un codice di stato diverso da HTTP/200 devono eseguire il backoff (vedi Frequenza delle richieste).
HTTP/1.1 200 OK Content-Type: application/json
Corpo della risposta
Il corpo della risposta include le informazioni sulla corrispondenza (i nomi degli elenchi e gli hash completi, i metadati, se disponibili e le durate della cache). Nell'esempio, il corpo della risposta include anche una durata minima di attesa. Per ulteriori dettagli, consulta il corpo della risposta fullHashes.find e le spiegazioni che seguono l'esempio di codice.
{
"matches": [{
"threatType": "MALWARE",
"platformType": "WINDOWS",
"threatEntryType": "URL",
"threat": {
"hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
},
"threatEntryMetadata": {
"entries": [{
"key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==", // base64-encoded "malware_threat_type"
"value": "TEFORElORw==" // base64-encoded "LANDING"
}]
},
"cacheDuration": "300.000s"
}, {
"threatType": "SOCIAL_ENGINEERING",
"platformType": "WINDOWS",
"threatEntryType": "URL",
"threat": {
"hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
},
"threatEntryMetadata": {
"entries": []
},
"cacheDuration": "300.000s"
}],
"minimumWaitDuration": "300.000s",
"negativeCacheDuration": "300.000s"
}
Corrisponde a
L'oggetto Corrispondenze restituisce un hash completo corrispondente per due dei prefissi hash. Gli URL corrispondenti a questi hash sono considerati non sicuri. Non è stata trovata alcuna corrispondenza per il terzo prefisso hash, quindi non viene restituito nulla; l'URL corrispondente a questo prefisso hash è considerato sicuro.
Tieni presente che questo esempio associa un hash completo a un prefisso hash; tuttavia, potrebbero esserci più hash completi mappati allo stesso prefisso di hash.
Metadati
Il campo threatEntryMetadata è facoltativo e fornisce ulteriori informazioni sulla corrispondenza delle minacce. Al momento, i metadati sono disponibili per l'elenco di Navigazione sicura MALWARE/WINDOWS/URL (consulta la sezione Metadati).
Durate della cache
I campi cacheDuration e negativeCacheDuration indicano per quanto tempo gli hash devono essere considerati non sicuri o sicuri (consulta Memorizzazione nella cache).
Durate minime di attesa
Il campo minimumWaitDuration indica che il client deve attendere 300 secondi (5 minuti) prima di inviare un'altra richiesta fullHashes. Tieni presente che un periodo di attesa può essere incluso o meno nella risposta (consulta Frequenza delle richieste).