diff --git a/README.md b/README.md index 02ce36a..9cfaba2 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,8 @@ Binaries will be placed in directories named like `bin-linux-amd64/` and `bin-windows-amd64/`. -- [Install](http://nginx.org/en/docs/install.html) **nginx** +- [Install](https://nginx.org/en/docs/install.html) **nginx** +- To install server certificate on nginx see [docs/install-server-certificate.md](docs/install-server-certificate.md) - To configure nginx see [docs/provider-setup.md](docs/provider-setup.md) ## csaf_uploader diff --git a/docs/install-server-certificate.md b/docs/install-server-certificate.md new file mode 100644 index 0000000..94b0340 --- /dev/null +++ b/docs/install-server-certificate.md @@ -0,0 +1,72 @@ +# Configure TLS Certificate for HTTPS + +## Get a webserver TLS certificate + +There are three ways to get a TLS certificate for your HTTPS server: + 1. Get it from a certificate provider who will run a certificate + authority (CA) and also offers + [extended validation](https://en.wikipedia.org/wiki/Extended_Validation_Certificate) (EV) + for the certificate. This will cost a fee. + If possible, create the private key yourself, + then send a Certificate Signing Request (CSR). + Overall follow the documentation of the CA operator. + 2. Get a domain validated TLS certificate via + [Let's encrypt](https://letsencrypt.org/) without a fee. + See their instruction, e.g. + [certbot for nignx on Ubuntu](https://certbot.eff.org/instructions?ws=nginx&os=ubuntufocal). + 3. Run your own little CA. Which has the major drawback that someone + will have to import the root certificate in the webbrowsers manually. + Suitable for development purposes. + +To decide between 1. and 2. you will need to weight the extra +efforts and costs of the level of extended validation against +a bit of extra trust for the security advisories +that will be served under the domain. + + +## Install the files for ngnix + +Place the certificates on the server machine. +This includes the certificate for your webserver, the intermediate +certificates and the root certificate. The latter may already be on your +machine as part of the trust anchors for webbrowsers. + +Follow the [nginx documentation](https://docs.nginx.com/nginx/admin-guide/security-controls/terminating-ssl-http/) +to further configure TLS with your private key and the certificates. + +We recommend to + * restrict the TLS protocol version and ciphers following a current + recommendation (e.g. [BSI-TR-02102-2](https://www.bsi.bund.de/SharedDocs/Downloads/EN/BSI/Publications/TechGuidelines/TG02102/BSI-TR-02102-2.html)). + + +### Example configuration + +Assuming the relevant server block is in `/etc/nginx/sites-enabled/default`, +change the `listen` configuration and add options so nginx +finds your your private key and the certificate chain. + +```nginx +server { + listen 443 ssl http2 default_server; # ipv4 + listen [::]:443 ssl http2 default_server; # ipv6 + server_name www.example.com + + ssl_certificate /etc/ssl/{domainName}.pem; # or bundle.crt + ssl_certificate_key /etc/ssl/{domainName}.key"; + + ssl_protocols TLSv1.2 TLSv1.3; + # Other Config + # ... +} +``` + +Replace `{domainName}` with the name for your certificate in the example. + +Reload or restart nginx to apply the changes (e.g. `systemctl reload nginx` +on Debian or Ubuntu.) + +Technical hints: + * When allowing or requiring `TLSv1.3` webbrowsers like +Chromium (seen with version 98) may have higher requirements +on the server certificates they allow, +otherwise they do not connect with `ERR_SSL_KEY_USAGE_INCOMPATIBLE`. diff --git a/docs/provider-setup.md b/docs/provider-setup.md index da47fca..d737f03 100644 --- a/docs/provider-setup.md +++ b/docs/provider-setup.md @@ -7,7 +7,7 @@ The following instructions are for an Debian 11 server setup. ```(shell) apt-get install nginx fcgiwrap cp /usr/share/doc/fcgiwrap/examples/nginx.conf /etc/nginx/fcgiwrap.conf -systemctl status fcgiwrap.servic +systemctl status fcgiwrap.service systemctl status fcgiwrap.socket systemctl is-enabled fcgiwrap.service systemctl is-enabled fcgiwrap.socket