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