mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-04-12 20:30:52 +08:00
Code Issues Packages Projects Releases Wiki Activity

remove parts of OSSL_HTTP_transfer.pod that are better described in OSSL_HTTP_transfer.pod

Browse Source 
Reviewed-by: Dmitry Belyavskiy <beldmit@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/25541)
This commit is contained in:
Dr. David von Oheimb 2024-10-07 21:17:59 +02:00
parent 0ba139f4b9
commit 153adbc540
2 changed files with 20 additions and 36 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
doc/man3/OSSL_HTTP_REQ_CTX.pod
View File

@ -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<keep_alive> argument is
nonzero the function must be used before calling OSSL_HTTP_REQ_CTX_set1_req().
If the I<content_type> argument is not NULL,
the client will check that the specified content-type string
If the I<expected_content_type> argument is not NULL, the client will
check in a case-insensitive way that the specified C<Content-Type> 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<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 the I<content_type> argument specifies C<text/html>,
this is matched by C<text/html>, C<text/html; charset=UTF-8>, etc.
For instance, if the I<expected_content_type> argument specifies C<text/html>,
this is matched by C<Text/HTML>, C<text/html; charset=UTF-8>, etc.
If the I<asn1> parameter is nonzero a structure in ASN.1 encoding will be
If the I<expect_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 (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
the subsequent HTTP transfer (sending the request and receiving a response)
is allowed to take.
@ -123,6 +124,7 @@ I<timeout> == 0 enables waiting indefinitely, i.e., no timeout can occur.
This is the default.
I<timeout> < 0 takes over any value set via the I<overall_timeout> argument of
L<OSSL_HTTP_open(3)> with the default being 0, which means no timeout.
If the I<keep_alive> 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<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.
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<Content-Length> 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<rctx> if provided by the server as <Content-Length> header field, else 0.
in I<rctx> if provided by the server as C<Content-Length> header field, else 0.
OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed
response content length for I<rctx> to I<len>. If not set or I<len> is 0
then the B<OSSL_HTTP_DEFAULT_MAX_RESP_LEN> is used, which currently is 100 KiB.
If the C<Content-Length> 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<rctx> is still alive, i.e., has not been closed.

29
doc/man3/OSSL_HTTP_transfer.pod
View File

@ -176,32 +176,10 @@ else HTTP POST with the contents of I<req> and optional I<content_type>, where
the length of the data in I<req> 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<headers> may contain additional custom HTTP header lines.
If the I<expected_content_type> 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<expected_content_type> specifies C<text/html>,
this is matched by C<text/html>, C<text/html; charset=UTF-8>, etc.
If the I<expect_asn1> parameter is nonzero,
a structure in ASN.1 encoding will be expected as response content.
The I<max_resp_len> parameter specifies the maximum allowed
response content length, where the value 0 indicates no limit.
If the I<timeout> 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<overall_timeout> parameter value given
when opening the HTTP transfer will be used instead.
If I<keep_alive> 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<expected_content_type>, I<expect_asn1>, I<timeout>,
and I<keep_alive> parameters, see L<OSSL_HTTP_REQ_CTX_set_expected(3)>.
OSSL_HTTP_exchange() exchanges any form of HTTP request and response
as specified by I<rctx>, 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<OPENSSL_free(3)>.
If the response header contains one or more "Content-Length" header lines and/or
If the response header contains one or more C<Content-Length> 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<OSSL_HTTP_parse_url(3)>, L<BIO_new_connect(3)>,
L<ASN1_item_i2d_mem_bio(3)>, L<ASN1_item_d2i_bio(3)>,
L<OSSL_HTTP_REQ_CTX_set_expected(3)>,
L<OSSL_HTTP_is_alive(3)>,
L<OSSL_trace_enabled(3)>, and L<openssl-env(7)>.