ضبط أمان الشبكة

تتيح لك ميزة "إعداد أمان الشبكات" تخصيص إعدادات أمان الشبكات في تطبيقك بطريقة آمنة وتوضيحية في ملف إعدادات بدون تعديل رمز التطبيق. يمكن ضبط هذه الإعدادات لنطاقات معيّنة ولتطبيق معيّن. وفي ما يلي الميزات الرئيسية لهذه الوظيفة:

  • كيانات الثقة المخصّصة: يمكنك تخصيص مراجع التصديق (CA) الموثوق بها لاتصالات التطبيق الآمنة. على سبيل المثال، الوثوق بشهادات معيّنة موقَّعة ذاتيًا أو حصر مجموعة هيئات إصدار الشهادات العامة التي يثق بها التطبيق.
  • عمليات الإلغاء المخصّصة لتصحيح الأخطاء فقط: يمكنك تصحيح الأخطاء في الاتصالات الآمنة في أحد التطبيقات بأمان بدون تعريض قاعدة المستخدمين المثبّتة لأي مخاطر إضافية.
  • إيقاف البيانات غير المشفّرة: لحماية التطبيقات من الاستخدام غير المقصود للبيانات غير المشفّرة.
  • شفافية الشهادات: يمكنك حصر الاتصالات الآمنة التي يجريها التطبيق على استخدام الشهادات التي تم تسجيلها بشكل يمكن إثباته.
  • تثبيت الشهادات: يمكنك حصر الاتصال الآمن لتطبيق بشهادات معيّنة.

إضافة ملف إعدادات أمان الشبكة

تستخدم ميزة "إعداد أمان الشبكات" ملف XML تحدّد فيه إعدادات تطبيقك. ويجب تضمين إدخال في بيان تطبيقك للإشارة إلى هذا الملف. يوضّح مقتطف الرمز التالي من ملف البيان كيفية إنشاء هذا الإدخال: 

<?xml version="1.0" encoding="utf-8"?>
<manifest ... >
    <application android:networkSecurityConfig="@xml/network_security_config"
                    ... >
        ...
    </application>
</manifest>

تخصيص جهات إصدار الشهادات الموثوق بها

قد تريد أن يثق تطبيقك بمجموعة مخصّصة من هيئات التصديق بدلاً من الإعداد التلقائي للمنصة. في ما يلي الأسباب الأكثر شيوعًا لذلك:

  • الاتصال بمضيف لديه هيئة إصدار شهادات (CA) مخصّصة، مثل هيئة إصدار شهادات (CA) موقّعة ذاتيًا أو صادرة داخليًا داخل شركة
  • قصر مجموعة هيئات إصدار الشهادات (CA) على هيئات إصدار الشهادات (CA) التي تثق بها فقط بدلاً من كل هيئات إصدار الشهادات (CA) المثبَّتة مسبقًا
  • الوثوق في هيئات إصدار شهادات إضافية غير مضمّنة في النظام

