1 /*
2  * Copyright (C) 2015 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package libcore.net;
18 
19 import static android.annotation.SystemApi.Client.MODULE_LIBRARIES;
20 
21 import android.annotation.SystemApi;
22 import android.compat.annotation.UnsupportedAppUsage;
23 
24 /**
25  * Network security policy for this process/application.
26  *
27  * <p>Network stacks/components are expected to honor this policy. Components which can use the
28  * Android framework API should be accessing this policy via the framework's
29  * {@code android.security.NetworkSecurityPolicy} instead of via this class.
30  *
31  * <p>The policy can be determined by the {@link #isCleartextTrafficPermitted()},
32  * {@link #isCleartextTrafficPermitted(String)} and
33  * {@link #isCertificateTransparencyVerificationRequired(String)} methods.
34  *
35  * @hide
36  */
37 @SystemApi(client = MODULE_LIBRARIES)
38 @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
39 @libcore.api.IntraCoreApi
40 public abstract class NetworkSecurityPolicy {
41 
42     private static volatile NetworkSecurityPolicy instance = new DefaultNetworkSecurityPolicy();
43 
44     /**
45      * Constructs a default {@code NetworkSecurityPolicy}.
46      *
47      * @see {@link #DefaultNetworkSecurityPolicy}.
48      *
49      * @hide
50      */
51     @SystemApi(client = MODULE_LIBRARIES)
52     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
53     @libcore.api.IntraCoreApi
NetworkSecurityPolicy()54     public NetworkSecurityPolicy() {
55     }
56 
57     /**
58      * Gets current singleton {@code NetworkSecurityPolicy} instance.
59      *
60      * @return the current {@code NetworkSecurityPolicy}.
61      *
62      * @hide
63      */
64     @SystemApi(client = MODULE_LIBRARIES)
65     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
66     @libcore.api.IntraCoreApi
getInstance()67     public static NetworkSecurityPolicy getInstance() {
68         return instance;
69     }
70 
71     /**
72      * Sets current singleton instance
73      *
74      * @param policy new {@code NetworlSecurityPolicy} instance.
75      *
76      * @hide
77      */
78     @SystemApi(client = MODULE_LIBRARIES)
79     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
setInstance(NetworkSecurityPolicy policy)80     public static void setInstance(NetworkSecurityPolicy policy) {
81         if (policy == null) {
82             throw new NullPointerException("policy == null");
83         }
84         instance = policy;
85     }
86 
87     /**
88      * Returns {@code true} if cleartext network traffic (e.g. HTTP, FTP, XMPP, IMAP, SMTP --
89      * without TLS or STARTTLS) is permitted for all network communications of this process.
90      *
91      * <p>{@link #isCleartextTrafficPermitted(String)} should be used to determine if cleartext
92      * traffic is permitted for a specific host.
93      *
94      * <p>When cleartext network traffic is not permitted, the platform's components (e.g. HTTP
95      * stacks, {@code WebView}, {@code MediaPlayer}) will refuse this process's requests to use
96      * cleartext traffic. Third-party libraries are encouraged to do the same.
97      *
98      * <p>This flag is honored on a best effort basis because it's impossible to prevent all
99      * cleartext traffic from an application given the level of access provided to applications on
100      * Android. For example, there's no expectation that {@link java.net.Socket} API will honor this
101      * flag. Luckily, most network traffic from apps is handled by higher-level network stacks which
102      * can be made to honor this flag. Platform-provided network stacks (e.g. HTTP and FTP) honor
103      * this flag from day one, and well-established third-party network stacks will eventually
104      * honor it.
105      *
106      * @return {@code true} if cleartext traffic is permitted and {@code false} otherwise.
107      *
108      * @hide
109      */
110     @UnsupportedAppUsage
111     @SystemApi(client = MODULE_LIBRARIES)
112     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
isCleartextTrafficPermitted()113     public abstract boolean isCleartextTrafficPermitted();
114 
115     /**
116      * Returns {@code true} if cleartext network traffic (e.g. HTTP, FTP, XMPP, IMAP, SMTP --
117      * without TLS or STARTTLS) is permitted for communicating with {@code hostname} for this
118      * process.
119      *
120      * <p>See {@link #isCleartextTrafficPermitted} for more details.
121      *
122      * @param hostname hostname to check if cleartext traffic is permitted for
123      * @return {@code true} if cleartext traffic is permitted and {@code false} otherwise
124      *
125      * @hide
126      */
127     @SystemApi(client = MODULE_LIBRARIES)
128     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
isCleartextTrafficPermitted(String hostname)129     public abstract boolean isCleartextTrafficPermitted(String hostname);
130 
131     /**
132      * Returns {@code true} if Certificate Transparency information is required to be presented by
133      * the server and verified by the client in TLS connections to {@code hostname}.
134      *
135      * <p>See RFC6962 section 3.3 for more details.
136      *
137      * @param hostname hostname to check whether certificate transparency verification
138      *                 is required
139      * @return {@code true} if certificate transparency verification is required and
140      *         {@code false} otherwise
141      *
142      * @hide
143      */
144     @SystemApi(client = MODULE_LIBRARIES)
145     @libcore.api.CorePlatformApi(status = libcore.api.CorePlatformApi.Status.STABLE)
146     @libcore.api.IntraCoreApi
isCertificateTransparencyVerificationRequired(String hostname)147     public abstract boolean isCertificateTransparencyVerificationRequired(String hostname);
148 
149     /**
150      * Default network security policy that allows cleartext traffic and does not require
151      * certificate transparency verification.
152      *
153      * @hide
154      */
155     public static final class DefaultNetworkSecurityPolicy extends NetworkSecurityPolicy {
156         @Override
isCleartextTrafficPermitted()157         public boolean isCleartextTrafficPermitted() {
158             return true;
159         }
160 
161         @Override
isCleartextTrafficPermitted(String hostname)162         public boolean isCleartextTrafficPermitted(String hostname) {
163             return isCleartextTrafficPermitted();
164         }
165 
166         @Override
isCertificateTransparencyVerificationRequired(String hostname)167         public boolean isCertificateTransparencyVerificationRequired(String hostname) {
168             return false;
169         }
170     }
171 }
172