From 2b3a71bca0635d9ab1ded1c59a82a066b918477f Mon Sep 17 00:00:00 2001 From: Bernhard Reiter Date: Tue, 31 May 2022 15:24:26 +0200 Subject: [PATCH] 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