doc/man{1,3}: fix details on IPv6 host addresses and of whitespace in no_proxy

Reviewed-by: Viktor Dukhovni <viktor@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25010)

doc/man1/openssl-cmp.pod.in

@@ -513,6 +513,7 @@ Reason numbers defined in RFC 5280 are:
 The I<host> domain name or IP address and optionally I<port>
 of the CMP server to connect to using HTTP(S).
 IP address may be for v4 or v6, such as C<127.0.0.1> or C<[::1]> for localhost.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 
 This option excludes I<-port> and I<-use_mock_srv>.
 It is ignored if I<-rspin> is given with enough filename arguments.
@@ -527,6 +528,7 @@ If a path is included it provides the default value for the B<-path> option.
 
 The HTTP(S) proxy server to use for reaching the CMP server unless B<-no_proxy>
 applies, see below.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that
 the optional C<http://> or C<https://> prefix is ignored (note that using TLS
 may be required by B<-tls_used> or B<-server> with the prefix C<https>),

doc/man1/openssl-ocsp.pod.in

@@ -31,7 +31,7 @@ B<openssl> B<ocsp>
 [B<-url> I<URL>]
 [B<-host> I<host>:I<port>]
 [B<-path> I<pathname>]
-[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]>]
+[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>]
 [B<-no_proxy> I<addresses>]
 [B<-header>]
 [B<-timeout> I<seconds>]
@@ -168,7 +168,7 @@ with B<-serial>, B<-cert> and B<-host> options).
 =item B<-url> I<responder_url>
 
 Specify the responder host and optionally port and path via a URL.
- Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
+Both HTTP and HTTPS (SSL/TLS) URLs can be specified.
 The optional userinfo and fragment components are ignored.
 Any given query component is handled as part of the path component.
 For details, see the B<-host> and B<-path> options described next.
@@ -179,17 +179,20 @@ If the B<-host> option is present then the OCSP request is sent to the host
 I<host> on port I<port>.
 The I<host> may be a domain name or an IP (v4 or v6) address,
 such as C<127.0.0.1> or C<[::1]> for localhost.
+If it is an IPv6 address, it must be enclosed in C<[> and C<]>.
+
 The B<-path> option specifies the HTTP pathname to use or "/" by default.
 This is equivalent to specifying B<-url> with scheme
 http:// and the given I<host>, I<port>, and optional I<pathname>.
 
-=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]>
+=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>
 
 The HTTP(S) proxy server to use for reaching the OCSP server unless B<-no_proxy>
 applies, see below.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that
 the optional C<http://> or C<https://> prefix is ignored,
-as well as any userinfo and path components.
+as well as any userinfo, path, query, and fragment components.
 Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY>
 in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>.
 

doc/man1/openssl-s_client.pod.in

@@ -10,11 +10,11 @@ openssl-s_client - SSL/TLS client program
 B<openssl> B<s_client>
 [B<-help>]
 [B<-ssl_config> I<section>]
-[B<-connect> I<host:port>]
+[B<-connect> I<host>:I<port>]
 [B<-host> I<hostname>]
 [B<-port> I<port>]
-[B<-bind> I<host:port>]
-[B<-proxy> I<host:port>]
+[B<-bind> I<host>:I<port>]
+[B<-proxy> I<host>:I<port>]
 [B<-proxy_user> I<userid>]
 [B<-proxy_pass> I<arg>]
 [B<-unix> I<path>]
@@ -168,6 +168,7 @@ This specifies the host and optional port to connect to. It is possible to
 select the host and port using the optional target positional argument instead.
 If neither this nor the target positional argument are specified then an attempt
 is made to connect to the local host on port 4433.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 
 =item B<-host> I<hostname>
 
@@ -177,17 +178,19 @@ Host to connect to; use B<-connect> instead.
 
 Connect to the specified port; use B<-connect> instead.
 
-=item B<-bind> I<host:port>
+=item B<-bind> I<host>:I<port>
 
 This specifies the host address and or port to bind as the source for the
 connection.  For Unix-domain sockets the port is ignored and the host is
 used as the source socket address.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 
-=item B<-proxy> I<host:port>
+=item B<-proxy> I<host>:I<port>
 
 When used with the B<-connect> flag, the program uses the host and port
 specified with this flag and issues an HTTP CONNECT command to connect
 to the desired server.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 
 =item B<-proxy_user> I<userid>
 
@@ -865,10 +868,11 @@ or may request a certificate.
 
 =item I<host>:I<port>
 
-Rather than providing B<-connect>, the target hostname and optional port may
+Rather than providing B<-connect>, the target host and optional port may
 be provided as a single positional argument after all options. If neither this
 nor B<-connect> are provided, falls back to attempting to connect to
 I<localhost> on port I<4433>.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 
 =back
 

doc/man1/openssl-s_server.pod.in

@@ -75,7 +75,7 @@ B<openssl> B<s_server>
 [B<-status>]
 [B<-status_verbose>]
 [B<-status_timeout> I<int>]
-[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]>]
+[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>]
 [B<-no_proxy> I<addresses>]
 [B<-status_url> I<val>]
 [B<-status_file> I<infile>]
@@ -520,13 +520,14 @@ certificate signer that is required for certificate status requests.
 
 Sets the timeout for OCSP response to I<int> seconds.
 
