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