تثق الاتصالات الآمنة (التي تستخدم بروتوكولات مثل TLS وHTTPS) من جميع التطبيقات تلقائيًا في شهادات المراجع المصدّقة المثبَّتة مسبقًا في النظام، كما تثق التطبيقات التي تستهدف الإصدار 6.0 (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأقدم تلقائيًا في متجر شهادات المراجع المصدّقة التي أضافها المستخدم. يمكنك تخصيص عمليات ربط تطبيقك باستخدام base-config (للتخصيص على مستوى التطبيق) أو domain-config (للتخصيص على مستوى النطاق).

ضبط مرجع مصدّق مخصّص

ملاحظة: لا يتم إجراء عملية التحقّق من شهادة الشفافية على الاتصالات التي تستخدم نقاط ارتساء مخصّصة.

قد تحتاج إلى الاتصال بمضيف يستخدم شهادة طبقة المقابس الآمنة (SSL) موقَّعة ذاتيًا أو بمضيف أصدرت شهادة طبقة المقابس الآمنة (SSL) الخاصة به هيئة إصدار الشهادات (CA) غير عامة تثق بها، مثل هيئة إصدار الشهادات (CA) الداخلية لشركتك. يوضّح مقتطف الرمز التالي كيفية ضبط تطبيقك لاستخدام شهادة هيئة إصدار الشهادات (CA) مخصّصة في res/xml/network_security_config.xml: 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

أضِف الشهادة الموقّعة ذاتيًا أو شهادة CA غير العامة بتنسيق PEM أو DER إلى res/raw/my_ca.

تقييد مجموعة مصادر الشهادات الموثوقة

إذا كنت لا تريد أن يثق تطبيقك بجميع مراجع التصديق التي يثق بها النظام، يمكنك بدلاً من ذلك تحديد مجموعة أصغر من مراجع التصديق التي يثق بها تطبيقك. ويحمي هذا الإجراء التطبيق من الشهادات الاحتيالية الصادرة عن أي من مراجع التصديق الأخرى.

يشبه الإعداد الذي يهدف إلى حصر مجموعة مراجع التصديق الموثوق بها عملية الوثوق بهيئة إصدار شهادات مخصّصة لنطاق معيّن، باستثناء أنّه يتم توفير مراجع تصديق متعددة في المورد. يوضّح مقتطف الرمز التالي كيفية حصر مجموعة مراجع التصديق الموثوق بها في تطبيقك ضمن res/xml/network_security_config.xml: 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">secure.example.com</domain>
        <domain includeSubdomains="true">cdn.example.com</domain>
        <trust-anchors>
            <certificates src="@raw/trusted_roots"/>
        </trust-anchors>
    </domain-config>
</network-security-config>

أضِف جهات التصديق الموثوق بها بتنسيق PEM أو DER إلى res/raw/trusted_roots. يُرجى العِلم أنّه في حال استخدام تنسيق PEM، يجب أن يحتوي الملف على بيانات PEM فقط بدون أي نص إضافي. يمكنك أيضًا تقديم عناصر <certificates> متعددة بدلاً من عنصر واحد.

الوثوق بمراجع تصديق إضافية

قد تحتاج إلى أن يثق تطبيقك في هيئات إصدار شهادات إضافية لا يثق فيها النظام، مثلاً إذا كان النظام لا يتضمّن هيئة إصدار الشهادات بعد أو إذا كانت هيئة إصدار الشهادات لا تستوفي متطلبات إدراجها في نظام Android. يمكنك تحديد مصادر شهادات متعددة لإعدادات في res/xml/network_security_config.xml باستخدام رمز مثل المقتطف التالي. 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="@raw/extracas"/>
            <certificates src="system"/>
        </trust-anchors>
    </base-config>
</network-security-config>

ضبط شهادات CA لتصحيح الأخطاء

عند تصحيح أخطاء تطبيق يتصل عبر HTTPS، قد تحتاج إلى الاتصال بخادم تطوير محلي لا يتضمّن شهادة طبقة المقابس الآمنة (SSL) الخاصة بخادم الإنتاج. لإتاحة ذلك بدون إجراء أي تعديل على الرمز البرمجي لتطبيقك، يمكنك تحديد مراجع مصدّقة مخصّصة لتصحيح الأخطاء فقط، وهي مراجع مصدّقة موثوق بها فقط عندما تكون قيمة android:debuggable هي true، وذلك باستخدام debug-overrides. عادةً ما تضبط بيئات التطوير المتكاملة وأدوات الإنشاء هذه العلامة تلقائيًا للإصدارات غير النهائية.

وهذا الإجراء أكثر أمانًا من الرمز الشرطي العادي لأنّ متاجر التطبيقات لا تقبل التطبيقات التي تم وضع علامة عليها بأنّها قابلة للتصحيح، وذلك كإجراء احترازي للأمان.

يوضّح المقتطف أدناه كيفية تحديد مراجع مصادقة مخصّصة لتصحيح الأخطاء فقط في res/xml/network_security_config.xml: 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <debug-overrides>
        <trust-anchors>
            <certificates src="@raw/debug_cas"/>
        </trust-anchors>
    </debug-overrides>
</network-security-config>

شفافية الشهادة

ملاحظة: لا تتوفّر ميزة &quot;شفافية الشهادات&quot; إلا على الإصدار 16 من نظام التشغيل Android (المستوى 36 من واجهة برمجة التطبيقات).

شهادات الشفافية (CT، RFC 6962) هي معيار إنترنت مصمَّم لتعزيز أمان الشهادات الرقمية. ويشترط ذلك على مراجع التصديق إرسال جميع الشهادات الصادرة إلى سجلّ علني يتم فيه تسجيلها، ما يزيد من الشفافية والمساءلة في عملية إصدار الشهادات.

من خلال الاحتفاظ بسجلّ يمكن التحقّق منه لجميع الشهادات، تجعل &quot;شفافية الشهادات&quot; من الصعب جدًا على الجهات المسيئة تزوير الشهادات أو على مصادر الشهادات إصدارها عن طريق الخطأ. يساعد ذلك في حماية المستخدمين من هجمات الوسيط وغيرها من تهديدات الأمان. لمزيد من المعلومات، يُرجى الاطّلاع على الشرح في transparency.dev. ولمزيد من المعلومات حول الامتثال لسياسة "شفافية الشهادات" على Android، يُرجى الاطّلاع على سياسة "شفافية الشهادات" على Android.

يعتمد السلوك التلقائي لشفافية الشهادات على مستوى واجهة برمجة التطبيقات:

  • بدءًا من الإصدار 17 من نظام التشغيل Android (المستوى 37 من واجهة برمجة التطبيقات)، يتم تفعيل ميزة "شفافية الشهادات" تلقائيًا. يمكن للتطبيقات إيقاف الميزة إما على مستوى العالم أو لكل نطاق على حدة.
  • في نظام التشغيل Android 16 (المستوى 36 لواجهة برمجة التطبيقات)، تكون ميزة "شهادة الشفافية" غير مفعَّلة تلقائيًا. يمكن للتطبيقات تفعيل الميزة إما على مستوى العالم أو لكل نطاق على حدة.
  • في نظام التشغيل Android 15 (المستوى 35 لواجهة برمجة التطبيقات) والإصدارات الأقدم، لا تتوفّر ميزة "شفافية الشهادات".

إيقاف ميزة "شفافية الشهادات"

ملاحظة: في نظام التشغيل Android 16 (مستوى واجهة برمجة التطبيقات 36)، يجب تفعيل ميزة &quot;شفافية الشهادات&quot; من خلال ضبط <certificateTransparency enabled="true"/> (تكون هذه الميزة غير مفعّلة تلقائيًا).

إذا كنت تريد أن يتصل تطبيقك بوجهات بدون الحاجة إلى تسجيل شهاداتها في سجلّات &quot;شهادة الشفافية&quot;، يمكنك إيقاف ميزة &quot;شهادة الشفافية&quot;.

على سبيل المثال، قد تريد السماح لتطبيقك بإجراء اتصالات مع secure.example.com بدون اشتراط توفّر شهادة الشفافية. 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">secure.example.com</domain>
        <certificateTransparency enabled="false"/>
    </domain-config>
</network-security-config>

رسالة ClientHello مشفّرة

ملاحظة: لا تتوفّر ميزة "تشفير Client Hello" إلا على الإصدار 17 من نظام التشغيل Android (مستوى واجهة برمجة التطبيقات 37)، وتتطلّب أن تتوافق مكتبة الشبكات في التطبيق مع ميزة ECH. لن يتم تطبيق الإعدادات المحدّدة هنا إلا إذا كانت مكتبة الشبكات تستخدم ECH.

‫Encrypted Client Hello ‏(ECH، RFC 9849) هي إضافة إلى بروتوكول أمان طبقة النقل (TLS) مصمَّمة لتحسين خصوصية الاتصالات الآمنة. ويعمل ذلك من خلال تشفير الأجزاء الحسّاسة من عملية المصافحة الأولية لبروتوكول أمان طبقة النقل (TLS)، وأبرزها حقل "إشارة اسم الخادم" (SNI).

من خلال تشفير SNI، تمنع ميزة ECH الوسطاء على الشبكة من مراقبة اسم النطاق المحدّد الذي يحاول العميل الاتصال به. ويساعد ذلك في منع تتبُّع المستخدمين أو مراقبتهم استنادًا إلى النطاقات التي يزورونها، ما يقلّل من تسرُّب البيانات المهمة المتعلقة بالخصوصية والذي يحدث في عمليات تأكيد الاتصال العادية من خلال بروتوكول أمان طبقة النقل (TLS).

يعتمد السلوك التلقائي لميزة "مرحبًا أيها العميل المشفر" على مستوى واجهة برمجة التطبيقات:

  • بدءًا من الإصدار 17 من نظام التشغيل Android (المستوى 37 من واجهة برمجة التطبيقات)، يتم استخدام ميزة ECH في الوضع "مفعَّلة" تلقائيًا. يمكن للتطبيقات إيقاف هذه الميزة أو تعديل سلوكها على مستوى العالم أو على أساس كل نطاق.
  • لا تتوفّر ميزة "التشفير الشامل" على الإصدار 16 من نظام التشغيل Android (المستوى 36 لواجهة برمجة التطبيقات) والإصدارات الأقدم.

إيقاف ميزة Encrypted Client Hello

يمكنك إيقاف الميزة في أي وقت. على سبيل المثال، إذا أردت إيقاف ECH عند إجراء اتصالات بموقع disable-ech.example.com فقط، مع إبقاء ECH مفعّلاً لجميع النطاقات الأخرى، يمكنك استخدام الإعداد التالي: 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <domainEncryption mode="enabled"/>
    </base-config>
    <domain-config>
        <domain includeSubdomains="true">disable-ech.example.com</domain>
        <domainEncryption mode="disabled"/>
    </domain-config>
</network-security-config>

البيانات غير المشفّرة

يمكن للمطوّرين تفعيل أو إيقاف حركة البيانات غير المشفرة (باستخدام بروتوكول HTTP غير المشفّر بدلاً من HTTPS) لتطبيقاتهم. يمكنك الاطّلاع على NetworkSecurityPolicy.isCleartextTrafficPermitted() لمزيد من التفاصيل.

يعتمد السلوك التلقائي لحركة بيانات النص العادي على مستوى واجهة برمجة التطبيقات:

  • حتى الإصدار 8.1 من نظام التشغيل Android (المستوى 27 من واجهة برمجة التطبيقات)، يتم تفعيل إمكانية استخدام النص العادي تلقائيًا. يمكن للتطبيقات إيقاف إرسال البيانات غير المشفّرة للحصول على أمان إضافي.
  • بدءًا من الإصدار 9 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات)، يتم إيقاف إمكانية استخدام النص العادي تلقائيًا. يمكن للتطبيقات التي تتطلّب بيانات غير مشفّرة الموافقة على البيانات غير المشفّرة.