-=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]>
+=item B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>
 
 The HTTP(S) proxy server to use for reaching the OCSP server unless B<-no_proxy>
 applies, see below.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 The proxy port defaults to 80 or 443 if the scheme is C<https>; apart from that
 the optional C<http://> or C<https://> prefix is ignored,
-as well as any userinfo and path components.
+as well as any userinfo, path, query, and fragment components.
 Defaults to the environment variable C<http_proxy> if set, else C<HTTP_PROXY>
 in case no TLS is used, otherwise C<https_proxy> if set, else C<HTTPS_PROXY>.
 

doc/man1/openssl-s_time.pod.in

@@ -50,6 +50,7 @@ Print out a usage message.
 =item B<-connect> I<host>:I<port>
 
 This specifies the host and optional port to connect to.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 
 =item B<-www> I<page>
 

doc/man3/BIO_s_connect.pod

@@ -64,7 +64,7 @@ a single call: that is it creates a new connect BIO with hostname B<name>.
 
 BIO_set_conn_hostname() uses the string B<name> to set the hostname.
 The hostname can be an IP address; if the address is an IPv6 one, it
-must be enclosed with brackets C<[> and C<]>.
+must be enclosed in brackets C<[> and C<]>.
 The hostname can also include the port in the form hostname:port;
 see L<BIO_parse_hostserv(3)> and BIO_set_conn_port() for details.
 

doc/man3/OSSL_CMP_CTX_new.pod

@@ -391,8 +391,10 @@ If TLS is not used this defaults to the value of
 the environment variable C<http_proxy> if set, else C<HTTP_PROXY>.
 Otherwise defaults to the value of C<https_proxy> if set, else C<HTTPS_PROXY>.
 An empty proxy string specifies not to use a proxy.
-Else the format is C<[http[s]://]address[:port][/path]>,
-where any path given is ignored.
+Otherwise the format is
+C<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>,
+where any given userinfo, path, query, and fragment is ignored.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 The default port number is 80, or 443 in case C<https:> is given.
 
 OSSL_CMP_CTX_set1_no_proxy() sets the list of server hostnames not to use

doc/man3/OSSL_HTTP_parse_url.pod

@@ -46,20 +46,21 @@ Return the determined proxy host unless the exclusion value,
 which is a list of proxy hosts separated by C<,> and/or whitespace,
 contains I<server>.
 Otherwise return NULL.
-In case I<server> is a string enclosed with C<[> and C<]>, it is assumed to be
-an escaped IPv6 address and so the C<[> and C<]> are ignored for the comparison.
+When I<server> is a string delimited by C<[> and C<]>, which are used for IPv6
+addresses, the enclosing C<[> and C<]> are stripped prior to comparison.
 
 OSSL_parse_url() parses its input string I<url> as a URL of the form
 C<[scheme://][userinfo@]host[:port][/path][?query][#fragment]> and splits it up
 into scheme, userinfo, host, port, path, query, and fragment components.
 The host (or server) component may be a DNS name or an IP address
-where IPv6 addresses should be enclosed in square brackets C<[> and C<]>.
+where IPv6 addresses must be enclosed in square brackets C<[> and C<]>.
 The port component is optional and defaults to C<0>.
 If given, it must be in decimal form.  If the I<pport_num> argument is not NULL
 the integer value of the port number is assigned to I<*pport_num> on success.
 The path component is also optional and defaults to C</>.
 Each non-NULL result pointer argument I<pscheme>, I<puser>, I<phost>, I<pport>,
 I<ppath>, I<pquery>, and I<pfrag>, is assigned the respective url component.
+Any IPv6 address in I<*phost> is enclosed in C<[> and C<]>.
 On success, they are guaranteed to contain non-NULL string pointers, else NULL.
 It is the responsibility of the caller to free them using L<OPENSSL_free(3)>.
 If I<pquery> is NULL, any given query component is handled as part of the path.
@@ -74,7 +75,7 @@ and the scheme is C<https>, else 0.
 The port component is optional and defaults to C<443> if the scheme is C<https>,
 else C<80>.
 Note that relative paths must be given with a leading C</>,
-otherwise the first path element is interpreted as the hostname.
+otherwise the first path element is interpreted as the host.
 
 Calling the deprecated function OCSP_parse_url(url, host, port, path, ssl)
 is equivalent to

doc/man3/OSSL_HTTP_transfer.pod

@@ -77,12 +77,14 @@ If TLS is not used this defaults to the environment variable C<http_proxy>
 if set, else C<HTTP_PROXY>.
 If I<use_ssl> != 0 it defaults to C<https_proxy> if set, else C<HTTPS_PROXY>.
 An empty proxy string C<""> forbids using a proxy.
-Else the format is
+Otherwise, the format is
 C<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>,
 where any userinfo, path, query, and fragment given is ignored.
+If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>.
 The default proxy port number is 80, or 443 in case "https:" is given.
 The HTTP client functions connect via the given proxy unless the I<server>
-is found in the optional list I<no_proxy> of proxy hostnames (if not NULL;
+is found in the optional list I<no_proxy> of proxy hostnames or IP addresses
+separated by C<,> and/or whitespace (if not NULL;
 default is the environment variable C<no_proxy> if set, else C<NO_PROXY>).
 Proxying plain HTTP is supported directly,
 while using a proxy for HTTPS connections requires a suitable callback function