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

@@ -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.
 
-<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../docs/scripts/setupProviderForITest.sh&lines=83-88) -->
+Many setups use `www-data` as user id, so you could do something like
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../docs/scripts/setupProviderForITest.sh&lines=84-86) -->
+<!-- MARKDOWN-AUTO-DOCS:END -->
+
+**This and the other settings are just examples, please adjust permissions and paths according to your webserver and security needs.**
+
+<!-- MARKDOWN-AUTO-DOCS:START (CODE:src=../docs/scripts/setupProviderForITest.sh&lines=94-99) -->
 <!-- The below code snippet is automatically added from ../docs/scripts/setupProviderForITest.sh -->
 ```sh
 # upload_signature = true
@@ -103,8 +116,13 @@ canonical_url_prefix = "https://localhost:8443"
 ```
 <!-- MARKDOWN-AUTO-DOCS:END -->
 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.

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

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