docs/getting-started-guide/security_considerations.rst

   1 .. _security_considerations:
   2
   3 ***********************
   4 Security Considerations
   5 ***********************
   6
   7 This document discusses the various security issues that might affect
   8 OpenDaylight. The document also lists specific recommendations to
   9 mitigate security risks.
  10
  11 This document also contains information about the corrective steps
  12 you can take if you discover a security issue with
  13 OpenDaylight, and if necessary, contact the Security Response Team,
  14 which is tasked with identifying and resolving security threats.
  15
  16 Overview of OpenDaylight Security
  17 =================================
  18
  19 There are many different kinds of security vulnerabilities that could affect
  20 an OpenDaylight deployment, but this guide focuses on those where (a) the
  21 servers, virtual machines or other devices running OpenDaylight have been
  22 properly physically (or virtually in the case of VMs) secured against untrusted
  23 individuals and (b) individuals who have access, either via remote logins or
  24 physically, will not attempt to attack or subvert the deployment intentionally
  25 or otherwise.
  26
  27 While those attack vectors are real, they are out of the scope of this
  28 document.
  29
  30 What remains in scope is attacks launched from a server, virtual machine, or
  31 device other than the one running OpenDaylight where the attack does not have
  32 valid credentials to access the OpenDaylight deployment.
  33
  34 The rest of this document gives specific recommendations for deploying
  35 OpenDaylight in a secure manner, but first we highlight some high-level
  36 security advantages of OpenDaylight.
  37
  38 * Separating the control and management planes from the data plane (both
  39   logically and, in many cases, physically) allows possible security threats to
  40   be forced into a smaller attack surface.
  41
  42 * Having centralized information and network control gives network
  43   administrators more visibility and control over the entire network, enabling
  44   them to make better decisions faster. At the same time,
  45   centralization of network control can be an advantage only if access to that
  46   control is secure.
  47
  48   .. note:: While both previous advantages improve security, they also make
  49             an OpenDaylight deployment an attractive target for attack making
  50             understanding these security considerations even more important.
  51
  52 * The ability to more rapidly evolve southbound protocols and how they are used
  53   provides more and faster mechanisms to enact appropriate security mitigations
  54   and remediations.
  55
  56 * OpenDaylight is built from OSGi bundles and the Karaf Java container. Both
  57   Karaf and OSGi provide some level of isolation with explicit code boundaries,
  58   package imports, package exports, and other security-related features.
  59
  60 * OpenDaylight has a history of rapidly addressing known vulnerabilities and
  61   a well-defined process for reporting and dealing with them.
  62
  63 OpenDaylight Security Resources
  64 ===============================
  65
  66 * If you have any security issues, you can send a mail to
  67   *security@lists.opendaylight.org*.
  68
  69 * For the list of current OpenDaylight security issues that are either being
  70   fixed or resolved, refer to
  71   https://wiki.opendaylight.org/view/Security:Advisories.
  72
  73 * To learn more about the OpenDaylight security issues policies and procedure,
  74   refer to https://wiki.opendaylight.org/view/Security:Main
  75
  76 .. _security_deployment_recommendations:
  77
  78 Deployment Recommendations
  79 ==========================
  80
  81 We recommend that you follow the deployment guidelines in setting up
  82 OpenDaylight to minimize security threats.
  83
  84 * The default credentials should be changed before deploying OpenDaylight.
  85
  86 * OpenDaylight should be deployed in a private network that cannot be accessed
  87   from the internet.
  88
  89 * Separate the data network (that connects devices using the network) from the
  90   management network (that connects the network devices to OpenDaylight).
  91
  92   .. note:: Deploying OpenDaylight on a separate, private management network does not
  93             eliminate threats, but only mitigates them. By construction, some
  94             messages must flow from the data network to the management network, e.g.,
  95             OpenFlow *packet_in* messages, and these create an attack surface even if
  96             it is a small one.
  97
  98 * Implement an authentication policy for devices that connect to both the data
  99   and management network. These are the devices which bridge, likely untrusted,
 100   traffic from the data network to the management network.
 101
 102 Securing OSGi bundles
 103 =====================
 104
 105 OSGi is a Java-specific framework that improves the way that Java classes
 106 interact within a single JVM. It provides an enhanced version of the
 107 *java.lang.SecurityManager* (ConditionalPermissionAdmin) in terms of security.
 108
 109 Java provides a security framework that allows a security policy to grant
 110 permissions, such as reading a file or opening a network connection, to
 111 specific code. The code maybe classes from the jarfile loaded from a specific
 112 URL, or a class signed by a specific key. OSGi builds on the standard Java
 113 security model to add the following features:
 114
 115 * A set of OSGi-specific permission types, such as one that grants the right
 116   to register an OSGi service or get an OSGi service from the service registry.
 117
 118 * The ability to dynamically modify permissions at runtime. This includes the
 119   ability to specify permissions by using code rather than a text configuration
 120   file.
 121
 122 * A flexible predicate-based approach to determining which rules are
 123   applicable to which *ProtectionDomain*. This approach is much more powerful
 124   than the standard Java security policy which can only grant rights based on a
 125   jarfile URL or class signature. A few standard predicates are provided,
 126   including selecting rules based upon bundle symbolic-name.
 127
 128 * Support for bundle *local permissions* policies with optional further
 129   constraints such as *DENY* operations. Most of this functionality is accessed
 130   by using the *OSGi ConditionalPermissionAdmin* service which is part of the
 131   OSGi core and can be obtained from the OSGi service registry. The
 132   *ConditionalPermissionAdmin* API replaces the earlier *PermissionAdmin* API.
 133
 134 For more information, refer to http://www.osgi.org/Main/HomePage.
 135
 136 .. _securing-karaf:
 137
 138 Securing the Karaf container
 139 ============================
 140
 141 Apache Karaf is a OSGi-based runtime platform which provides a lightweight
 142 container for OpenDaylight and applications. Apache Karaf uses
 143 either Apache Felix Framework or Eclipse Equinox OSGi frameworks, and provide
 144 additional features on top of the framework.
 145
 146 Apache Karaf provides a security framework based on Java Authentication and
 147 Authorization Service (JAAS) in compliance with OSGi recommendations,
 148 while providing RBAC (Role-Based Access Control) mechanism for the console and
 149 Java Management Extensions (JMX).
 150
 151 The Apache Karaf security framework is used internally to control the access
 152 to the following components:
 153
 154 * OSGi services
 155
 156 * console commands
 157
 158 * JMX layer
 159
 160 * WebConsole
 161
 162 The remote management capabilities are present in Apache Karaf by default,
 163 however they can be disabled by using various configuration alterations. These
 164 configuration options may be applied to the OpenDaylight Karaf distribution.
 165
 166 .. note:: Refer to the following list of publications for more information on
 167           implementing security for the Karaf container.
 168
 169 * For role-based JMX administration, refer to
 170   http://karaf.apache.org/manual/latest/users-guide/monitoring.html.
 171
 172 * For remote SSH access configuration, refer to
 173   http://karaf.apache.org/manual/latest/users-guide/remote.html.
 174
 175 * For WebConsole access, refer to
 176   http://karaf.apache.org/manual/latest/users-guide/webconsole.html.
 177
 178 * For Karaf security features, refer to
 179   http://karaf.apache.org/manual/latest/developers-guide/security-framework.html.
 180
 181 Disabling the remote shutdown port
 182 ----------------------------------
 183
 184 You can lock down your deployment post installation. Set
 185 ``karaf.shutdown.port=-1`` in ``etc/custom.properties`` or ``etc/config.properties`` to
 186 disable the remote shutdown port.
 187
 188 Securing Southbound Plugins
 189 ===========================
 190
 191 Many individual southbound plugins provide mechanisms to secure their
 192 communication with network devices. For example, the OpenFlow plugin supports
 193 TLS connections with bi-directional authentication and the NETCONF plugin
 194 supports connecting over SSH. Meanwhile, the Unified Secure Channel plugin
 195 provides a way to form secure, remote connections for supported devices.
 196
 197 When deploying OpenDaylight, you should carefully investigate the secure
 198 mechanisms to connect to devices using the relevant plugins.
 199
 200 Securing OpenDaylight using AAA
 201 ===============================
 202
 203 AAA stands for Authentication, Authorization, and Accounting. All three of
 204 these services can help improve the security posture of an OpenDaylight deployment.
 205
 206 The vast majority of OpenDaylight's northbound APIs (and all RESTCONF APIs) are
 207 protected by AAA by default when installing the +odl-restconf+ feature. In the
 208 cases that APIs are *not* protected by AAA, this will be noted in the
 209 per-project release notes.
 210
 211 By default, OpenDaylight has only one user account with the username and
 212 password *admin*. This should be changed before deploying OpenDaylight.
 213
 214 Securing RESTCONF using HTTPS
 215 =============================
 216
 217 To secure Jetty RESTful services, including RESTCONF, you must configure the
 218 Jetty server to utilize SSL by performing the following steps.
 219
 220 #. Issue the following command sequence to create a self-signed certificate for
 221    use by the ODL deployment.
 222
 223    ::
 224
 225         keytool -keystore .keystore -alias jetty -genkey -keyalg RSA
 226          Enter keystore password:  123456
 227         What is your first and last name?
 228           [Unknown]:  odl
 229         What is the name of your organizational unit?
 230           [Unknown]:  odl
 231         What is the name of your organization?
 232           [Unknown]:  odl
 233         What is the name of your City or Locality?
 234           [Unknown]:
 235         What is the name of your State or Province?
 236           [Unknown]:
 237         What is the two-letter country code for this unit?
 238           [Unknown]:
 239         Is CN=odl, OU=odl, O=odl,
 240         L=Unknown, ST=Unknown, C=Unknown correct?
 241           [no]:  yes
 242
 243
 244 #.  After the key has been obtained, make the following changes to
 245     the ``etc/custom.properties`` file to set a few default properties.
 246
 247     ::
 248
 249         org.osgi.service.http.secure.enabled=true
 250         org.osgi.service.http.port.secure=8443
 251         org.ops4j.pax.web.ssl.keystore=./etc/.keystore
 252         org.ops4j.pax.web.ssl.password=123456
 253         org.ops4j.pax.web.ssl.keypassword=123456
 254
 255 #. Then edit the ``etc/jetty.xml`` file with the appropriate HTTP connectors.
 256
 257    For example:
 258
 259    ::
 260
 261         <?xml version="1.0"?>
 262         <!--
 263          Licensed to the Apache Software Foundation (ASF) under one
 264          or more contributor license agreements.  See the NOTICE file
 265          distributed with this work for additional information
 266          regarding copyright ownership.  The ASF licenses this file
 267          to you under the Apache License, Version 2.0 (the
 268          "License"); you may not use this file except in compliance
 269          with the License.  You may obtain a copy of the License at
 270
 271            http://www.apache.org/licenses/LICENSE-2.0
 272
 273         Unless required by applicable law or agreed to in writing,
 274         software distributed under the License is distributed on an
 275         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 276          KIND, either express or implied.  See the License for the
 277          specific language governing permissions and limitations
 278          under the License.
 279         -->
 280         <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//
 281         DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
 282
 283         <Configure id="Server" class="org.eclipse.jetty.server.Server">
 284
 285             <!-- Use this connector for many frequently idle connections and for
 286                 threadless continuations. -->
 287             <New id="http-default" class="org.eclipse.jetty.server.HttpConfiguration">
 288                 <Set name="secureScheme">https</Set>
 289                 <Set name="securePort">
 290                     <Property name="jetty.secure.port" default="8443" />
 291                 </Set>
 292                 <Set name="outputBufferSize">32768</Set>
 293                 <Set name="requestHeaderSize">8192</Set>
 294                 <Set name="responseHeaderSize">8192</Set>
 295
 296                 <!-- Default security setting: do not leak our version -->
 297                 <Set name="sendServerVersion">false</Set>
 298
 299                 <Set name="sendDateHeader">false</Set>
 300                 <Set name="headerCacheSize">512</Set>
 301             </New>
 302
 303             <Call name="addConnector">
 304                 <Arg>
 305                     <New class="org.eclipse.jetty.server.ServerConnector">
 306                         <Arg name="server">
 307                             <Ref refid="Server" />
 308                         </Arg>
 309                         <Arg name="factories">
 310                             <Array type="org.eclipse.jetty.server.ConnectionFactory">
 311                                 <Item>
 312                                     <New class="org.eclipse.jetty.server.HttpConnectionFactory">
 313                                         <Arg name="config">
 314                                             <Ref refid="http-default"/>
 315                                         </Arg>
 316                                     </New>
 317                                 </Item>
 318                             </Array>
 319                         </Arg>
 320                         <Set name="host">
 321                             <Property name="jetty.host"/>
 322                         </Set>
 323                         <Set name="port">
 324                             <Property name="jetty.port" default="8181"/>
 325                         </Set>
 326                         <Set name="idleTimeout">
 327                             <Property name="http.timeout" default="300000"/>
 328                         </Set>
 329                         <Set name="name">jetty-default</Set>
 330                     </New>
 331                 </Arg>
 332             </Call>
 333
 334             <!-- =========================================================== -->
 335             <!-- Configure Authentication Realms -->
 336             <!-- Realms may be configured for the entire server here, or -->
 337             <!-- they can be configured for a specific web app in a context -->
 338             <!-- configuration (see $(jetty.home)/contexts/test.xml for an -->
 339             <!-- example). -->
 340             <!-- =========================================================== -->
 341             <Call name="addBean">
 342                 <Arg>
 343                     <New class="org.eclipse.jetty.jaas.JAASLoginService">
 344                         <Set name="name">karaf</Set>
 345                         <Set name="loginModuleName">karaf</Set>
 346                         <Set name="roleClassNames">
 347                             <Array type="java.lang.String">
 348                                 <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal</Item>
 349                             </Array>
 350                         </Set>
 351                     </New>
 352                 </Arg>
 353             </Call>
 354             <Call name="addBean">
 355                 <Arg>
 356                    <New class="org.eclipse.jetty.jaas.JAASLoginService">
 357                         <Set name="name">default</Set>
 358                         <Set name="loginModuleName">karaf</Set>
 359                         <Set name="roleClassNames">
 360                             <Array type="java.lang.String">
 361                                 <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal</Item>
 362                             </Array>
 363                         </Set>
 364                     </New>
 365                 </Arg>
 366             </Call>
 367         </Configure>
 368
 369
 370 The configuration snippet above adds a connector that is protected by SSL on
 371 port 8443. You can test that the changes have succeeded by restarting Karaf,
 372 issuing the following ``curl`` command, and ensuring that the 2XX HTTP status
 373 code appears in the returned message.
 374
 375 ::
 376
 377         curl -u admin:admin -v -k https://localhost:8443/restconf/modules
 378
 379 Security Considerations for Clustering
 380 ======================================
 381
 382 While OpenDaylight clustering provides many benefits including high
 383 availability, scale-out performance, and data durability, it also opens a new
 384 attack surface in the form of the messages exchanged between the various
 385 instances of OpenDaylight in the cluster. In the current OpenDaylight release,
 386 these messages are neither encrypted nor authenticated meaning that anyone with
 387 access to the management network where OpenDaylight exchanges these clustering
 388 messages can forge and/or read the messages. This means that if clustering is
 389 enabled, it is even more important that the management network be kept secure
 390 from any untrusted entities.