docs/getting-started-guide/security_considerations.rst

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