1=pod
2
3=head1 NAME
4
5OSSL_HTTP_REQ_CTX,
6OSSL_HTTP_REQ_CTX_new,
7OSSL_HTTP_REQ_CTX_free,
8OSSL_HTTP_REQ_CTX_set_request_line,
9OSSL_HTTP_REQ_CTX_add1_header,
10OSSL_HTTP_REQ_CTX_set_expected,
11OSSL_HTTP_REQ_CTX_set1_req,
12OSSL_HTTP_REQ_CTX_nbio,
13OSSL_HTTP_REQ_CTX_nbio_d2i,
14OSSL_HTTP_REQ_CTX_exchange,
15OSSL_HTTP_REQ_CTX_get0_mem_bio,
16OSSL_HTTP_REQ_CTX_get_resp_len,
17OSSL_HTTP_REQ_CTX_set_max_response_length,
18OSSL_HTTP_is_alive
19- HTTP client low-level functions
20
21=head1 SYNOPSIS
22
23 #include <openssl/http.h>
24
25 typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX;
26
27 OSSL_HTTP_REQ_CTX *OSSL_HTTP_REQ_CTX_new(BIO *wbio, BIO *rbio, int buf_size);
28 void OSSL_HTTP_REQ_CTX_free(OSSL_HTTP_REQ_CTX *rctx);
29
30 int OSSL_HTTP_REQ_CTX_set_request_line(OSSL_HTTP_REQ_CTX *rctx, int method_POST,
31                                        const char *server, const char *port,
32                                        const char *path);
33 int OSSL_HTTP_REQ_CTX_add1_header(OSSL_HTTP_REQ_CTX *rctx,
34                                   const char *name, const char *value);
35
36 int OSSL_HTTP_REQ_CTX_set_expected(OSSL_HTTP_REQ_CTX *rctx,
37                                    const char *content_type, int asn1,
38                                    int timeout, int keep_alive);
39 int OSSL_HTTP_REQ_CTX_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type,
40                                const ASN1_ITEM *it, const ASN1_VALUE *req);
41 int OSSL_HTTP_REQ_CTX_nbio(OSSL_HTTP_REQ_CTX *rctx);
42 int OSSL_HTTP_REQ_CTX_nbio_d2i(OSSL_HTTP_REQ_CTX *rctx,
43                                ASN1_VALUE **pval, const ASN1_ITEM *it);
44 BIO *OSSL_HTTP_REQ_CTX_exchange(OSSL_HTTP_REQ_CTX *rctx);
45
46 BIO *OSSL_HTTP_REQ_CTX_get0_mem_bio(const OSSL_HTTP_REQ_CTX *rctx);
47 size_t OSSL_HTTP_REQ_CTX_get_resp_len(const OSSL_HTTP_REQ_CTX *rctx);
48 void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx,
49                                                unsigned long len);
50
51 int OSSL_HTTP_is_alive(const OSSL_HTTP_REQ_CTX *rctx);
52
53=head1 DESCRIPTION
54
55B<OSSL_HTTP_REQ_CTX> is a context structure for an HTTP request and response,
56used to collect all the necessary data to perform that request.
57
58This file documents low-level HTTP functions rarely used directly.  High-level
59HTTP client functions like L<OSSL_HTTP_get(3)> and L<OSSL_HTTP_transfer(3)>
60should be preferred.
61
62OSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure,
63which gets populated with the B<BIO> to write/send the request to (I<wbio>),
64the B<BIO> to read/receive the response from (I<rbio>, which may be equal to
65I<wbio>), and the maximum expected response header line length I<buf_size>.
66A value <= 0 indicates that
67the B<OSSL_HTTP_DEFAULT_MAX_LINE_LEN> of 4KiB should be used.
68I<buf_size> is also used as the number of content bytes that are read at a time.
69The allocated context structure includes an internal memory B<BIO>,
70which collects the HTTP request header lines.
71
72OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I<rctx>.
73The I<rbio> is not free'd, I<wbio> will be free'd if I<free_wbio> is set.
74If the argument is NULL, nothing is done.
75
76OSSL_HTTP_REQ_CTX_set_request_line() adds the 1st HTTP request line to I<rctx>.
77The HTTP method is determined by I<method_POST>,
78which should be 1 to indicate C<POST> or 0 to indicate C<GET>.
79I<server> and I<port> may be set to give the server and the optional port that
80an HTTP proxy shall forward the request to, otherwise they must be left NULL.
81I<path> provides the HTTP request path; if left NULL, C</> is used.
82For backward compatibility, I<path> may begin with C<http://> and thus convey
83an absoluteURI. In this case it indicates HTTP proxy use and provides also the
84server (and optionally the port) that the proxy shall forward the request to.
85In this case the I<server> and I<port> arguments must be NULL.
86
87OSSL_HTTP_REQ_CTX_add1_header() adds header I<name> with value I<value> to the
88context I<rctx>. It can be called more than once to add multiple header lines.
89For example, to add a C<Host> header for C<example.com> you would call:
90
91 OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
92
93OSSL_HTTP_REQ_CTX_set_expected() optionally sets in I<rctx> some expectations
94of the HTTP client on the response.
95Due to the structure of an HTTP request, if the I<keep_alive> argument is
96nonzero the function must be used before calling OSSL_HTTP_REQ_CTX_set1_req().
97If the I<content_type> parameter
98is not NULL then the client will check that the given content type string
99is included in the HTTP header of the response and return an error if not.
100If the I<asn1> parameter is nonzero a structure in ASN.1 encoding will be
101expected as the response content and input streaming is disabled.  This means
102that an ASN.1 sequence header is required, its length field is checked, and
103OSSL_HTTP_REQ_CTX_get0_mem_bio() should be used to get the buffered response.
104Otherwise (by default) any input format is allowed without length checks.
105In this case the BIO given as I<rbio> argument to OSSL_HTTP_REQ_CTX_new() should
106be used directly to read the response contents, which may support streaming.
107If the I<timeout> parameter is > 0 this indicates the maximum number of seconds
108the subsequent HTTP transfer (sending the request and receiving a response)
109is allowed to take.
110I<timeout> == 0 enables waiting indefinitely, i.e., no timeout can occur.
111This is the default.
112I<timeout> < 0 takes over any value set via the I<overall_timeout> argument of
113L<OSSL_HTTP_open(3)> with the default being 0, which means no timeout.
114If the I<keep_alive> parameter is 0, which is the default, the connection is not
115kept open after receiving a response. This is the default behavior for HTTP 1.0.
116If the value is 1 or 2 then a persistent connection is requested.
117If the value is 2 then a persistent connection is required,
118i.e., an error occurs in case the server does not grant it.
119
120OSSL_HTTP_REQ_CTX_set1_req() finalizes the HTTP request context.
121It is needed if the I<method_POST> parameter in the
122OSSL_HTTP_REQ_CTX_set_request_line() call was 1
123and an ASN.1-encoded request should be sent.
124It must also be used when requesting "keep-alive",
125even if a GET request is going to be sent, in which case I<req> must be NULL.
126Unless I<req> is NULL, the function adds the DER encoding of I<req> using
127the ASN.1 template I<it> to do the encoding (which does not support streaming).
128The HTTP header C<Content-Length> is filled out with the length of the request.
129I<content_type> must be NULL if I<req> is NULL.
130If I<content_type> isn't NULL,
131the HTTP header C<Content-Type> is also added with the given string value.
132The header lines are added to the internal memory B<BIO> for the request header.
133
134OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in I<rctx>
135and to gather the response via HTTP, using the I<wbio> and I<rbio>
136that were given when calling OSSL_HTTP_REQ_CTX_new().
137The function may need to be called again if its result is -1, which indicates
138L<BIO_should_retry(3)>.  In such a case it is advisable to sleep a little in
139between, using L<BIO_wait(3)> on the read BIO to prevent a busy loop.
140
141OSSL_HTTP_REQ_CTX_nbio_d2i() is like OSSL_HTTP_REQ_CTX_nbio() but on success
142in addition parses the response, which must be a DER-encoded ASN.1 structure,
143using the ASN.1 template I<it> and places the result in I<*pval>.
144
145OSSL_HTTP_REQ_CTX_exchange() calls OSSL_HTTP_REQ_CTX_nbio() as often as needed
146in order to exchange a request and response or until a timeout is reached.
147On success it returns a pointer to the BIO that can be used to read the result.
148If an ASN.1-encoded response was expected, this is the BIO
149returned by OSSL_HTTP_REQ_CTX_get0_mem_bio() when called after the exchange.
150This memory BIO does not support streaming.
151Otherwise the returned BIO is the I<rbio> given to OSSL_HTTP_REQ_CTX_new(),
152which may support streaming.
153When this BIO is returned, it has been read past the end of the response header,
154such that the actual response body can be read from it.
155The returned BIO pointer MUST NOT be freed by the caller.
156
157OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
158Before the HTTP request is sent, this could be used to adapt its header lines.
159I<Use with caution!>
160After receiving a response via HTTP, the BIO represents the current state of
161reading the response header. If the response was expected to be ASN.1 encoded,
162its contents can be read via this BIO, which does not support streaming.
163The returned BIO pointer must not be freed by the caller.
164
165OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents
166in I<rctx> if provided by the server as <Content-Length> header field, else 0.
167
168OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed
169response content length for I<rctx> to I<len>. If not set or I<len> is 0
170then the B<OSSL_HTTP_DEFAULT_MAX_RESP_LEN> is used, which currently is 100 KiB.
171If the C<Content-Length> header is present and exceeds this value or
172the content is an ASN.1 encoded structure with a length exceeding this value
173or both length indications are present but disagree then an error occurs.
174
175OSSL_HTTP_is_alive() can be used to query if the HTTP connection
176given by I<rctx> is still alive, i.e., has not been closed.
177It returns 0 if I<rctx> is NULL.
178
179If the client application requested or required a persistent connection
180and this was granted by the server, it can keep I<rctx> as long as it wants
181to send further requests and OSSL_HTTP_is_alive() returns nonzero,
182else it should call I<OSSL_HTTP_REQ_CTX_free(rctx)> or L<OSSL_HTTP_close(3)>.
183In case the client application keeps I<rctx> but the connection then dies
184for any reason at the server side, it will notice this obtaining an
185I/O error when trying to send the next request via I<rctx>.
186
187=head1 WARNINGS
188
189The server's response may be unexpected if the hostname that was used to
190create the I<wbio>, any C<Host> header, and the host specified in the
191request URL do not match.
192
193Many of these functions must be called in a certain order.
194
195First, the HTTP request context must be allocated:
196OSSL_HTTP_REQ_CTX_new().
197
198Then, the HTTP request must be prepared with request data:
199
200=over 4
201
202=item 1.
203
204Calling OSSL_HTTP_REQ_CTX_set_request_line().
205
206=item 2.
207
208Adding extra header lines with OSSL_HTTP_REQ_CTX_add1_header().
209This is optional and may be done multiple times with different names.
210
211=item 3.
212
213Finalize the request using OSSL_HTTP_REQ_CTX_set1_req().
214This may be omitted if the GET method is used and "keep-alive" is not requested.
215
216=back
217
218When the request context is fully prepared, the HTTP exchange may be performed
219with OSSL_HTTP_REQ_CTX_nbio() or OSSL_HTTP_REQ_CTX_exchange().
220
221=head1 RETURN VALUES
222
223OSSL_HTTP_REQ_CTX_new() returns a pointer to a B<OSSL_HTTP_REQ_CTX>, or NULL
224on error.
225
226OSSL_HTTP_REQ_CTX_free() and OSSL_HTTP_REQ_CTX_set_max_response_length()
227do not return values.
228
229OSSL_HTTP_REQ_CTX_set_request_line(), OSSL_HTTP_REQ_CTX_add1_header(),
230OSSL_HTTP_REQ_CTX_set1_req(), and OSSL_HTTP_REQ_CTX_set_expected()
231return 1 for success and 0 for failure.
232
233OSSL_HTTP_REQ_CTX_nbio() and OSSL_HTTP_REQ_CTX_nbio_d2i()
234return 1 for success, 0 on error or redirection, -1 if retry is needed.
235
236OSSL_HTTP_REQ_CTX_exchange() and OSSL_HTTP_REQ_CTX_get0_mem_bio()
237return a pointer to a B<BIO> on success as described above or NULL on failure.
238The returned BIO must not be freed by the caller.
239
240OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents
241or 0 if not available or an error occurred.
242
243OSSL_HTTP_is_alive() returns 1 if its argument is non-NULL
244and the client requested a persistent connection
245and the server did not disagree on keeping the connection open, else 0.
246
247=head1 SEE ALSO
248
249L<BIO_should_retry(3)>,
250L<BIO_wait(3)>,
251L<ASN1_item_d2i_bio(3)>,
252L<ASN1_item_i2d_mem_bio(3)>,
253L<OSSL_HTTP_open(3)>,
254L<OSSL_HTTP_get(3)>,
255L<OSSL_HTTP_transfer(3)>,
256L<OSSL_HTTP_close(3)>
257
258=head1 HISTORY
259
260The functions described here were added in OpenSSL 3.0.
261
262=head1 COPYRIGHT
263
264Copyright 2015-2024 The OpenSSL Project Authors. All Rights Reserved.
265
266Licensed under the Apache License 2.0 (the "License").  You may not use
267this file except in compliance with the License.  You can obtain a copy
268in the file LICENSE in the source distribution or at
269L<https://www.openssl.org/source/license.html>.
270
271=cut
272