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