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);
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.
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.
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,
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.
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,
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.
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)>.
projects / thirdparty / openssl.git / commitdiff
