{"id":28610903,"url":"https://github.com/wolfSSL/wolfssl-nginx","last_synced_at":"2025-06-11T23:02:46.053Z","repository":{"id":41119386,"uuid":"78588323","full_name":"wolfSSL/wolfssl-nginx","owner":"wolfSSL","description":"Adds wolfSSL support to Nginx.","archived":false,"fork":false,"pushed_at":"2025-03-13T00:58:42.000Z","size":230,"stargazers_count":35,"open_issues_count":2,"forks_count":13,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-27T08:36:31.930Z","etag":null,"topics":["gplv3","http-tls13","nginx","nginx-source","secure-webserver","security","tls13","wolfssl","wolfssl-nginx","wolfssl-support"],"latest_commit_sha":null,"homepage":"https://www.wolfssl.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wolfSSL.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-01-11T00:45:18.000Z","updated_at":"2025-03-13T00:58:46.000Z","dependencies_parsed_at":"2025-03-13T01:28:21.311Z","dependency_job_id":"24f216a1-9bbb-4b56-a521-f7e8cf9ea29d","html_url":"https://github.com/wolfSSL/wolfssl-nginx","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/wolfSSL/wolfssl-nginx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfssl-nginx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfssl-nginx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfssl-nginx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfssl-nginx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wolfSSL","download_url":"https://codeload.github.com/wolfSSL/wolfssl-nginx/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wolfSSL%2Fwolfssl-nginx/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259360728,"owners_count":22845817,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gplv3","http-tls13","nginx","nginx-source","secure-webserver","security","tls13","wolfssl","wolfssl-nginx","wolfssl-support"],"created_at":"2025-06-11T23:01:52.073Z","updated_at":"2025-06-11T23:02:46.047Z","avatar_url":"https://github.com/wolfSSL.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"# wolfssl-nginx\n\n## wolfSSL Support in Nginx\n\nwolfSSL is supported in Nginx. There are minor changes to the Nginx code base\nand recompilation is required.\n\nThe tested versions:\n - wolfSSL 5.1.0\n - wolfSSL 3.14\n - wolfSSL 3.13.0 (with patch applied: wolfssl-3.13.0-nginx.patch)\n - Nginx 1.21.4\n - Nginx 1.19.6\n - Nginx 1.17.5\n - Nginx 1.16.1\n - Nginx 1.15.0\n - Nginx 1.14.0\n - Nginx 1.13.12\n - Nginx 1.13.8\n - Nginx 1.13.2\n - Nginx 1.13.0\n - Nginx 1.12.2\n - Nginx 1.12.1\n - Nginx 1.12.0\n - Nginx 1.11.13\n - Nginx 1.11.10\n - Nginx 1.11.7\n - Nginx 1.10.3\n - Nginx 1.7.7\n\n### Building\n\nFirst you will need Nginx source package and wolfSSL source code.\n\nNow build and install wolfSSL.\nPlease make sure to configure wolfSSL with ```./configure --prefix=/usr/local --enable-nginx```.\n\nTo enable wolfSSL support in Nginx the source code must be patched:\n 1. Change into the Nginx source directory.\n 2. Apply patch: patch -p1 \u003c \u003cwolfssl-nginx\u003e/nginx-\u003cnginx-version\u003e-wolfssl.patch\n\nNow rebuild Nginx:\n 1. Configure Nginx with this command (extra options may be added as required):\n   - ./configure --with-wolfssl=/usr/local --with-http_ssl_module\n 2. Build Nginx: make\n\n### Testing\n\n#### `nginx-tests`\n\nNginx has a repository of tests that can be obtained with the following command:\n - git clone https://github.com/nginx/nginx-tests.git\n\nTo run the tests see the `nginx-tests` README. Tests are expected to pass with \nexceptions. An example of running the tests:\n 1. Change into the `nginx-tests` directory.\n 2. Run tests: `TEST_NGINX_BINARY=../nginx-\u003cnginx-version\u003e-wolfssl/objs/nginx prove .`\n\nThere are patch sets available in the `nginx-tests-patches` directory for the\nnginx-tests testsuite. These patches fix issues with running the tests against\na version of Nginx that was compiled with wolfSSL. They also add some further\ndebug capabilities. The patch file names are in the structure:\n\n```\n\u003cyear\u003e-\u003cmonth\u003e-\u003cday\u003e-\u003cnginx-tests commit\u003e.patch\n```\n\nThe patch should be applied before running any tests using `patch -p1 \u003c \u003cpath/to/patch\u003e`.\nThe date and commit hash in the file name refer to the version of nginx-tests\nthat the patch was prepared for.\n\n#### Debugging `nginx-tests`\n\nTo use the new gdbserver feature, the Nginx configuration of the test needs to\nbe changed to include `master_process off;`. This can be done for all tests\nwith the following `sed` command. Please note that some tests rely on on a\nmaster and worker process structure. Please check if the test passes without\nconfiguration changes first.\n\n```\nsed -e 's/daemon off;/master_process off;\\ndaemon off;/g' -i *.t\n```\n\nFor an easy way to remove all of the `master_process off;` changes, please use\nthis `perl` command: \n\n```\nperl -0777 -i -pe 's/master_process off;\\n//g' *.t\n```\n\n#### `nginx-tests` Caveats\n\nWithout applying the appropriate patchset, there will be failures of SSL tests\nfor the following reasons:\n - using non-default, insecure cipher suites, multiple certificate chains not\n   supported (ssl_certificate.t)\n - using non-default, insecure cipher suites (ssl_stapling.t)\n\nNote: the file ssl_ecc.t in wolfssl-nginx can be used with the Nginx test\nsystem.\nNote: the file ssl_stapling.t.patch can be used to patch the ssl_stapling.t\nfile in nginx-tests to work with wolfSSL. The version available in the testing\nrepository uses different certs on the same server. This is not supported\nby wolfSSL so this patch moves the certs to separate server instances.\n\n#### Internal Tests\n\nThere are additional tests available in wolfssl-nginx. These are in addition\nto the Nginx tests. The OpenSSL's superapp is required for OCSP Stapling\ntesting. To test:\n 1. Change into wolfssl-nginx directory.\n 2. Run the script: ./test.sh (If using IPv6 then set IPV6=yes.)\n 3. When working, the number of FAIL and UNKNOWN will be 0.\n\nTesting is only supported on Linux with bash.\n\n## Post-Quantum Algorithms\n\nYou can now enable the use of post-quantum algorithms for your HTTPS connections over TLS 1.3. As of the writing of this passage, there has been a lot of flux within the specifications of post-quantum algorithms which has affected backwards compatibility. To that end, here are the version of software that were used to generate these instructions:\n\n- https://github.com/wolfSSL/wolfssl.git at 539056e7\n- https://github.com/anhu/curl.git at branch wolfssl_pq_rename\n- https://github.com/wolfSSL/osp.git at 07072fb2\n- https://github.com:anhu/wolfssl-nginx.git at branch pq-fixup\n- https://nginx.org/download/nginx-1.21.4.tar.gz\n\nNOTE: for curl and wolfssl-nginx the upstream repo likely already have these\n      branches merged in.\n\nFirst, you will need to build the OpenQuantumSafe group's liboqs and their fork of OpenSSL to generate the certificate chain that uses ML-DSA signature scheme. Alternatively, for your convenience, we have already generated some test certificates and they can be found in the wolfSSL OSP repo in the oqs directory.\n\nWhen building wolfSSL, you will need to add a couple extra flags:\n\n```\n./configure --prefix=/usr/local --enable-nginx --enable-kyber --enable-dilithium\nmake all\nmake check\nsudo make install\n```\n\nNow, you can continue on with the instructions for building nginx above, but also apply the nginx-1.21.4-pq.patch patch.\n\nNow 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:\n\n```\n    server {\n        listen                    443 ssl;\n        server_name               localhost;\n\n        ssl_certificate           /path/to/osp/oqs/mldsa87_entity_cert.pem\n        ssl_certificate_key       /path/to/osp/oqs/mldsa87_entity_key.pem\n\n        ssl_session_cache         shared:SSL:1m;\n        ssl_session_timeout       5m;\n\n        ssl_protocols             TLSv1.3;\n        ssl_ciphers               TLS_AES_256_GCM_SHA384;\n        ssl_prefer_server_ciphers on;\n\n        location / {\n            root   html;\n            index  index.html index.htm;\n        }\n    }\n```\n\nNOTE: You will need to change the path of the certificate and key.\n\nYou can now execute the nginx web server by doing the following:\n\n```\nsudo /usr/local/nginx/sbin/nginx\n```\n\nCheck `/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.\n\nNOTE: You will need to change the path of the root certificate and use your IP address.\n\n## Licensing\n\nwolfSSL 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.\n\nThe NGINX patches in this repository are licensed under their respective project licenses.\n\n## Support\n\nFor support or build issues, please contact the wolfSSL support team at support@wolfssl.com.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FwolfSSL%2Fwolfssl-nginx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FwolfSSL%2Fwolfssl-nginx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FwolfSSL%2Fwolfssl-nginx/lists"}