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

@@ -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.

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.

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.

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.

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.

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.

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.