Cette page a été traduite par l'API Cloud Translation.

API Safe Browsing Update (v4)

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).