Adding upstream version 2.2.0.upstream/2.2.0upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

3 files changed, 263 insertions, 0 deletions

diff --git a/doc/examples/https/httpd2/kea-httpd2.conf b/doc/examples/https/httpd2/kea-httpd2.conf
new file mode 100644
index 0000000..b138673
--- /dev/null
+++ b/doc/examples/https/httpd2/kea-httpd2.conf
@@ -0,0 +1,129 @@
+#   This file contains a partial Apache2 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 certificate authority (CA). The clients' certificates must
+#   be signed by the CA.
+#
+#   Note that the steps provided below to generate and setup certificates
+#   are provided as an example for testing purposes only. Always
+#   consider best known security measures to protect your production
+#   environment.
+#
+#   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 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
+#   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
+#
+#   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:
+#
+#   Include /path/to/kea-httpd2.conf
+#
+#   and specify a path appropriate for your system.
+#
+#
+#   Apache2 server configuration starts here.
+#
+#   Address and port that the server should bind to.
+#   Usually an explicit address is specified to avoid binding to
+#   many addresses. For testing https connection on the localhost
+#   use:
+#       Listen [::1]:443         or
+#       Listen 127.0.0.1:443
+Listen *:443
+
+#   List the ciphers that the client is permitted to negotiate,
+#   and that httpd will negotiate as the client of a proxied server.
+#   See the OpenSSL documentation for a complete list of ciphers, and
+#   ensure these follow appropriate best practices for this deployment.
+#   httpd 2.2.30, 2.4.13 and later force-disable aNULL, eNULL and EXP ciphers,
+#   while OpenSSL disabled these by default in 0.9.8zf/1.0.0r/1.0.1m/1.0.2a.
+SSLCipherSuite HIGH:MEDIUM:!MD5:!RC4
+SSLProxyCipherSuite HIGH:MEDIUM:!MD5:!RC4
+
+#   User agents such as web browsers are not configured for the user's
+#   own preference of either security or performance, therefore this
+#   must be the prerogative of the web server administrator who manages
+#   cpu load versus confidentiality, so enforce the server's cipher order.
+SSLHonorCipherOrder on
+
+#   List the protocol versions which clients are allowed to connect with.
+#   Disable SSLv2 and SSLv3 by default (cf. RFC 7525 3.1.1).  TLSv1 (1.0)
+#   should be disabled as quickly as practical.  By the end of 2016, only
+#   the TLSv1.2 protocol or later should remain in use.
+SSLProtocol all -SSLv2 -SSLv3
+SSLProxyProtocol all -SSLv2 -SSLv3
+
+#   Semaphore:
+#   Configure the path to the mutual exclusion semaphore the
+#   SSL engine uses internally for inter-process synchronization.
+SSLMutex  "file:/usr/local/var/run/apache2/ssl_mutex"
+
+<VirtualHost *:443>
+    #    For URLs such as https://kea.example.org/kea, forward the requests
+    #    to http://127.0.0.1:8000
+    ProxyPass /kea http://127.0.0.1:8000/
+    ProxyPassReverse /kea http://127.0.0.1:8000/
+
+    #    Disable connection keep alive between the proxy and Kea because
+    #    Kea doesn't support this mechanism.
+    SetEnv proxy-nokeepalive 1
+
+    #    Set server name.
+    ServerName kea.example.org
+
+    #   Enable SSL for this virtual host.
+    SSLEngine on
+
+    #   Server certificate and private key.
+    SSLCertificateFile "/path/to/kea-proxy.crt"
+    SSLCertificateKeyFile "/path/to/kea-proxy.key"
+
+    #   Enable verification of the client certificate.
+    SSLVerifyClient require
+
+    #   Certificate Authority. Client certificate must be signed by the CA.
+    SSLCACertificateFile "/path/to/ca.crt"
+
+</VirtualHost>
diff --git a/doc/examples/https/nginx/kea-nginx.conf b/doc/examples/https/nginx/kea-nginx.conf
new file mode 100644
index 0000000..cdbd7b3
--- /dev/null
+++ b/doc/examples/https/nginx/kea-nginx.conf
@@ -0,0 +1,88 @@
+#   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 certificate authority (CA). The clients' certificates must
+#   be signed by the CA.
+#
+#   Note that the steps provided below to generate and setup certificates
+#   are provided as an example for testing purposes only. Always
+#   consider best known security measures to protect your production
+#   environment.
+#
+#   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 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
+#   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
+#
+#   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.
+
+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 the URL https://kea.example.org forward the
+        # requests to http://127.0.0.1:8000.
+        # kea-shell defaults to / but --path can be used to set another value
+        # for instance kea-shell --path kea which will matches location /kea
+        location / {
+            proxy_pass http://127.0.0.1:8000;
+        }
+    }
+}
diff --git a/doc/examples/https/shell/kea-stunnel.conf b/doc/examples/https/shell/kea-stunnel.conf
new file mode 100644
index 0000000..1d40aca
--- /dev/null
+++ b/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 8888 -->
+;       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:8888
+
+    ; 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