إيقاف البيانات غير المشفّرة

ملاحظة: لا تنطبق الإرشادات الواردة في هذا القسم إلا على التطبيقات التي تستهدف الإصدار 8.1 من نظام التشغيل Android (المستوى 27 من واجهة برمجة التطبيقات) أو الإصدارات الأقدم.

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

على سبيل المثال، قد تريد أن يضمن تطبيقك إجراء عمليات الاتصال secure.example.com دائمًا عبر HTTPS لحماية حركة البيانات الحساسة من الشبكات المعادية. 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="false">
        <domain includeSubdomains="true">secure.example.com</domain>
    </domain-config>
</network-security-config>

الموافقة على البيانات غير المشفّرة

ملاحظة: لا تنطبق الإرشادات الواردة في هذا القسم إلا على التطبيقات التي تستهدف الإصدار 9 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) أو الإصدارات الأحدث.

إذا كان تطبيقك يحتاج إلى الاتصال بوجهات باستخدام زيارات غير مرمّزة (HTTP)، يمكنك الموافقة على إتاحة الزيارات غير المرمّزة إلى تلك الوجهات.

على سبيل المثال، قد تريد السماح لتطبيقك بإجراء اتصالات غير آمنة بـ insecure.example.com. 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">insecure.example.com</domain>
    </domain-config>
