Merge "Address pending comments for NetworkSecurityPolicy."

core/java/android/security/NetworkSecurityPolicy.java

@@ -19,48 +19,61 @@ package android.security;
 /**
  * Network security policy.
  *
+ * <p>Network stacks/components should honor this policy to make it possible to centrally control
+ * the relevant aspects of network security behavior.
+ *
+ * <p>The policy currently consists of a single flag: whether cleartext network traffic is
+ * permitted. See {@link #isCleartextTrafficPermitted()}.
+ *
  * @hide
  */
 public class NetworkSecurityPolicy {
 
-  private static final NetworkSecurityPolicy INSTANCE = new NetworkSecurityPolicy();
+    private static final NetworkSecurityPolicy INSTANCE = new NetworkSecurityPolicy();
 
-  private boolean mCleartextTrafficPermitted = true;
+    private volatile boolean mCleartextTrafficPermitted = true;
 
-  private NetworkSecurityPolicy() {}
+    private NetworkSecurityPolicy() {}
 
-  /**
-   * Gets the policy.
-   */
-  public static NetworkSecurityPolicy getInstance() {
-    return INSTANCE;
-  }
-
-  /**
-   * Checks whether cleartext network traffic (e.g., HTTP, WebSockets, XMPP, IMAP, SMTP -- without
-   * TLS or STARTTLS) is permitted for this process.
-   *
-   * <p>When cleartext network traffic is not permitted, the platform's components (e.g., HTTP
-   * stacks, {@code WebView}, {@code MediaPlayer}) will refuse this process's requests to use
-   * cleartext traffic. Third-party libraries are encouraged to honor this setting as well.
-   */
-  public boolean isCleartextTrafficPermitted() {
-    synchronized (this) {
-      return mCleartextTrafficPermitted;
+    /**
+     * Gets the policy for this process.
+     *
+     * <p>It's fine to cache this reference. Any changes to the policy will be immediately visible
+     * through the reference.
+     */
+    public static NetworkSecurityPolicy getInstance() {
+        return INSTANCE;
     }
-  }
 
-  /**
-   * Sets whether cleartext network traffic is permitted for this process.
-   *
-   * <p>This method is used by the platform early on in the application's initialization to set the
-   * policy.
-   *
-   * @hide
-   */
-  public void setCleartextTrafficPermitted(boolean permitted) {
-    synchronized (this) {
-      mCleartextTrafficPermitted = permitted;
+    /**
+     * Returns whether cleartext network traffic (e.g. HTTP, FTP, WebSockets, XMPP, IMAP, SMTP --
+     * without TLS or STARTTLS) is permitted for this process.
+     *
+     * <p>When cleartext network traffic is not permitted, the platform's components (e.g. HTTP and
+     * FTP stacks, {@code WebView}, {@code MediaPlayer}) will refuse this process's requests to use
+     * cleartext traffic. Third-party libraries are strongly encouraged to honor this setting as
+     * well.
+     *
+     * <p>This flag is honored on a best effort basis because it's impossible to prevent all
+     * cleartext traffic from Android applications given the level of access provided to them. For
+     * example, there's no expectation that the {@link java.net.Socket} API will honor this flag
+     * because it cannot determine whether its traffic is in cleartext. However, most network
+     * traffic from applications is handled by higher-level network stacks/components which can
+     * honor this aspect of the policy.
+     */
+    public boolean isCleartextTrafficPermitted() {
+        return mCleartextTrafficPermitted;
+    }
+
+    /**
+     * Sets whether cleartext network traffic is permitted for this process.
+     *
+     * <p>This method is used by the platform early on in the application's initialization to set
+     * the policy.
+     *
+     * @hide
+     */
+    public void setCleartextTrafficPermitted(boolean permitted) {
+        mCleartextTrafficPermitted = permitted;
     }
-  }
 }