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