Merge pull request #18 from anhu/nginx-pq

Add patch and documentation to allow nginx to use post-quantum algorithms.

README.md

@@ -6,6 +6,7 @@ wolfSSL is supported in Nginx. There are minor changes to the Nginx code base
 and recompilation is required.
 
 The tested versions:
+ - wolfSSL 5.1.0
  - wolfSSL 3.14
  - wolfSSL 3.13.0 (with patch applied: wolfssl-3.13.0-nginx.patch)
  - Nginx 1.21.4
@@ -32,9 +33,7 @@ The tested versions:
 First you will need Nginx source package and wolfSSL source code.
 
 Now build and install wolfSSL.
-Please make sure to configure wolfSSL with ```./configure --enable-nginx```.
+Please make sure to configure wolfSSL with ```./configure --prefix=/usr/local --enable-nginx```.
-The default installation directory is:
-    /usr/local.
 
 To enable wolfSSL support in Nginx the source code must be patched:
  1. Change into the Nginx source directory.
@@ -115,6 +114,59 @@ testing. To test:
 
 Testing is only supported on Linux with bash.
 
+## Post-Quantum Algorithms
+
+Starting with wolfSSL version 5.1.0 and nginx version 1.21.4, You can now enable the integration of liboqs in wolfSSL thus enabling post-quantum algorithms for your HTTPS connections over TLS 1.3.
+
+First, you will need to build the OpenQuantumSafe group's liboqs and their fork of OpenSSL to generate the certificate chain that uses the post-quantum FALCON signature scheme. Instructions for that are in wolfSSL git repository's INSTALL file. Note that when you generate your certificates, you will need to add your IP address as a subject alternative name. See here for more details: https://www.openssl.org/docs/manmaster/man5/x509v3_config.html
+
+When building wolfSSL, you will need to add a couple extra flags:
+
+```
+./configure --prefix=/usr/local --enable-nginx --with-liboqs
+make all
+make check
+sudo make install
+```
+
+Now, you can continue on with the instructions for building nginx above, but also apply the nginx-1.21.4-pq.patch patch.
+
+Now that all the software is built and installed, you will need to add a section in the nginx.conf file to enable TLS 1.3 and use the correct certificates. Edit `/usr/local/nginx/conf/nginx.conf`. Nginx's install process should have put a default version there. Search for the section with the title `HTTPS server` and replace that section with the following:
+
+```
+    server {
+        listen                    443 ssl;
+        server_name               localhost;
+
+        ssl_certificate           /path/to/falcon_level5_entity_cert.pem;
+        ssl_certificate_key       /path/to/falcon_level5_entity_key.pem;
+
+        ssl_session_cache         shared:SSL:1m;
+        ssl_session_timeout       5m;
+
+        ssl_protocols             TLSv1.3;
+        ssl_ciphers               TLS_AES_256_GCM_SHA384;
+        ssl_prefer_server_ciphers on;
+
+        location / {
+            root   html;
+            index  index.html index.htm;
+        }
+    }
+```
+
+NOTE: You will need to change the path of the certificate and key.
+
+You can now execute the nginx web server by doing the following:
+
+```
+sudo /usr/local/nginx/sbin/nginx
+```
+
+Check `/usr/local/nginx/logs/error.log` to see if there were any errors and ensure that `/usr/local/nginx/logs/nginx.pid` exists. It is created upon successful launch of the server daemon process.
+
+NOTE: You will need to change the path of the root certificate and use your IP address.
+
 ## Licensing
 
 wolfSSL and wolfCrypt are either licensed for use under the GPLv3 (or at your option any later version) or a standard commercial license. For users who cannot use wolfSSL under GPLv3 (or any later version), a commercial license to wolfSSL and wolfCrypt is available. For license inquiries, please contact wolfSSL Inc. directly at licensing@wolfssl.com.

nginx-1.21.4-pq.patch

