diff --git a/README.md b/README.md index 5afd070..017310b 100644 --- a/README.md +++ b/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```. -The default installation directory is: - /usr/local. +Please make sure to configure wolfSSL with ```./configure --prefix=/usr/local --enable-nginx```. 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. diff --git a/nginx-1.21.4-pq.patch b/nginx-1.21.4-pq.patch new file mode 100644 index 0000000..38a4215 --- /dev/null +++ b/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,