From a153906d039c9944a0dba67d56cc7f2bae6f0140 Mon Sep 17 00:00:00 2001 From: "Sascha L. Teichmann" Date: Fri, 18 Aug 2023 11:24:39 +0200 Subject: [PATCH] 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 Co-authored-by: Bernhard Reiter --- cmd/csaf_checker/config.go | 2 +- cmd/csaf_downloader/config.go | 2 +- cmd/csaf_uploader/main.go | 2 +- docs/csaf_aggregator.md | 2 +- docs/csaf_checker.md | 2 +- docs/csaf_downloader.md | 16 +++++++++++++++- docs/csaf_uploader.md | 2 +- docs/examples/aggregator.toml | 2 +- 8 files changed, 22 insertions(+), 8 deletions(-) diff --git a/cmd/csaf_checker/config.go b/cmd/csaf_checker/config.go index ca5c74a..e62a9f5 100644 --- a/cmd/csaf_checker/config.go +++ b/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"` diff --git a/cmd/csaf_downloader/config.go b/cmd/csaf_downloader/config.go index 92ca690..723171b 100644 --- a/cmd/csaf_downloader/config.go +++ b/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"` diff --git a/cmd/csaf_uploader/main.go b/cmd/csaf_uploader/main.go index 48844a7..96293ef 100644 --- a/cmd/csaf_uploader/main.go +++ b/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"` diff --git a/docs/csaf_aggregator.md b/docs/csaf_aggregator.md index 9b92dd7..df250b4 100644 --- a/docs/csaf_aggregator.md +++ b/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. ``` diff --git a/docs/csaf_checker.md b/docs/csaf_checker.md index f555c69..9541b5f 100644 --- a/docs/csaf_checker.md +++ b/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) diff --git a/docs/csaf_downloader.md b/docs/csaf_downloader.md index f2ed419..5be48fa 100644 --- a/docs/csaf_downloader.md +++ b/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). diff --git a/docs/csaf_uploader.md b/docs/csaf_uploader.md index 6bb3213..5926461 100644 --- a/docs/csaf_uploader.md +++ b/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 diff --git a/docs/examples/aggregator.toml b/docs/examples/aggregator.toml index 3595c44..9cf2bf5 100644 --- a/docs/examples/aggregator.toml +++ b/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]]