From 1d9ec351133c8ae8fd3eccd03bc74c550b0fa05d Mon Sep 17 00:00:00 2001 From: "Dr. David von Oheimb" Date: Mon, 7 Oct 2024 21:17:59 +0200 Subject: [PATCH] remove parts of OSSL_HTTP_transfer.pod that better described in OSSL_HTTP_transfer.pod --- doc/man3/OSSL_HTTP_REQ_CTX.pod | 27 ++++++++++++++++----------- doc/man3/OSSL_HTTP_transfer.pod | 29 ++++------------------------- 2 files changed, 20 insertions(+), 36 deletions(-) diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod index 2a1485cbe9a26d..6090542d540636 100644 --- a/doc/man3/OSSL_HTTP_REQ_CTX.pod +++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod @@ -35,7 +35,7 @@ OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines const char *name, const char *value); int OSSL_HTTP_REQ_CTX_set_expected(OSSL_HTTP_REQ_CTX *rctx, - const char *content_type, int asn1, + const char *expected_content_type, int expect_asn1, int timeout, int keep_alive); int OSSL_HTTP_REQ_CTX_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type, const ASN1_ITEM *it, const ASN1_VALUE *req); @@ -99,23 +99,24 @@ of the HTTP client on the response. Due to the structure of an HTTP request, if the I argument is nonzero the function must be used before calling OSSL_HTTP_REQ_CTX_set1_req(). -If the I argument is not NULL, -the client will check that the specified content-type string +If the I argument is not NULL, the client will +check in a case-insensitive way that the specified C string value is included in the HTTP header of the response and return an error if not. -In the content-type header line the specified string should be present either +In the C header line the specified string should be present either as a whole, or in case the specified string does not include a C<;> character, it is sufficient that the specified string appears as a prefix in the header line, followed by a C<;> character and any further text. -For instance, if the I argument specifies C, -this is matched by C, C, etc. +For instance, if the I argument specifies C, +this is matched by C, C, etc. -If the I parameter is nonzero a structure in ASN.1 encoding will be +If the I 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 (by default) any input format is allowed without length checks. In this case the BIO given as I argument to OSSL_HTTP_REQ_CTX_new() should be used directly to read the response contents, which may support streaming. + If the I parameter is > 0 this indicates the maximum number of seconds the subsequent HTTP transfer (sending the request and receiving a response) is allowed to take. @@ -123,6 +124,7 @@ I == 0 enables waiting indefinitely, i.e., no timeout can occur. This is the default. I < 0 takes over any value set via the I argument of L with the default being 0, which means no timeout. + If the I parameter is 0, which is the default, the connection is not kept open after receiving a response. This is the default behavior for HTTP 1.0. If the value is 1 or 2 then a persistent connection is requested. @@ -149,6 +151,12 @@ that were given when calling OSSL_HTTP_REQ_CTX_new(). The function may need to be called again if its result is -1, which indicates L. In such a case it is advisable to sleep a little in between, using L on the read BIO to prevent a busy loop. +See OSSL_HTTP_REQ_CTX_set_expected() how the response content type, +the response body, the HTTP transfer timeout, and "keep-alive" are treated. +If the C header is present in the response +and its value exceeds the maximum allowed response content length +or the content is an ASN.1-encoded structure with a length exceeding this value +or both length indications are present but disagree then an error occurs. OSSL_HTTP_REQ_CTX_nbio_d2i() is like OSSL_HTTP_REQ_CTX_nbio() but on success in addition parses the response, which must be a DER-encoded ASN.1 structure, @@ -175,14 +183,11 @@ 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 if provided by the server as header field, else 0. +in I if provided by the server as C header field, else 0. OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed response content length for I to I. If not set or I is 0 then the B is used, which currently is 100 KiB. -If the C header is present and exceeds this value or -the content is an ASN.1 encoded structure with a length exceeding this value -or both length indications are present but disagree then an error occurs. OSSL_HTTP_is_alive() can be used to query if the HTTP connection given by I is still alive, i.e., has not been closed. diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod index f6be9e3f77d765..c0cb11161b771b 100644 --- a/doc/man3/OSSL_HTTP_transfer.pod +++ b/doc/man3/OSSL_HTTP_transfer.pod @@ -176,32 +176,10 @@ else HTTP POST with the contents of I and optional I, where the length of the data in I does not need to be determined in advance: the BIO will be read on-the-fly while sending the request, which supports streaming. The optional list I may contain additional custom HTTP header lines. - -If the I argument is not NULL, -the client will check that the specified content-type string -is included in the HTTP header of the response and return an error if not. -In the content-type header line the specified string should be present either -as a whole, or in case the specified string does not include a C<;> character, -it is sufficient that the specified string appears as a prefix -in the header line, followed by a C<;> character and any further text. -For instance, if I specifies C, -this is matched by C, C, etc. - -If the I parameter is nonzero, -a structure in ASN.1 encoding will be expected as response content. The I parameter specifies the maximum allowed response content length, where the value 0 indicates no limit. -If the I parameter is > 0 this indicates the maximum number of seconds -the subsequent HTTP transfer (sending the request and receiving a response) -is allowed to take. -A value of 0 enables waiting indefinitely, i.e., no timeout. -A value < 0 indicates that the I parameter value given -when opening the HTTP transfer will be used instead. -If I is 0 the connection is not kept open -after receiving a response, which is the default behavior for HTTP 1.0. -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. +For the meaning of the I, I, I, +and I parameters, see L. OSSL_HTTP_exchange() exchanges any form of HTTP request and response as specified by I, which must include both connection and request data, @@ -212,7 +190,7 @@ 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 function returns NULL and the caller is responsible for deallocating the URL with L. -If the response header contains one or more "Content-Length" header lines and/or +If the response header contains one or more C 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. @@ -285,6 +263,7 @@ OSSL_HTTP_close() returns 0 if anything went wrong while disconnecting, else 1. L, L, L, L, +L, L, L