X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fgetting-started-guide%2Fsecurity_considerations.rst;h=fe06b33087fa82f8d327450b753f4d222be1c110;hb=HEAD;hp=fa3c5da58607c53495e07b88a63e74fe60987a38;hpb=6322b726513b44a27785433c1dcbbd9314a355ce;p=docs.git diff --git a/docs/getting-started-guide/security_considerations.rst b/docs/getting-started-guide/security_considerations.rst index fa3c5da58..fe06b3308 100644 --- a/docs/getting-started-guide/security_considerations.rst +++ b/docs/getting-started-guide/security_considerations.rst @@ -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