[master] Merge branch 'trac5304'

doc/guide/agent.xml

@@ -179,8 +179,105 @@
       Control Agent doesn't natively support secure HTTP connections like
       SSL or TLS. In order to setup secure connection please use one
       of the available third party HTTP servers and configure it to run
-      as a reverse proxy to the Control Agent.
+      as a reverse proxy to the Control Agent. Kea has been tested with
+      two major HTTP server implentations working as a reverse proxy:
+      Apache2 and nginx. Example configurations including extensive
+      comments are provided in the <filename>doc/examples/https/</filename>
+      directory.
     </para>
+
+    <para>
+      The reverse proxy forwards HTTP requests received over secure
+      connection to the Control Agent using (not secured) HTTP. Typically,
+      the reverse proxy and the Control Agent are running on the same machine,
+      but it is possible to configure them to run on separate machines as
+      well. In this case, security depends on the protection of the
+      communications between the reverse proxy and the Control Agent.
+    </para>
+
+    <para>Apart from providing the encryption layer for the control channel,
+    a reverse proxy server is also often used for authentication of the
+    controlling clients. In this case, the client must present a valid
+    certificate when it connects via reverse proxy. The proxy server
+    authenticates the client by checking if the presented certifcate is
+    signed by the certificate authority used by the server.</para>
+
+    <para>To illustrate this, we provide a sample configuration for the
+    nginx server running as a reverse proxy to the Kea Control Agent.
+    The server enables authentication of the clients using
+    certificates.</para>
+
+<screen>
+#   The server certificate and key can be generated as follows:
+#
+#   openssl genrsa -des3 -out kea-proxy.key 4096
+#   openssl req -new -x509 -days 365 -key kea-proxy.key -out kea-proxy.crt
+#
+#   The CA certificate and key can be generated as follows:
+#
+#   openssl genrsa -des3 -out ca.key 4096
+#   openssl req -new -x509 -days 365 -key ca.key -out ca.crt
+#
+#
+#   The client certificate needs to be generated and signed:
+#
+#   openssl genrsa -des3 -out kea-client.key 4096
+#   openssl req -new -key kea-client.key -out kea-client.csr
+#   openssl x509 -req -days 365 -in kea-client.csr -CA ca.crt \
+#           -CAkey ca.key -set_serial 01 -out kea-client.crt
+#
+#   Note that the 'common name' value used when generating the client
+#   and the server certificates must differ from the value used
+#   for the CA certificate.
+#
+#   The client certificate must be deployed on the client system.
+#   In order to test the proxy configuration with 'curl' run
+#   command similar to the following:
+#
+#   curl -k --key kea-client.key --cert kea-client.crt -X POST \
+#        -H Content-Type:application/json -d '{ "command": "list-commands" }' \
+#         https://kea.example.org/kea
+#
+#
+#
+#   nginx configuration starts here.
+
+events {
+}
+
+http {
+        #   HTTPS server
+    server {
+        #     Use default HTTPS port.
+        listen 443 ssl;
+        #     Set server name.
+        server_name kea.example.org;
+
+        #   Server certificate and key.
+        ssl_certificate /path/to/kea-proxy.crt;
+        ssl_certificate_key /path/to/kea-proxy.key;
+
+        #   Certificate Authority. Client certificate must be signed by the CA.
+        ssl_client_certificate /path/to/ca.crt;
+
+        # Enable verification of the client certificate.
+        ssl_verify_client on;
+
+        # For URLs such as https://kea.example.org/kea, forward the
+        # requests to http://127.0.0.1:8080.
+        location /kea {
+            proxy_pass http://127.0.0.1:8080;
+        }
+    }
+}
+</screen>
+
+  <note>
+    <simpara>Note that the configuration snippet provided above is for testing
+    purposes only. Consult security policies and best practices of your
+    organization which apply to this setup.</simpara>
+  </note>
+
   </section>
 
   <section id="agent-limitations">