</network-security-config>

إذا كان تطبيقك بحاجة إلى تفعيل زيارات cleartext إلى أي نطاق، اضبط cleartextTrafficPermitted="true" في base-config. يُرجى العِلم أنّه يجب تجنُّب هذا الإعداد غير الآمن كلما أمكن ذلك. 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config cleartextTrafficPermitted="true">
    </base-config>
</network-security-config>

تثبيت الشهادات

في العادة، يثق التطبيق بجميع شهادات CA المثبَّتة مسبقًا. في حال أصدرت أي من هذه الجهات شهادة احتيالية، سيتعرّض التطبيق لخطر هجوم من وسيط. تختار بعض التطبيقات حصر مجموعة الشهادات التي تقبلها إما عن طريق حصر مجموعة شهادات CA التي تثق بها أو عن طريق تثبيت الشهادات.

يتم تثبيت الشهادة من خلال تقديم مجموعة من الشهادات حسب تجزئة المفتاح العام (SubjectPublicKeyInfo لشهادة X.509). بعد ذلك، لا تكون سلسلة الشهادات صالحة إلا إذا كانت تحتوي على مفتاح عام واحد على الأقل من المفاتيح العامة المثبّتة.

يُرجى العِلم أنّه عند استخدام تثبيت الشهادات، عليك دائمًا تضمين مفتاح احتياطي حتى لا يتأثر اتصال تطبيقك في حال اضطرارك إلى التبديل إلى مفاتيح جديدة أو تغيير هيئات إصدار الشهادات (عند التثبيت على شهادة CA أو شهادة وسيطة تابعة لهيئة إصدار الشهادات هذه). بخلاف ذلك، يجب إرسال تحديث للتطبيق لاستعادة الاتصال.

بالإضافة إلى ذلك، يمكن ضبط وقت انتهاء صلاحية رموز PIN، وبعدها لا يتم تثبيت الرموز. يساعد ذلك في تجنُّب مشاكل الاتصال في التطبيقات التي لم يتم تحديثها. ومع ذلك، قد يؤدي ضبط وقت انتهاء صلاحية لعمليات التثبيت إلى السماح للمهاجمين بتجاوز الشهادات المثبّتة.

يوضّح المقتطف أدناه كيفية تثبيت الشهادات في res/xml/network_security_config.xml: 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <pin-set expiration="2018-01-01">
            <pin digest="SHA-256">7HIpactkIAq2Y49orFOOQKurWxmmSFZhBCoQYcRhJ3Y=</pin>
            <!-- backup pin -->
            <pin digest="SHA-256">fwza0LRMXouZHRC8Ei+4PyuldPDcf3UKgO/04cDM1oE=</pin>
        </pin-set>
    </domain-config>
</network-security-config>

سلوك اكتساب الإعدادات

يتم اكتساب القيم التي لم يتم ضبطها في إعداد معيّن. يسمح هذا السلوك بإعدادات أكثر تعقيدًا مع الحفاظ على إمكانية قراءة ملف الإعدادات.

على سبيل المثال، يتم أخذ القيم غير المضبوطة في domain-config من العنصر الرئيسي domain-config، إذا كان متداخلاً، أو من base-config، إذا لم يكن متداخلاً. القيم التي لم يتم ضبطها في base-config تستخدم القيم التلقائية للنظام الأساسي.

على سبيل المثال، لنفترض أنّ جميع عمليات الربط بالنطاقات الفرعية من example.com يجب أن تستخدم مجموعة مخصّصة من مراجع التصديق. بالإضافة إلى ذلك، يُسمح بزيارات cleartext إلى هذه النطاقات باستثناء الاتصال بـ secure.example.com. من خلال تضمين إعدادات secure.example.com ضمن إعدادات example.com، لن تحتاج إلى تكرار trust-anchors.

يوضّح المقتطف أدناه كيف سيبدو هذا التداخل في res/xml/network_security_config.xml: 

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config>
        <domain includeSubdomains="true">example.com</domain>
        <trust-anchors>
            <certificates src="@raw/my_ca"/>
        </trust-anchors>
        <domain-config cleartextTrafficPermitted="false">
            <domain includeSubdomains="true">secure.example.com</domain>
        </domain-config>
    </domain-config>
</network-security-config>

إعدادات المضيف المحلي

بشكل عام، لا داعي لفرض ميزات أمان الشبكة على اتصالات localhost. على سبيل المثال، نادرًا ما تكون شهادة الشفافية مطلوبة لعمليات الربط بالمضيف المحلي.

بدءًا من الإصدار 17 من نظام التشغيل Android (المستوى 37 من واجهة برمجة التطبيقات) والإصدارات الأحدث، إذا لم يتم تحديد أي إعدادات لعنوان localhost، سيتم تضمين إعدادات ضمنية. بشكلٍ تلقائي، ينفّذ هذا الإعداد ما يلي:

  • تسمح هذه السمة بنقل البيانات غير المشفّرة.
  • لا يفرض "شهادة الشفافية" (CT).
  • لا يفرض تثبيت الشهادة.
  • يتم تفويض <base-config> للتعامل مع نقاط الارتكاز الموثوق بها.

يُعتبر الإعداد يستهدف المضيف المحلي إذا كان النطاق:

  • localhost
  • ip6-localhost أو
  • عنوان IP رقمي وInetAddress.isLoopback() هو true (على سبيل المثال، 127.0.0.1 أو [::1])

تنسيق ملف الإعداد

