mirror of
https://github.com/gocsaf/csaf.git
synced 2025-12-22 11:55:40 +01:00
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.
This commit is contained in:
Bernhard Reiter
parent
562538122a
commit
2b3a71bca0
3 changed files with 65 additions and 11 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue