[[198282]]

網絡安全性配置特性讓應用可以在一個安全的聲明性配置文件中自定義其網絡安全設置，而無需修改應用代碼。可以針對特定域和特定應用配置這些設置。此特性的主要功能如下所示：

• 自定義信任錨：針對應用的安全連接自定義哪些證書頒發機構 (CA) 值得信任。例如，信任特定的自簽署證書或限制應用信任的公共 CA 集。
• 僅調試重寫：在應用中以安全方式調試安全連接，而不會增加已安裝用戶的風險。
• 明文通信選擇退出：防止應用意外使用明文通信。
• 證書固定：將應用的安全連接限制為特定的證書。

添加安全配置文件

網絡安全性配置特性使用一個 XML 文件，您可以在該文件中指定應用的設置。您必須在應用的清單中包含一個條目以指向該文件。以下代碼摘自一份清單，演示了如何創建此條目：

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

自定義可信 CA

應用可能需要信任自定義的 CA 集，而不是平臺默認值。出現此情況的最常見原因包括：

• 連接到具有自定義證書頒發機構的主機，如自簽署或在公司內部簽發的 CA。
• 將 CA 集僅限于您信任的 CA，而不是每個預裝 CA。
• 信任系統中未包含的附加 CA。

默認情況下，來自所有應用的安全連接(使用 TLS 和 HTTPS 之類的協議)均信任預裝的系統 CA，而面向 Android 6.0(API 級別 23)及更低版本的應用默認情況下還會信任用戶添加的 CA 存儲。應用可以使用 base-config(應用范圍的自定義)或 domain-config(按域自定義)自定義自己的連接。

配置自定義 CA

假設您要連接到使用自簽署 SSL 證書的主機，或者連接到其 SSL 證書是由您信任的非公共 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>  

以 PEM 或 DER 格式將自簽署或非公共 CA 證書添加到 res/raw/my_ca。

限制可信 CA 集

如果應用不想信任系統信任的所有 CA，則可以自行指定，縮減要信任的 CA 集。這樣可以防止應用信任任何其他 CA 簽發的欺詐性證書。

限制可信 CA 集的配置與針對特定域信任自定義 CA 相似，不同的是，前者要在資源中提供多個 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 格式將可信 CA 添加到 res/raw/trusted_roots。請注意，如果使用 PEM 格式，文件必須僅包含 PEM 數據，且沒有額外的文本。您還可以提供多個 <certificates> 元素，而不是只提供一個元素。

信任附加 CA

應用可能需要信任系統不信任的附加 CA，出現此情況的原因可能是系統還未包含此 CA，或 CA 不符合添加到 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 證書的本地開發服務器。為了支持此操作，而又不對應用的代碼進行任何修改，您可以通過使用 debug-overrides 指定僅在 android:debuggable 為 true 時才可信的僅調試 CA。通常，IDE 和構建工具會自動為非發布版本設置此標記。

這比一般的條件代碼更安全，因為出于安全考慮，應用存儲不接受被標記為可調試的應用。

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>  

選擇退出明文通信

旨在連接到僅使用安全連接的目的地的應用可以選擇不再對這些目的地提供明文(使用解密的 HTTP 協議而非 HTTPS)支持。此選項有助于防止應用因外部源(如后端服務器)提供的網址發生變化而意外回歸。請參閱 NetworkSecurityPolicy.isCleartextTrafficPermitted()，了解更多詳情。

例如，應用可能需要確保與 secure.example.com 的所有連接始終通過 HTTPS 完成，以防止來自惡意網絡的敏感流量。

res/xml/network_security_config.xml：

<?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>  

固定證書

一般情況下，應用信任所有預裝 CA。如果有預裝 CA 簽發欺詐性證書，則應用將面臨被中間人攻擊的風險。有些應用通過限制信任的 CA 集或通過證書固定來選擇限制其接受的證書集。

通過按公鑰的哈希值(X.509 證書的 SubjectPublicKeyInfo)提供證書集完成證書固定。然后，只有至少包含一個已固定的公鑰時，證書鏈才有效。

