java.net.UnknownServiceException: CLEARTEXT communication to (..) not permitted by network security policy

 

Retrofit2 라이브러리를 사용하여 서버와의 HTTP 통신을 구현하다 보면 아래와 같은 에러가 발생하는 경우가 있다. 

java.net.UnknownServiceException: CLEARTEXT communication to (..) not permitted by network security policy

Network Security Policy 즉, 네트워크 보안 정책과 관련된 이슈이다. 우선, 위의 에러가 발생하는 이유는 통신하려고 하는 대상의 주소가 http로 구성되어있기 때문이다. 또한, 현재 개발하고 있는 개발환경이 Android 9.0 (API Level 28, Pie) 이상인지 확인해보아야 한다. Android 9.0부터는 네트워크를 https로 사용하도록 강제하고 있다.

 

출처 : https://developers-kr.googleblog.com/2018/08/introducing-android-9-pie.html

 

아래 문서는 Google의 Android Developer Blog에서 소개하는 관련 사항에 대한 해결법이다.

https://android-developers.googleblog.com/2018/04/protecting-users-with-tls-by-default-in.html

 

1. 주소 변경

사용 중인 네트워크 주소를 https로 강제 변경하면 된다. 하지만, https로 구성되어있지 않는 경우에는 강제로 변경할 수 없다. 

 

---

2. 특정 주소 허용

접근하려고 하는 주소가 http로 구성되어도 접근할 수 있게 허용해주도록 설정할 수 있다.

아래와 같이 작성하여 추가한다.

 

res/xml/network_security_config.xml

<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true>TARGET_URL</domain>
    </domain-config>
</network-security-config>

 

Cleartext는 암호화되지 않았거나 암호화되어야 하는 전송된 혹은 저장된 정보를 뜻한다. 일반적으로 HTTP 프로토콜과 같은 Cleartext Network Traffic을 이용하여 서버와의 통신을 수행하는데, 도청이나 컨텐츠 변조와 같은 위험을 높이는 리스크가 존재한다. Third-Party에서 인가되지 않은 데이터를 주입시키거나 사용자 정보를 유출하는 것과 같다. 이는 개발자가 HTTPS 프로토콜과 같은 보안 프로토콜을 사용하는 이유이다.

---

3. 모든 주소 허용

최근에는 Glide 라이브러리를 사용하여 이미지를 로딩하던 도중 에러가 발생했었다. 해당 주소는 기본적으로 http로 구성되어있고 https도 지원이 되는 URL이였다. 위의 방법으로도 해결 가능하지만 이미지를 가져오는 경우 개발자가 임의로 조작할 수 없기 때문에 어쩔 수 없이 http 주소를 사용해야 하는 경우가 존재할 수 있다. 아래 코드는 모든 주소를 허용하도록 설정하는 코드이다.

 

res/xml/network_security_config.xml

<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
</network-security-config>

 

두 번째와 세 번째 해결 방법을 사용하면 Manifest에 해당 xml파일을 config파일로 지정해야 한다.

 

<application
    ...
    ...
    android:networkSecurityConfig="@xml/network_security_config" >

</application>

---

4.  Manifest 자체에서 clearTextTraffic 허용

가장 간단한 방법으로는 Manifest 파일에 속성 하나를 추가하는 것이다. 

 

<application
	...
    ...
    android:usesCleartextTraffic="true">
    
</application>

 

위의 속성은 Android 6.0부터 새로 추가된 속성으로 Android 9.0이전까지는 default value가 true였지만 Android 9.0부터는 https를 지원하기 때문에 false로 바뀌었었다. 이에 따라 http를 사용하기 위해서는 이 속성을 다시 true로 바꾸어야 한다.

 

References

https://stackoverflow.com/questions/45940861/android-8-cleartext-http-traffic-not-permitted

Android 8: Cleartext HTTP traffic not permitted

https://blog.naver.com/PostView.nhn?blogId=websearch&logNo=221679280143 

안드로이드 CLEARTEXT communication to x.x.x not permitted by network security policy 문제 해결 방법

https://medium.com/@son.rommer/fix-cleartext-traffic-error-in-android-9-pie-2f4e9e2235e6

Fix Cleartext Traffic Error in Android 9 Pie