From 65651dc02b2833e004a856df6fd5364d5b994de9 Mon Sep 17 00:00:00 2001 From: Daniel Stenberg Date: Wed, 5 Jun 2024 10:10:47 +0200 Subject: [PATCH] cmdline: expand proxy option explanations - do less references to other options - provide more specific text about proxies - added more see-also references Closes #13887 --- docs/cmdline-opts/proxy-cacert.md | 8 +++++++- docs/cmdline-opts/proxy-cert-type.md | 10 +++++++++- docs/cmdline-opts/proxy-cert.md | 10 +++++++++- docs/cmdline-opts/proxy-crlfile.md | 6 +++++- docs/cmdline-opts/proxy-key-type.md | 5 ++++- docs/cmdline-opts/proxy-key.md | 4 +++- docs/cmdline-opts/proxy-negotiate.md | 1 + docs/cmdline-opts/proxy-ntlm.md | 1 + docs/cmdline-opts/proxy-pass.md | 4 +++- docs/cmdline-opts/proxy-service-name.md | 3 ++- docs/cmdline-opts/proxy-ssl-allow-beast.md | 13 ++++++++++++- docs/cmdline-opts/proxy-tlsauthtype.md | 7 ++++++- docs/cmdline-opts/proxy-tlspassword.md | 8 +++++++- docs/cmdline-opts/proxy-tlsuser.md | 6 +++++- docs/cmdline-opts/proxy-tlsv1.md | 5 ++++- docs/cmdline-opts/ssl-allow-beast.md | 11 +++++++---- docs/cmdline-opts/tlspassword.md | 4 ++-- 17 files changed, 87 insertions(+), 19 deletions(-) diff --git a/docs/cmdline-opts/proxy-cacert.md b/docs/cmdline-opts/proxy-cacert.md index ec0dd9f143..189ed390d2 100644 --- a/docs/cmdline-opts/proxy-cacert.md +++ b/docs/cmdline-opts/proxy-cacert.md @@ -18,4 +18,10 @@ Example: # `--proxy-cacert` -Same as --cacert but used in HTTPS proxy context. +Use the specified certificate file to verify the HTTPS proxy. The file may +contain multiple CA certificates. The certificate(s) must be in PEM format. + +This allows you to use a different trust for the proxy compared to the remote +server connected to via the proxy. + +Equivalent to --cacert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cert-type.md b/docs/cmdline-opts/proxy-cert-type.md index 3f46bb6181..c2e8ed1ec1 100644 --- a/docs/cmdline-opts/proxy-cert-type.md +++ b/docs/cmdline-opts/proxy-cert-type.md @@ -9,10 +9,18 @@ Category: proxy tls Multi: single See-also: - proxy-cert + - proxy-key Example: - --proxy-cert-type PEM --proxy-cert file -x https://proxy $URL --- # `--proxy-cert-type` -Same as --cert-type but used in HTTPS proxy context. +Set type of the provided client certificate when using HTTPS proxy. PEM, DER, +ENG and P12 are recognized types. + +The default type depends on the TLS backend and is usually PEM, however for +Secure Transport and Schannel it is P12. If --proxy-cert is a pkcs11: URI then +ENG is the default type. + +Equivalent to --cert-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-cert.md b/docs/cmdline-opts/proxy-cert.md index 3068f3cd10..a588329d06 100644 --- a/docs/cmdline-opts/proxy-cert.md +++ b/docs/cmdline-opts/proxy-cert.md @@ -8,6 +8,8 @@ Added: 7.52.0 Category: proxy tls Multi: single See-also: + - proxy + - proxy-key - proxy-cert-type Example: - --proxy-cert file -x https://proxy $URL @@ -15,4 +17,10 @@ Example: # `--proxy-cert` -Same as --cert but used in HTTPS proxy context. +Use the specified client certificate file when communicating with an HTTPS +proxy. The certificate must be in PKCS#12 format if using Secure Transport, or +PEM format if using any other engine. If the optional password is not +specified, it is queried for on the terminal. Use --proxy-key to provide the +private key. + +This option is the equivalent to --cert but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-crlfile.md b/docs/cmdline-opts/proxy-crlfile.md index ab47fb0a0d..726e449557 100644 --- a/docs/cmdline-opts/proxy-crlfile.md +++ b/docs/cmdline-opts/proxy-crlfile.md @@ -16,4 +16,8 @@ Example: # `--proxy-crlfile` -Same as --crlfile but used in HTTPS proxy context. +Provide filename for a PEM formatted file with a Certificate Revocation List +that specifies peer certificates that are considered revoked when +communicating with an HTTPS proxy. + +Equivalent to --crlfile but only used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-key-type.md b/docs/cmdline-opts/proxy-key-type.md index 8740935b56..587c13c592 100644 --- a/docs/cmdline-opts/proxy-key-type.md +++ b/docs/cmdline-opts/proxy-key-type.md @@ -16,4 +16,7 @@ Example: # `--proxy-key-type` -Same as --key-type but used in HTTPS proxy context. +Specify the private key file type your --proxy-key provided private key uses. +DER, PEM, and ENG are supported. If not specified, PEM is assumed. + +Equivalent to --key-type but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-key.md b/docs/cmdline-opts/proxy-key.md index cfe507845e..7caa636e36 100644 --- a/docs/cmdline-opts/proxy-key.md +++ b/docs/cmdline-opts/proxy-key.md @@ -16,4 +16,6 @@ Example: # `--proxy-key` -Same as --key but used in HTTPS proxy context. +Specify the filename for your private key when using client certificates with +your HTTPS proxy. This option is the equivalent to --key but used in HTTPS +proxy context. diff --git a/docs/cmdline-opts/proxy-negotiate.md b/docs/cmdline-opts/proxy-negotiate.md index 9bedf5dc4a..0285155c6a 100644 --- a/docs/cmdline-opts/proxy-negotiate.md +++ b/docs/cmdline-opts/proxy-negotiate.md @@ -9,6 +9,7 @@ Multi: mutex See-also: - proxy-anyauth - proxy-basic + - proxy-service-name Example: - --proxy-negotiate --proxy-user user:passwd -x proxy $URL --- diff --git a/docs/cmdline-opts/proxy-ntlm.md b/docs/cmdline-opts/proxy-ntlm.md index f8375a620e..e403f98ec3 100644 --- a/docs/cmdline-opts/proxy-ntlm.md +++ b/docs/cmdline-opts/proxy-ntlm.md @@ -9,6 +9,7 @@ Multi: mutex See-also: - proxy-negotiate - proxy-anyauth + - proxy-user Example: - --proxy-ntlm --proxy-user user:passwd -x http://proxy $URL --- diff --git a/docs/cmdline-opts/proxy-pass.md b/docs/cmdline-opts/proxy-pass.md index feba6e0838..596bce0766 100644 --- a/docs/cmdline-opts/proxy-pass.md +++ b/docs/cmdline-opts/proxy-pass.md @@ -16,4 +16,6 @@ Example: # `--proxy-pass` -Same as --pass but used in HTTPS proxy context. +Passphrase for the private key for HTTPS proxy client certificate. + +Equivalent to --pass but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-service-name.md b/docs/cmdline-opts/proxy-service-name.md index 534222f449..b3d665d8b4 100644 --- a/docs/cmdline-opts/proxy-service-name.md +++ b/docs/cmdline-opts/proxy-service-name.md @@ -10,10 +10,11 @@ Multi: single See-also: - service-name - proxy + - proxy-negotiate Example: - --proxy-service-name "shrubbery" -x proxy $URL --- # `--proxy-service-name` -Set the service name for proxy negotiation. +Set the service name for SPNEGO when doing proxy authentication. diff --git a/docs/cmdline-opts/proxy-ssl-allow-beast.md b/docs/cmdline-opts/proxy-ssl-allow-beast.md index f2deedbb55..875e70ccb2 100644 --- a/docs/cmdline-opts/proxy-ssl-allow-beast.md +++ b/docs/cmdline-opts/proxy-ssl-allow-beast.md @@ -15,4 +15,15 @@ Example: # `--proxy-ssl-allow-beast` -Same as --ssl-allow-beast but used in HTTPS proxy context. +Do not work around a security flaw in the TLS1.0 protocol known as BEAST when +communicating to an HTTPS proxy. If this option is not used, the TLS layer may +use workarounds known to cause interoperability problems with some older +server implementations. + +This option only changes how curl does TLS 1.0 with an HTTPS proxy and has no +effect on later TLS versions. + +**WARNING**: this option loosens the TLS security, and by using this flag you +ask for exactly that. + +Equivalent to --ssl-allow-beast but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsauthtype.md b/docs/cmdline-opts/proxy-tlsauthtype.md index 067e4c5988..684a7d55ef 100644 --- a/docs/cmdline-opts/proxy-tlsauthtype.md +++ b/docs/cmdline-opts/proxy-tlsauthtype.md @@ -10,10 +10,15 @@ Multi: single See-also: - proxy - proxy-tlsuser + - proxy-tlspassword Example: - --proxy-tlsauthtype SRP -x https://proxy $URL --- # `--proxy-tlsauthtype` -Same as --tlsauthtype but used in HTTPS proxy context. +Set TLS authentication type with HTTPS proxy. The only supported option is +`SRP`, for TLS-SRP (RFC 5054). This option works only if the underlying +libcurl is built with TLS-SRP support. + +Equivalent to --tlsauthtype but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlspassword.md b/docs/cmdline-opts/proxy-tlspassword.md index 3c6d06c6a5..fe9ae7d2e2 100644 --- a/docs/cmdline-opts/proxy-tlspassword.md +++ b/docs/cmdline-opts/proxy-tlspassword.md @@ -16,4 +16,10 @@ Example: # `--proxy-tlspassword` -Same as --tlspassword but used in HTTPS proxy context. +Set password to use with the TLS authentication method specified with +--proxy-tlsauthtype when using HTTPS proxy. Requires that --proxy-tlsuser is +set. + +This option does not work with TLS 1.3. + +Equivalent to --tlspassword but used in HTTPS proxy context. diff --git a/docs/cmdline-opts/proxy-tlsuser.md b/docs/cmdline-opts/proxy-tlsuser.md index 1c626ee754..3517701119 100644 --- a/docs/cmdline-opts/proxy-tlsuser.md +++ b/docs/cmdline-opts/proxy-tlsuser.md @@ -16,4 +16,8 @@ Example: # `--proxy-tlsuser` -Same as --tlsuser but used in HTTPS proxy context. +Set username for use for HTTPS proxy with the TLS authentication method +specified with --proxy-tlsauthtype. Requires that --proxy-tlspassword also is +set. + +This option does not work with TLS 1.3. diff --git a/docs/cmdline-opts/proxy-tlsv1.md b/docs/cmdline-opts/proxy-tlsv1.md index 0dda72f4b6..7b322e3a32 100644 --- a/docs/cmdline-opts/proxy-tlsv1.md +++ b/docs/cmdline-opts/proxy-tlsv1.md @@ -14,4 +14,7 @@ Example: # `--proxy-tlsv1` -Same as --tlsv1 but used in HTTPS proxy context. +Use at least TLS version 1.x when negotiating with an HTTPS proxy. That means +TLS version 1.0 or higher + +Equivalent to --tlsv1 but for an HTTPS proxy context. diff --git a/docs/cmdline-opts/ssl-allow-beast.md b/docs/cmdline-opts/ssl-allow-beast.md index 29f2b450c2..f9933b77af 100644 --- a/docs/cmdline-opts/ssl-allow-beast.md +++ b/docs/cmdline-opts/ssl-allow-beast.md @@ -16,9 +16,12 @@ Example: # `--ssl-allow-beast` -Do not work around a security flaw in the SSL3 and TLS1.0 protocols known as -BEAST. If this option is not used, the SSL layer may use workarounds known to -cause interoperability problems with some older SSL implementations. +Do not work around a security flaw in the TLS1.0 protocol known as BEAST. If +this option is not used, the TLS layer may use workarounds known to cause +interoperability problems with some older server implementations. -**WARNING**: this option loosens the SSL security, and by using this flag you +This option only changes how curl does TLS 1.0 and has no effect on later TLS +versions. + +**WARNING**: this option loosens the TLS security, and by using this flag you ask for exactly that. diff --git a/docs/cmdline-opts/tlspassword.md b/docs/cmdline-opts/tlspassword.md index 4b1817994f..6a1bb23a15 100644 --- a/docs/cmdline-opts/tlspassword.md +++ b/docs/cmdline-opts/tlspassword.md @@ -16,7 +16,7 @@ Example: # `--tlspassword` -Set password for use with the TLS authentication method specified with ---tlsauthtype. Requires that --tlsuser also be set. +Set password to use with the TLS authentication method specified with +--tlsauthtype. Requires that --tlsuser is set. This option does not work with TLS 1.3. -- 2.47.3