Update to follow style guide
[docs.git] / docs / getting-started-guide / security_considerations.rst
1 ***********************
2 Security Considerations
3 ***********************
4
5 This document discusses the various security issues that might affect
6 OpenDaylight. The document also lists specific recommendations to
7 mitigate security risks.
8
9 This document also contains information about the corrective steps
10 you can take if you discover a security issue with
11 OpenDaylight, and if necessary, contact the Security Response Team,
12 which is tasked with identifying and resolving security threats.
13
14 Overview of OpenDaylight Security
15 =================================
16
17 There are many different kinds of security vulnerabilities that could affect
18 an OpenDaylight deployment, but this guide focuses on those where (a) the
19 servers, virtual machines or other devices running OpenDaylight have been
20 properly physically (or virtually in the case of VMs) secured against untrusted
21 individuals and (b) individuals who have access, either via remote logins or
22 physically, will not attempt to attack or subvert the deployment intentionally
23 or otherwise.
24
25 While those attack vectors are real, they are out of the scope of this
26 document.
27
28 What remains in scope is attacks launched from a server, virtual machine, or
29 device other than the one running OpenDaylight where the attack does not have
30 valid credentials to access the OpenDaylight deployment.
31
32 The rest of this document gives specific recommendations for deploying
33 OpenDaylight in a secure manner, but first we highlight some high-level
34 security advantages of OpenDaylight.
35
36 * Separating the control and management planes from the data plane (both
37   logically and, in many cases, physically) allows possible security threats to
38   be forced into a smaller attack surface.
39
40 * Having centralized information and network control gives network
41   administrators more visibility and control over the entire network, enabling
42   them to make better decisions faster. At the same time,
43   centralization of network control can be an advantage only if access to that
44   control is secure.
45
46   .. note:: While both previous advantages improve security, they also make
47             an OpenDaylight deployment an attractive target for attack making
48             understanding these security considerations even more important.
49
50 * The ability to more rapidly evolve southbound protocols and how they are used
51   provides more and faster mechanisms to enact appropriate security mitigations
52   and remediations.
53
54 * OpenDaylight is built from OSGi bundles and the Karaf Java container. Both
55   Karaf and OSGi provide some level of isolation with explicit code boundaries,
56   package imports, package exports, and other security-related features.
57
58 * OpenDaylight has a history of rapidly addressing known vulnerabilities and
59   a well-defined process for reporting and dealing with them.
60
61 OpenDaylight Security Resources
62 ===============================
63
64 * If you have any security issues, you can send a mail to
65   *security@lists.opendaylight.org*.
66
67 * For the list of current OpenDaylight security issues that are either being
68   fixed or resolved, refer to
69   https://wiki.opendaylight.org/view/Security_Advisories.
70
71 * To learn more about the OpenDaylight security issues policies and procedure,
72   refer to https://wiki.opendaylight.org/view/Security:Main
73
74 Deployment Recommendations
75 ==========================
76
77 We recommend that you follow the deployment guidelines in setting up
78 OpenDaylight to minimize security threats.
79
80 * The default credentials should be changed before deploying OpenDaylight.
81
82 * OpenDaylight should be deployed in a private network that cannot be accessed
83   from the internet.
84
85 * Separate the data network (that connects devices using the network) from the
86   management network (that connects the network devices to OpenDaylight).
87
88   .. note:: Deploying OpenDaylight on a separate, private management network does not
89             eliminate threats, but only mitigates them. By construction, some
90             messages must flow from the data network to the management network, e.g.,
91             OpenFlow *packet_in* messages, and these create an attack surface even if
92             it is a small one.
93
94 * Implement an authentication policy for devices that connect to both the data
95   and management network. These are the devices which bridge, likely untrusted,
96   traffic from the data network to the management network.
97
98 Securing OSGi bundles
99 =====================
100
101 OSGi is a Java-specific framework that improves the way that Java classes
102 interact within a single JVM. It provides an enhanced version of the
103 *java.lang.SecurityManager* (ConditionalPermissionAdmin) in terms of security.
104
105 Java provides a security framework that allows a security policy to grant
106 permissions, such as reading a file or opening a network connection, to
107 specific code. The code maybe classes from the jarfile loaded from a specific
108 URL, or a class signed by a specific key. OSGi builds on the standard Java
109 security model to add the following features:
110
111 * A set of OSGi-specific permission types, such as one that grants the right
112   to register an OSGi service or get an OSGi service from the service registry.
113
114 * The ability to dynamically modify permissions at runtime. This includes the
115   ability to specify permissions by using code rather than a text configuration
116   file.
117
118 * A flexible predicate-based approach to determining which rules are
119   applicable to which *ProtectionDomain*. This approach is much more powerful
120   than the standard Java security policy which can only grant rights based on a
121   jarfile URL or class signature. A few standard predicates are provided,
122   including selecting rules based upon bundle symbolic-name.
123
124 * Support for bundle *local permissions* policies with optional further
125   constraints such as *DENY* operations. Most of this functionality is accessed
126   by using the *OSGi ConditionalPermissionAdmin* service which is part of the
127   OSGi core and can be obtained from the OSGi service registry. The
128   *ConditionalPermissionAdmin* API replaces the earlier *PermissionAdmin* API.
129
130 For more information, refer to http://www.osgi.org/Main/HomePage.
131
132 Securing the Karaf container
133 ============================
134
135 Apache Karaf is a OSGi-based runtime platform which provides a lightweight
136 container for OpenDaylight and applications. Apache Karaf uses
137 either Apache Felix Framework or Eclipse Equinox OSGi frameworks, and provide
138 additional features on top of the framework.
139
140 Apache Karaf provides a security framework based on Java Authentication and
141 Authorization Service (JAAS) in compliance with OSGi recommendations,
142 while providing RBAC (Role-Based Access Control) mechanism for the console and
143 Java Management Extensions (JMX).
144
145 The Apache Karaf security framework is used internally to control the access
146 to the following components:
147
148 * OSGi services
149
150 * console commands
151
152 * JMX layer
153
154 * WebConsole
155
156 The remote management capabilities are present in Apache Karaf by default,
157 however they can be disabled by using various configuration alterations. These
158 configuration options may be applied to the OpenDaylight Karaf distribution.
159
160 .. note:: Refer to the following list of publications for more information on
161           implementing security for the Karaf container.
162
163 * For role-based JMX administration, refer to
164   http://karaf.apache.org/manual/latest/users-guide/monitoring.html.
165
166 * For remote SSH access configuration, refer to
167   http://karaf.apache.org/manual/latest/users-guide/remote.html.
168
169 * For WebConsole access, refer to
170   http://karaf.apache.org/manual/latest/users-guide/webconsole.html.
171
172 * For Karaf security features, refer to
173   http://karaf.apache.org/manual/latest/developers-guide/security-framework.html.
174
175 Disabling the remote shutdown port
176 ----------------------------------
177
178 You can lock down your deployment post installation. Set
179 ``karaf.shutdown.port=-1`` in ``etc/custom.properties`` or ``etc/config.properties`` to
180 disable the remote shutdown port.
181
182 Securing Southbound Plugins
183 ===========================
184
185 Many individual southbound plugins provide mechanisms to secure their
186 communication with network devices. For example, the OpenFlow plugin supports
187 TLS connections with bi-directional authentication and the NETCONF plugin
188 supports connecting over SSH. Meanwhile, the Unified Secure Channel plugin
189 provides a way to form secure, remote connections for supported devices.
190
191 When deploying OpenDaylight, you should carefully investigate the secure
192 mechanisms to connect to devices using the relevant plugins.
193
194 Securing OpenDaylight using AAA
195 ===============================
196
197 AAA stands for Authentication, Authorization, and Accounting. All three of
198 can help improve the security posture of and OpenDaylight deployment. In this
199 release, only authentication is fully supported, while authorization is an
200 experimental feature and accounting remains a work in progress.
201
202 The vast majority of OpenDaylight's northbound APIs (and all RESTCONF APIs) are
203 protected by AAA by default when installing the +odl-restconf+ feature. In the
204 cases that APIs are *not* protected by AAA, this will be noted in the
205 per-project release notes.
206
207 By default, OpenDaylight has only one user account with the username and
208 password *admin*. This should be changed before deploying OpenDaylight.
209
210 Security Considerations for Clustering
211 ======================================
212
213 While OpenDaylight clustering provides many benefits including high
214 availability, scale-out performance, and data durability, it also opens a new
215 attack surface in the form of the messages exchanged between the various
216 instances of OpenDaylight in the cluster. In the current OpenDaylight release,
217 these messages are neither encrypted nor authenticated meaning that anyone with
218 access to the management network where OpenDaylight exchanges these clustering
219 messages can forge and/or read the messages. This means that if clustering is
220 enabled, it is even more important that the management network be kept secure
221 from any untrusted entities.