네트워크 보안 구성

네트워크 보안 구성 기능을 사용하면 앱 코드를 수정하지 않고도 안전한 선언적 구성 파일에서 앱의 네트워크 보안 설정을 맞춤설정할 수 있습니다. 이러한 설정은 특정 도메인 및 특정 앱용으로 구성할 수 있습니다. 이 기능의 핵심 요소는 다음과 같습니다.

  • 맞춤 신뢰 앵커: 앱의 보안 연결을 위해 신뢰할 수 있는 인증 기관(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 인증서를 사용하는 호스트 또는 신뢰할 수 있는 비공개 CA(예: 사내 CA)에서 발급한 SSL 인증서를 사용하는 호스트에 연결해야 할 수 있습니다. 다음 코드 발췌 부분은 res/xml/network_security_config.xml에서 맞춤 CA에 맞게 앱을 구성하는 방법을 보여줍니다.

<?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에 추가합니다.

신뢰할 수 있는 CA 세트 제한

앱이 시스템에서 신뢰하는 모든 CA를 신뢰하지 않도록 하려면 대신 신뢰할 수 있는 CA 세트를 줄여서 지정할 수 있습니다. 이 방법은 다른 CA에서 발급된 허위 인증서로부터 앱을 보호해줍니다.

신뢰할 수 있는 CA 세트를 제한하는 구성은 특정 도메인에서 맞춤 CA를 신뢰하는 것과 비슷하지만 여러 CA가 리소스에서 제공된다는 점이 다릅니다. 다음 코드 발췌 부분은 res/xml/network_security_config.xml에서 앱의 신뢰할 수 있는 CA 세트를 제한하는 방법을 보여줍니다.

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

신뢰할 수 있는 CA를 PEM 또는 DER 형식으로 res/raw/trusted_roots에 추가합니다. PEM 형식을 사용하는 경우 파일에는 PEM 데이터 포함하고 다른 추가 텍스트를 포함해서는 안 됩니다. 하나가 아닌 여러 <certificates> 요소를 제공할 수도 있습니다.

신뢰하는 CA 추가

시스템에 의해 아직 CA가 포함되지 않았거나 CA가 Android 시스템에 포함되기 위한 요구사항을 충족하지 않는 경우와 같이 시스템에서 신뢰하지 않는 추가 CA를 앱에서 신뢰하도록 할 수 있습니다. 다음 발췌 내용과 같은 코드를 사용하여 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:debuggabletrue일 때 신뢰할 수 있는 디버그 전용 CA를 지정하면 됩니다. 일반적으로 IDE 및 빌드 도구는 비출시 빌드에 이 플래그를 자동으로 설정합니다.

보안 예방 조치로 앱 스토어에서 디버그 가능으로 표시된 앱은 허용하지 않기 때문에 일반적인 조건 코드보다 안전합니다.

아래 발췌 부분은 res/xml/network_security_config.xml에서 디버그 전용 CA를 지정하는 방법을 보여줍니다.

<?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 8.1(API 수준 27) 이하를 타겟팅하는 앱에만 적용됩니다. Android 9(API 수준 28)부터는 일반 텍스트 지원이 기본적으로 사용되지 않습니다.

앱이 보안 연결만 사용하여 대상에 연결하도록 하려면 이러한 대상에 대한 일반 텍스트 지원을 선택 해제하면 됩니다(HTTPS 대신 암호화되지 않은 HTTP 프로토콜 사용). 이 옵션은 백엔드 서버 등의 외부 소스가 제공하는 URL의 변경사항으로 인해 앱에서 우연히 회귀가 일어나는 일을 방지합니다. 자세한 내용은 NetworkSecurityPolicy.isCleartextTrafficPermitted()를 참고하세요.

예를 들어 민감한 트래픽을 적대적인 네트워크로부터 보호하기 위해 앱에서 항상 HTTPS를 통해 secure.example.com에 연결하도록 할 수 있습니다.

아래 발췌 부분은 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의 중간 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에 연결할 때를 제외하고 허용됩니다. 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>

구성 파일 형식

네트워크 보안 구성 기능은 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 9(API 수준 28) 이상을 타겟팅하는 앱의 기본 구성은 다음과 같습니다.

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

Android 7.0(API 수준 24)부터 Android 8.1(API 수준 27) 이상을 타겟팅하는 앱의 기본 구성은 다음과 같습니다.

<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를 디버깅하거나 앱의 보안 트래픽에 중간자 공격을 테스트하는 데 유용할 수 있습니다.

debug-overrides 요소에서 지정되지 않으면 기본값은 "false"이고 지정되면 기본값은 "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"만 지원됩니다.

추가 리소스

네트워크 보안 구성에 관한 자세한 내용은 다음 리소스를 참고하세요.

Codelab