From baae1ebf26df6f93375d05505ee7c68b49e72645 Mon Sep 17 00:00:00 2001 From: Marcin Siodelski Date: Wed, 5 Jul 2017 18:08:59 +0200 Subject: [PATCH] [5304] Documented how to setup reverse proxy for control agent. --- doc/guide/agent.xml | 98 ++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 97 insertions(+), 1 deletion(-) diff --git a/doc/guide/agent.xml b/doc/guide/agent.xml index 1dc02f9d36..9c8e4c4189 100644 --- a/doc/guide/agent.xml +++ b/doc/guide/agent.xml @@ -179,8 +179,104 @@ 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 doc/examples/https/ + directory. + + + 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. + + + 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. + + 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. + + +# 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; + } + } +} + + + + 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. + +
-- 2.47.2