Document that client-passphrase option is experimental

* Label the option experimental and limited at all places.
 * Point to the downloader documentation as single point to write more.
 * Add more hints on how the old PEM block encryption is experimental
   and why it often shall not be used.
---------

Co-authored-by: JanHoefelmeyer <hoefelmeyer.jan@gmail.com>
Co-authored-by: Bernhard Reiter <bernhard@intevation.de>

docs/csaf_aggregator.md

@@ -98,7 +98,7 @@ allow_single_provider   // debugging option (default false)
 ignorepattern           // patterns of advisory URLs to be ignored (see checker doc for details)
 client_cert             // path to client certificate to access access-protected advisories
 client_key              // path to client key to access access-protected advisories
-client_passphrase       // client passphrase to access access-protected advisories
+client_passphrase       // optional client cert passphrase (limited, experimental, see downloader doc)
 header                  // adds extra HTTP header fields to the client
 timerange               // Accepted time range of advisories to handle. See checker doc for details.
 ```

docs/csaf_checker.md

@@ -12,7 +12,7 @@ Application Options:
       --insecure                        Do not check TLS certificates from provider
       --client-cert=CERT-FILE           TLS client certificate file (PEM encoded data)
       --client-key=KEY-FILE             TLS client private key file (PEM encoded data)
-      --client-passphrase=PASSPHRASE    Optional passphrase for the client certificate
+      --client-passphrase=PASSPHRASE    Optional passphrase for the client cert (limited, experimental, see downloader doc)
       --version                         Display version of the binary
   -v, --verbose                         Verbose output
   -r, --rate=                           The average upper limit of https operations per second (defaults to unlimited)

docs/csaf_downloader.md

@@ -12,7 +12,7 @@ Application Options:
       --ignoresigcheck                  Ignore signature check results, just warn on mismatch
       --client-cert=CERT-FILE           TLS client certificate file (PEM encoded data)
       --client-key=KEY-FILE             TLS client private key file (PEM encoded data)
-      --client-passphrase=PASSPHRASE    Optional passphrase for the client certificate
+      --client-passphrase=PASSPHRASE    Optional passphrase for the client cert (limited, experimental, see doc)
       --version                         Display version of the binary
   -v, --verbose                         Verbose output
   -r, --rate=                           The average upper limit of https operations per second (defaults to
@@ -113,4 +113,18 @@ In the config file this has to be noted as:
 ignorepattern = [".*white.*", ".*red.*"]
 ```
 
+#### beware of client cert passphrase
+
+The `client-passphrase` option implements a legacy private
+key protection mechanism based on RFC 1423, see
+[DecryptPEMBlock](https://pkg.go.dev/crypto/x509@go1.20.6#DecryptPEMBlock).
+Thus it considered experimental and most likely to be removed
+in a future release. Please only use this option, if you fully understand
+the security implications!
+Note that for fully automated processes, it usually not make sense
+to protect the client certificate's private key with a passphrase.
+Because the passphrase has to be accessible to the process anyway to run
+unattented. In this situation the processing environment should be secured
+properly instead.
+
 [^1]: Accepted syntax is described [here](https://github.com/google/re2/wiki/Syntax).

docs/csaf_uploader.md

@@ -16,7 +16,7 @@ Application Options:
   -P, --passphrase=PASSPHRASE               Passphrase to unlock the OpenPGP key
       --client-cert=CERT-FILE.crt           TLS client certificate file (PEM encoded data)
       --client-key=KEY-FILE.pem             TLS client private key file (PEM encoded data)
-      --client-passphrase=PASSPHRASE        Optional passphrase for the client certificate
+      --client-passphrase=PASSPHRASE        Optional passphrase for the client cert (limited, experimental, see downloader doc)
   -i, --password-interactive                Enter password interactively
   -I, --passphrase-interactive              Enter OpenPGP key passphrase interactively
       --insecure                            Do not check TLS certificates from provider

docs/examples/aggregator.toml

@@ -42,7 +42,7 @@ insecure = true
   write_indices = true
   client_cert = "./../devca1/testclient1.crt"
   client_key = "./../devca1/testclient1-key.pem"
-#  client_passphrase =
+#  client_passphrase = # Limited and experimental, see downloader doc.
 #  header =
 
 [[providers]]