Overview

واجهة برمجة تطبيقات بوابة HTTP في ميزة "التصفّح الآمن"

ملاحظة: لا تزال هذه المستندات قيد التطوير حاليًا. ومن المتوقّع حدوث تحسينات في المستقبل القريب.

واجهة برمجة تطبيقات بوابة HTTP التي تستخدم ميزة "التصفّح الآمن" هي واجهة برمجة تطبيقات للحفاظ على الخصوصية تم تصميمها استنادًا إلى بروتوكول IETF RFC الذي يحمل اسم Oblivious HTTP ، RFC 9458.

نظرة عامة

واجهة برمجة تطبيقات بوابة HTTP في ميزة "التصفّح الآمن" من Google هي خدمة من Google تتيح لتطبيقات العملاء التحقّق من عناوين URL وفقًا لقوائم Google المعدّلة باستمرار التي تتضمّن موارد الويب غير الآمنة مع تفعيل إجراءات إضافية لحماية الخصوصية.

ويتم تحقيق ذلك باستخدام بروتوكول خفيف يُسمى Oblivious HTTP أو OHTTP اختصارًا. وهو بروتوكول بدون حالة يمكن أن يستخدمه عملاء ميزة "التصفّح الآمن" للوصول إلى واجهات برمجة التطبيقات Google Safe Browse V5 API من أجل الحصول على إجراءات حماية فعّالة وزيادة التغطية بدون المساس بخصوصية المستخدمين.

ملاحظة: لا يمكن الوصول إلى واجهات برمجة التطبيقات للإصدار 4 من ميزة "التصفّح الآمن من Google" من خلال هذه الخدمة.

بروتوكول HTTP الخاص بالتصفح الآمن

بروتوكول RFC

Oblivious HTTP هو بروتوكول بسيط تم تعريفه في RFC 9458، ويُستخدم لتشفير رسائل HTTP وإرسالها من عميل إلى خادم مستهدف. ويستخدم ذلك خدمة نقل موثوق بها بطريقة تحدّ من استخدام الخادم المستهدف للبيانات الوصفية، مثل عنوان IP ومعلومات الاتصال لتحديد هوية العميل، ما يوفّر الخصوصية والأمان أعلى بروتوكول HTTP/S العادي. يستخدم البروتوكول بروتوكول HTTP الثنائي، المحدد في RFC 9292، لترميز/فك ترميز طلبات/استجابات HTTP.

على مستوى عالٍ، يقف عنصر الإرسال بين مورد العميل والبوابة الذي يعمل على إنشاء وكيل لزيارات العميل عن طريق إزالة جميع معرّفات العملاء من خلال إزالة جميع معرّفات العملاء، بما في ذلك السمات الحساسة للخصوصية مثل عناوين IP، ما يؤدي إلى إخفاء هوية طلبات HTTP الواردة إلى خدمة المدخل بشكل فعّال. تكمن الفائدة الإضافية لـ OHTTP في أنّ جميع الطلبات تخضع للتشفير التام بين الأطراف، ما يعني أنّ طلبات البحث في ميزة "التصفّح الآمن" (أي قيم التجزئة المُقتطَعة من تعبيرات عناوين URL) لن تكون مرئية للإرسال. يُرجى الرجوع إلى مشاركة المدوّنة للاطّلاع على مثال عن عملية التنفيذ في Chrome.

الشكل: تدفق OHTTP

ويمكن للعملاء اختيار أي موفِّر خدمة للإرسال (على سبيل المثال، سريعًا) للدمج مع الخدمة. يجب أن يستخدم جهاز الإرسال مصادقة Oauth 2.0 مع نطاق الترخيص التالي للوصول إلى الخدمة.

// OAuth Authorization scope:
https://www.googleapis.com/auth/3p-relay-safe-browsing

نقاط نهاية واجهة برمجة التطبيقات

المفتاح العام OHTTP

ستوفّر نقطة النهاية هذه إعدادات المفتاح العام OHTTP على النحو المحدّد في RFC 9458، الذي سيستخدمه العميل لتشفير طلب OHTTP.

GET https://safebrowsingohttpgateway.googleapis.com/v1/ohttp/hpkekeyconfig?key=<API key>

مفتاح واجهة برمجة التطبيقات أعلاه ليس ضروريًا تمامًا، فلا يغيّر الخادم المفتاح العام OHTTP بناءً على مفتاح واجهة برمجة التطبيقات المُقدَّم. ويُسمح للعملاء بالتأكد من هذه الحقيقة من خلال استخدام مفاتيح واجهة برمجة تطبيقات صالحة مختلفة للوصول إلى نقطة النهاية هذه أو عدم استخدام أي مفاتيح واجهة برمجة تطبيقات تمامًا، والتحقق من أن الاستجابة تحتوي بالفعل على نفس مفتاح OHTTP العام. ومع ذلك، ننصح باستخدام مفتاح واجهة برمجة التطبيقات لتسهيل تصحيح الأخطاء، ويتيح ذلك للعملاء الاطّلاع على إحصاءات مثل عدد الطلبات على Google Cloud Console. إذا كان العميل يريد توفير مفتاح واجهة برمجة التطبيقات، يُرجى الرجوع إلى هذه الوثائق حول كيفية إعداد مفاتيح واجهة برمجة التطبيقات.

وفقًا لما هو منصوص عليه في قسم اقتراحات الخصوصية، بهدف تحقيق أهداف الاتساق الرئيسية، ننصح مورّدي العملاء بإعداد بنية أساسية لتوزيع مفاتيح مركزية من أجل جلب المفتاح من نقطة النهاية هذه وتوزيعه بعد ذلك على تطبيقات العملاء.

وفقًا لإرشادات إدارة المفاتيح، يتم تدوير المفاتيح بانتظام على الخادم. على العملاء إعادة تحميل المفتاح، أي استرجاع النسخة المحلية من المفتاح وتعديلها من حين لآخر لتجنُّب تعذُّر فك التشفير.

على العملاء إعادة تحميل (جلب وتعديل) المفتاح العام مرة واحدة يوميًا. في حالة استخدام آلية توزيع مركزية، يجب أن تتأكد هذه الآلية من جلب المفاتيح وتوزيعها مرة واحدة يوميًا.

طلب OHTTP المغلف

ستعرض نقطة النهاية هذه طلب OHTTP المضمّن في نص HTTP لطلب POST، وذلك من خلال تنفيذ فك تشفير الطلب، وبعد ذلك تشفير استجابة OHTTP لكي تتم إعادة توجيهها مرة أخرى إلى أداة "الإرسال" في استجابة HTTP. يجب أن يضمِّن العميل عنوان طلب Content-Type على أنّه message/ohttp-req في طلب HTTP POST.

POST https://safebrowsingohttpgateway.googleapis.com/v1/ohttp:handleOhttpEncapsulatedRequest?key=<API key>

ملاحظة: وفقًا للإرشادات المتعلّقة بـ RFC، عليك ترميز الطلب الداخلي (راجِع مستندات V5 حول كيفية إنشاء طلب ميزة "التصفّح الآمن") باستخدام بروتوكول Binary HTTP (بروتوكول HTTP الثنائي، RFC 9292.

مكتبات العملاء

تتضمن Google Quiche عمليات تنفيذ من جهة العميل لكل من بروتوكولَي OHTTP وBHTTP. ننصح العملاء باستخدام هذه المكتبات. يمكنك الرجوع إلى الرمز الزائف لمعرفة كيفية إنشاء طلبات OHTTP للوصول إلى واجهة برمجة التطبيقات.

نموذج لعملية التنفيذ من جهة العميل

يجلب العملاء مفتاح HTTP العام Oblivious من نقطة نهاية المفتاح العام. بعد ذلك، قم بتهيئة مفتاح quiche OHTTP مثل ذلك، مع تهيئة عميل quiche OHTTP.

        auto ohttp_key_cfgs = quiche::ObliviousHttpKeyConfigs::ParseConcatenatedKeys(std::string public_key);
        auto key_config = ohttp_key_cfgs->PreferredConfig();
        auto public_key = ohttp_key_cfgs->GetPublicKeyForId(key_config.GetKeyId())
        auto ohttp_client = quiche::ObliviousHttpClient::Create(public_key, key_config);

سيستخدم برنامج العميل ترميز HTTP الثنائي لإنشاء طلب BHTTP كخطوة أولى قبل التشفير.

    quiche::BinaryHttpRequest::ControlData bhttp_ctrl_data{
      .method = "POST",
      .scheme = "https",
      .authority = "safebrowsing.googleapis.com",
      .path = "/v5/hashes:search?key=<API key>&hashPrefixes=<HASH prefix 1>&hashPrefixes=<HASH prefix 2>",
    };
    quiche::BinaryHttpRequest bhttp_request(bhttp_ctrl_data);

بعد ذلك، سيقوم العميل بتشفير طلب HTTP الثنائي الذي تم إنشاؤه في الخطوة أعلاه.

      auto bhttp_serialized = bhttp_request.Serialize();
      auto ohttp_request = ohttp_client.CreateObliviousHttpRequest(*bhttp_serialized);
      //  Client must include this in POST body, and add `Content-Type` header as "message/ohttp-req".
      auto payload_include_in_post_body = ohttp_request.EncapsulateAndSerialize();

بعد تلقّي الردّ من Relay، سيفكّ العميل تشفير الاستجابة. ستتضمّن الاستجابة عنوان الاستجابة Content-Type على النحو التالي ohttp-res.

      auto ctx = std::move(ohttp_request).ReleaseContext();
      auto ohttp_response = ohttp_client.DecryptObliviousHttpResponse("data included in body of http_response", ctx);

بعد فك تشفير استجابة OHTTP بنجاح، يمكنك فك ترميز الإخراج باستخدام Binary HTTP مثل ذلك.

      auto bhttp_response = BinaryHttpResponse::Create(ohttp_response.GetPlaintextData());
      if (bhttp_response.status_code() == 200) {
        auto http_response = bhttp_response.body();
        auto response_headers = bhttp_response.GetHeaderFields();
      }