http_client.c: fix comment and documentation of the memory BIOs used

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Hugo Landau <hlandau@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/18674)

(cherry picked from commit 7d5019c15af8f88443a7edddd4b150a7dafeda5d)

diff --git a/crypto/http/http_client.c b/crypto/http/http_client.c
index aa76ca1972eafbb7d2c8d81b7cc1cb8d57b2d14b..9f4555280c80c9808c5247fe7e79a103359a84c8 100644 (file)
--- a/crypto/http/http_client.c
+++ b/crypto/http/http_client.c
@@ -53,7 +53,7 @@ struct ossl_http_req_ctx_st {
     char *proxy;                /* Optional proxy name or URI */
     char *server;               /* Optional server host name */
     char *port;                 /* Optional server port */
-    BIO *mem;                   /* Memory BIO holding request/response header */
+    BIO *mem;                   /* Mem BIO holding request header or response */
     BIO *req;                   /* BIO holding the request provided by caller */
     int method_POST;            /* HTTP method is POST (else GET) */
     char *expected_ct;          /* Optional expected Content-Type */

diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod
index ad2d731153502ceb0cc9683ac545608b330c0740..a2495d35a527d91a592480aaaf5119daab55c9c2 100644 (file)
--- a/doc/man3/OSSL_HTTP_REQ_CTX.pod
+++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod
@@ -66,8 +66,8 @@ I<wbio>), and the maximum expected response header line length I<buf_size>.
 A value <= 0 indicates that
 the B<OSSL_HTTP_DEFAULT_MAX_LINE_LEN> of 4KiB should be used.
 I<buf_size> is also used as the number of content bytes that are read at a time.
-The allocated context structure is also populated with an internal allocated
-memory B<BIO>, which collects the HTTP request and additional headers as text.
+The allocated context structure includes an internal memory B<BIO>,
+which collects the HTTP request header lines.
 
 OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I<rctx>.
 The I<rbio> is not free'd, I<wbio> will be free'd if I<free_wbio> is set.
@@ -80,7 +80,7 @@ that the request should go through, otherwise they should be left NULL.
 I<path> is the HTTP request path; if left NULL, C</> is used.
 
 OSSL_HTTP_REQ_CTX_add1_header() adds header I<name> with value I<value> to the
-context I<rctx>. It can be called more than once to add multiple headers.
+context I<rctx>. It can be called more than once to add multiple header lines.
 For example, to add a C<Host> header for C<example.com> you would call:
 
  OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
@@ -96,7 +96,7 @@ If the I<asn1> parameter is nonzero a structure in ASN.1 encoding will be
 expected as the response content and input streaming is disabled.  This means
 that an ASN.1 sequence header is required, its length field is checked, and
 OSSL_HTTP_REQ_CTX_get0_mem_bio() should be used to get the buffered response.
-Otherwise any input format is allowed without length checks, which is the default.
+Otherwise (by default) any input format is allowed without length checks.
 In this case the BIO given as I<rbio> argument to OSSL_HTTP_REQ_CTX_new() should
 be used directly to read the response contents, which may support streaming.
 If the I<timeout> parameter is > 0 this indicates the maximum number of seconds
@@ -124,7 +124,7 @@ The HTTP header C<Content-Length> is filled out with the length of the request.
 I<content_type> must be NULL if I<req> is NULL.
 If I<content_type> isn't NULL,
 the HTTP header C<Content-Type> is also added with the given string value.
-All of this ends up in the internal memory B<BIO>.
+The header lines are added to the internal memory B<BIO> for the request header.
 
 OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in I<rctx>
 and to gather the response via HTTP, using the I<wbio> and I<rbio>
@@ -143,17 +143,17 @@ On success it returns a pointer to the BIO that can be used to read the result.
 If an ASN.1-encoded response was expected, this is the BIO
 returned by OSSL_HTTP_REQ_CTX_get0_mem_bio() when called after the exchange.
 This memory BIO does not support streaming.
-Otherwise it may be the I<rbio> given when calling OSSL_HTTP_REQ_CTX_new(),
-and this BIO has been read past the end of the response headers,
-such that the actual response body can be read via this BIO,
+Otherwise the returned BIO is the I<rbio> given to OSSL_HTTP_REQ_CTX_new(),
 which may support streaming.
-The returned BIO pointer must not be freed by the caller.
+When this BIO is returned, it has been read past the end of the response header,
+such that the actual response body can be read from it.
+The returned BIO pointer MUST NOT be freed by the caller.
 
 OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
-Before sending the request, this could used to modify the HTTP request text.
+Before the HTTP request is sent, this could be used to adapt its header lines.
 I<Use with caution!>
 After receiving a response via HTTP, the BIO represents the current state of
-reading the response headers. If the response was expected to be ASN.1 encoded,
+reading the response header. If the response was expected to be ASN.1 encoded,
 its contents can be read via this BIO, which does not support streaming.
 The returned BIO pointer must not be freed by the caller.
 
@@ -200,7 +200,7 @@ Calling OSSL_HTTP_REQ_CTX_set_request_line().
 
 =item 2.
 
-Adding extra headers with OSSL_HTTP_REQ_CTX_add1_header().
+Adding extra header lines with OSSL_HTTP_REQ_CTX_add1_header().
 This is optional and may be done multiple times with different names.
 
 =item 3.
@@ -229,7 +229,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()
-return a pointer to a B<BIO> on success and NULL on failure.
+return a pointer to a B<BIO> on success as described above or NULL on failure.
 The returned BIO must not be freed by the caller.
 
 OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents

diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index 1a5a973d528125370d0f763504a7e611924bb420..f7d28d2b403d0efc8cd7ce2d1dcd2b012514bdfa 100644 (file)
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -202,7 +202,7 @@ 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 any given maximum response length.
 If an ASN.1-encoded response is expected, the function returns on success
-the contents as a memory BIO, which does not support streaming.
+the contents buffered in a memory BIO, which does not support streaming.
 Otherwise it returns directly the read BIO that holds the response contents,
 which allows a response of indefinite length and may support streaming.
 The caller is responsible for freeing the BIO pointer obtained.
@@ -253,8 +253,8 @@ OSSL_HTTP_proxy_connect() and OSSL_HTTP_set1_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.
+return a memory BIO that buffers all the data received if an ASN.1-encoded
+response is expected, otherwise a BIO that may support streaming.
 The BIO must be freed by the caller.
 On failure, they return NULL.
 Failure conditions include connection/transfer timeout, parse errors, etc.