सुरक्षित ब्राउज़िंग अपडेट एपीआई (v4)

खास जानकारी

Update API, आपके क्लाइंट ऐप्लिकेशन को किसी स्थानीय डेटाबेस में मेमोरी के लिए, सुरक्षित ब्राउज़िंग सूचियों के हैश किए गए वर्शन डाउनलोड करने की सुविधा देता है. इसके बाद, यूआरएल की स्थानीय तौर पर जांच की जा सकती है. अगर लोकल डेटाबेस में कोई मिलान मिलता है, सिर्फ़ तभी क्लाइंट को सुरक्षित ब्राउज़िंग सर्वर पर एक अनुरोध भेजना होगा. इससे इस बात की पुष्टि की जा सकेगी कि यूआरएल, सुरक्षित ब्राउज़िंग की सूचियों में शामिल है या नहीं.

Update API का इस्तेमाल करने से पहले, आपको एक लोकल डेटाबेस सेट अप करना होगा. सुरक्षित ब्राउज़िंग की मदद से, Go पैकेज लिया जा सकता है. ज़्यादा जानकारी के लिए, लोकल डेटाबेस में डेटाबेस सेटअप सेक्शन देखें.

लोकल डेटाबेस को अपडेट करना

मौजूदा समय में बने रहने के लिए, क्लाइंट को समय-समय पर अपने लोकल डेटाबेस में सुरक्षित ब्राउज़िंग की सूचियों को अपडेट करना होगा. बैंडविड्थ बचाने के लिए, क्लाइंट रॉ यूआरएल के बजाय यूआरएल के हैश प्रीफ़िक्स डाउनलोड करते हैं. उदाहरण के लिए, अगर "www.badurl.com/" सुरक्षित ब्राउज़िंग की सूची में है, तो क्लाइंट, यूआरएल के बजाय उस यूआरएल का SHA256 हैश प्रीफ़िक्स डाउनलोड करते हैं. ज़्यादातर मामलों में हैश प्रीफ़िक्स चार बाइट लंबे होते हैं. इसका मतलब है कि एक सूची को डाउनलोड करने पर, औसत बैंडविड्थ की लागत कंप्रेस करने से पहले चार बाइट होती है.

लोकल डेटाबेस में सुरक्षित ब्राउज़िंग की सूचियों को अपडेट करने के लिए, threatListUpdates.fetch तरीके का इस्तेमाल करके, एचटीटीपी POST अनुरोध भेजें:

• एचटीटीपी POST अनुरोध में, उन सूचियों के नाम शामिल होते हैं जिन्हें अपडेट किया जाना है. साथ ही, इसमें क्लाइंट से जुड़ी अलग-अलग शर्तें भी शामिल होती हैं, जो मेमोरी और बैंडविथ की सीमाओं को ध्यान में रखकर बनाई जाती हैं.
• एचटीटीपी POST रिस्पॉन्स, पूरा अपडेट या कुछ हद तक अपडेट देता है. जवाब हो सकता है कि कम से कम इंतज़ार की अवधि भी दे.

उदाहरण: invalidListUpdate.fetch

एचटीटीपी पोस्ट अनुरोध

यहां दिए गए उदाहरण में, सुरक्षित ब्राउज़िंग की किसी एक सूची के लिए अपडेट का अनुरोध किया गया है.

अनुरोध का हेडर

अनुरोध के हेडर में अनुरोध का यूआरएल और कॉन्टेंट का टाइप शामिल होता है. यूआरएल में अपनी एपीआई कुंजी को API_KEY से बदलना न भूलें.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

अनुरोध का मुख्य भाग

अनुरोध के मुख्य हिस्से में, क्लाइंट की जानकारी (आईडी और वर्शन) और अपडेट की जानकारी (सूची का नाम, सूची की स्थिति, और क्लाइंट से जुड़ी पाबंदियां) शामिल होती है. ज़्यादा जानकारी के लिए, threatListअपडेट.fetch अनुरोध का मुख्य हिस्सा और कोड के उदाहरण में दी गई जानकारी देखें.

{
  "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"]
    }
  }]
}

क्लाइंट की जानकारी

