From: Colin Dixon Date: Wed, 22 Jun 2016 04:57:53 +0000 (-0700) Subject: Migrating security considerations to reST X-Git-Tag: release/beryllium-sr3~33 X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=commitdiff_plain;h=ee30621b74c46e08866d1f41c36fe010d08435bf;p=docs.git Migrating security considerations to reST Change-Id: Iebb4e6e031bc9d760edd3323ef28f6f68b311512 Signed-off-by: Colin Dixon --- diff --git a/docs/getting-started-guide/index.rst b/docs/getting-started-guide/index.rst index 249ab99c9..25cc48a59 100644 --- a/docs/getting-started-guide/index.rst +++ b/docs/getting-started-guide/index.rst @@ -16,3 +16,5 @@ Getting Started Guide release_notes project-specific-guides/index common-features/index + security_considerations + diff --git a/manuals/getting-started-guide/src/main/asciidoc/chapter_security_considerations.adoc b/docs/getting-started-guide/security_considerations.rst old mode 100755 new mode 100644 similarity index 69% rename from manuals/getting-started-guide/src/main/asciidoc/chapter_security_considerations.adoc rename to docs/getting-started-guide/security_considerations.rst index b7463dbc9..ad9fdeda4 --- a/manuals/getting-started-guide/src/main/asciidoc/chapter_security_considerations.adoc +++ b/docs/getting-started-guide/security_considerations.rst @@ -1,4 +1,5 @@ -== Security Considerations +Security Considerations +======================= This document discusses the various security issues that might affect OpenDaylight. The document also lists specific recommendations to @@ -9,7 +10,8 @@ you can take if you discover a security issue with OpenDaylight, and if necessary, contact the Security Response Team, which is tasked with identifying and resolving security threats. -=== Overview of OpenDaylight Security +Overview of OpenDaylight Security +--------------------------------- There are many different kinds of security vulnerabilities that could affect an OpenDaylight deployment, but this guide focuses on those where (a) the @@ -26,17 +28,6 @@ What remains in scope is attacks launched from a server, virtual machine, or device other than the one running OpenDaylight where the attack does not have valid credentials to access the OpenDaylight deployment. -//* *Code vulnerability*: This is defined as the vulnerability that arises -//because of malicious human access to the applications and services that define -//your business. With the increased usage of cloud and virtualized solutions, -//there has been a rise in newer types of security threats. Your users require -//access to data from anywhere and at any time. At present, there are a number -//of recommended security strategies for your datacenter. However, with the -//disparity of hardware vendors used across cloud services, it is difficult to -//state with complete certainty that virtualized data centers are completely -//secured. Access vulnerability, thus, is not a hallmark particular to -//OpenDaylight, but to all services and businesses that run on the cloud. - The rest of this document gives specific recommendations for deploying OpenDaylight in a secure manner, but first we highlight some high-level security advantages of OpenDaylight. @@ -50,11 +41,11 @@ security advantages of OpenDaylight. them to make better decisions faster. At the same time, centralization of network control can be an advantage only if access to that control is secure. -+ -NOTE: While both previous advantages improve security, they also make - an OpenDaylight deployment an attractive target for attack making - understanding these security considerations even more important. -+ + + .. note:: While both previous advantages improve security, they also make + an OpenDaylight deployment an attractive target for attack making + understanding these security considerations even more important. + * The ability to more rapidly evolve southbound protocols and how they are used provides more and faster mechanisms to enact appropriate security mitigations and remediations. @@ -66,20 +57,21 @@ NOTE: While both previous advantages improve security, they also make * OpenDaylight has a history of rapidly addressing known vulnerabilities and a well-defined process for reporting and dealing with them. -=== OpenDaylight Security Resources +OpenDaylight Security Resources +------------------------------- * If you have any security issues, you can send a mail to -*security@lists.opendaylight.org*. + *security@lists.opendaylight.org*. * For the list of current OpenDaylight security issues that are either being -fixed or resolved, refer to -https://wiki.opendaylight.org/view/Security_Advisories. + fixed or resolved, refer to + https://wiki.opendaylight.org/view/Security_Advisories. * To learn more about the OpenDaylight security issues policies and procedure, -refer to -https://wiki.opendaylight.org/view/Security:Main + refer to https://wiki.opendaylight.org/view/Security:Main -=== Deployment Recommendations +Deployment Recommendations +-------------------------- We recommend that you follow the deployment guidelines in setting up OpenDaylight to minimize security threats. @@ -91,18 +83,19 @@ OpenDaylight to minimize security threats. * Separate the data network (that connects devices using the network) from the management network (that connects the network devices to OpenDaylight). -+ -NOTE: Deploying OpenDaylight on a separate, private management network does not - eliminate threats, but only mitigates them. By construction, some - messages must flow from the data network to the management network, e.g., - OpenFlow +packet_in+ messages, and these create an attack surface even if - it is a small one. -+ + + .. note:: Deploying OpenDaylight on a separate, private management network does not + eliminate threats, but only mitigates them. By construction, some + messages must flow from the data network to the management network, e.g., + OpenFlow *packet_in* messages, and these create an attack surface even if + it is a small one. + * Implement an authentication policy for devices that connect to both the data and management network. These are the devices which bridge, likely untrusted, traffic from the data network to the management network. -=== Securing OSGi bundles +Securing OSGi bundles +--------------------- OSGi is a Java-specific framework that improves the way that Java classes interact within a single JVM. It provides an enhanced version of the @@ -115,27 +108,28 @@ URL, or a class signed by a specific key. OSGi builds on the standard Java security model to add the following features: * A set of OSGi-specific permission types, such as one that grants the right -to register an OSGi service or get an OSGi service from the service registry. + to register an OSGi service or get an OSGi service from the service registry. * The ability to dynamically modify permissions at runtime. This includes the -ability to specify permissions by using code rather than a text configuration -file. + ability to specify permissions by using code rather than a text configuration + file. * A flexible predicate-based approach to determining which rules are -applicable to which *ProtectionDomain*. This approach is much more powerful -than the standard Java security policy which can only grant rights based on a -jarfile URL or class signature. A few standard predicates are provided, -including selecting rules based upon bundle symbolic-name. + applicable to which *ProtectionDomain*. This approach is much more powerful + than the standard Java security policy which can only grant rights based on a + jarfile URL or class signature. A few standard predicates are provided, + including selecting rules based upon bundle symbolic-name. * Support for bundle *local permissions* policies with optional further -constraints such as *DENY* operations. Most of this functionality is accessed -by using the *OSGi ConditionalPermissionAdmin* service which is part of the -OSGi core and can be obtained from the OSGi service registry. The -+ConditionalPermissionAdmin+ API replaces the earlier *PermissionAdmin* API. + constraints such as *DENY* operations. Most of this functionality is accessed + by using the *OSGi ConditionalPermissionAdmin* service which is part of the + OSGi core and can be obtained from the OSGi service registry. The + *ConditionalPermissionAdmin* API replaces the earlier *PermissionAdmin* API. For more information, refer to http://www.osgi.org/Main/HomePage. -=== Securing the Karaf container +Securing the Karaf container +---------------------------- Apache Karaf is a OSGi-based runtime platform which provides a lightweight container for OpenDaylight and applications. Apache Karaf uses @@ -162,28 +156,30 @@ The remote management capabilities are present in Apache Karaf by default, however they can be disabled by using various configuration alterations. These configuration options may be applied to the OpenDaylight Karaf distribution. -NOTE: Refer to the following list of publications for more information on -implementing security for the Karaf container. +.. note:: Refer to the following list of publications for more information on + implementing security for the Karaf container. * For role-based JMX administration, refer to -http://karaf.apache.org/manual/latest/users-guide/monitoring.html. + https://karaf.apache.org/manual/latest/monitoring. * For remote SSH access configuration, refer to -http://karaf.apache.org/manual/latest/users-guide/remote.html. + https://karaf.apache.org/manual/latest/remote. * For WebConsole access, refer to -http://karaf.apache.org/manual/latest/users-guide/webconsole.html. + https://karaf.apache.org/manual/latest/webconsole. * For Karaf security features, refer to -http://karaf.apache.org/manual/latest/developers-guide/security-framework.html. + https://karaf.apache.org/manual/latest/security. -==== Disabling the remote shutdown port +Disabling the remote shutdown port +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You can lock down your deployment post installation. Set -karaf.shutdown.port=-1 in +etc/custom.properties or etc/config.properties+ to +``karaf.shutdown.port=-1`` in ``etc/custom.properties`` or ``etc/config.properties`` to disable the remote shutdown port. -=== Securing Southbound Plugins +Securing Southbound Plugins +--------------------------- Many individual southbound plugins provide mechanisms to secure their communication with network devices. For example, the OpenFlow plugin supports @@ -194,7 +190,8 @@ provides a way to form secure, remote connections for supported devices. When deploying OpenDaylight, you should carefully investigate the secure mechanisms to connect to devices using the relevant plugins. -=== Securing OpenDaylight using AAA +Securing OpenDaylight using AAA +------------------------------- AAA stands for Authentication, Authorization, and Accounting. All three of can help improve the security posture of and OpenDaylight deployment. In this @@ -207,9 +204,10 @@ cases that APIs are *not* protected by AAA, this will be noted in the per-project release notes. By default, OpenDaylight has only one user account with the username and -password _admin_. This should be changed before deploying OpenDaylight. +password *admin*. This should be changed before deploying OpenDaylight. -=== Security Considerations for Clustering +Security Considerations for Clustering +-------------------------------------- While OpenDaylight clustering provides many benefits including high availability, scale-out performance, and data durability, it also opens a new diff --git a/manuals/getting-started-guide/src/main/asciidoc/bk-getting-started-guide.adoc b/manuals/getting-started-guide/src/main/asciidoc/bk-getting-started-guide.adoc index 071ae8475..51716bce4 100644 --- a/manuals/getting-started-guide/src/main/asciidoc/bk-getting-started-guide.adoc +++ b/manuals/getting-started-guide/src/main/asciidoc/bk-getting-started-guide.adoc @@ -59,7 +59,9 @@ the end of their file. = Getting to know OpenDaylight -include::chapter_security_considerations.adoc[] +== Placeholder + +Placeholder to keep the build working before this whole book is deleted. :numbered!: