[5302] Updates in the kea-nginx.conf commentary.

doc/examples/https/nginx/kea-nginx.conf

@@ -1,51 +1,65 @@
-# This file contains an example configuration of the nginx HTTP server.
-# nginx is configured as a reverse proxy for Kea RESTful API. It enables
-# HTTPS for Kea to provide secure comunication and client side
-# certificate verification to allow only authorized clients to
-# access the Kea RESTful API.
+#   This file contains an example nginx HTTP server configuration which
+#   enables reverse proxy service for Kea RESTful API. An access to
+#   the service is protected by client's certificate verification
+#   mechanism. Before using this configuration a server administrator
+#   must generate server certificate and private key as well as
+#   the certifiate authority (CA). The clients' certificates must
+#   be signed by the CA.
 
-events {
-}
-
-# Minimal HTTPS server configuration for Kea.
+#   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
+#
 #
-# Note: in order to generate self signed certificates the following
-# command can be used.
+#   The client certificate needs to be generated and signed:
 #
-# Client certificate and key:
-# openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout \
-#     kea-client.key -out kea-client.crt
+#   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
 #
-# Server certificate and key:
-# openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout \
-#     kea-rest.key -out key-rest.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.
 #
-# Then start the HTTPS server:
-# nginx -c /path/to/kea-nginx.conf start
+#   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:
 #
-# In order to test the configuration with curl:
-# 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
+#   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
-    #
+    #   HTTPS server
     server {
-        # Use default HTTPS default port.
-        listen       443 ssl;
-        # Set server name.
-        server_name  kea.example.org;
+        #     Use default HTTPS port.
+        listen 443 ssl;
+        #     Set server name.
+        server_name kea.example.org;
+
+        #   Server certificate and key.
+        ssl_certificate kea-proxy.crt;
+        ssl_certificate_key kea-proxy.key;
 
-        # Server certificate and key.
-        ssl_certificate        kea-rest.crt;
-        ssl_certificate_key    kea-rest.key;
+        #   Certificate Authority. Client certificate must be signed by the CA.
+        ssl_client_certificate ca.crt;
 
-        # Client certificate which must be sent by the client to be
-        # authorized.
-        ssl_client_certificate kea-client.crt;
         # Enable verification of the client certificate.
-        ssl_verify_client      on;
+        ssl_verify_client on;
 
         # For URLs such as https://kea.example.org/kea, forward the
         # requests to http://127.0.0.1:8080.