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

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

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

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

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

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

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

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

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

تثق الاتصالات الآمنة (التي تستخدم بروتوكولات مثل بروتوكول أمان طبقة النقل (TLS) وHTTPS) من جميع التطبيقات تلقائيًا في شهادات هيئة إصدار الشهادات (CA) المثبَّتة مسبقًا على النظام، كما تثق التطبيقات التي تستهدف الإصدار 6.0 (المستوى 23 من واجهة برمجة التطبيقات) والإصدارات الأقدم تلقائيًا في متجر شهادات هيئة إصدار الشهادات (CA) التي أضافها المستخدم. يمكنك تخصيص عمليات ربط تطبيقك باستخدام 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>

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

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

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

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

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

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

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

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

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

على سبيل المثال، قد تريد السماح لتطبيقك بإجراء اتصالات 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 من واجهة برمجة التطبيقات) أو الإصدارات الأقدم.

إذا كنت تريد أن يتصل تطبيقك بالوجهات باستخدام اتصالات آمنة فقط، يمكنك إيقاف إتاحة زيارات cleartext إلى هذه الوجهات. يساعد هذا الخيار في منع حدوث تراجع غير مقصود في أداء التطبيقات بسبب التغييرات في عناوين 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>

إذا كان تطبيقك بحاجة إلى الموافقة على زيارات النص غير المرمّز إلى أي نطاق، اضبط 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" | "opportunistic" | "disabled"]/>

description:

يتحكّم هذا الإعداد في سلوك Encrypted Client Hello (ECH) في ما يتعلّق بالاتصالات بالنطاقات المحدّدة.

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

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

• enabled: فرض استخدام ECH في اتصال عند توفير إعدادات ECH أثناء تأكيد الاتصال عبر TLS، وتفعيل ECH GREASE في الحالات الأخرى
• ‫opportunistic: استخدام ECH في اتصال عند توفير إعدادات ECH أثناء تأكيد الاتصال من خلال بروتوكول أمان طبقة النقل في حال تعذُّر الاتصال أو عدم توفير الإعدادات، سيتم الرجوع إلى رسالة ClientHello عادية غير مشفّرة باستخدام بروتوكول أمان طبقة النقل. لا يفعِّل هذا الوضع إضافة GREASE في ECH.
• ‫disabled: لا تحاول استخدام ECH أو ECH GREASE على أي اتصالات.

إذا لم يتم تحديدها، تكون القيمة التلقائية mode هي "opportunistic".

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