clientID और clientVersion फ़ील्ड से, लागू किए गए क्लाइंट की पहचान खास तौर पर की जानी चाहिए, न कि किसी उपयोगकर्ता की. (क्लाइंट की जानकारी का इस्तेमाल, सर्वर साइड लॉगिंग में किया जाता है. Client-ID के लिए कोई भी नाम चुना जा सकता है. हालांकि, हमारा सुझाव है कि आप ऐसा नाम चुनें जो क्लाइंट की असली पहचान दिखाता हो. जैसे, आपकी कंपनी का नाम. इसे अंग्रेज़ी के छोटे अक्षरों में लिखा जाना चाहिए.

सुरक्षित ब्राउज़िंग की सूचियां

threatType, platformType, और threatEntryType फ़ील्ड को सुरक्षित ब्राउज़िंग की सूचियों (नाम) की पहचान करने के लिए जोड़ा जाता है. उदाहरण में, एक सूची की पहचान की गई है: MALWARE/WINDOWS/URL. अनुरोध भेजने से पहले, पक्का कर लें कि आपने टाइप के जो कॉम्बिनेशन बताए हैं वे मान्य हैं (सुरक्षित ब्राउज़िंग सूचियां देखें).

क्लाइंट की स्थिति

state फ़ील्ड में, सुरक्षित ब्राउज़िंग की मौजूदा क्लाइंट स्थिति होती है. (क्लाइंट की स्थिति, threatListअपडेट.fetch रिस्पॉन्स के newClientState फ़ील्ड में दिखती है.) शुरुआती अपडेट के लिए, state फ़ील्ड को खाली छोड़ दें.

साइज़ कंस्ट्रेंट

maxUpdateEntries फ़ील्ड उन अपडेट की कुल संख्या बताता है जिन्हें क्लाइंट मैनेज कर सकता है (उदाहरण में, 2048). maxDatabaseEntries फ़ील्ड में ऐसी एंट्री की कुल संख्या बताई जाती है जिन्हें स्थानीय डेटाबेस मैनेज कर सकता है (उदाहरण में, 4096). क्लाइंट को, मेमोरी और बैंडविथ की सीमाओं को सुरक्षित रखने और सूची के बढ़ने से रोकने के लिए साइज़ के पैमाने तय करने चाहिए. ज़्यादा जानकारी के लिए, (अपडेट की पाबंदियां देखें).

समर्थित कंप्रेशन

supportedCompressions फ़ील्ड में, क्लाइंट के साथ काम करने वाले कंप्रेशन टाइप की सूची होती है. इस उदाहरण में, क्लाइंट सिर्फ़ रॉ, बिना कंप्रेस किए गए डेटा के साथ काम करता है. हालांकि, सुरक्षित ब्राउज़िंग की मदद से कई तरह के कंप्रेस किए जा सकते हैं. ज़्यादा जानकारी के लिए, कंप्रेशन देखें.

एचटीटीपी POST रिस्पॉन्स

इस उदाहरण में, रिस्पॉन्स, अनुरोध किए गए कंप्रेशन टाइप का इस्तेमाल करके, सुरक्षित ब्राउज़िंग सूची के लिए, कुछ हद तक अपडेट करता है.

रिस्पॉन्स हेडर

रिस्पॉन्स हेडर में एचटीटीपी स्टेटस कोड और कॉन्टेंट का टाइप शामिल होता है. एचटीटीपी/200 के अलावा जिन क्लाइंट को स्टेटस कोड मिलता है उन्हें बैक-ऑफ़ मोड चालू करना होगा (अनुरोध फ़्रीक्वेंसी देखें).

HTTP/1.1 200 OK
Content-Type: application/json

जवाब का मुख्य भाग

रिस्पॉन्स के मुख्य हिस्से में अपडेट की जानकारी शामिल होती है. जैसे, लोकल डेटाबेस में लागू किए जाने वाले बदलावों की सूची का नाम, रिस्पॉन्स टाइप, हटाने की जानकारी, नए क्लाइंट स्टेटस, और चेकसम. उदाहरण में, जवाब में कम से कम इंतज़ार की अवधि भी शामिल है. ज़्यादा जानकारी के लिए, threatListList.fetch जवाब का मुख्य हिस्सा देखें और कोड के उदाहरण में दी गई एक्सप्लेनेशंस देखें.

{
  "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"
}

डेटाबेस अपडेट

responseType फ़ील्ड में कुछ हिस्सा या पूरा अपडेट दिखेगा. उदाहरण में, कुछ हद तक अपडेट किया गया है, इसलिए रिस्पॉन्स में जोड़ना और हटाना, दोनों शामिल हैं. जोड़े जाने के कई सेट हो सकते हैं, लेकिन हटाए जाने का सिर्फ़ एक सेट (डेटाबेस अपडेट देखें).

नए क्लाइंट की स्थिति

अपडेट की गई नई सुरक्षित ब्राउज़िंग सूची के लिए, newClientState फ़ील्ड में क्लाइंट की नई स्थिति होती है. बाद में किए जाने वाले अपडेट के अनुरोधों के लिए, क्लाइंट को क्लाइंट की नई स्थिति को सेव करना होगा (threatListअपडेट.fetch अनुरोध में state फ़ील्ड या fullHashes.find अनुरोध में clientStates फ़ील्ड).

चेकसम

चेकसम क्लाइंट को यह पुष्टि करने देता है कि लोकल डेटाबेस में कोई गड़बड़ी नहीं है. अगर चेकसम मैच नहीं करता है, तो क्लाइंट को डेटाबेस हटाना होगा और खाली state फ़ील्ड के साथ अपडेट फिर से जारी करना होगा. हालांकि, इस स्थिति में भी क्लाइंट को अपडेट के लिए दिए गए समय के अंतराल का पालन करना होगा. (अनुरोध की फ़्रीक्वेंसी देखें).

इंतज़ार का कम से कम समय

minimumWaitDuration फ़ील्ड से पता चलता है कि अपडेट का दूसरा अनुरोध भेजने से पहले, क्लाइंट को 593.44 सेकंड (9.89 मिनट) का इंतज़ार करना होगा. ध्यान दें कि जवाब में इंतज़ार की अवधि शामिल की जा सकती है और नहीं भी (अनुरोध की फ़्रीक्वेंसी देखें).

यूआरएल की जांच की जा रही है

यह देखने के लिए कि कोई यूआरएल, सुरक्षित ब्राउज़िंग की सूची में है या नहीं, क्लाइंट को सबसे पहले यूआरएल के हैश और हैश प्रीफ़िक्स का पता लगाना होगा. ज़्यादा जानकारी के लिए, यूआरएल और हैशिंग देखें. इसके बाद, क्लाइंट लोकल डेटाबेस से क्वेरी करता है और यह पता लगाता है कि कोई मैच है या नहीं. अगर हैश प्रीफ़िक्स स्थानीय डेटाबेस में मौजूद नहीं है, तो यूआरएल को सुरक्षित माना जाता है, न कि सुरक्षित ब्राउज़िंग की सूचियों में.

अगर लोकल डेटाबेस में हैश प्रीफ़िक्स मौजूद है (हैश प्रीफ़िक्स कोलीशन), तो क्लाइंट को पुष्टि के लिए सुरक्षित ब्राउज़िंग सर्वर को हैश प्रीफ़िक्स भेजना होगा. सर्वर ऐसे सभी SHA 256 हैश दिखाएंगे जिनमें दिए गए हैश प्रीफ़िक्स शामिल हैं. अगर उनमें से कोई एक पूरी लंबाई वाला हैश, बताए गए यूआरएल के पूरे हैश से मेल खाता है, तो यूआरएल को असुरक्षित माना जाता है. अगर कोई भी पूरी लंबाई वाला हैश, बताए गए यूआरएल के पूरे हैश से मेल नहीं खाता, तो उस यूआरएल को सुरक्षित माना जाता है.

आप जिन यूआरएल की जांच कर रहे हैं उनके बारे में Google को किसी भी समय जानकारी नहीं मिलती है. Google, यूआरएल के हैश प्रीफ़िक्स के बारे में जान लेता है. हालांकि, हैश प्रीफ़िक्स से असल यूआरएल के बारे में ज़्यादा जानकारी नहीं मिलती.

यह देखने के लिए कि यूआरएल, सुरक्षित ब्राउज़िंग की सूची में शामिल है या नहीं, fullHashes.find वाले तरीके का इस्तेमाल करके, एचटीटीपी POST अनुरोध भेजें:

• एचटीटीपी POST अनुरोध में ज़्यादा से ज़्यादा 500 खतरे की एंट्री शामिल हो सकती हैं.
• एचटीटीपी POST अनुरोध में, जांच किए जाने वाले यूआरएल के हैश प्रीफ़िक्स शामिल होते हैं. क्लाइंट को बैंडविथ के इस्तेमाल को कम करने के लिए, एक ही अनुरोध में कई खतरों की एंट्री का बैच बनाने की सलाह दी जाती है.
• एचटीटीपी POST रिस्पॉन्स, मेल खाने वाले पूरी लंबाई वाले हैश के साथ-साथ पॉज़िटिव और नेगेटिव कैश अवधि दिखाता है. जवाब मिलने पर कुछ समय तक इंतज़ार हो सकता है.

उदाहरण: FullHashes.find

एचटीटीपी पोस्ट अनुरोध

नीचे दिए गए उदाहरण में, दो सुरक्षित ब्राउज़िंग सूचियों के नाम और तीन हैश प्रीफ़िक्स भेजे गए हैं, ताकि उनकी तुलना की जा सके और पुष्टि की जा सके.

अनुरोध का हेडर

अनुरोध के हेडर में अनुरोध का यूआरएल और कॉन्टेंट का टाइप शामिल होता है. यूआरएल में अपनी एपीआई पासकोड को API_KEY से बदलना न भूलें.

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

अनुरोध का मुख्य भाग

अनुरोध के मुख्य हिस्से में, क्लाइंट की जानकारी (आईडी और वर्शन), क्लाइंट की स्थिति, और खतरे की जानकारी (सूची के नाम और हैश प्रीफ़िक्स) शामिल होती है. JSON अनुरोधों के लिए, हैश प्रीफ़िक्स को base64 कोड में बदला गया फ़ॉर्म भेजा जाना चाहिए. ज़्यादा जानकारी के लिए, fullHashes.find अनुरोध का मुख्य हिस्सा देखें और कोड के उदाहरण में दिए गए एक्सप्लेनेशंस देखें.

{
  "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=="}
    ]
  }
}

