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 une version hachée des listes de navigation sécurisée en vue de les stocker dans une base de données locale. Les URL peuvent ensuite être vérifiées localement. Si une correspondance est détectée dans la base de données locale, le client doit envoyer une requête aux serveurs de navigation sécurisée pour vérifier si l'URL figure dans les listes de navigation sécurisée.

Avant d'utiliser l'API Update, vous devez configurer une base de données locale. La navigation sécurisée fournit un package Go que vous pouvez utiliser pour démarrer. Pour en savoir plus, 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 leur base de données locale. Pour économiser la bande passante, les clients téléchargent les préfixes de hachage des URL plutôt que les 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 l'URL elle-même. Dans la plupart des cas, les préfixes de hachage ont une longueur de 4 octets, ce qui signifie que le coût moyen de la bande passante du téléchargement d'une seule entrée de liste est de 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 à la méthode threatListUpdates.fetch:

La requête HTTP POST inclut les noms des listes à mettre à jour ainsi que diverses contraintes client afin de prendre en compte les limites de mémoire et de 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: ThreatListUpdates.fetch

Requête HTTP POST

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 clé API par 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 comprend 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 ThratListUpdates.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 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. Toutefois, nous vous recommandons de choisir un nom qui représente la véritable identité du client, tel que le nom de votre entreprise, présenté en un seul mot, tout en minuscules.)

Listes de navigation sécurisée

Les champs threatType, platformType et threatEntryType sont combinés pour identifier (nom) les listes de navigation sécurisée. Dans l'exemple, une liste est identifiée : MALWARE/WINDOWS/URL. Avant d'envoyer une requête, assurez-vous que les combinaisons de types que vous spécifiez sont valides (consultez la section Listes de navigation sécurisée).

État du client

Le champ state contient l'état actuel du client dans la liste de navigation sécurisée. (Les états du 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 indique le nombre total de mises à jour que le client peut gérer (2 048 dans cet exemple). Le champ maxDatabaseEntries indique le nombre total d'entrées que la base de données locale peut gérer (4 096 dans cet exemple). Les clients doivent définir des contraintes de taille pour protéger les limites de mémoire et de bande passante, ainsi que pour éviter la croissance des listes. Pour en savoir plus, consultez la section Mettre à jour les contraintes.

Compressions acceptées

Le champ supportedCompressions liste les types de compression acceptés par le client. Dans cet exemple, le client n'accepte que les données brutes non compressées. Toutefois, la navigation sécurisée accepte d'autres types de compression (voir 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 du 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 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, ajouts et suppressions à appliquer à la base de données locale, nouvel état du client et somme de contrôle). Dans cet exemple, la réponse inclut également une durée d'attente minimale. Pour en savoir plus, consultez le corps de la réponse ThreatListUpdates.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 à la fois des ajouts et des suppressions. Il peut y avoir plusieurs ensembles d'ajouts, mais un seul ensemble de suppressions (voir Mises à jour de bases de données).

État du nouveau 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 (le champ state dans la requête ThreatListUpdates.fetch ou le champ clientStates dans la requête fullHashes.find).

Sommes de contrôle

La somme de contrôle permet aux clients de vérifier que la base de données locale n'a pas été corrompue. Si la somme de contrôle ne correspond pas, le client doit effacer la base de données et réémettre une mise à jour avec un champ state vide. Toutefois, les clients dans cette situation doivent toujours respecter 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 requête de mise à jour. Notez qu'une période d'attente peut être incluse ou non dans la réponse (consultez la section 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 la section 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 n'est pas présent dans la base de données locale, l'URL est considérée comme sûre (elle ne figure pas dans les listes de navigation sécurisée).

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 navigation sécurisée pour validation. Les serveurs renverront tous les hachages SHA 256 complets contenant le préfixe de hachage donné. Si l'un de ces hachages complets correspond à celui de l'URL en question, cette dernière est considérée comme non sécurisée. Si aucun hachage complet ne correspond à celui de l'URL en question, cette URL est considérée comme sûre.

À aucun moment, Google n'a connaissance des URL que vous examinez. Google mémorise les préfixes de hachage des URL, mais ceux-ci ne fournissent pas beaucoup d'informations sur les URL réelles.

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 encouragé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 complets correspondants, ainsi que les durées de cache positives et 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 votre clé API par API_KEY 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 comprend les informations sur le client (ID et version), les états du client et les informations sur la menace (les noms de la liste et les préfixes de hachage). Pour les requêtes JSON, les préfixes de hachage doivent être envoyés 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 suggérons de choisir un nom qui représente la véritable identité du client, tel que le nom de votre entreprise, présenté comme un seul mot, tout en minuscules.)

Tous les états du client

Le champ clientStates contient les états du client pour toutes les listes de navigation sécurisée dans la base de données locale du client. (Les états du client sont renvoyés dans le champ newClientState de la réponse ThreatListUpdates.fetch.)

Listes de navigation sécurisée

Les champs threatTypes, platformTypes et threatEntryTypes sont combinés pour identifier (nom) les listes de navigation sécurisée. Dans l'exemple, deux listes sont identifiées: MALWARE/WINDOWS/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 (consultez la section 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 présent dans la base de données locale. Par exemple, si le préfixe de hachage local fait 4 octets, l'entrée de menace doit avoir une longueur de 4 octets. Si le préfixe de hachage local a été allongé à sept octets, l'entrée de la menace doit comporter sept octets.

Dans cet exemple, la requête comprend 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 non 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 attendre (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 correspondance (noms de la liste et hachages complets, métadonnées, le cas échéant, et durées de cache). Dans cet exemple, le corps de la réponse inclut également une 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 n'a été trouvée pour le troisième préfixe de hachage. Rien n'est donc renvoyé. L'URL correspondant à ce préfixe est considérée comme sûre.

Notez que cet exemple met en correspondance un hachage complet avec un préfixe de hachage. Toutefois, il peut y avoir plusieurs hachages complets correspondant au même préfixe.

Métadonnées

Le champ threatEntryMetadata est facultatif et fournit des informations supplémentaires sur la mise en correspondance des menaces. Les métadonnées sont actuellement disponibles pour la liste de navigation sécurisée MALWARE/WINDOWS/URL (voir Métadonnées).

Durées du cache

Les champs cacheDuration et negativeCacheDuration indiquent la durée pendant laquelle les hachages doivent être considérés comme non sécurisés ou sûrs (voir la section Mise en cache).

Durées d'attente minimales

Le champ minimumWaitDuration indique que le client doit attendre 300 secondes (5 minutes) avant d'envoyer une autre requête fullHashes. Notez qu'une période d'attente peut être incluse ou non dans la réponse (consultez la section Fréquence des requêtes).