Présentation
L'API Update permet à vos applications clientes de télécharger des versions hachées des listes Safe Browsing en vue de les stocker dans une base de données locale. Les URL peuvent ensuite être vérifiées localement. Le client ne doit envoyer une requête aux serveurs de navigation sécurisée pour vérifier si l'URL figure sur les listes de navigation sécurisée que si une correspondance est détectée dans la base de données locale.
Avant d'utiliser l'API Update, vous devez configurer une base de données locale. La navigation sécurisée offre que vous pouvez utiliser pour aller de l’avant. Pour plus d'informations, consultez la section "Configuration de la base de données" sous Bases de données locales.
Mettre à jour la base de données locale
Pour rester à jour, les clients sont tenus de mettre régulièrement à jour les listes de navigation sécurisée dans leurs base de données locale. Pour économiser de la bande passante, les clients téléchargent les préfixes de hachage des URL au lieu des URL brutes. Par exemple, si "www.badurl.com/" figure sur une liste de navigation sécurisée, les clients téléchargent le Préfixe de hachage SHA256 de cette URL plutôt que de l'URL elle-même. Dans la majorité des cas, les préfixes de hachage peuvent comporter 4 octets, ce qui signifie que le coût moyen en termes de bande passante pour le téléchargement d'une seule entrée de liste équivaut à 4 octets avant compression.
Pour mettre à jour les listes de navigation sécurisée dans la base de données locale, envoyez une requête HTTP POST
au
threatListUpdates.fetch
méthode:
- La requête HTTP
POST
inclut les noms des listes à mettre à jour, ainsi que diverses informations pour tenir compte des limitations de la mémoire et de la bande passante. - La réponse HTTP
POST
renvoie une mise à jour complète ou partielle. La réponse peut également renvoyer une durée d'attente minimale.
Exemple: menaceListUpdates.fetch
Requête POST HTTP
Dans l'exemple suivant, les mises à jour d'une seule liste de navigation sécurisée sont demandées.
En-tête de requête
L'en-tête de requête inclut l'URL de la requête et le type de contenu. N'oubliez pas de remplacer votre API
pour API_KEY
dans l'URL.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
Corps de la requête
Le corps de la requête inclut les informations sur le client (ID et version) et les informations de mise à jour (nom de la liste, état de la liste et contraintes du client). Pour en savoir plus, consultez le corps de la requête threatListUpdates.fetch et les explications qui suivent l'exemple de code.
{ "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"] } }] }
Informations sur le client
Les champs clientID
et clientVersion
doivent identifier de manière unique une implémentation client, et non une
un utilisateur individuel. (Les informations client sont utilisées dans la journalisation côté serveur. Vous pouvez choisir n'importe quel nom pour l'ID client, mais nous vous recommandons de choisir un nom qui représente l'identité réelle du client, comme le nom de votre entreprise, présenté en un seul mot, en minuscules.)
Listes de la navigation sécurisée
Les champs threatType
, platformType
et threatEntryType
sont combinés pour identifier (nommer) les listes de navigation sécurisée. Dans l'exemple, une liste est identifiée:
LOGICIEL MALVEILLANT/FENÊTRES/URL. Avant d'envoyer une requête, assurez-vous que les combinaisons de types que vous spécifiez sont valides (voir Listes de navigation sécurisée).
État du client
Le champ state
contient l'état actuel du client de la liste de navigation sécurisée.
(Les états client sont renvoyés dans le champ newClientState
de la réponse threatListUpdates.fetch.)
Pour les mises à jour initiales, laissez le champ state
vide.
Contraintes de taille
Le champ maxUpdateEntries
spécifie le nombre total de mises à jour que le client peut gérer (dans l'exemple : 2 048). Le champ maxDatabaseEntries
indique le nombre total d'entrées que l'adresse
la base de données peut gérer (dans cet exemple, 4096). Les clients doivent définir des contraintes de taille
pour limiter les limitations de mémoire et de bande passante, et pour éviter les attaques de type liste
de croissance. Pour plus d'informations,
(voir Mettre à jour les contraintes).
Compressions acceptées
Le champ supportedCompressions
répertorie les types de compression acceptés par le client. Dans
exemple, le client ne prend en charge que des données brutes non compressées. La navigation sécurisée offre quant à elle
(voir la section Compression).
Réponse HTTP POST
Dans cet exemple, la réponse renvoie une mise à jour partielle de la liste de navigation sécurisée à l'aide de la méthode le type de compression demandé.
En-tête de réponse
L'en-tête de réponse inclut le code d'état HTTP. et le type de contenu. Les clients qui reçoivent un code d'état autre que HTTP/200 doivent passer en mode d'attente (voir la section Fréquence des requêtes).
HTTP/1.1 200 OK Content-Type: application/json
Corps de la réponse
Le corps de la réponse inclut les informations de mise à jour (nom de la liste, type de réponse, des ajouts et suppressions à la base de données locale, le nouveau client et une somme de contrôle). Dans l'exemple, la réponse inclut également une durée d'attente minimale. Pour plus consultez les Corps de la réponsethreatListUpdates.fetch et les explications qui suivent l'exemple de code.
{ "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" }
Mises à jour de la base de données
Le champ responseType
indique une mise à jour partielle ou complète. Dans l'exemple, une mise à jour partielle est renvoyée. La réponse inclut donc les ajouts et les suppressions. Il peut y avoir plusieurs ensembles d'ajouts, mais un seul ensemble de suppressions (voir Mises à jour de la base de données).
Nouvel état du client
Le champ newClientState
contient le nouvel état du client pour la liste de navigation sécurisée récemment mise à jour.
Les clients doivent enregistrer le nouvel état du client pour les requêtes de mise à jour ultérieures (champ state
dans
Requête ThreatListUpdates.fetch
ou le champ clientStates
dans
fullHashes.find).
Sommes de contrôle
Les sommes de contrôle permettent aux clients de vérifier que la base de données locale n'a pas été corrompue. Si le
ne correspond pas, le client doit effacer la base de données et renvoyer une mise à jour avec
state
. Toutefois, les clients dans cette situation doivent toujours suivre les intervalles de temps pour les mises à jour
(voir Fréquence des requêtes).
Durées d'attente minimales
Le champ minimumWaitDuration
indique que le client doit attendre 593,44 secondes (9,89 minutes).
avant d'envoyer une autre demande de mise à jour. Notez qu'une période d'attente peut ou non être incluse dans le
(voir Fréquence des requêtes).
Vérification des URL
Pour vérifier si une URL figure sur une liste de navigation sécurisée, le client doit d'abord calculer le hachage et le préfixe de hachage de l'URL (voir URL et hachage). Le client interroge ensuite la base de données locale pour déterminer s'il existe une correspondance. Si le préfixe de hachage est absente de la base de données locale, l'URL est considérée comme fiable Parcourir des listes).
Si le préfixe de hachage est présent dans la base de données locale (conflit de préfixe de hachage), le client doit l'envoyer aux serveurs de la navigation sécurisée pour vérification. Les serveurs renverront tous les hachages SHA-256 en longueur complète qui contiennent le préfixe de hachage donné. Si l'un de ces hachages de la longueur correspond au hachage complet de l'URL en question, alors l'URL est considérée comme non sécurisée. Si aucun des hachages de la longueur totale ne correspond à celui de l'URL en question, celle-ci est considérée comme sûre.
À aucun moment, Google n'a connaissance des URL que vous examinez. Google apprend le hachage préfixes des URL, mais les préfixes de hachage ne fournissent pas beaucoup d'informations sur les URL elles-mêmes.
Pour vérifier si une URL figure sur une liste de navigation sécurisée, envoyez une requête HTTP POST
à la méthode fullHashes.find :
- La requête HTTP
POST
peut inclure jusqu'à 500 entrées de menace. - La requête HTTP
POST
inclut les préfixes de hachage des URL à vérifier. Les clients sont invités à regrouper plusieurs entrées de menaces dans une seule requête afin de réduire l'utilisation de la bande passante. - La réponse HTTP
POST
renvoie les hachages de la longueur complète correspondants, ainsi que les valeurs positives et des durées de cache négatives. La réponse peut également renvoyer une durée d'attente minimale.
Exemple: fullHashes.find
Requête HTTP POST
Dans l'exemple suivant, les noms de deux listes de navigation sécurisée et de trois préfixes de hachage sont envoyés à des fins de comparaison et de vérification.
En-tête de requête
L'en-tête de requête inclut l'URL de la requête et le type de contenu. N'oubliez pas de remplacer API_KEY
par votre clé API dans l'URL.
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Corps de la requête
Le corps de la requête inclut les informations sur le client (ID et version), les états du client et les informations sur la menace (noms de liste et préfixes de hachage). Pour les requêtes JSON, les préfixes de hachage doivent sont envoyées sous forme encodée en base64. Pour en savoir plus, consultez le corps de la requête fullHashes.find et les explications qui suivent l'exemple de code.
{ "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=="} ] } }
Informations sur le client
Les champs clientID
et clientVersion
doivent identifier de manière unique une implémentation client, et non un utilisateur individuel. (Les informations client sont utilisées dans la journalisation côté serveur. Vous pouvez choisir n'importe quel nom pour l'ID client, mais nous vous recommandons de choisir un nom qui représente l'identité réelle du client, comme le nom de votre entreprise, présenté en un seul mot, en minuscules.)
Tous les états du client
Le champ clientStates
contient les états client pour toutes les listes de navigation sécurisée dans la base de données locale du client. (Les états client sont renvoyés dans le champ newClientState
de la réponse threatListUpdates.fetch.)
Listes de la navigation sécurisée
Les champs threatTypes
, platformTypes
et threatEntryTypes
se combinent pour identifier (nommer) les listes de navigation sécurisée. Dans cet exemple, deux listes sont identifiées: LOGICIEL MALVEILLANT/FENÊTRES/URL et
SOCIAL_ENGINEERING/WINDOWS/URL. Avant d'envoyer une requête, assurez-vous que les combinaisons de types que vous spécifiez sont valides (voir Listes de navigation sécurisée).
Préfixes de hachage des menaces
Le tableau threatEntries contient les préfixes de hachage des URL que vous souhaitez vérifier.
Le champ hash
doit contenir le préfixe de hachage exact qui est présent dans la base de données locale. Pour
Par exemple, si la longueur du préfixe de hachage local est de 4 octets, l'entrée de menace doit faire 4 octets. Si le
le préfixe de hachage local a été rallongé à 7 octets, alors que l'entrée de la menace doit faire 7 octets.
Dans l'exemple, la requête inclut trois préfixes de hachage. Les trois préfixes sont comparés à chacune des listes de navigation sécurisée pour déterminer s'il existe un hachage complet correspondant.
Remarque : L'API Update et la méthode fullHashes.find doivent toujours utiliser le champ hash
, et jamais le champ URL
(voir ThreatEntry).
Réponse HTTP POST
Dans l'exemple suivant, la réponse renvoie les données correspondantes, organisées par liste de navigation sécurisée. ainsi que les durées de cache et d'attente.
En-tête de réponse
L'en-tête de réponse inclut le code d'état HTTP et le type de contenu. Les clients qui reçoivent un code d'état autre que HTTP/200 doivent s'arrêter (voir la section Fréquence des requêtes).
HTTP/1.1 200 OK Content-Type: application/json
Corps de la réponse
Le corps de la réponse inclut des informations sur les correspondances (les noms de la liste, les hachages complets, les métadonnées, le cas échéant, et les durées de mise en cache). Dans l'exemple, le corps de la réponse inclut également la durée d'attente minimale. Pour en savoir plus, consultez le corps de la réponse fullHashes.find et les explications qui suivent l'exemple de code.
{ "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" }
Correspond à
L'objet Correspondances renvoie un hachage complet correspondant pour deux des préfixes de hachage. Les URL correspondant à ces hachages sont considérées comme non sécurisées. Aucune correspondance trouvée pour le troisième préfixe de hachage, donc rien n'est renvoyé. l'URL correspondant à ce préfixe de hachage est considérée comme sûre.
Notez que cet exemple met en correspondance un hachage complet avec un préfixe de hachage. il pourrait toutefois y avoir plusieurs hachages complets qui correspondent au même préfixe de hachage.
Métadonnées
Le champ threatEntryMetadata
est facultatif et fournit des informations supplémentaires sur la correspondance de menace. Actuellement, les métadonnées sont disponibles pour la liste de navigation sécurisée LOGICIELS MALVEILLANTS/FENÊTRES/URL
(voir Métadonnées).
Durées de cache
Les champs cacheDuration
et negativeCacheDuration
indiquent la durée pendant laquelle les hachages doivent être considérés comme sécurisés ou non sécurisés (voir Mise en cache).
Durées d'attente minimales
Le champ minimumWaitDuration
indique que le client doit attendre 300 secondes (5 minutes) avant
en envoyant une autre requête fullHashes. Notez qu'un délai d'attente peut ou non être inclus dans la réponse (voir Fréquence des requêtes).