mirror/openssl
2
0
Fork 0
mirror of https://github.com/openssl/openssl.git synced 2025-01-18 13:44:20 +08:00
Code Issues Packages Projects Releases Wiki Activity

OSSL_HTTP_REQ_CTX.pod and OSSL_HTTP_transfer.pod: various improvements

Browse Source 
Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13960)
This commit is contained in:
Dr. David von Oheimb 2021-01-25 20:44:39 +01:00 committed by Dr. David von Oheimb
parent 4d190f99ef
commit 6aab42c390
2 changed files with 27 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

31
doc/man3/OSSL_HTTP_REQ_CTX.pod
View File

@ -56,8 +56,8 @@ should be preferred.
OSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure,
which gets populated with the B<BIO> to send the request to (I<wbio>),
the B<BIO> to read the response from (I<rbio>, which may be equal to I<wbio>),
the maximum expected response header line length (I<maxline>, where any
zero or less indicates using the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB;
the maximum expected response header line length (I<maxline>, where a value <= 0
indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB should be used;
this length is also used as the number of content bytes read at a time),
the request method (I<method_POST>, which may be 1 to indicate that the C<POST>
method is to be used, or 0 to indicate that the C<GET> method is to be used),
@ -90,27 +90,31 @@ 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");
OSSL_HTTP_REQ_CTX_i2d() finalizes the HTTP request context by adding the DER
encoding of I<req>, using the ASN.1 template I<it> to do the encoding. The
HTTP header C<Content-Length> is automatically filled out, and if
OSSL_HTTP_REQ_CTX_i2d() finalizes the HTTP request context by adding
the DER encoding of I<req>, using the ASN.1 template I<it> to do the encoding.
The HTTP header C<Content-Length> is automatically filled out, and if
I<content_type> isn't NULL, the HTTP header C<Content-Type> is also added with
its content as value. All of this ends up in the internal memory B<BIO>.
This requires that I<method_POST> was 1 in the OSSL_HTTP_REQ_CTX_new() call.
OSSL_HTTP_REQ_CTX_nbio() attempts the exchange of request and response via HTTP,
using the I<rbio> and I<wbio> that were given in the OSSL_HTTP_REQ_CTX_new()
call. When successful, the contents of the internal memory B<BIO> is replaced
with the contents of the HTTP response, without the response headers.
OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared I<rctx>
and gathering the response via HTTP, using the I<rbio> and I<wbio>
that were given when calling OSSL_HTTP_REQ_CTX_new().
When successful, the contents of the internal memory B<BIO> contains
the contents of the HTTP response, without the response headers.
It 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 to prevent a busy loop.
between using L<BIO_wait(3)> on the read BIO to prevent a busy loop.
OSSL_HTTP_REQ_CTX_sendreq_d2i() calls OSSL_HTTP_REQ_CTX_nbio(), possibly
several times until a timeout is reached, and DER decodes the received
response using the ASN.1 template I<it>.
OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>. This can
be used to affect the HTTP request text. I<Use with caution!>
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.
I<Use with caution!>
After receiving a response via HTTP, the BIO represents
the current state of reading the response headers and contents.
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
@ -173,6 +177,9 @@ OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
=head1 SEE ALSO
L<BIO_should_retry(3)>,
L<BIO_wait(3)>,
L<OSSL_HTTP_get(3)>,
L<OSSL_HTTP_transfer(3)>
=head1 COPYRIGHT

14
doc/man3/OSSL_HTTP_transfer.pod
View File

@ -123,10 +123,11 @@ while using a proxy for HTTPS connections requires a suitable callback function
such as OSSL_HTTP_proxy_connect(), described below.
The I<maxline> parameter specifies the response header maximum line length,
where a value <= 0 indicates using the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB.
This length is also used as the number of content bytes read at a time.
where a value <= 0 indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB
should be used.
This length is also used as the number of content bytes that are read at a time.
The I<max_resp_len> parameter specifies the maximum response length,
where 0 indicates the B<HTTP_DEFAULT_MAX_RESP_LEN>, which currently is 100 KiB.
where 0 indicates B<HTTP_DEFAULT_MAX_RESP_LEN>, which currently is 100 KiB.
An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and
OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer()
@ -218,9 +219,10 @@ other HTTP client implementations such as wget, curl, and git.
=head1 RETURN VALUES
OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
OSSL_HTTP_transfer() return on success the data received via HTTP, else NULL.
Error conditions include connection/transfer timeout, parse errors, etc.
On success, OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
OSSL_HTTP_transfer() return a memory BIO containing the data received via HTTP.
This must be freed by the caller. On failure, NULL is returned.
Failure conditions include connection/transfer timeout, parse errors, etc.
OSSL_HTTP_proxy_connect() and OSSL_HTTP_parse_url()
return 1 on success, 0 on error.