Fix release schedule headers
[docs.git] / docs / getting-started-guide / security_considerations.rst
index fa3c5da58607c53495e07b88a63e74fe60987a38..fe06b33087fa82f8d327450b753f4d222be1c110 100644 (file)
@@ -1,5 +1,8 @@
+.. _security_considerations:
+
+***********************
 Security Considerations
-=======================
+***********************
 
 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
----------------------------------
+=================================
 
 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
--------------------------------
+===============================
 
 * 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,
-  refer to https://wiki.opendaylight.org/view/Security:Main
+  refer to https://wiki-archive.opendaylight.org/view/Security:Main
+
+.. _security_deployment_recommendations:
 
 Deployment Recommendations
---------------------------
+==========================
 
 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
----------------------
+=====================
 
 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.
 
-* 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.
 
@@ -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.
 
-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
-----------------------------
+============================
 
-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.
@@ -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
-  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
-  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
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+----------------------------------
 
 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
----------------------------
+===========================
 
 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
--------------------------------
+===============================
 
-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
-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.
 
+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
---------------------------------------
+======================================
 
 While OpenDaylight clustering provides many benefits including high
 availability, scale-out performance, and data durability, it also opens a new