Questo documento si applica al seguente metodo: API Update (v4): threatListUpdates.fetch.
Configurazione del database
I client che utilizzano l'API Update devono configurare un database locale e eseguire un download iniziale degli elenchi di Navigazione sicura con cui vogliono lavorare. Per iniziare, puoi creare ed eseguire il deployment del pacchetto safebrowsing Go (oppure utilizzare il pacchetto per modellare la tua implementazione). Per ulteriori informazioni, visita la pagina https://github.com/google/safebrowsing/.
Aggiornamenti del database
Per garantire la protezione dalle minacce più recenti, si consiglia ai client di aggiornare regolarmente i propri elenchi locali di Navigazione sicura utilizzando il metodo threatListUpdates.fetch. La richiestathreatListUpdates.fetch specifica gli elenchi da aggiornare. Se i client hanno limitazioni di memoria o larghezza di banda, possono anche utilizzare la richiesta per impostare vincoli di aggiornamento (consulta la sezione Vincoli di aggiornamento). La rispostathreatListUpdates.fetch restituisce un aggiornamento completo o parziale per ogni elenco, come spiegato di seguito.Aggiornamenti completi
Gli aggiornamenti completi vengono restituiti quando il client lascia vuoto il campo state nella richiestathreatListUpdates.fetch o quando il server stabilisce che è necessario un aggiornamento completo. Per gli aggiornamenti completi, vengono restituite solo aggiunte. Il client deve cancellare il database locale prima di applicare gli aggiornamenti ed eseguire il controllo di convalida.
Gli aggiornamenti completi vengono restituiti quando il client invia la richiesta iniziale di un elenco. In questo caso, il campo state nella richiesta viene lasciato vuoto perché non c'è alcun valore da fornire, mentre il campo newClientState nella risposta restituisce lo stato iniziale dell'elenco locale. Gli aggiornamenti completi vengono restituiti anche quando il client lascia volutamente vuoto il campo state per le richieste successive. Questa operazione forzerà un aggiornamento completo e restituirà un nuovo stato nel campo newClientState della risposta.
A volte, il server Navigazione sicura restituisce un aggiornamento completo quando il client richiede solo un aggiornamento parziale. Questo può accadere quando il client inizialmente scarica una versione ridotta dell'elenco e quindi esegue l'aggiornamento a una versione più grande dell'elenco. Il server restituisce semplicemente un aggiornamento completo con l'intero elenco. Questa situazione può verificarsi anche se il client non ha scaricato dati da molto tempo e richiede un aggiornamento parziale. Anche in questo caso, il server restituirà semplicemente un aggiornamento completo con l'intero elenco.
Aggiornamenti parziali
Gli aggiornamenti parziali vengono restituiti quando il client fornisce un valore per il campo state nella richiestathreatListUpdates.fetch (l'eccezione, come indicato sopra, si verifica quando il server determina che è necessario un aggiornamento completo). Per gli aggiornamenti parziali, vengono restituite sia le addizioni sia le rimozioni. Il client aggiorna gli elenchi nel database locale (applicando le rimozioni prima delle aggiunte), quindi esegue il controllo di convalida.
Aggiunte
Le aggiunte sono prefissi hash SHA256 che devono essere aggiunti al database locale. La stragrande maggioranza dei prefissi hash è lunga 4 byte, ma alcuni possono avere una lunghezza compresa tra 4 e 32 byte. Pertanto, potrebbero essere restituite più serie di aggiunte; ad esempio, una contenente i prefissi a 4 byte e l'altra a 5 byte.
Se il client supporta la compressione, la risposta può essere compressa utilizzando la compressione Rice. Tuttavia, vengono compressi solo i prefissi hash da 4 byte. I prefissi hash più lunghi vengono sempre inviati in formato non compresso e non elaborato (vedi Compressione).
Rimozioni
Le rimozioni sono indici in base zero nel database client ordinato lessicograficamente che puntano a voci che devono essere rimosse dal database locale. Verrà restituito un solo insieme di rimozioni.
Se il cliente supporta la compressione, vengono restituiti "hash di riso" e "indici di riso". Se la compressione non è supportata, vengono restituiti "hash non elaborati" e "indici non elaborati" (vedi Compressione).
Controlli di convalida
Quando viene restituita la rispostathreatListUpdates.fetch, con un aggiornamento completo o parziale, il client deve eseguire un controllo di convalida.
Il client aggiorna prima gli elenchi nel database locale (applicando le rimozioni prima delle aggiunte). Il client calcola quindi l'hash SHA256 dell'elenco locale (ordinato lessicograficamente) e lo confronta con il checksum restituito nella risposta. Se i due valori sono uguali, l'elenco di Navigazione sicura viene considerato "corretto".
Se i due valori non sono uguali, l'elenco di Navigazione sicura viene considerato "corrotto". Il client deve cancellare l'elenco dal database ed emettere un secondo aggiornamento con il campo state impostato sulla stringa vuota; questa operazione forzerà un aggiornamento completo e restituirà un nuovo elenco e uno stato.