تستخدم ميزة "إعدادات أمان الشبكة" تنسيق ملف XML. يوضّح نموذج عينة التعليمات البرمجية التالي البنية العامة للملف:

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <base-config>
        <trust-anchors>
            <certificates src="..."/>
            ...
        </trust-anchors>
    </base-config>

    <domain-config>
        <domain>android.com</domain>
        ...
        <trust-anchors>
            <certificates src="..."/>
            ...
        </trust-anchors>
        <pin-set>
            <pin digest="...">...</pin>
            ...
        </pin-set>
    </domain-config>
    ...
    <debug-overrides>
        <trust-anchors>
            <certificates src="..."/>
            ...
        </trust-anchors>
    </debug-overrides>
</network-security-config>

توضّح الأقسام التالية البنية والتفاصيل الأخرى الخاصة بتنسيق الملف.

<network-security-config>

يمكن أن تحتوي على:
0 أو 1 من <base-config>
أي عدد من <domain-config>
0 أو 1 من <debug-overrides>

<base-config>

بنية الجملة:
<base-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</base-config>
يمكن أن تحتوي على:
<trust-anchors> <certificateTransparency> <domainEncryption>
description:
الإعدادات التلقائية المستخدَمة في جميع الاتصالات التي لا يغطيها domain-config.

تستخدِم أي قيم لم يتم ضبطها القيم التلقائية للمنصة.

في ما يلي الإعداد التلقائي للتطبيقات التي تستهدف الإصدار 9 من نظام التشغيل Android (المستوى 28 من واجهة برمجة التطبيقات) والإصدارات الأحدث: 

<base-config cleartextTrafficPermitted="false">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

يكون الإعداد التلقائي للتطبيقات التي تستهدف الإصدار 7.0 من نظام التشغيل Android (المستوى 24 لواجهة برمجة التطبيقات) إلى الإصدار 8.1 (المستوى 27 لواجهة برمجة التطبيقات) على النحو التالي: 

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
    </trust-anchors>
</base-config>