क्लाइंट की जानकारी

clientID और clientVersion फ़ील्ड से, लागू किए गए क्लाइंट की पहचान खास तौर पर की जानी चाहिए, न कि किसी उपयोगकर्ता की. (क्लाइंट की जानकारी का इस्तेमाल, सर्वर साइड लॉगिंग में किया जाता है. Client-ID के लिए कोई भी नाम चुना जा सकता है. हालांकि, हमारा सुझाव है कि आप ऐसा नाम चुनें जो क्लाइंट की असली पहचान दिखाता हो. जैसे, आपकी कंपनी का नाम, जिसे अंग्रेज़ी के छोटे अक्षरों में लिखा गया हो.

सभी क्लाइंट की स्थितियां

clientStates फ़ील्ड में क्लाइंट के लोकल डेटाबेस में मौजूद, सभी सुरक्षित ब्राउज़िंग की सूचियों के लिए क्लाइंट स्टेट होते हैं. (क्लाइंट की स्थिति, threatListअपडेट.fetch रिस्पॉन्स के newClientState फ़ील्ड में दिखती है.)

सुरक्षित ब्राउज़िंग की सूचियां

threatTypes, platformTypes, और threatEntryTypes फ़ील्ड, सुरक्षित ब्राउज़िंग सूचियों (नाम) की पहचान करने के लिए जुड़ जाते हैं. इस उदाहरण में, दो सूचियों की पहचान की गई है: MALWARE/WINDOWS/URL और SOCIAL_engineERING/WINDOWS/URL. अनुरोध भेजने से पहले, पक्का कर लें कि आपने टाइप के जो कॉम्बिनेशन बताए हैं वे मान्य हैं (सुरक्षित ब्राउज़िंग सूचियां देखें).

थ्रेट हैश प्रीफ़िक्स

खतराEntries कलेक्शन में, उन यूआरएल के हैश प्रीफ़िक्स शामिल होते हैं जिनकी आपको जांच करनी है. hash फ़ील्ड में वही हैश प्रीफ़िक्स होना चाहिए जो लोकल डेटाबेस में मौजूद है. उदाहरण के लिए, अगर लोकल हैश प्रीफ़िक्स चार बाइट लंबा है, तो खतरे की एंट्री चार बाइट होनी चाहिए. अगर लोकल हैश प्रीफ़िक्स को सात बाइट तक बढ़ाया गया था, तो खतरे की एंट्री 7 बाइट की होनी चाहिए.

इस उदाहरण में, अनुरोध में तीन हैश प्रीफ़िक्स शामिल हैं. तीनों प्रीफ़िक्स की तुलना सुरक्षित ब्राउज़िंग की सूची से की जाएगी, ताकि यह तय किया जा सके कि कोई पूरी अवधि वाला हैश फ़ंक्शन है या नहीं.

ध्यान दें: Update API और fullHashes.find तरीके को हमेशा hash फ़ील्ड का इस्तेमाल करना चाहिए, न कि URLफ़ील्ड का (ThreatEntry देखें).

एचटीटीपी POST रिस्पॉन्स

यहां दिए गए उदाहरण में, रिस्पॉन्स, मेल खाने वाला डेटा दिखाता है, जो सुरक्षित ब्राउज़िंग की सूची के हिसाब से व्यवस्थित किया जाता है. साथ ही, कैश मेमोरी और इंतज़ार की अवधि भी इसमें दिखती है.

रिस्पॉन्स हेडर

रिस्पॉन्स हेडर में एचटीटीपी स्टेटस कोड और कॉन्टेंट का टाइप शामिल होता है. जिन क्लाइंट को एचटीटीपी/200 के अलावा कोई स्टेटस कोड मिलता है उन्हें बैक-ऑफ़ करना होगा (अनुरोध फ़्रीक्वेंसी देखें).

HTTP/1.1 200 OK
Content-Type: application/json

जवाब का मुख्य भाग

रिस्पॉन्स के मुख्य हिस्से में, मैच की जानकारी शामिल होती है. जैसे, सूची के नाम और पूरे हैश, अगर मेटाडेटा उपलब्ध हो, तो वह और कैश मेमोरी की अवधि. उदाहरण में, जवाब के मुख्य हिस्से में कम से कम इंतज़ार की अवधि भी शामिल की गई है. ज़्यादा जानकारी के लिए, fullHashes.find रिस्पॉन्स बॉडी देखें और कोड के उदाहरण में दी गई जानकारी देखें.

{
  "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"
}

मिलते-जुलते वीडियो

मैच ऑब्जेक्ट, दो हैश प्रीफ़िक्स के लिए, मैच करने वाला पूरी लंबाई वाला हैश दिखाता है. इन हैश से जुड़े यूआरएल असुरक्षित माने जाते हैं. तीसरे हैश प्रीफ़िक्स के लिए कोई मिलान नहीं मिला, इसलिए कुछ नहीं मिला. इस हैश प्रीफ़िक्स से जुड़े यूआरएल को सुरक्षित माना जाता है.

ध्यान दें कि यह उदाहरण एक पूरी लंबाई वाले हैश से एक हैश प्रीफ़िक्स से मेल खाता है. हालांकि, यहां ऐसे कई पूरे हैश हो सकते हैं जो एक ही हैश प्रीफ़िक्स से मैप करते हों.

मेटाडेटा

threatEntryMetadata फ़ील्ड में जानकारी देना ज़रूरी नहीं है. इससे, खतरे से जुड़े मैच के बारे में ज़्यादा जानकारी मिलती है. फ़िलहाल, मेटाडेटा, मैलवेयर/Windows/यूआरएल सुरक्षित ब्राउज़िंग सूची के लिए उपलब्ध है (मेटाडेटा देखें).

कैश मेमोरी की अवधि

cacheDuration और negativeCacheDuration फ़ील्ड से पता चलता है कि हैश को कितने समय के लिए असुरक्षित या सुरक्षित माना जाना चाहिए. ज़्यादा जानकारी के लिए कैशिंग देखें.

इंतज़ार का कम से कम समय

minimumWaitDuration फ़ील्ड से पता चलता है कि क्लाइंट को फिर से FullHashes का अनुरोध करने से पहले 300 सेकंड (5 मिनट) तक इंतज़ार करना होगा. ध्यान दें कि जवाब में इंतज़ार का समय शामिल हो भी सकता है और नहीं भी (अनुरोध की फ़्रीक्वेंसी देखें).