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>

cmd/csaf_checker/config.go

@@ -33,7 +33,7 @@ type config struct {
 	Insecure               bool              `long:"insecure" description:"Do not check TLS certificates from provider" toml:"insecure"`
 	ClientCert             *string           `long:"client-cert" description:"TLS client certificate file (PEM encoded data)" value-name:"CERT-FILE" toml:"client_cert"`
 	ClientKey              *string           `long:"client-key" description:"TLS client private key file (PEM encoded data)" value-name:"KEY-FILE" toml:"client_key"`
-	ClientPassphrase       *string           `long:"client-passphrase" description:"Optional passphrase for the client certificate" value-name:"PASSPHRASE" toml:"client_passphrase"`
+	ClientPassphrase       *string           `long:"client-passphrase" description:"Optional passphrase for the client cert (limited, experimental, see downloader doc)" value-name:"PASSPHRASE" toml:"client_passphrase"`
 	Version                bool              `long:"version" description:"Display version of the binary" toml:"-"`
 	Verbose                bool              `long:"verbose" short:"v" description:"Verbose output" toml:"verbose"`
 	Rate                   *float64          `long:"rate" short:"r" description:"The average upper limit of https operations per second (defaults to unlimited)" toml:"rate"`

cmd/csaf_downloader/config.go

@@ -29,7 +29,7 @@ type config struct {
 	IgnoreSignatureCheck bool              `long:"ignoresigcheck" description:"Ignore signature check results, just warn on mismatch" toml:"ignoresigcheck"`
 	ClientCert           *string           `long:"client-cert" description:"TLS client certificate file (PEM encoded data)" value-name:"CERT-FILE" toml:"client_cert"`
 	ClientKey            *string           `long:"client-key" description:"TLS client private key file (PEM encoded data)" value-name:"KEY-FILE" toml:"client_key"`
-	ClientPassphrase     *string           `long:"client-passphrase" description:"Optional passphrase for the client certificate" value-name:"PASSPHRASE" toml:"client_passphrase"`
+	ClientPassphrase     *string           `long:"client-passphrase" description:"Optional passphrase for the client cert (limited, experimental, see doc)" value-name:"PASSPHRASE" toml:"client_passphrase"`
 	Version              bool              `long:"version" description:"Display version of the binary" toml:"-"`
 	Verbose              bool              `long:"verbose" short:"v" description:"Verbose output" toml:"verbose"`
 	Rate                 *float64          `long:"rate" short:"r" description:"The average upper limit of https operations per second (defaults to unlimited)" toml:"rate"`

cmd/csaf_uploader/main.go

@@ -49,7 +49,7 @@ type options struct {
 	Passphrase       *string `short:"P" long:"passphrase" description:"Passphrase to unlock the OpenPGP key" value-name:"PASSPHRASE"`
 	ClientCert       *string `long:"client-cert" description:"TLS client certificate file (PEM encoded data)" value-name:"CERT-FILE.crt"`
 	ClientKey        *string `long:"client-key" description:"TLS client private key file (PEM encoded data)" value-name:"KEY-FILE.pem"`
-	ClientPassphrase *string `long:"client-passphrase" description:"Optional passphrase for the client certificate" value-name:"PASSPHRASE"`
+	ClientPassphrase *string `long:"client-passphrase" description:"Optional passphrase for the client cert (limited, experimental, see downloader doc)" value-name:"PASSPHRASE"`
 
 	PasswordInteractive   bool `short:"i" long:"password-interactive" description:"Enter password interactively" no-ini:"true"`
 	PassphraseInteractive bool `short:"I" long:"passphrase-interactive" description:"Enter OpenPGP key passphrase interactively" no-ini:"true"`

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]]