X-Git-Url: https://git.opendaylight.org/gerrit/gitweb?a=blobdiff_plain;f=docs%2Fgetting-started-guide%2Fsecurity_considerations.rst;h=33f79eb8aa517ea80fe29946fff4ddd0a863392c;hb=a5d2ffcb2ec9a02a39949d94bf194d9f9d9fdf21;hp=70ac5ac7f4f2250ff3583ce6bb111168bd59483c;hpb=062b9a780a6e28d797cf16cc59dc0cf7a77fce87;p=docs.git

diff --git a/docs/getting-started-guide/security_considerations.rst b/docs/getting-started-guide/security_considerations.rst
index 70ac5ac7f..33f79eb8a 100644
--- a/docs/getting-started-guide/security_considerations.rst
+++ b/docs/getting-started-guide/security_considerations.rst
@@ -133,6 +133,8 @@ security model to add the following features:
 
 For more information, refer to http://www.osgi.org/Main/HomePage.
 
+.. _securing-karaf:
+
 Securing the Karaf container
 ============================
 
@@ -165,16 +167,16 @@ 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
 
 * 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_framework
 
 Disabling the remote shutdown port
 ----------------------------------
@@ -199,9 +201,7 @@ 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.
+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
@@ -211,6 +211,171 @@ 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 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/custom.properties`` 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.password=123456
+        org.ops4j.pax.web.ssl.keypassword=123456
+
+#. Then edit the ``etc/jetty.xml`` file with the appropriate HTTP connectors.
+
+   For example:
+
+   ::
+
+        <?xml version="1.0"?>
+        <!--
+         Licensed to the Apache Software Foundation (ASF) under one
+         or more contributor license agreements.  See the NOTICE file
+         distributed with this work for additional information
+         regarding copyright ownership.  The ASF licenses this file
+         to you under the Apache License, Version 2.0 (the
+         "License"); you may not use this file except in compliance
+         with the License.  You may obtain a copy of the License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+        Unless required by applicable law or agreed to in writing,
+        software distributed under the License is distributed on an
+        "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+         KIND, either express or implied.  See the License for the
+         specific language governing permissions and limitations
+         under the License.
+        -->
+        <!DOCTYPE Configure PUBLIC "-//Mort Bay Consulting//
+        DTD Configure//EN" "http://jetty.mortbay.org/configure.dtd">
+
+        <Configure id="Server" class="org.eclipse.jetty.server.Server">
+
+            <!-- Use this connector for many frequently idle connections and for
+                threadless continuations. -->
+            <New id="http-default" class="org.eclipse.jetty.server.HttpConfiguration">
+                <Set name="secureScheme">https</Set>
+                <Set name="securePort">
+                    <Property name="jetty.secure.port" default="8443" />
+                </Set>
+                <Set name="outputBufferSize">32768</Set>
+                <Set name="requestHeaderSize">8192</Set>
+                <Set name="responseHeaderSize">8192</Set>
+
+                <!-- Default security setting: do not leak our version -->
+                <Set name="sendServerVersion">false</Set>
+
+                <Set name="sendDateHeader">false</Set>
+                <Set name="headerCacheSize">512</Set>
+            </New>
+
+            <Call name="addConnector">
+                <Arg>
+                    <New class="org.eclipse.jetty.server.ServerConnector">
+                        <Arg name="server">
+                            <Ref refid="Server" />
+                        </Arg>
+                        <Arg name="factories">
+                            <Array type="org.eclipse.jetty.server.ConnectionFactory">
+                                <Item>
+                                    <New class="org.eclipse.jetty.server.HttpConnectionFactory">
+                                        <Arg name="config">
+                                            <Ref refid="http-default"/>
+                                        </Arg>
+                                    </New>
+                                </Item>
+                            </Array>
+                        </Arg>
+                        <Set name="host">
+                            <Property name="jetty.host"/>
+                        </Set>
+                        <Set name="port">
+                            <Property name="jetty.port" default="8181"/>
+                        </Set>
+                        <Set name="idleTimeout">
+                            <Property name="http.timeout" default="300000"/>
+                        </Set>
+                        <Set name="name">jetty-default</Set>
+                    </New>
+                </Arg>
+            </Call>
+
+            <!-- =========================================================== -->
+            <!-- Configure Authentication Realms -->
+            <!-- Realms may be configured for the entire server here, or -->
+            <!-- they can be configured for a specific web app in a context -->
+            <!-- configuration (see $(jetty.home)/contexts/test.xml for an -->
+            <!-- example). -->
+            <!-- =========================================================== -->
+            <Call name="addBean">
+                <Arg>
+                    <New class="org.eclipse.jetty.jaas.JAASLoginService">
+                        <Set name="name">karaf</Set>
+                        <Set name="loginModuleName">karaf</Set>
+                        <Set name="roleClassNames">
+                            <Array type="java.lang.String">
+                                <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal</Item>
+                            </Array>
+                        </Set>
+                    </New>
+                </Arg>
+            </Call>
+            <Call name="addBean">
+                <Arg>
+                   <New class="org.eclipse.jetty.jaas.JAASLoginService">
+                        <Set name="name">default</Set>
+                        <Set name="loginModuleName">karaf</Set>
+                        <Set name="roleClassNames">
+                            <Array type="java.lang.String">
+                                <Item>org.apache.karaf.jaas.boot.principal.RolePrincipal</Item>
+                            </Array>
+                        </Set>
+                    </New>
+                </Arg>
+            </Call>
+        </Configure>
+
+
+The configuration snippet above adds a connector that is protected by SSL on
+port 8443. 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/restconf/modules
+
 Security Considerations for Clustering
 ======================================