[openssl] master update

[dev at ddvo.net]

The branch master has been updated
       via  a26c089ba3637a3283cc0e76ea9529e90d18ba0d (commit)
       via  4258845e4eb86854f723c0160c051a727ec08a56 (commit)
      from  4f716249643fe97a2bdf59a11cc10e1bef8103e9 (commit)


- Log -----------------------------------------------------------------
commit a26c089ba3637a3283cc0e76ea9529e90d18ba0d
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date:   Fri Oct 22 12:04:35 2021 +0200

    OSSL_HTTP_transfer.pod: clarify that resulting BIO must be freed
    
    Reviewed-by: Tomas Mraz <tomas at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/16888)

commit 4258845e4eb86854f723c0160c051a727ec08a56
Author: Dr. David von Oheimb <David.von.Oheimb at siemens.com>
Date:   Fri Oct 22 12:04:11 2021 +0200

    OSSL_HTTP_REQ_CTX.pod: clarify that resulting BIO must not be freed
    
    Reviewed-by: Tomas Mraz <tomas at openssl.org>
    (Merged from https://github.com/openssl/openssl/pull/16888)

-----------------------------------------------------------------------

Summary of changes:
 doc/man3/OSSL_HTTP_REQ_CTX.pod  | 18 +++++++++++-------
 doc/man3/OSSL_HTTP_transfer.pod | 10 +++++++---
 2 files changed, 18 insertions(+), 10 deletions(-)

diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod
index 0c270780e1..ad2d731153 100644
--- a/doc/man3/OSSL_HTTP_REQ_CTX.pod
+++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod
@@ -139,13 +139,15 @@ using the ASN.1 template I<it> and places the result in I<*pval>.
 
 OSSL_HTTP_REQ_CTX_exchange() calls OSSL_HTTP_REQ_CTX_nbio() as often as needed
 in order to exchange a request and response or until a timeout is reached.
-If successful and an ASN.1-encoded response was expected, the response contents
-should be read via the BIO returned by OSSL_HTTP_REQ_CTX_get0_mem_bio().
-Else the I<rbio> that was given when calling OSSL_HTTP_REQ_CTX_new()
-represents the current state of reading the response.
-If OSSL_HTTP_REQ_CTX_exchange() was successful, this BIO has been read past the
-end of the response headers, such that the actual response contents can be read
-via this BIO, which may support streaming.
+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,
+which may support streaming.
+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.
@@ -153,6 +155,7 @@ 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,
 its contents can be read via this BIO, which does not support streaming.
+The returned BIO pointer must not be freed by the caller.
 
 OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents
 in I<rctx> if provided by the server as <Content-Length> header field, else 0.
@@ -227,6 +230,7 @@ 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.
+The returned BIO must not be freed by the caller.
 
 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 ab30f5385f..ff29c79837 100644
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -185,10 +185,11 @@ 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 any given maximum response length.
-On receiving a response, the function returns the contents as a memory BIO,
-which does not support streaming, in case an ASN.1-encoded response is expected.
-Else it returns directly the read BIO that holds the response contents,
+If an ASN.1-encoded response is expected, the function returns on success
+the contents as 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.
 
 OSSL_HTTP_get() uses HTTP GET to obtain data from I<bio> if non-NULL,
 else from the server contained in the I<url>, and returns it as a BIO.
@@ -202,6 +203,7 @@ If the scheme component of the I<url> is C<https> a TLS connection is requested
 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_set1_request(), respectively.
+The caller is responsible for freeing the BIO pointer obtained.
 
 OSSL_HTTP_transfer() exchanges an HTTP request and response
 over a connection managed via I<prctx> without supporting redirection.
@@ -213,6 +215,7 @@ 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_set1_request(), respectively.
+The caller is responsible for freeing the BIO pointer obtained.
 
 OSSL_HTTP_close() closes the connection and releases I<rctx>.
 The I<ok> parameter is passed to any BIO update function
@@ -238,6 +241,7 @@ is expected, else 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.
+The caller is responsible for freeing the BIO pointer obtained.
 
 OSSL_HTTP_close() returns 0 if anything went wrong while disconnecting, else 1.