From 26a8fb0b551124f9628d9ccdb193f61e3b855e3a Mon Sep 17 00:00:00 2001 From: Bernhard Reiter Date: Tue, 23 Aug 2022 14:50:39 +0200 Subject: [PATCH 1/3] Improve provider documentation * Add description about the api endpoints offered by the provider and why create should only be called once. improves #168 --- docs/csaf_provider.md | 21 ++++++++++++++++++++- docs/csaf_uploader.md | 3 +++ 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/docs/csaf_provider.md b/docs/csaf_provider.md index 74c0587..6e63741 100644 --- a/docs/csaf_provider.md +++ b/docs/csaf_provider.md @@ -1,8 +1,27 @@ -`csaf_provider` implements the CGI interface for webservers +`csaf_provider` implements a CGI interface for webservers and reads its configuration from a [TOML](https://toml.io/en/) file. The [setup docs](../README.md#setup-trusted-provider) explain how to wire this up with nginx and where the config file lives. +When installed, two entpoints are offered, +and you should use the [csaf_uploader](../docs/csaf_uploader) +to access them: + +### /api/create + +Must be called once after all configuration values are set. +It will write the `provider-metadata.json` and may write +or update the`security.txt`. + +Once the files exist, they will **not** be overwriten +by additional `create` calls, even if the config values have been changed. +Changes should happen rarely and can be done manually. + + +### /api/upload +Called for each upload of a document and will update +the CSAF structure in the file system accordingly. + ## Provider options diff --git a/docs/csaf_uploader.md b/docs/csaf_uploader.md index c977055..9998351 100644 --- a/docs/csaf_uploader.md +++ b/docs/csaf_uploader.md @@ -28,6 +28,9 @@ Help Options: -h, --help Show this help message ``` E.g. creating the initial directories and files. +This must only be done once, as subsequent `create` calls to the +[csaf_provider](../docs/csaf_provider.md) +may not lead to the desired result. ```bash ./csaf_uploader -a create -u https://localhost/cgi-bin/csaf_provider.go From 2575302fbd653976a37b7bdee2de99d75f897355 Mon Sep 17 00:00:00 2001 From: "Sascha L. Teichmann" Date: Tue, 23 Aug 2022 15:48:17 +0200 Subject: [PATCH 2/3] Mentioned the OpenPGP keys --- docs/csaf_provider.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/csaf_provider.md b/docs/csaf_provider.md index 6e63741..5ff6fe6 100644 --- a/docs/csaf_provider.md +++ b/docs/csaf_provider.md @@ -16,7 +16,8 @@ or update the`security.txt`. Once the files exist, they will **not** be overwriten by additional `create` calls, even if the config values have been changed. Changes should happen rarely and can be done manually. - +Also keep an eye on having the keys in the `.well-known/csaf/openpgp` +folder match the ones mentioned in the `provider-metadata.json`. ### /api/upload Called for each upload of a document and will update From 0e1b90869587196758127db42c0de42c2815d43b Mon Sep 17 00:00:00 2001 From: Fadi Abbud Date: Wed, 24 Aug 2022 09:07:56 +0200 Subject: [PATCH 3/3] Fix typo --- docs/csaf_provider.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/csaf_provider.md b/docs/csaf_provider.md index 5ff6fe6..8996189 100644 --- a/docs/csaf_provider.md +++ b/docs/csaf_provider.md @@ -3,7 +3,7 @@ and reads its configuration from a [TOML](https://toml.io/en/) file. The [setup docs](../README.md#setup-trusted-provider) explain how to wire this up with nginx and where the config file lives. -When installed, two entpoints are offered, +When installed, two endpoints are offered, and you should use the [csaf_uploader](../docs/csaf_uploader) to access them: