Commit a920453b authored by Marcin Siodelski's avatar Marcin Siodelski
Browse files

[master] Merge branch 'trac5304'

parents d12fe71d 487ff038
......@@ -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">
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment