[5282] Updated previous https examples for macOS and added a stunnel one for client/shell

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
@@ -41,7 +41,18 @@
 #        -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
 #
 #   nginx configuration starts here.
 
@@ -68,6 +79,7 @@ http {
 
         # For URLs such as https://kea.example.org/kea, forward the
         # requests to http://127.0.0.1:8080.
+        # Use the / location for URLs with no path.
         location /kea {
             proxy_pass http://127.0.0.1:8080;
         }

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 8443 ==>
+;           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:8443
+
+    ; client certificate
+    cert = kea-client.crt
+
+    ; client private key
+    key = kea-client.key
+
+    ; check server certificate
+    verifyPeer = yes
+
+    ; server certificate
+    CAfile = kea-proxy.crt