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 android.compat.annotation.UnsupportedAppUsage;
20 
21 /**
22  * Network security policy for this process/application.
23  *
24  * <p>Network stacks/components are expected to honor this policy. Components which can use the
25  * Android framework API should be accessing this policy via the framework's
26  * {@code android.security.NetworkSecurityPolicy} instead of via this class.
27  *
28  * <p>The policy currently consists of a single flag: whether cleartext network traffic is
29  * permitted. See {@link #isCleartextTrafficPermitted()}.
30  *
31  * @hide
32  */
33 @libcore.api.CorePlatformApi
34 @libcore.api.IntraCoreApi
35 public abstract class NetworkSecurityPolicy {
36 
37     private static volatile NetworkSecurityPolicy instance = new DefaultNetworkSecurityPolicy();
38 
39     @libcore.api.CorePlatformApi
40     @libcore.api.IntraCoreApi
NetworkSecurityPolicy()41     public NetworkSecurityPolicy() {
42     }
43 
44     @libcore.api.CorePlatformApi
45     @libcore.api.IntraCoreApi
getInstance()46     public static NetworkSecurityPolicy getInstance() {
47         return instance;
48     }
49 
50     @libcore.api.CorePlatformApi
setInstance(NetworkSecurityPolicy policy)51     public static void setInstance(NetworkSecurityPolicy policy) {
52         if (policy == null) {
53             throw new NullPointerException("policy == null");
54         }
55         instance = policy;
56     }
57 
58     /**
59      * Returns {@code true} if cleartext network traffic (e.g. HTTP, FTP, XMPP, IMAP, SMTP --
60      * without TLS or STARTTLS) is permitted for all network communications of this process.
61      *
62      * <p>{@link #isCleartextTrafficPermitted(String)} should be used to determine if cleartext
63      * traffic is permitted for a specific host.
64      *
65      * <p>When cleartext network traffic is not permitted, the platform's components (e.g. HTTP
66      * stacks, {@code WebView}, {@code MediaPlayer}) will refuse this process's requests to use
67      * cleartext traffic. Third-party libraries are encouraged to do the same.
68      *
69      * <p>This flag is honored on a best effort basis because it's impossible to prevent all
70      * cleartext traffic from an application given the level of access provided to applications on
71      * Android. For example, there's no expectation that {@link java.net.Socket} API will honor this
72      * flag. Luckily, most network traffic from apps is handled by higher-level network stacks which
73      * can be made to honor this flag. Platform-provided network stacks (e.g. HTTP and FTP) honor
74      * this flag from day one, and well-established third-party network stacks will eventually
75      * honor it.
76      */
77     @UnsupportedAppUsage
78     @libcore.api.CorePlatformApi
isCleartextTrafficPermitted()79     public abstract boolean isCleartextTrafficPermitted();
80 
81     /**
82      * Returns {@code true} if cleartext network traffic (e.g. HTTP, FTP, XMPP, IMAP, SMTP --
83      * without TLS or STARTTLS) is permitted for communicating with {@code hostname} for this
84      * process.
85      *
86      * <p>See {@link #isCleartextTrafficPermitted} for more details.
87      */
88     @libcore.api.CorePlatformApi
isCleartextTrafficPermitted(String hostname)89     public abstract boolean isCleartextTrafficPermitted(String hostname);
90 
91     /**
92      * Returns {@code true} if Certificate Transparency information is required to be presented by
93      * the server and verified by the client in TLS connections to {@code hostname}.
94      *
95      * <p>See RFC6962 section 3.3 for more details.
96      */
97     @libcore.api.CorePlatformApi
98     @libcore.api.IntraCoreApi
isCertificateTransparencyVerificationRequired(String hostname)99     public abstract boolean isCertificateTransparencyVerificationRequired(String hostname);
100 
101     public static final class DefaultNetworkSecurityPolicy extends NetworkSecurityPolicy {
102         @Override
isCleartextTrafficPermitted()103         public boolean isCleartextTrafficPermitted() {
104             return true;
105         }
106 
107         @Override
isCleartextTrafficPermitted(String hostname)108         public boolean isCleartextTrafficPermitted(String hostname) {
109             return isCleartextTrafficPermitted();
110         }
111 
112         @Override
isCertificateTransparencyVerificationRequired(String hostname)113         public boolean isCertificateTransparencyVerificationRequired(String hostname) {
114             return false;
115         }
116     }
117 }
118