From 2b3a71bca0635d9ab1ded1c59a82a066b918477f Mon Sep 17 00:00:00 2001 From: Bernhard Reiter Date: Tue, 31 May 2022 15:24:26 +0200 Subject: [PATCH 1/3] Improve setup documentation * Add general hints that this example only shows how the components work together and that a GNU/Linux admin should be consulted for a secure setup. * Adjust the scripts that setup a testing instance to use better permissions as good example. * Add a section about security considerations. --- docs/provider-setup.md | 51 +++++++++++++++++++++++---- docs/scripts/setupProviderForITest.sh | 19 +++++++--- docs/test-keys/Readme.md | 6 +++- 3 files changed, 65 insertions(+), 11 deletions(-) diff --git a/docs/provider-setup.md b/docs/provider-setup.md index 1e1dac2..e9703f3 100644 --- a/docs/provider-setup.md +++ b/docs/provider-setup.md @@ -2,7 +2,10 @@ The provider is meant to run as an CGI program in an nginx enviroment. -The following instructions are for an Debian 11 server setup. +The following instructions are for a Debian 11 server setup +and explain how it works in principle. For a production setup +adjust the examples to your needs. + ```(shell) apt-get install nginx fcgiwrap @@ -89,9 +92,19 @@ Create `cgi-bin` folder if not exists `mkdir -p /usr/lib/cgi-bin/`. Rename and place the `csaf_provider` binary file under `/usr/lib/cgi-bin/csaf_provider.go`. -Create configuration file under `/usr/lib/csaf/config.toml`: +Create configuration file under `/usr/lib/csaf/config.toml` +and make sure is has good restrictive permissions. +It must be readable by the user id, which the webserver fastcgi interface +uses to start the CGI-binary, as `csaf_provider.go` must be able to read it. - +Many setups use `www-data` as user id, so you could do something like + + + + +**This and the other settings are just examples, please adjust permissions and paths according to your webserver and security needs.** + + ```sh # upload_signature = true @@ -103,8 +116,13 @@ canonical_url_prefix = "https://localhost:8443" ``` with suitable [replacements](#provider-options) -(This configuration examples assumes that the private/public keys are available under `/usr/lib/csaf/`). +**Attention:** You need to properly protect the private keys +for the OpenPGP and TLS crypto setup. A few variants are possible +from the software side, but selecting the proper one depends +on your requirements for secure operations and authentication. +Consult an admin with experience for securily operating a web based service +on a GNU/Linux operating system. Create the folders: ```(shell) @@ -152,7 +170,8 @@ Replace {DNSNAME} with a server block file name. ## Provider options Provider has many config options described as following: - - password: Authentication password for accessing the CSAF provider. + - password: Authentication password for accessing the CSAF provider. This is + a simple authentication method useful for testing or as additional shareable password in combination with TLS client certificates. - key: The private OpenPGP key. - folder: Specify the root folder. Default: `/var/www/`. - web: Specify the web folder. Default: `/var/www/html`. @@ -163,7 +182,7 @@ Provider has many config options described as following: - upload_signature: Send signature with the request, an additional input-field in the web interface will be shown to let user enter an ascii armored signature. Default: `false`. - openpgp_url: URL to OpenPGP key-server. Default: `https://openpgp.circl.lu`. - canonical_url_prefix: start of the URL where contents shall be accessible from the internet. Default: `https://$SERVER_NAME`. - - no_passphrase: Let user send password with the request, if set to true the input-field in the web interface will be disappeared. Default: `false`. + - no_passphrase: Let user send the passphrase for the OpenPGP key with the request, if set to true the input-field in the web interface will not appear. Default: `false`. - no_validation: Validate the uploaded CSAF document against the JSON schema. Default: `false`. - no_web_ui: Disable the web interface. Default: `false`. - dynamic_provider_metadata: Take the publisher from the CSAF document. Default: `false`. @@ -173,3 +192,23 @@ Provider has many config options described as following: - provider_metadata.publisher: Set the publisher. Default: `{"category"= "vendor", "name"= "Example", "namespace"= "https://example.com"}`. - upload_limit: Set the upload limit size of the file. Default: `50 MiB`. - issuer: The issuer of the CA, which if set, restricts the writing permission and the accessing to the web-interface to only the client certificates signed with this CA. + + +### Security considerations + +* A good setup variant is to install the provider in a server machine which is + dedicated to the service, so there are only trustable admin users allowed + to login. For example a virtual machine can be used. +* Uploading should be done with the uploader and secured by TLS + client certificates which are individual per person allowed to upload. + This way it can be traced in the log, who did which uploads. +* For TLS client and setups with normal security requirement, + it should be okay to run a small internal + certificate authority like the example + in [development-client-certs.md](development-client-certs.md), + and import the root certificate on the systems that are allowed to + upload. +* The single `password` is only for very simple settings, testing or + (planned feature) as + additional method in the special situation that TLS client certificates + are already necessary to access the network system where the uploader is. diff --git a/docs/scripts/setupProviderForITest.sh b/docs/scripts/setupProviderForITest.sh index b3faf6a..f6c2a66 100755 --- a/docs/scripts/setupProviderForITest.sh +++ b/docs/scripts/setupProviderForITest.sh @@ -14,7 +14,7 @@ set -e sudo chgrp -R www-data /var/www -sudo chmod -R g+w /var/www +sudo chmod -R g+ws /var/www export NGINX_CONFIG_PATH=/etc/nginx/sites-available/default export DNS_NAME=csaf.data.security.localhost @@ -73,11 +73,22 @@ pushd ../.. export PATH=$PATH:/usr/local/go/bin make build_linux # Place the binary under the corresponding path. -sudo mkdir -p /usr/lib/cgi-bin/ +sudo mkdir /usr/lib/cgi-bin/ +sudo chgrp www-data /usr/lib/cgi-bin/ +sudo chmod o-rwx /usr/lib/cgi-bin/ sudo cp bin-linux-amd64/csaf_provider /usr/lib/cgi-bin/csaf_provider.go -sudo mkdir -p /usr/lib/csaf/ +sudo mkdir /usr/lib/csaf/ +sudo chgrp www-data /usr/lib/csaf/ +sudo chmod g+s,o-rwx /usr/lib/csaf/ +sudo touch /usr/lib/csaf/config.toml +sudo chgrp www-data /usr/lib/csaf/config.toml +sudo chmod g+r,o-rwx /usr/lib/csaf/config.toml + sudo cp docs/test-keys/*.asc /usr/lib/csaf/ +sudo chgrp www-data /usr/lib/csaf/private.asc +sudo chmod o-rwx /usr/lib/csaf/private.asc + # Configuration file echo ' # upload_signature = true @@ -86,7 +97,7 @@ key = "/usr/lib/csaf/private.asc" #tlps = ["green", "red"] canonical_url_prefix = "https://localhost:8443" #no_passphrase = true -' | sudo tee /usr/lib/csaf/config.toml +' | sudo tee --append /usr/lib/csaf/config.toml # Create the Folders curl https://localhost:8443/cgi-bin/csaf_provider.go/create --cert-type p12 --cert ~/devca1/testclient1.p12 --insecure diff --git a/docs/test-keys/Readme.md b/docs/test-keys/Readme.md index 70c2b93..743a107 100644 --- a/docs/test-keys/Readme.md +++ b/docs/test-keys/Readme.md @@ -1,4 +1,8 @@ -OpenPGP key-pair for testing. +OpenPGP key-pair for testing only. + +Note: as this keypair is fully public, **do not use it for production**. +Create your own keypair with the security properties and operational +measures you need. This has been created with: * gpg (GnuPG) 2.2.19 From 773047a91dd9c56ece3a54af84173a6b8418240b Mon Sep 17 00:00:00 2001 From: Bernhard Reiter Date: Tue, 31 May 2022 15:32:41 +0200 Subject: [PATCH 2/3] Fix script at one mkdir for existing directory --- docs/scripts/setupProviderForITest.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/scripts/setupProviderForITest.sh b/docs/scripts/setupProviderForITest.sh index f6c2a66..d334dbb 100755 --- a/docs/scripts/setupProviderForITest.sh +++ b/docs/scripts/setupProviderForITest.sh @@ -73,7 +73,7 @@ pushd ../.. export PATH=$PATH:/usr/local/go/bin make build_linux # Place the binary under the corresponding path. -sudo mkdir /usr/lib/cgi-bin/ +sudo mkdir -p /usr/lib/cgi-bin/ sudo chgrp www-data /usr/lib/cgi-bin/ sudo chmod o-rwx /usr/lib/cgi-bin/ sudo cp bin-linux-amd64/csaf_provider /usr/lib/cgi-bin/csaf_provider.go From 873fa9ccb40dbfaecea8e726911844f6bcd4f5db Mon Sep 17 00:00:00 2001 From: Bernhard Reiter Date: Tue, 31 May 2022 15:58:46 +0200 Subject: [PATCH 3/3] Improve docs * Correct language in a few points. * Move upload example to use TLS client certificates as recommended. --- README.md | 4 ++-- docs/provider-setup.md | 32 ++++++++++++++++++-------------- 2 files changed, 20 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 8bd497e..350e832 100644 --- a/README.md +++ b/README.md @@ -50,8 +50,8 @@ Binaries will be placed in directories named like `bin-linux-amd64/` and `bin-wi ### Setup (Trusted Provider) -- [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) +- [Install](https://nginx.org/en/docs/install.html) **nginx** +- To install a TLS 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) - To configure nginx for client certificate authentication see [docs/client-certificate-setup.md](docs/client-certificate-setup.md) diff --git a/docs/provider-setup.md b/docs/provider-setup.md index e9703f3..5fa364f 100644 --- a/docs/provider-setup.md +++ b/docs/provider-setup.md @@ -11,7 +11,7 @@ adjust the examples to your needs. apt-get install nginx fcgiwrap cp /usr/share/doc/fcgiwrap/examples/nginx.conf /etc/nginx/fcgiwrap.conf ``` -Check if the CGI server and the fcgiwrap Socket active (running): +Check if the CGI server and the fcgiwrap Socket are active (running): ```bash systemctl status fcgiwrap.service systemctl status fcgiwrap.socket @@ -87,17 +87,18 @@ server { ``` Reload nginx to apply the changes (e.g. ```systemctl reload nginx``` on Debian or Ubuntu). -Create `cgi-bin` folder if not exists `mkdir -p /usr/lib/cgi-bin/`. +Create `cgi-bin` folder if it not exists: `mkdir -p /usr/lib/cgi-bin/`. Rename and place the `csaf_provider` binary file under `/usr/lib/cgi-bin/csaf_provider.go`. Create configuration file under `/usr/lib/csaf/config.toml` -and make sure is has good restrictive permissions. -It must be readable by the user id, which the webserver fastcgi interface -uses to start the CGI-binary, as `csaf_provider.go` must be able to read it. +and make sure is has good, restrictive permissions. +It must be readable by the user(id), which the webserver's fastcgi interface +uses to start the CGI-binary with, +as `csaf_provider.go` must be able to read it. -Many setups use `www-data` as user id, so you could do something like +Many systems use `www-data` as user id, so you could do something like @@ -126,15 +127,18 @@ on a GNU/Linux operating system. Create the folders: ```(shell) -curl https://192.168.56.102/cgi-bin/csaf_provider.go/create --cert-type p12 --cert {clientCertificatfile} +curl https://192.168.56.102/cgi-bin/csaf_provider.go/create --cert-type p12 --cert {clientCertificat.p12} ``` -Replace {clientCertificate} with the client certificate file. +Replace {clientCertificate.p12} with the client certificate file +in pkcs12 format which includes the corresponding key as well. + Or using the uploader: ```(shell) -./csaf_uploader -a create -u http://192.168.56.102/cgi-bin/csaf_provider.go -p {password} +./csaf_uploader --action create --url https://192.168.56.102/cgi-bin/csaf_provider.go --client-cert {clientCert.crt} --client-key {clientKey.pem} ``` -Replace {password} with the password used for the authentication with csaf_provider. -This needs to set the `password` option in `config.toml`. + +Again replacing `{clientCert.crt}` and `{clientKey.pem}` accordingly. + To let nginx resolves the DNS record `csaf.data.security.domain.tld` to fulfill the [Requirement 10](https://docs.oasis-open.org/csaf/csaf/v2.0/cs01/csaf-v2.0-cs01.html#7110-requirement-10-dns-path) configure a new server block (virtual host) in a separated file under `/etc/nginx/available-sites/{DNSNAME}` like following: @@ -202,12 +206,12 @@ Provider has many config options described as following: * Uploading should be done with the uploader and secured by TLS client certificates which are individual per person allowed to upload. This way it can be traced in the log, who did which uploads. -* For TLS client and setups with normal security requirement, +* For TLS client setups with normal security requirements, it should be okay to run a small internal certificate authority like the example in [development-client-certs.md](development-client-certs.md), - and import the root certificate on the systems that are allowed to - upload. + and import the root certificate on the systems that have users which + want to upload. * The single `password` is only for very simple settings, testing or (planned feature) as additional method in the special situation that TLS client certificates