From: David von Oheimb Date: Thu, 1 Aug 2024 19:36:02 +0000 (+0200) Subject: doc/man{1,3}: fix details on IPv6 host addresses and of whitespace in no_proxy X-Git-Tag: openssl-3.1.8~118 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=caa60eae817457bab6403941ac8a24ab1eed7ec3;p=thirdparty%2Fopenssl.git doc/man{1,3}: fix details on IPv6 host addresses and of whitespace in no_proxy Reviewed-by: Viktor Dukhovni Reviewed-by: Tomas Mraz Reviewed-by: Neil Horman Reviewed-by: Paul Dale (Merged from https://github.com/openssl/openssl/pull/25533) (cherry picked from commit 28970d1d36f851b3731707f839b90870b2c0f349) --- diff --git a/doc/man1/openssl-cmp.pod.in b/doc/man1/openssl-cmp.pod.in index f54519f22ab..956764c1469 100644 --- a/doc/man1/openssl-cmp.pod.in +++ b/doc/man1/openssl-cmp.pod.in @@ -456,6 +456,7 @@ Reason numbers defined in RFC 5280 are: The I domain name or IP address and optionally I 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. @@ -470,6 +471,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; apart from that the optional C or C prefix is ignored (note that TLS may be selected by B<-tls_used>), as well as any path, userinfo, and query, and fragment diff --git a/doc/man1/openssl-ocsp.pod.in b/doc/man1/openssl-ocsp.pod.in index 823f9bc53db..fd23a44df06 100644 --- a/doc/man1/openssl-ocsp.pod.in +++ b/doc/man1/openssl-ocsp.pod.in @@ -31,7 +31,7 @@ B B [B<-url> I] [B<-host> I:I] [B<-path> I] -[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]>] +[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>] [B<-no_proxy> I] [B<-header>] [B<-timeout> I] @@ -161,7 +161,7 @@ with B<-serial>, B<-cert> and B<-host> options). =item B<-url> I 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. @@ -172,17 +172,20 @@ If the B<-host> option is present then the OCSP request is sent to the host I on port I. The I 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, I, and optional I. -=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; apart from that the optional C or C 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 if set, else C in case no TLS is used, otherwise C if set, else C. diff --git a/doc/man1/openssl-s_client.pod.in b/doc/man1/openssl-s_client.pod.in index 94f7621b1e1..31729d6bdd2 100644 --- a/doc/man1/openssl-s_client.pod.in +++ b/doc/man1/openssl-s_client.pod.in @@ -10,11 +10,11 @@ openssl-s_client - SSL/TLS client program B B [B<-help>] [B<-ssl_config> I
] -[B<-connect> I] +[B<-connect> I:I] [B<-host> I] [B<-port> I] -[B<-bind> I] -[B<-proxy> I] +[B<-bind> I:I] +[B<-proxy> I:I] [B<-proxy_user> I] [B<-proxy_pass> I] [B<-unix> I] @@ -157,6 +157,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 @@ -166,17 +167,19 @@ Host to connect to; use B<-connect> instead. Connect to the specified port; use B<-connect> instead. -=item B<-bind> I +=item B<-bind> I:I 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 +=item B<-proxy> I:I 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 @@ -799,10 +802,11 @@ proceed unless the B<-verify_return_error> option is used. =item I:I -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 on port I<4433>. +If the host string is an IPv6 address, it must be enclosed in C<[> and C<]>. =back diff --git a/doc/man1/openssl-s_server.pod.in b/doc/man1/openssl-s_server.pod.in index 99a252a8225..9bec3cf4776 100644 --- a/doc/man1/openssl-s_server.pod.in +++ b/doc/man1/openssl-s_server.pod.in @@ -74,7 +74,7 @@ B B [B<-status>] [B<-status_verbose>] [B<-status_timeout> I] -[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path]>] +[B<-proxy> I<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>] [B<-no_proxy> I] [B<-status_url> I] [B<-status_file> I] @@ -504,13 +504,14 @@ a verbose printout of the OCSP response. Sets the timeout for OCSP response to I 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; apart from that the optional C or C 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 if set, else C in case no TLS is used, otherwise C if set, else C. diff --git a/doc/man1/openssl-s_time.pod.in b/doc/man1/openssl-s_time.pod.in index 2b82cf1e983..ca41f59362f 100644 --- a/doc/man1/openssl-s_time.pod.in +++ b/doc/man1/openssl-s_time.pod.in @@ -50,6 +50,7 @@ Print out a usage message. =item B<-connect> I:I 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 diff --git a/doc/man3/BIO_s_connect.pod b/doc/man3/BIO_s_connect.pod index ab813b32d03..a3c9e6428e4 100644 --- a/doc/man3/BIO_s_connect.pod +++ b/doc/man3/BIO_s_connect.pod @@ -59,7 +59,7 @@ a single call: that is it creates a new connect BIO with hostname B. BIO_set_conn_hostname() uses the string B 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 and BIO_set_conn_port() for details. diff --git a/doc/man3/OSSL_CMP_CTX_new.pod b/doc/man3/OSSL_CMP_CTX_new.pod index 9b4054fe5d0..9a78e643432 100644 --- a/doc/man3/OSSL_CMP_CTX_new.pod +++ b/doc/man3/OSSL_CMP_CTX_new.pod @@ -350,8 +350,10 @@ If TLS is not used this defaults to the value of the environment variable C if set, else C. Otherwise defaults to the value of C if set, else C. 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 is given. OSSL_CMP_CTX_set1_no_proxy() sets the list of server hostnames not to use diff --git a/doc/man3/OSSL_HTTP_parse_url.pod b/doc/man3/OSSL_HTTP_parse_url.pod index f139f275aad..bc29fb18d14 100644 --- a/doc/man3/OSSL_HTTP_parse_url.pod +++ b/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. Otherwise return NULL. -In case I 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 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 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 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, I, I, I, I, I, and I, 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. If I is NULL, any given query component is handled as part of the path. @@ -74,7 +75,7 @@ and the scheme is C, else 0. The port component is optional and defaults to C<443> if the scheme is C, 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 diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index 6a4d7d2dced..21af7fac6f8 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -77,12 +77,14 @@ If TLS is not used this defaults to the environment variable C if set, else C. If I != 0 it defaults to C if set, else C. 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 -is found in the optional list I of proxy hostnames (if not NULL; +is found in the optional list I of proxy hostnames or IP addresses +separated by C<,> and/or whitespace (if not NULL; default is the environment variable C if set, else C). Proxying plain HTTP is supported directly, while using a proxy for HTTPS connections requires a suitable callback function