[master] Merging trac5282 (client https)

doc/Makefile.am

@@ -13,6 +13,7 @@ nobase_dist_doc_DATA += examples/ddns/sample1.json
 nobase_dist_doc_DATA += examples/ddns/template.json
 nobase_dist_doc_DATA += examples/https/httpd2/kea-httpd2.conf
 nobase_dist_doc_DATA += examples/https/nginx/kea-nginx.conf
+nobase_dist_doc_DATA += examples/https/shell/kea-stunnel.conf
 nobase_dist_doc_DATA += examples/kea4/advanced.json
 nobase_dist_doc_DATA += examples/kea4/backends.json
 nobase_dist_doc_DATA += examples/kea4/cassandra.json

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

@@ -27,7 +27,7 @@
 #   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
+#           -CAkey ca.key -set_serial 10 -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
@@ -41,6 +41,19 @@
 #        -H Content-Type:application/json -d '{ "command": "list-commands" }' \
 #         https://kea.example.org/kea
 #
+#   On some curl running on macOS the crypto library requires a PKCS#12
+#   bundle with the private key and the certificate as the cert argument.
+#   The PKCS#12 file can be generated by:
+#
+#   openssl pkcs12 -export -in kea-client.crt -inkey kea-client.key \
+#           -out kea-client.p12
+#
+#   If the password is kea, curl command becomes:
+#
+#   curl -k --cert kea-client.p12:kea -X POST \
+#        -H Content-Type:application/json -d '{ "command": "list-commands" }' \
+#         https://kea.example.org/kea
+#
 #
 #   In order to use this configuration within your Apache2 configuration
 #   put the following line in the main Apache 2 configuration file:

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

@@ -27,7 +27,7 @@
 #   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
+#           -CAkey ca.key -set_serial 10 -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
@@ -39,9 +39,20 @@
 #
 #   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
+#         https://kea.example.org
 #
+#   On some curl running on macOS the crypto library requires a PKCS#12
+#   bundle with the private key and the certificate as the cert argument.
+#   The PKCS#12 file can be generated by:
 #
+#   openssl pkcs12 -export -in kea-client.crt -inkey kea-client.key \
+#           -out kea-client.p12
+#
+#   If the password is kea, curl command becomes:
+#
+#   curl -k --cert kea-client.p12:kea -X POST \
+#        -H Content-Type:application/json -d '{ "command": "list-commands" }' \
+#         https://kea.example.org
 #
 #   nginx configuration starts here.
 
@@ -66,10 +77,12 @@ http {
         # 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;
+        # For the URL https://kea.example.org forward the
+        # requests to http://127.0.0.1:8000.
+        # Since kea-shell doesn't currently support URLs with paths we
+        # use location /
+        location / {
+            proxy_pass http://127.0.0.1:8000;
         }
     }
 }

doc/examples/https/shell/kea-stunnel.conf

@@ -0,0 +1,46 @@
+;   This file contains an example stunnel TLS client configuration which
+;   enables secure transport for Kea RESTful API. An access to
+;   the service is protected by client's and server's certificate
+;   verification mechanism (as known as mutual authentication).
+;
+;   Note that the setup below (and reused nginx or httpd2 setups)
+;   are provided as an example for testing purposes only. Always
+;   consider best known security measures to protect your production
+;   environment.
+;
+;   Transport marked with ==> (vs -->) is secured against passive
+;   (i.e. eavesdropping) and active (i.e. man-in-the-middle) attacks
+;
+;   kea-shell -- 127.0.0.1 port 8080 -->
+;       stunnel == 127.0.0.1 port 443 ==>
+;           nginx -- 127.0.0.1 port 8000 -->
+;               kea-agent
+;
+;   stunnel configuration starts here.
+
+; in the case you would like to follow what happens
+;; foreground = yes
+;; debug = 7
+
+; kea service
+[kea]
+    ; client (vs server) mode
+    client = yes
+
+    ; accept requests from the kea-shell tool
+    accept = 127.0.0.1:8080
+
+    ; forward requests to the https peer
+    connect = 127.0.0.1:443
+
+    ; client certificate
+    cert = kea-client.crt
+
+    ; client private key
+    key = kea-client.key
+
+    ; check server certificate
+    verifyPeer = yes
+
+    ; server certificate
+    CAfile = kea-proxy.crt

doc/guide/agent.xml

@@ -267,6 +267,11 @@ http {
     organization which apply to this setup.</simpara>
   </note>
 
+    <para>When you use an HTTP client without TLS support as <command>
+    kea-shell</command> you can use an HTTP/HTTPS translator such as stunnel
+    in client mode. A sample configuration is provided in the
+    <filename>doc/examples/https/shell/</filename> directory</para>
+
   </section>
 
   <section id="agent-limitations">