X-Git-Url: https://git.openssl.org/?p=openssl.git;a=blobdiff_plain;f=doc%2Fman3%2FOSSL_HTTP_transfer.pod;h=4459f541f3b2e2be84a414ae2291e7c3de887112;hp=68010cb6bdcf3ec5d0a3f81311f84698b4dc9aab;hb=e98c7350bfaf0ae1f2b72d68d4c5721de24a478f;hpb=29f178bddfdbd11218fbcba0b8060297696968e3 diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index 68010cb6bd..4459f541f3 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -17,14 +17,14 @@ OSSL_HTTP_parse_url typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail); - BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *proxy_port, + BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy, BIO *bio, BIO *rbio, OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, const STACK_OF(CONF_VALUE) *headers, int maxline, unsigned long max_resp_len, int timeout, const char *expected_content_type, int expect_asn1); ASN1_VALUE *OSSL_HTTP_get_asn1(const char *url, - const char *proxy, const char *proxy_port, + const char *proxy, const char *no_proxy, BIO *bio, BIO *rbio, OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, const STACK_OF(CONF_VALUE) *headers, @@ -33,17 +33,17 @@ OSSL_HTTP_parse_url const ASN1_ITEM *it); ASN1_VALUE *OSSL_HTTP_post_asn1(const char *server, const char *port, const char *path, int use_ssl, - const char *proxy, const char *proxy_port, + const char *proxy, const char *no_proxy, BIO *bio, BIO *rbio, OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, const STACK_OF(CONF_VALUE) *headers, const char *content_type, - ASN1_VALUE *req, const ASN1_ITEM *req_it, + const ASN1_VALUE *req, const ASN1_ITEM *req_it, int maxline, unsigned long max_resp_len, int timeout, const char *expected_ct, const ASN1_ITEM *rsp_it); BIO *OSSL_HTTP_transfer(const char *server, const char *port, const char *path, - int use_ssl, const char *proxy, const char *proxy_port, + int use_ssl, const char *proxy, const char *no_proxy, BIO *bio, BIO *rbio, OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, const STACK_OF(CONF_VALUE) *headers, @@ -69,17 +69,18 @@ and returns it on success as a pointer to I. OSSL_HTTP_post_asn1() uses the HTTP POST method to send a request B with the ASN.1 structure defined in B and the given B to -the given B and optional B and B, which defaults to "/". +the given B and optional B and B. If B is nonzero a TLS connection is requested and the B parameter, described below, must be provided. The optional list B may contain additional custom HTTP header lines. The expected structure of the response is specified by B. On success it returns the response as a pointer to B. -OSSL_HTTP_transfer() exchanges an HTTP request and response with -the given B and optional B and B, which defaults to "/". -If B is nonzero a TLS connection is requested and the B -parameter, described below, must be provided. +OSSL_HTTP_transfer() exchanges any form of HTTP request and response. +It implements the core of the functions described above. +If B parameter is NULL it defaults to "/". +If B is nonzero a TLS connection is requested +and the B parameter, described below, must be provided. If B is NULL it uses the HTTP GET method, else it uses HTTP POST to send a request with the contents of the memory BIO and optional B. The optional list B may contain additional custom HTTP header lines. @@ -91,22 +92,36 @@ L. The above functions have the following parameters in common. -If the B parameter is not NULL the HTTP client functions connect -via the given proxy and the optionally given B. -Proxying plain HTTP is supported directly, -while using a proxy for HTTPS connections requires a suitable callback function -such as OSSL_HTTP_proxy_connect(), described below. - -Typically the B and B parameters are NULL and the client creates a -network BIO internally for connecting to the given server and port (optionally -via a proxy and its port), and uses it for exchanging the request and response. -If B is given and B is NULL then the client uses this BIO instead. +Typically the OpenSSL build supports sockets +and the B and B parameters are both NULL. +In this case the client creates a network BIO internally +for connecting to the given B +at the specified B (if any, defaulting to 80 for HTTP or 443 for HTTPS), +optionally via a B (respecting B) as described below. +Then the client uses this internal BIO for exchanging the request and response. +If B is given and B is NULL then the client uses this B instead. If both B and B are given (which may be memory BIOs for instance) then no explicit connection is attempted, B is used for writing the request, and B for reading the response. As soon as the client has flushed B the server must be ready to provide a response or indicate a waiting condition via B. +The optional B parameter can be used to set the address of the an +HTTP(S) proxy to use (unless overridden by "no_proxy" settings). +If TLS is not used this defaults to the environment variable B +if set, else B. +If B != 0 it defaults to B if set, else B. +An empty proxy string specifies not to use a proxy. +Else the format is I<[http[s]://]address[:port][/path]>, +where any path given is ignored. +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 B +is found in the optional list B of proxy hostnames (if not NULL; +default is the environment variable B if set, else B). +Proxying plain HTTP is supported directly, +while using a proxy for HTTPS connections requires a suitable callback function +such as B, described below. + The B parameter specifies the response header maximum line length, where 0 indicates the default value, which currently is 4k. The B parameter specifies the maximum response length, @@ -115,7 +130,7 @@ where 0 indicates the default value, which currently is 100k. An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer() this is only the case if the B parameter is nonzero. -If the response header contains one or more Content-Length header lines and/or +If the response header contains one or more "Content-Length" header lines and/or an ASN.1-encoded response is expected, which should include a total length, the length indications received are checked for consistency and for not exceeding the maximum response length. @@ -139,7 +154,7 @@ B is a BIO connect/disconnect callback function with prototype The callback may modify the HTTP BIO provided in the B argument, whereby it may make use of a custom defined argument B, which may for instance refer to an I structure. -During connection establishment, just after calling BIO_connect_retry(), +During connection establishment, just after calling BIO_do_connect_retry(), the function is invoked with the B argument being 1 and the B argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled. On disconnect B is 0 and B is 1 if no error occurred, else 0. @@ -164,11 +179,12 @@ Here is a simple example that supports TLS connections (but not via a proxy): After disconnect the modified BIO will be deallocated using BIO_free_all(). OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function -to set up an SSL/TLS connection via an HTTP proxy. +to set up an SSL/TLS connection via an HTTPS proxy. It promotes the given BIO B representing a connection pre-established with a TLS proxy using the HTTP CONNECT method, optionally using proxy client credentials B and B, to connect with TLS protection ultimately to B and B. +If the B argument is NULL or the empty string it defaults to "443". The B parameter is used as described above. Since this function is typically called by appplications such as L it uses the B and B parameters (unless @@ -184,6 +200,13 @@ them copies of the respective string components. The strings returned this way must be deallocated by the caller using L unless they are NULL, which is their default value on error. +=head1 NOTES + +The names of the environment variables used by this implementation: +B, B, B, B, B, and +B, have been chosen for maximal compatibility with +other HTTP client implementations such as wget, curl, and git. + =head1 RETURN VALUES OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and