請注意，使用證書固定時，您應始終包含一個備份密鑰，這樣，當您被強制切換到新密鑰或更改 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> 
        <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 的子域的所有連接都必須使用自定義 CA 集。此外，允許使用這些域的明文通信，連接到 secure.example.com 時除外。通過在 example.com 的配置中嵌套 secure.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>  

配置文件格式

網絡安全性配置特性使用 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>

• 說明：

目的地不在 domain-config 涵蓋范圍內的所有連接所使用的默認配置。未設置的任何值均使用平臺默認值。面向 Android 7.0(API 級別 24)及更高版本應用的默認配置如下所示：

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

面向 Android 6.0(API 級別 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>  

• 可以包含：
  • 1 個或多個 <domain>
  • 0 或 1 個 <trust-anchors>
  • 0 或 1 個 <pin-set>
• 任意數量的已嵌套 <domain-config>
• 說明

用于按照 domain 元素的定義連接到特定目的地的配置。請注意，如果有多個 domain-config 元素涵蓋某個目的地，將使用匹配域規則最具體(最長)的配置。

<domain>

• 語法：

<domain includeSubdomains=["true" | "false"]>example.com</domain> 

• 屬性：
  • includeSubdomains
  • 如果為 "true"，此域規則將與域及所有子域(包括子域的子域)匹配。否則，該規則僅適用于精確匹配項。
• 說明：

<debug-overrides>

• 語法：

<debug-overrides> 
 
... 
 
</debug-overrides>  

• 可以包含：
  • 0 或 1 個 <trust-anchors>
• 說明：

在 android:debuggable 為 "true" 時將應用的重寫，IDE 和構建工具生成的非發布版本通常屬于此情況。在 debug-overrides 中指定的信任錨將添加到所有其他配置，并且當服務器的證書鏈使用其中一個僅調試信任錨時，將不執行證書固定。如果 android:debuggable 為 "false"，將完全忽略此部分。

<trust-anchors>

• 語法：

<trust-anchors> 
 
... 
 
</trust-anchors>  

• 可以包含：

任意數量的 <certificates>

• 說明：

用于安全連接的信任錨集。

<certificates>

• 語法：

<certificates src=["system" | "user" | "raw resource"] 
 
overridePins=["true" | "false"] />  

• 說明：

用于 trust-anchors 元素的 X.509 證書集。

• 屬性：
  • src
  • CA 證書的來源。每個證書可為下列狀態之一：
    • 指向包含 X.509 證書的文件的原始資源 ID。證書必須以 DER 或 PEM 格式編碼。如果為 PEM 證書，則文件不得包含額外的非 PEM 數據，例如注釋。
    • 用于預裝系統 CA 證書的 "system"
    • 用于用戶添加的 CA 證書的 "user"
  • overridePins
  • 指定此來源的 CA 是否繞過證書固定。如果為 "true"，則不對此來源的 CA 簽署的證書鏈執行證書固定。這對于調試 CA 或測試對應用的安全流量進行中間人攻擊 (MiTM) 非常有用。默認值為 "false"，除非在 debug-overrides 元素中另外指定(在這種情況下，默認值為 "true")。

<pin-set>

• 語法：

<pin-set expiration="date"> 
 
... 
 
</pin-set>  

• 可以包含：

任意數量的 <pin>

• 說明：

一組公鑰固定。對于要信任的安全連接，信任鏈中必須有一個公鑰位于固定集中。有關固定格式，請參閱 <pin>。

• 屬性：
  • expiration
  • 采用 yyyy-MM-dd 格式的日期，固定在該日期過期，因而將停用固定。如果未設置該屬性，則固定不會過期。設置到期時間有助于防止未更新到其固定集(例如，在用戶停用應用更新時)的應用出現連接問題。

<pin>

• 語法：

<pin digest=["SHA-256"]>base64 encoded digest of X.509 
 
SubjectPublicKeyInfo (SPKI)</pin>  

• 屬性：
  • digest
  • 用于生成固定的摘要算法。目前僅支持 "SHA-256"。