Code Review / docs.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
Chore: Update downloads page for Potassium SR3
[docs.git] / docs / getting-started-guide / security_considerations.rst
diff --git a/docs/getting-started-guide/security_considerations.rst b/docs/getting-started-guide/security_considerations.rst
index fa3c5da58607c53495e07b88a63e74fe60987a38..fe06b33087fa82f8d327450b753f4d222be1c110 100644 (file)
--- a/docs/getting-started-guide/security_considerations.rst
+++ b/docs/getting-started-guide/security_considerations.rst
@@ -1,5 +1,8 @@
+.. _security_considerations:
+
+***********************
 Security Considerations
 Security Considerations
-=======================
+***********************
 
 This document discusses the various security issues that might affect
 OpenDaylight. The document also lists specific recommendations to
 
 This document discusses the various security issues that might affect
 OpenDaylight. The document also lists specific recommendations to
@@ -11,7 +14,7 @@ OpenDaylight, and if necessary, contact the Security Response Team,
 which is tasked with identifying and resolving security threats.
 
 Overview of OpenDaylight Security
 which is tasked with identifying and resolving security threats.
 
 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
 
 There are many different kinds of security vulnerabilities that could affect
 an OpenDaylight deployment, but this guide focuses on those where (a) the
@@ -58,20 +61,22 @@ security advantages of OpenDaylight.
   a well-defined process for reporting and dealing with them.
 
 OpenDaylight Security Resources
   a well-defined process for reporting and dealing with them.
 
 OpenDaylight Security Resources
--------------------------------
+===============================
 
 * If you have any security issues, you can send a mail to
   *security@lists.opendaylight.org*.
 
 * For the list of current OpenDaylight security issues that are either being
   fixed or resolved, refer to
 
 * If you have any security issues, you can send a mail to
   *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.
+  https://wiki-archive.opendaylight.org/view/Security:Advisories.
 
 * To learn more about the OpenDaylight security issues policies and procedure,
 
 * To learn more about the OpenDaylight security issues policies and procedure,
-  refer to https://wiki.opendaylight.org/view/Security:Main
+  refer to https://wiki-archive.opendaylight.org/view/Security:Main
+
+.. _security_deployment_recommendations:
 
 Deployment Recommendations
 
 Deployment Recommendations
---------------------------
+==========================
 
 We recommend that you follow the deployment guidelines in setting up
 OpenDaylight to minimize security threats.
 
 We recommend that you follow the deployment guidelines in setting up
 OpenDaylight to minimize security threats.
@@ -95,7 +100,7 @@ OpenDaylight to minimize security threats.
   traffic from the data network to the management network.
 
 Securing OSGi bundles
   traffic from the data network to the management network.
 
 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
 
 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
@@ -110,7 +115,7 @@ 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.
 
 * 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.
 
-* The ability to dynamically modify permissions at runtime. This includes the
+* The ability to dynamically modify permissions at run-time. 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.
 
@@ -126,12 +131,14 @@ security model to add the following features:
   OSGi core and can be obtained from the OSGi service registry. The
   *ConditionalPermissionAdmin* API replaces the earlier *PermissionAdmin* API.
 
   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.
+For more information, refer to https://www.osgi.org
+
+.. _securing-karaf:
 
 Securing the Karaf container
 
 Securing the Karaf container
-----------------------------
+============================
 
 
-Apache Karaf is a OSGi-based runtime platform which provides a lightweight
+Apache Karaf is a OSGi-based run-time platform which provides a lightweight
 container for OpenDaylight and applications. Apache Karaf uses
 either Apache Felix Framework or Eclipse Equinox OSGi frameworks, and provide
 additional features on top of the framework.
 container for OpenDaylight and applications. Apache Karaf uses
 either Apache Felix Framework or Eclipse Equinox OSGi frameworks, and provide
 additional features on top of the framework.
