Ce document s'applique à la méthode suivante : API Update (v4) : threatListUpdates.fetch.
Configuration de la base de données
Les clients qui utilisent l'API Update doivent configurer une base de données locale et effectuer un premier téléchargement des listes de navigation sécurisée avec lesquelles ils souhaitent travailler. Pour commencer, vous pouvez compiler et déployer le package Go safebrowsing (ou l'utiliser pour modéliser votre propre implémentation). Pour en savoir plus, consultez la page https://github.com/google/safebrowsing/.
Mises à jour de la base de données
Pour se protéger contre les dernières menaces, les clients sont vivement encouragés à mettre à jour régulièrement leurs listes de navigation sécurisée locales à l'aide de la méthode threatListUpdates.fetch. La requêtethreatListUpdates.fetch spécifie les listes à mettre à jour. Si les clients ont des limites de mémoire ou de bande passante, ils peuvent également utiliser la requête pour définir des contraintes de mise à jour (consultez Contraintes de mise à jour). La réponsethreatListUpdates.fetch renvoie une mise à jour complète ou partielle pour chaque liste, comme expliqué ci-dessous.Mises à jour complètes
Les mises à jour complètes sont renvoyées lorsque le client laisse le champ state vide de la requête ThreatListUpdates.fetch ou lorsque le serveur détermine qu'une mise à jour complète est requise. Pour des mises à jour complètes, seuls les ajouts sont renvoyés. Le client doit effacer la base de données locale avant d'appliquer les mises à jour et d'effectuer le contrôle de validation.
Les mises à jour complètes sont renvoyées lorsque le client envoie la demande initiale de liste. Dans ce cas, le champ state de la requête est laissé vide (car il n'y a aucune valeur à fournir), et le champ newClientState de la réponse renvoie l'état initial de la liste locale. Des mises à jour complètes sont également renvoyées lorsque le client laisse délibérément le champ state vide lors des requêtes suivantes. Cela force une mise à jour complète et renvoie un nouvel état dans le champ newClientState de la réponse.
Il arrive que le serveur de navigation sécurisée renvoie une mise à jour complète lorsque seule une mise à jour partielle est demandée par le client. Cela peut se produire lorsque le client télécharge initialement une petite version de la liste, puis effectue une mise à jour vers une version plus longue. Le serveur renvoie simplement une mise à jour complète de la liste complète. Cela peut également se produire si le client n'a pas téléchargé de données depuis longtemps et demande une mise à jour partielle. Là encore, le serveur renvoie simplement une mise à jour complète avec la liste complète.
Mises à jour partielles
Les mises à jour partielles sont renvoyées lorsque le client fournit une valeur pour le champ state dans la requête ThratListUpdates.fetch (l'exception, comme indiqué ci-dessus, se produit lorsque le serveur détermine qu'une mise à jour complète est nécessaire). Pour les mises à jour partielles, les ajouts et les suppressions sont tous deux renvoyés. Le client met à jour les listes dans la base de données locale (en appliquant les suppressions avant les ajouts), puis effectue le contrôle de validation.
Ajouts
Les ajouts sont des préfixes de hachage SHA256 qui doivent être ajoutés à la base de données locale. La grande majorité des préfixes de hachage font 4 octets, mais certains peuvent avoir une longueur comprise entre 4 et 32 octets. Par conséquent, plusieurs ensembles d'ajouts peuvent être renvoyés, par exemple l'un contenant les préfixes de quatre octets et l'autre contenant les préfixes de cinq octets.
Si le client prend en charge la compression, la réponse peut être compressée à l'aide de la compression Rice. Toutefois, seuls les préfixes de hachage de 4 octets sont compressés. Les préfixes de hachage plus longs sont toujours envoyés au format brut non compressé (voir la section Compression).
Déménagements
Les suppressions sont des index basés sur zéro dans la base de données cliente triée de façon lexicographique, pointant vers les entrées à supprimer de la base de données locale. Un seul ensemble de suppressions sera renvoyé.
Si le client accepte la compression, les valeurs "rices de riz" et "indices de riz" sont renvoyées. Si la compression n'est pas prise en charge, les "hachages bruts" et les "indices bruts" sont renvoyés (consultez la section Compression).
Contrôles de validation
Lorsque la réponse ThrreatListUpdates.fetch est renvoyée, avec une mise à jour complète ou partielle, le client doit effectuer un contrôle de validation.
Le client met d'abord à jour les listes dans la base de données locale (en appliquant les suppressions avant les ajouts). Le client calcule ensuite le hachage SHA256 de la liste locale (triée de manière lexicographique) et le compare à la somme de contrôle renvoyée dans la réponse. Si les deux valeurs sont égales, la liste de navigation sécurisée est considérée comme "correcte".
Si les deux valeurs ne sont pas égales, la liste de navigation sécurisée est considérée comme "corrompue". Le client doit effacer la liste de la base de données et renvoyer une deuxième mise à jour avec le champ state défini sur la chaîne vide. Cela force une mise à jour complète et renvoie une toute nouvelle liste et un nouvel état.