@@ -0,0 +1,124 @@
+diff -ur nginx-1.21.4/src/event/ngx_event_openssl.c nginx-1.21.4-pq/src/event/ngx_event_openssl.c
+--- nginx-1.21.4/src/event/ngx_event_openssl.c	2021-12-24 12:15:25.943693122 -0500
++++ nginx-1.21.4-pq/src/event/ngx_event_openssl.c	2021-12-22 15:18:26.681445109 -0500
+@@ -20,10 +20,14 @@
+ 
+ static X509 *ngx_ssl_load_certificate(ngx_pool_t *pool, char **err,
+     ngx_str_t *cert, STACK_OF(X509) **chain);
++ifndef HAVE_LIBOQS
++/* In the case that HAVE_LIBOQS is defined, these functions are unused as we
++ * call SSL_CTX_use_PrivateKey_file() instead. */
+ static EVP_PKEY *ngx_ssl_load_certificate_key(ngx_pool_t *pool, char **err,
+     ngx_str_t *key, ngx_array_t *passwords);
+ static int ngx_ssl_password_callback(char *buf, int size, int rwflag,
+     void *userdata);
++#endif
+ static int ngx_ssl_verify_callback(int ok, X509_STORE_CTX *x509_store);
+ static void ngx_ssl_info_callback(const ngx_ssl_conn_t *ssl_conn, int where,
+     int ret);
+@@ -433,7 +437,9 @@
+ {
+     char            *err;
+     X509            *x509;
++#ifndef HAVE_LIBOQS
+     EVP_PKEY        *pkey;
++#endif
+     STACK_OF(X509)  *chain;
+ 
+     x509 = ngx_ssl_load_certificate(cf->pool, &err, cert, &chain);
+@@ -524,6 +530,20 @@
+     }
+ #endif
+ 
++#ifdef HAVE_LIBOQS
++        if (ngx_get_full_name(cf->pool, (ngx_str_t *) &ngx_cycle->conf_prefix,
++                              key) != NGX_OK) {
++            return NGX_OK;
++        }
++
++        if (SSL_CTX_use_PrivateKey_file(ssl->ctx, (char *)key->data, SSL_FILETYPE_PEM)
++            < 1) {
++            ngx_ssl_error(NGX_LOG_EMERG, ssl->log, 0,
++                          "cannot load certificate key \"%s\"",
++                          key->data);
++            return NGX_ERROR;
++        }
++#else
+     pkey = ngx_ssl_load_certificate_key(cf->pool, &err, key, passwords);
+     if (pkey == NULL) {
+         if (err != NULL) {
+@@ -543,6 +563,7 @@
+     }
+ 
+     EVP_PKEY_free(pkey);
++#endif
+ 
+     return NGX_OK;
+ }
+@@ -554,7 +575,9 @@
+ {
+     char            *err;
+     X509            *x509;
++#ifndef HAVE_LIBOQS
+     EVP_PKEY        *pkey;
++#endif
+     STACK_OF(X509)  *chain;
+ 
+     x509 = ngx_ssl_load_certificate(pool, &err, cert, &chain);
+@@ -595,6 +618,20 @@
+ 
+ #endif
+ 
++#ifdef HAVE_LIBOQS
++    if (ngx_get_full_name(pool, (ngx_str_t *) &ngx_cycle->conf_prefix,
++                          key) != NGX_OK) {
++        return NGX_OK;
++    }
++
++    if (SSL_use_PrivateKey_file(c->ssl->connection, (char *)key->data, SSL_FILETYPE_PEM)
++        < 1) {
++        ngx_ssl_error(NGX_LOG_EMERG, c->log, 0,
++                      "cannot load certificate key \"%s\"",
++                      key->data);
++        return NGX_ERROR;
++    }
++#else
+     pkey = ngx_ssl_load_certificate_key(pool, &err, key, passwords);
+     if (pkey == NULL) {
+         if (err != NULL) {
+@@ -614,6 +651,7 @@
+     }
+ 
+     EVP_PKEY_free(pkey);
++#endif
+ 
+     return NGX_OK;
+ }
+@@ -709,6 +747,7 @@
+ }
+ 
+ 
++#ifndef HAVE_LIBOQS
+ static EVP_PKEY *
+ ngx_ssl_load_certificate_key(ngx_pool_t *pool, char **err,
+     ngx_str_t *key, ngx_array_t *passwords)
+@@ -824,8 +863,10 @@
+ 
+     return pkey;
+ }
++#endif
+ 
+ 
++#ifndef HAVE_LIBOQS
+ static int
+ ngx_ssl_password_callback(char *buf, int size, int rwflag, void *userdata)
+ {
+@@ -852,7 +893,7 @@
+ 
+     return size;
+ }
+-
++#endif
+ 
+ ngx_int_t
+ ngx_ssl_ciphers(ngx_conf_t *cf, ngx_ssl_t *ssl, ngx_str_t *ciphers,