@@ -160,26 +167,26 @@ configuration options may be applied to the OpenDaylight Karaf distribution.
           implementing security for the Karaf container.
 
 * For role-based JMX administration, refer to
           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_and_management_using_jmx
 
 * For remote SSH access configuration, refer to
 
 * 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
 
 * 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
 
 * 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
 
 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`` to
 disable the remote shutdown port.
 
 Securing Southbound Plugins
 disable the remote shutdown port.
 
 Securing Southbound Plugins
----------------------------
+===========================
 
 Many individual southbound plugins provide mechanisms to secure their
 communication with network devices. For example, the OpenFlow plugin supports
 
 Many individual southbound plugins provide mechanisms to secure their
 communication with network devices. For example, the OpenFlow plugin supports
@@ -191,23 +198,77 @@ When deploying OpenDaylight, you should carefully investigate the secure
 mechanisms to connect to devices using the relevant plugins.
 
 Securing OpenDaylight using AAA
 mechanisms to connect to devices using the relevant plugins.
 
 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
-release, only authentication is fully supported, while authorization is an
-experimental feature and accounting remains a work in progress.
+AAA stands for Authentication, Authorization, and Accounting.
+All three of these services can help improve the security posture of an
+OpenDaylight deployment.
 
 The vast majority of OpenDaylight's northbound APIs (and all RESTCONF APIs) are
 
 The vast majority of OpenDaylight's northbound APIs (and all RESTCONF APIs) are
-protected by AAA by default when installing the +odl-restconf+ feature. In the
-cases that APIs are *not* protected by AAA, this will be noted in the
+protected by AAA by default when installing the ``+odl-restconf+`` feature.
+In the 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.
 
 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.
 
+Securing RESTCONF using HTTPS
+=============================
+
+To secure Jetty RESTful services, including RESTCONF, you must configure the
+Jetty server to utilize SSL by performing the following steps.
+
+#. Issue the following command sequence to create a self-signed certificate in the ``etc`` folder for
+   use by the ODL deployment.
+
+   ::
+
+        keytool -keystore .keystore -alias jetty -genkey -keyalg RSA
+         Enter keystore password:  123456
+        What is your first and last name?
+          [Unknown]:  odl
+        What is the name of your organizational unit?
+          [Unknown]:  odl
+        What is the name of your organization?
+          [Unknown]:  odl
+        What is the name of your City or Locality?
+          [Unknown]:
+        What is the name of your State or Province?
+          [Unknown]:
+        What is the two-letter country code for this unit?
+          [Unknown]:
+        Is CN=odl, OU=odl, O=odl,
+        L=Unknown, ST=Unknown, C=Unknown correct?
+          [no]:  yes
+
+
+#.  After the key has been obtained, make the following changes to
+    the ``etc/org.ops4j.pax.web.cfg`` file to set a few default properties.
+
+    ::
+
+        org.osgi.service.http.secure.enabled=true
+        org.osgi.service.http.port.secure=8443
+        org.ops4j.pax.web.ssl.keystore=./etc/.keystore
+        org.ops4j.pax.web.ssl.keystore.password=123456
+        org.ops4j.pax.web.ssl.keystore.type=PKCS12
+        org.ops4j.pax.web.ssl.key.password=123456
+        org.ops4j.pax.web.ssl.key.alias=jetty
+
+
+You can test that the changes have succeeded by restarting Karaf,
+issuing the following ``curl`` command, and ensuring that the 2XX HTTP status
+code appears in the returned message.
+
+::
+
+        curl -u admin:admin -v -k https://localhost:8443/rests/operations
+
+A more advanced example of Jetty security configuration can be found in this article:
+https://access.redhat.com/documentation/en-us/red_hat_jboss_fuse/6.3/html/security_guide/webconsole#idm139646384633952
+
 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
 
 While OpenDaylight clustering provides many benefits including high
 availability, scale-out performance, and data durability, it also opens a new
OpenDaylight Documentation