يكون الإعداد التلقائي للتطبيقات التي تستهدف الإصدار 6.0 من نظام التشغيل Android (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأقدم على النحو التالي: 

<base-config cleartextTrafficPermitted="true">
    <trust-anchors>
        <certificates src="system" />
        <certificates src="user" />
    </trust-anchors>
</base-config>

<domain-config>

بنية الجملة:
<domain-config cleartextTrafficPermitted=["true" | "false"]>
    ...
</domain-config>
يمكن أن تحتوي على:
<domain>
0 أو 1 <certificateTransparency>
0 أو 1 <trust-anchors>
0 أو 1 <pin-set>
0 أو 1 <domainEncryption>
أي عدد من العناصر المتداخلة <domain-config>
description:
الإعدادات المستخدَمة للاتصالات بمقاصد معيّنة، كما هو محدّد بواسطة عناصر domain

يُرجى العِلم أنّه إذا كانت عناصر domain-config متعددة تغطي وجهة معيّنة، سيتم استخدام الإعداد الذي يتضمّن قاعدة النطاق الأكثر تحديدًا (الأطول) المطابقة.

<domain>

بنية الجملة:
<domain includeSubdomains=["true" | "false"]>example.com</domain>
السمات:
includeSubdomains
إذا كانت القيمة "true"، يتطابق قاعدة النطاق هذه مع النطاق وجميع النطاقات الفرعية، بما في ذلك النطاقات الفرعية للنطاقات الفرعية. وفي ما عدا ذلك، لا تنطبق القاعدة إلا على التطابقات التامة.

<certificateTransparency>

بنية الجملة:
<certificateTransparency enabled=["true" | "false"]/>
description:
إذا كانت القيمة true، سيستخدم التطبيق سجلّات &quot;شهادة الشفافية&quot; للتحقّق من صحة الشهادات. عندما يستخدم تطبيق شهادته الخاصة (أو متجر المستخدم)، من المحتمل ألا تكون الشهادة عامة وبالتالي لا يمكن التحقّق منها باستخدام ميزة "شفافية الشهادات". ويتم إيقاف عملية التحقّق تلقائيًا في هذه الحالات. سيظل بإمكانك فرض عملية التحقّق باستخدام <certificateTransparency enabled="true"/> في إعدادات النطاق. بالنسبة إلى كل <domain-config>، يتم التقييم بالترتيب التالي:
  1. في حال تفعيل certificateTransparency، فعِّل عملية تأكيد الحساب.
  2. إذا كان أي <trust-anchors> هو "user" أو مضمّن (أي "@raw/cert.pem")، أوقِف عملية إثبات الهوية.
  3. بخلاف ذلك، استخدِم الإعدادات الموروثة.

<domainEncryption>

بنية الجملة:
<domainEncryption mode=["enabled" | "disabled"]/>
description:
يتحكّم هذا الإعداد في سلوك Encrypted Client Hello (ECH) للاتصالات بالنطاقات المحدّدة.

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

يمكن أن تكون السمة mode إحدى القيم التالية:

  • enabled: فرض استخدام ECH في اتصال عند توفير إعدادات ECH أثناء تأكيد الاتصال عبر TLS، وتفعيل ECH GREASE في الحالات الأخرى
  • ‫disabled: لا تحاول استخدام ECH أو ECH GREASE على أي اتصالات.

إذا لم يتم تحديدها، تكون القيمة التلقائية mode هي "enabled" للتطبيقات التي تستهدف المستوى 37 أو مستوى أحدث لواجهة برمجة التطبيقات، و"disabled" في الحالات الأخرى.

<debug-overrides>

بنية الجملة:
<debug-overrides>
    ...
</debug-overrides>
يمكن أن تحتوي على:
0 أو 1 <trust-anchors>
description:
يتم تطبيق عمليات الإلغاء عند ضبط قيمة android:debuggable على "true"، وهو ما يحدث عادةً في الإصدارات غير النهائية التي يتم إنشاؤها بواسطة بيئات التطوير المتكاملة وأدوات الإنشاء. تتم إضافة مراسي الثقة المحدّدة في debug-overrides إلى جميع الإعدادات الأخرى، ولا يتم تثبيت الشهادات عندما تستخدم سلسلة شهادات الخادم أحد مراسي الثقة هذه المخصّصة لتصحيح الأخطاء فقط. إذا كانت قيمة android:debuggable هي "false"، سيتم تجاهل هذا القسم بالكامل.

<trust-anchors>

بنية الجملة:
<trust-anchors>
...
</trust-anchors>
يمكن أن تحتوي على:
أي عدد من <certificates>
description:
مجموعة من نقاط الارتكاز الموثوقة للاتصالات الآمنة

<certificates>

بنية الجملة:
<certificates src=["system" | "user" | "raw resource"]
              overridePins=["true" | "false"] />
description:
مجموعة من شهادات X.509 لعناصر trust-anchors
السمات:
src
مصدر شهادات CA يمكن أن تكون كل شهادة مما يلي:
  • معرّف مورد أولي يشير إلى ملف يحتوي على شهادات X.509 يجب ترميز الشهادات بتنسيق DER أو PEM. في حال شهادات PEM، يجب ألا يحتوي الملف على بيانات إضافية غير PEM، مثل التعليقات.
  • ‫"system" لشهادات CA للنظام المثبَّتة مسبقًا
  • "user" لشهادات CA التي أضافها المستخدم
overridePins

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

القيمة التلقائية هي "false" ما لم يتم تحديدها في عنصر debug-overrides، وفي هذه الحالة تكون القيمة التلقائية هي "true".

<pin-set>

بنية الجملة:
<pin-set expiration="date">
...
</pin-set>
يمكن أن تحتوي على:
أي عدد من <pin>
description:
مجموعة من دبابيس المفتاح العام. لكي يكون الاتصال الآمن موثوقًا به، يجب أن يكون أحد المفاتيح العامة في سلسلة الثقة ضمن مجموعة رموز التثبيت. يمكنك الاطّلاع على <pin> لمعرفة تنسيق الدبابيس.
السمات:
expiration
يمثّل هذا الحقل التاريخ الذي تنتهي فيه صلاحية الرموز، وبالتالي يتم إيقاف إمكانية تثبيت الرموز، ويكون التنسيق yyyy-MM-dd. إذا لم يتم ضبط السمة، لن تنتهي صلاحية رموز التعريف الشخصي.

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

<pin>

بنية الجملة:
<pin digest=["SHA-256"]>base64 encoded digest of X.509
    SubjectPublicKeyInfo (SPKI)</pin>
السمات:
digest
تمثّل هذه السمة خوارزمية الملخّص المستخدَمة لإنشاء الرمز. لا تتوفّر حاليًا سوى القيمة "SHA-256".