diff options
author | Dr. David von Oheimb <David.von.Oheimb@siemens.com> | 2021-05-03 16:33:10 +0200 |
---|---|---|
committer | Dr. David von Oheimb <dev@ddvo.net> | 2021-05-14 19:24:42 +0200 |
commit | 829902879eb7ba1260a9444f6b6b91d84ca61037 (patch) | |
tree | 3bfa9571c2115585d905421a45e7a9053ea84c66 /doc | |
parent | 22fe2b129922bc9322c41ce8beff1551c078c838 (diff) |
HTTP client API: Generalize to arbitrary request and response contents
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/15053)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man3/OSSL_HTTP_REQ_CTX.pod | 3 | ||||
-rw-r--r-- | doc/man3/OSSL_HTTP_transfer.pod | 34 |
2 files changed, 24 insertions, 13 deletions
diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod index 52e5d441f3..f5f70584df 100644 --- a/doc/man3/OSSL_HTTP_REQ_CTX.pod +++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod @@ -123,6 +123,7 @@ and to gather the response via HTTP, using the I<wbio> and I<rbio> that were given when calling OSSL_HTTP_REQ_CTX_new(). If successful, the contents of the internal memory B<BIO> contains the contents of the HTTP response, without the response headers. +This does not support streaming. The function may need to be called again if its result is -1, which indicates L<BIO_should_retry(3)>. In such a case it is advisable to sleep a little in between, using L<BIO_wait(3)> on the read BIO to prevent a busy loop. @@ -221,7 +222,7 @@ OSSL_HTTP_REQ_CTX_nbio() and OSSL_HTTP_REQ_CTX_nbio_d2i() return 1 for success, 0 on error or redirection, -1 if retry is needed. OSSL_HTTP_REQ_CTX_exchange() and OSSL_HTTP_REQ_CTX_get0_mem_bio() -returns a pointer to a B<BIO> on success and NULL on failure. +return a pointer to a B<BIO> on success and NULL on failure. OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents or 0 if not available or an error occurred. diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index 9745932e37..71294913e5 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -30,7 +30,7 @@ OSSL_HTTP_close const STACK_OF(CONF_VALUE) *headers, const char *content_type, BIO *req, const char *expected_content_type, int expect_asn1, - size_t max_resp_len, int timeout, int keep_alive); + int timeout, int keep_alive); BIO *OSSL_HTTP_exchange(OSSL_HTTP_REQ_CTX *rctx, char **redirection_url); BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy, BIO *bio, BIO *rbio, @@ -52,8 +52,8 @@ OSSL_HTTP_close =head1 DESCRIPTION -OSSL_HTTP_open() initiates an HTTP session using I<bio> if not NULL, else -by connecting to a given I<server> optionally via a I<proxy>. +OSSL_HTTP_open() initiates an HTTP session using the I<bio> argument if not +NULL, else by connecting to a given I<server> optionally via a I<proxy>. Typically the OpenSSL build supports sockets and the I<bio> parameter is NULL. In this case I<rbio> must be NULL as well, and the @@ -148,12 +148,12 @@ Since this function is typically called by applications such as L<openssl-s_client(1)> it uses the I<bio_err> and I<prog> parameters (unless NULL) to print additional diagnostic information in a user-oriented way. - OSSL_HTTP_set_request() sets up in I<rctx> the request header and content data and expectations on the response using the following parameters. If I<path> is NULL it defaults to "/". -If I<req_mem> is NULL the HTTP GET method will be used to send the request -else HTTP POST with the contents of I<req_mem> and optional I<content_type>. +If I<req> is NULL the HTTP GET method will be used to send the request +else HTTP POST with the contents of I<req> and optional I<content_type>, where +I<req> must contain data with determined length; streaming is not supported. The optional list I<headers> may contain additional custom HTTP header lines. If the parameter I<expected_content_type> is not NULL then the client will check that the given content type string @@ -172,15 +172,15 @@ If the value is 1 or 2 then a persistent connection is requested. If the value is 2 then a persistent connection is required, i.e., an error occurs in case the server does not grant it. -OSSL_HTTP_transfer() exchanges any form of HTTP request and response +OSSL_HTTP_exchange() exchanges any form of HTTP request and response as specified by I<rctx>, which must include both connection and request data, typically set up using OSSL_HTTP_open() and OSSL_HTTP_set_request(). It implements the core of the functions described below. If the HTTP method is GET and I<redirection_url> is not NULL the latter pointer is used to provide any new location that the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND). -In this case the caller is responsible for deallocating this URL with -L<OPENSSL_free(3)>. +In this case the function returns NULL and the caller is +responsible for deallocating the URL with L<OPENSSL_free(3)>. 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 @@ -203,6 +203,17 @@ and the I<bio_update_fn>, as described for OSSL_HTTP_open(), must be provided. Also the remaining parameters are interpreted as described for OSSL_HTTP_open() and OSSL_HTTP_set_request(), respectively. +OSSL_HTTP_transfer() exchanges an HTTP request and response +over a connection managed via I<prctx> without supporting redirection. +It combines OSSL_HTTP_open(), OSSL_HTTP_set_request(), OSSL_HTTP_exchange(), +and OSSL_HTTP_close(). +If I<prctx> is not NULL it reuses any open connection represented by a non-NULL +I<*prctx>. It keeps the connection open if a persistent connection is requested +or required and this was granted by the server, else it closes the connection +and assigns NULL to I<*prctx>. +The remaining parameters are interpreted as described for OSSL_HTTP_open() +and OSSL_HTTP_set_request(), respectively. + OSSL_HTTP_close() closes the connection and releases I<rctx>. The I<ok> parameter is passed to any BIO update function given during setup as described above for OSSL_HTTP_open(). @@ -222,9 +233,8 @@ OSSL_HTTP_proxy_connect() and OSSL_HTTP_set_request() return 1 on success, 0 on error. On success, OSSL_HTTP_exchange(), OSSL_HTTP_get(), and OSSL_HTTP_transfer() -return a memory BIO containing the data received if an ASN.1-encoded response -is expected, else a BIO that may support streaming. -The BIO must be freed by the caller. +return a memory BIO containing the data received. +This must be freed by the caller. On failure, they return NULL. Failure conditions include connection/transfer timeout, parse errors, etc. |