Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wolfssl/wolfssl-nginx
Adds wolfSSL support to Nginx.
https://github.com/wolfssl/wolfssl-nginx
gplv3 http-tls13 nginx nginx-source secure-webserver security tls13 wolfssl wolfssl-nginx wolfssl-support
Last synced: 2 months ago
JSON representation
Adds wolfSSL support to Nginx.
- Host: GitHub
- URL: https://github.com/wolfssl/wolfssl-nginx
- Owner: wolfSSL
- Created: 2017-01-11T00:45:18.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2023-11-13T17:39:11.000Z (about 1 year ago)
- Last Synced: 2024-04-28T02:36:03.789Z (9 months ago)
- Topics: gplv3, http-tls13, nginx, nginx-source, secure-webserver, security, tls13, wolfssl, wolfssl-nginx, wolfssl-support
- Language: Shell
- Homepage: https://www.wolfssl.com
- Size: 238 KB
- Stars: 33
- Watchers: 25
- Forks: 9
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# wolfssl-nginx
## wolfSSL Support in Nginx
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
- Nginx 1.19.6
- Nginx 1.17.5
- Nginx 1.16.1
- Nginx 1.15.0
- Nginx 1.14.0
- Nginx 1.13.12
- Nginx 1.13.8
- Nginx 1.13.2
- Nginx 1.13.0
- Nginx 1.12.2
- Nginx 1.12.1
- Nginx 1.12.0
- Nginx 1.11.13
- Nginx 1.11.10
- Nginx 1.11.7
- Nginx 1.10.3
- Nginx 1.7.7
### Building
First you will need Nginx source package and wolfSSL source code.
Now build and install wolfSSL.
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.
2. Apply patch: patch -p1 < /nginx--wolfssl.patch
Now rebuild Nginx:
1. Configure Nginx with this command (extra options may be added as required):
- ./configure --with-wolfssl=/usr/local --with-http_ssl_module
2. Build Nginx: make
### Testing
#### `nginx-tests`
Nginx has a repository of tests that can be obtained with the following command:
- git clone https://github.com/nginx/nginx-tests.git
To run the tests see the `nginx-tests` README. Tests are expected to pass with
exceptions. An example of running the tests:
1. Change into the `nginx-tests` directory.
2. Run tests: `TEST_NGINX_BINARY=../nginx--wolfssl/objs/nginx prove .`
There are patch sets available in the `nginx-tests-patches` directory for the
nginx-tests testsuite. These patches fix issues with running the tests against
a version of Nginx that was compiled with wolfSSL. They also add some further
debug capabilities. The patch file names are in the structure:
```
---.patch
```
The patch should be applied before running any tests using `patch -p1 < `.
The date and commit hash in the file name refer to the version of nginx-tests
that the patch was prepared for.
#### Debugging `nginx-tests`
To use the new gdbserver feature, the Nginx configuration of the test needs to
be changed to include `master_process off;`. This can be done for all tests
with the following `sed` command. Please note that some tests rely on on a
master and worker process structure. Please check if the test passes without
configuration changes first.
```
sed -e 's/daemon off;/master_process off;\ndaemon off;/g' -i *.t
```
For an easy way to remove all of the `master_process off;` changes, please use
this `perl` command:
```
perl -0777 -i -pe 's/master_process off;\n//g' *.t
```
#### `nginx-tests` Caveats
Without applying the appropriate patchset, there will be failures of SSL tests
for the following reasons:
- using non-default, insecure cipher suites, multiple certificate chains not
supported (ssl_certificate.t)
- using non-default, insecure cipher suites (ssl_stapling.t)
Note: the file ssl_ecc.t in wolfssl-nginx can be used with the Nginx test
system.
Note: the file ssl_stapling.t.patch can be used to patch the ssl_stapling.t
file in nginx-tests to work with wolfSSL. The version available in the testing
repository uses different certs on the same server. This is not supported
by wolfSSL so this patch moves the certs to separate server instances.
#### Internal Tests
There are additional tests available in wolfssl-nginx. These are in addition
to the Nginx tests. The OpenSSL's superapp is required for OCSP Stapling
testing. To test:
1. Change into wolfssl-nginx directory.
2. Run the script: ./test.sh (If using IPv6 then set IPV6=yes.)
3. When working, the number of FAIL and UNKNOWN will be 0.
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 [email protected].
The NGINX patches in this repository are licensed under their respective project licenses.
## Support
For support or build issues, please contact the wolfSSL support team at [email protected].