]>
Commit | Line | Data |
---|---|---|
29f178bd DDO |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
8f965908 DDO |
5 | OSSL_HTTP_open, |
6 | OSSL_HTTP_bio_cb_t, | |
7 | OSSL_HTTP_proxy_connect, | |
8ccbf00d | 8 | OSSL_HTTP_set1_request, |
8f965908 | 9 | OSSL_HTTP_exchange, |
29f178bd | 10 | OSSL_HTTP_get, |
29f178bd | 11 | OSSL_HTTP_transfer, |
8f965908 DDO |
12 | OSSL_HTTP_close |
13 | - HTTP client high-level functions | |
29f178bd DDO |
14 | |
15 | =head1 SYNOPSIS | |
16 | ||
17 | #include <openssl/http.h> | |
18 | ||
19 | typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, | |
20 | int connect, int detail); | |
8f965908 DDO |
21 | OSSL_HTTP_REQ_CTX *OSSL_HTTP_open(const char *server, const char *port, |
22 | const char *proxy, const char *no_proxy, | |
23 | int use_ssl, BIO *bio, BIO *rbio, | |
24 | OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, | |
25 | int buf_size, int overall_timeout); | |
26 | int OSSL_HTTP_proxy_connect(BIO *bio, const char *server, const char *port, | |
27 | const char *proxyuser, const char *proxypass, | |
28 | int timeout, BIO *bio_err, const char *prog); | |
8ccbf00d DDO |
29 | int OSSL_HTTP_set1_request(OSSL_HTTP_REQ_CTX *rctx, const char *path, |
30 | const STACK_OF(CONF_VALUE) *headers, | |
31 | const char *content_type, BIO *req, | |
32 | const char *expected_content_type, int expect_asn1, | |
33 | size_t max_resp_len, int timeout, int keep_alive); | |
8f965908 | 34 | BIO *OSSL_HTTP_exchange(OSSL_HTTP_REQ_CTX *rctx, char **redirection_url); |
afe554c2 | 35 | BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy, |
29f178bd DDO |
36 | BIO *bio, BIO *rbio, |
37 | OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, | |
8f965908 DDO |
38 | int buf_size, const STACK_OF(CONF_VALUE) *headers, |
39 | const char *expected_content_type, int expect_asn1, | |
40 | size_t max_resp_len, int timeout); | |
41 | BIO *OSSL_HTTP_transfer(OSSL_HTTP_REQ_CTX **prctx, | |
42 | const char *server, const char *port, | |
43 | const char *path, int use_ssl, | |
44 | const char *proxy, const char *no_proxy, | |
29f178bd DDO |
45 | BIO *bio, BIO *rbio, |
46 | OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, | |
8f965908 DDO |
47 | int buf_size, const STACK_OF(CONF_VALUE) *headers, |
48 | const char *content_type, BIO *req, | |
49 | const char *expected_content_type, int expect_asn1, | |
50 | size_t max_resp_len, int timeout, int keep_alive); | |
51 | int OSSL_HTTP_close(OSSL_HTTP_REQ_CTX *rctx, int ok); | |
29f178bd DDO |
52 | |
53 | =head1 DESCRIPTION | |
54 | ||
82990287 DDO |
55 | OSSL_HTTP_open() initiates an HTTP session using the I<bio> argument if not |
56 | NULL, else by connecting to a given I<server> optionally via a I<proxy>. | |
29f178bd | 57 | |
8f965908 | 58 | Typically the OpenSSL build supports sockets and the I<bio> parameter is NULL. |
119f8145 DDO |
59 | In this case I<rbio> must be NULL as well and the I<server> must be non-NULL. |
60 | The function creates a network BIO internally using L<BIO_new_connect(3)> | |
61 | for connecting to the given server and the optionally given I<port>, | |
62 | defaulting to 80 for HTTP or 443 for HTTPS. | |
8f965908 DDO |
63 | Then this internal BIO is used for setting up a connection |
64 | and for exchanging one or more request and response. | |
65 | If I<bio> is given and I<rbio> is NULL then this I<bio> is used instead. | |
d7fcee3b | 66 | If both I<bio> and I<rbio> are given (which may be memory BIOs for instance) |
8f965908 DDO |
67 | then no explicit connection is set up, but |
68 | I<bio> is used for writing requests and I<rbio> for reading responses. | |
d7fcee3b DDO |
69 | As soon as the client has flushed I<bio> the server must be ready to provide |
70 | a response or indicate a waiting condition via I<rbio>. | |
29f178bd | 71 | |
59b6b5a9 DDO |
72 | If I<bio> is given, it is an error to provide I<proxy> or I<no_proxy> arguments, |
73 | while I<server> and I<port> arguments may be given to support diagnostic output. | |
79a2bccd | 74 | If I<bio> is NULL the optional I<proxy> parameter can be used to set an |
4b1fe471 | 75 | HTTP(S) proxy to use (unless overridden by "no_proxy" settings). |
d7fcee3b DDO |
76 | If TLS is not used this defaults to the environment variable C<http_proxy> |
77 | if set, else C<HTTP_PROXY>. | |
78 | If I<use_ssl> != 0 it defaults to C<https_proxy> if set, else C<HTTPS_PROXY>. | |
79a2bccd DDO |
79 | An empty proxy string C<""> forbids using a proxy. |
80 | Else the format is | |
81 | C<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>, | |
82 | where any userinfo, path, query, and fragment given is ignored. | |
4b1fe471 | 83 | The default proxy port number is 80, or 443 in case "https:" is given. |
d7fcee3b DDO |
84 | The HTTP client functions connect via the given proxy unless the I<server> |
85 | is found in the optional list I<no_proxy> of proxy hostnames (if not NULL; | |
86 | default is the environment variable C<no_proxy> if set, else C<NO_PROXY>). | |
4b1fe471 DDO |
87 | Proxying plain HTTP is supported directly, |
88 | while using a proxy for HTTPS connections requires a suitable callback function | |
d7fcee3b | 89 | such as OSSL_HTTP_proxy_connect(), described below. |
4b1fe471 | 90 | |
8f965908 DDO |
91 | If I<use_ssl> is nonzero a TLS connection is requested |
92 | and the I<bio_update_fn> parameter must be provided. | |
29f178bd | 93 | |
8f965908 DDO |
94 | The parameter I<bio_update_fn>, which is optional if I<use_ssl> is 0, |
95 | may be used to modify the connection BIO used by the HTTP client, | |
96 | but cannot be used when both I<bio> and I<rbio> are given. | |
d7fcee3b | 97 | I<bio_update_fn> is a BIO connect/disconnect callback function with prototype |
29f178bd DDO |
98 | |
99 | BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail) | |
100 | ||
2080134e | 101 | The callback function may modify the BIO provided in the I<bio> argument, |
d7fcee3b | 102 | whereby it may make use of a custom defined argument I<arg>, |
2080134e DDO |
103 | which may for instance point to an B<SSL_CTX> structure. |
104 | During connection establishment, just after calling BIO_do_connect_retry(), the | |
35750cb9 DDO |
105 | callback function is invoked with the I<connect> argument being 1 and |
106 | I<detail> being 1 if I<use_ssl> is nonzero (i.e., HTTPS is requested), else 0. | |
d7fcee3b | 107 | On disconnect I<connect> is 0 and I<detail> is 1 if no error occurred, else 0. |
2080134e DDO |
108 | For instance, on connect the callback may push an SSL BIO to implement HTTPS; |
109 | after disconnect it may do some diagnostic output and pop and free the SSL BIO. | |
110 | ||
111 | The callback function must return either the potentially modified BIO I<bio>. | |
112 | or NULL to indicate failure, in which case it should not modify the BIO. | |
113 | ||
29f178bd DDO |
114 | Here is a simple example that supports TLS connections (but not via a proxy): |
115 | ||
cdaf072f | 116 | BIO *http_tls_cb(BIO *bio, void *arg, int connect, int detail) |
29f178bd | 117 | { |
29f178bd | 118 | if (connect && detail) { /* connecting with TLS */ |
8f965908 | 119 | SSL_CTX *ctx = (SSL_CTX *)arg; |
29f178bd | 120 | BIO *sbio = BIO_new_ssl(ctx, 1); |
8f965908 | 121 | |
cdaf072f DDO |
122 | bio = sbio != NULL ? BIO_push(sbio, bio) : NULL; |
123 | } else if (!connect) { /* disconnecting */ | |
124 | BIO *hbio; | |
125 | ||
126 | if (!detail) { /* an error has occurred */ | |
127 | /* optionally add diagnostics here */ | |
128 | } | |
129 | BIO_ssl_shutdown(bio); | |
130 | hbio = BIO_pop(bio); | |
131 | BIO_free(bio); /* SSL BIO */ | |
132 | bio = hbio; | |
29f178bd | 133 | } |
cdaf072f | 134 | return bio; |
29f178bd DDO |
135 | } |
136 | ||
137 | After disconnect the modified BIO will be deallocated using BIO_free_all(). | |
138 | ||
8f965908 | 139 | The I<buf_size> parameter specifies the response header maximum line length. |
647a5dbf DDO |
140 | A value <= 0 means that the B<OSSL_HTTP_DEFAULT_MAX_LINE_LEN> (4KiB) is used. |
141 | I<buf_size> is also used as the number of content bytes that are read at a time. | |
8f965908 DDO |
142 | |
143 | If the I<overall_timeout> parameter is > 0 this indicates the maximum number of | |
144 | seconds the overall HTTP transfer (i.e., connection setup if needed, | |
145 | sending requests, and receiving responses) is allowed to take until completion. | |
146 | A value <= 0 enables waiting indefinitely, i.e., no timeout. | |
147 | ||
29f178bd | 148 | OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function |
4b1fe471 | 149 | to set up an SSL/TLS connection via an HTTPS proxy. |
d7fcee3b | 150 | It promotes the given BIO I<bio> representing a connection |
29f178bd | 151 | pre-established with a TLS proxy using the HTTP CONNECT method, |
d7fcee3b DDO |
152 | optionally using proxy client credentials I<proxyuser> and I<proxypass>, |
153 | to connect with TLS protection ultimately to I<server> and I<port>. | |
154 | If the I<port> argument is NULL or the empty string it defaults to "443". | |
8f965908 DDO |
155 | If the I<timeout> parameter is > 0 this indicates the maximum number of |
156 | seconds the connection setup is allowed to take. | |
157 | A value <= 0 enables waiting indefinitely, i.e., no timeout. | |
bb361a27 | 158 | Since this function is typically called by applications such as |
d7fcee3b | 159 | L<openssl-s_client(1)> it uses the I<bio_err> and I<prog> parameters (unless |
29f178bd DDO |
160 | NULL) to print additional diagnostic information in a user-oriented way. |
161 | ||
8ccbf00d | 162 | OSSL_HTTP_set1_request() sets up in I<rctx> the request header and content data |
8f965908 | 163 | and expectations on the response using the following parameters. |
45c02183 DDO |
164 | If <rctx> indicates using a proxy for HTTP (but not HTTPS), the server host |
165 | (and optionally port) needs to be placed in the header; thus it must be present | |
166 | in I<rctx>. | |
167 | For backward compatibility, the server (and optional port) may also be given in | |
168 | the I<path> argument beginning with C<http://> (thus giving an absoluteURI). | |
8f965908 | 169 | If I<path> is NULL it defaults to "/". |
82990287 DDO |
170 | If I<req> is NULL the HTTP GET method will be used to send the request |
171 | else HTTP POST with the contents of I<req> and optional I<content_type>, where | |
8b5ca511 DDO |
172 | the length of the data in I<req> does not need to be determined in advance: the |
173 | BIO will be read on-the-fly while sending the request, which supports streaming. | |
8f965908 | 174 | The optional list I<headers> may contain additional custom HTTP header lines. |
52f61699 DDO |
175 | |
176 | If the I<expected_content_type> argument is not NULL, | |
177 | the client will check that the specified content-type string | |
8f965908 | 178 | is included in the HTTP header of the response and return an error if not. |
52f61699 DDO |
179 | In the content-type header line the specified string should be present either |
180 | as a whole, or in case the specified string does not include a C<;> character, | |
181 | it is sufficient that the specified string appears as a prefix | |
182 | in the header line, followed by a C<;> character and any further text. | |
183 | For instance, if I<expected_content_type> specifies C<text/html>, | |
184 | this is matched by C<text/html>, C<text/html; charset=UTF-8>, etc. | |
185 | ||
8f965908 DDO |
186 | If the I<expect_asn1> parameter is nonzero, |
187 | a structure in ASN.1 encoding will be expected as response content. | |
be799eb7 DDO |
188 | The I<max_resp_len> parameter specifies the maximum allowed |
189 | response content length, where the value 0 indicates no limit. | |
8f965908 DDO |
190 | If the I<timeout> parameter is > 0 this indicates the maximum number of seconds |
191 | the subsequent HTTP transfer (sending the request and receiving a response) | |
192 | is allowed to take. | |
193 | A value of 0 enables waiting indefinitely, i.e., no timeout. | |
194 | A value < 0 indicates that the I<overall_timeout> parameter value given | |
195 | when opening the HTTP transfer will be used instead. | |
196 | If I<keep_alive> is 0 the connection is not kept open | |
197 | after receiving a response, which is the default behavior for HTTP 1.0. | |
198 | If the value is 1 or 2 then a persistent connection is requested. | |
199 | If the value is 2 then a persistent connection is required, | |
200 | i.e., an error occurs in case the server does not grant it. | |
201 | ||
82990287 | 202 | OSSL_HTTP_exchange() exchanges any form of HTTP request and response |
8f965908 | 203 | as specified by I<rctx>, which must include both connection and request data, |
8ccbf00d | 204 | typically set up using OSSL_HTTP_open() and OSSL_HTTP_set1_request(). |
8f965908 DDO |
205 | It implements the core of the functions described below. |
206 | If the HTTP method is GET and I<redirection_url> | |
207 | is not NULL the latter pointer is used to provide any new location that | |
208 | the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND). | |
82990287 DDO |
209 | In this case the function returns NULL and the caller is |
210 | responsible for deallocating the URL with L<OPENSSL_free(3)>. | |
8f965908 DDO |
211 | If the response header contains one or more "Content-Length" header lines and/or |
212 | an ASN.1-encoded response is expected, which should include a total length, | |
213 | the length indications received are checked for consistency | |
214 | and for not exceeding any given maximum response length. | |
a26c089b | 215 | If an ASN.1-encoded response is expected, the function returns on success |
7d5019c1 | 216 | the contents buffered in a memory BIO, which does not support streaming. |
a26c089b | 217 | Otherwise it returns directly the read BIO that holds the response contents, |
8f965908 | 218 | which allows a response of indefinite length and may support streaming. |
a26c089b | 219 | The caller is responsible for freeing the BIO pointer obtained. |
8f965908 DDO |
220 | |
221 | OSSL_HTTP_get() uses HTTP GET to obtain data from I<bio> if non-NULL, | |
222 | else from the server contained in the I<url>, and returns it as a BIO. | |
223 | It supports redirection via HTTP status code 301 or 302. It is meant for | |
224 | transfers with a single round trip, so does not support persistent connections. | |
225 | If I<bio> is non-NULL, any host and port components in the I<url> are not used | |
226 | for connecting but the hostname is used, as usual, for the C<Host> header. | |
227 | Any userinfo and fragment components in the I<url> are ignored. | |
228 | Any query component is handled as part of the path component. | |
229 | If the scheme component of the I<url> is C<https> a TLS connection is requested | |
230 | and the I<bio_update_fn>, as described for OSSL_HTTP_open(), must be provided. | |
231 | Also the remaining parameters are interpreted as described for OSSL_HTTP_open() | |
8ccbf00d | 232 | and OSSL_HTTP_set1_request(), respectively. |
a26c089b | 233 | The caller is responsible for freeing the BIO pointer obtained. |
8f965908 | 234 | |
82990287 DDO |
235 | OSSL_HTTP_transfer() exchanges an HTTP request and response |
236 | over a connection managed via I<prctx> without supporting redirection. | |
8ccbf00d | 237 | It combines OSSL_HTTP_open(), OSSL_HTTP_set1_request(), OSSL_HTTP_exchange(), |
82990287 DDO |
238 | and OSSL_HTTP_close(). |
239 | If I<prctx> is not NULL it reuses any open connection represented by a non-NULL | |
240 | I<*prctx>. It keeps the connection open if a persistent connection is requested | |
241 | or required and this was granted by the server, else it closes the connection | |
242 | and assigns NULL to I<*prctx>. | |
243 | The remaining parameters are interpreted as described for OSSL_HTTP_open() | |
8ccbf00d | 244 | and OSSL_HTTP_set1_request(), respectively. |
a26c089b | 245 | The caller is responsible for freeing the BIO pointer obtained. |
82990287 | 246 | |
8f965908 DDO |
247 | OSSL_HTTP_close() closes the connection and releases I<rctx>. |
248 | The I<ok> parameter is passed to any BIO update function | |
249 | given during setup as described above for OSSL_HTTP_open(). | |
4ee464cf | 250 | It must be 1 if no error occurred during the HTTP transfer and 0 otherwise. |
8f965908 | 251 | |
4b1fe471 DDO |
252 | =head1 NOTES |
253 | ||
254 | The names of the environment variables used by this implementation: | |
d7fcee3b DDO |
255 | C<http_proxy>, C<HTTP_PROXY>, C<https_proxy>, C<HTTPS_PROXY>, C<no_proxy>, and |
256 | C<NO_PROXY>, have been chosen for maximal compatibility with | |
4b1fe471 DDO |
257 | other HTTP client implementations such as wget, curl, and git. |
258 | ||
e8fdb060 DDO |
259 | When built with tracing enabled, OSSL_HTTP_transfer() and all functions using it |
260 | may be traced using B<OSSL_TRACE_CATEGORY_HTTP>. | |
261 | See also L<OSSL_trace_enabled(3)> and L<openssl(1)/ENVIRONMENT>. | |
262 | ||
29f178bd DDO |
263 | =head1 RETURN VALUES |
264 | ||
8f965908 DDO |
265 | OSSL_HTTP_open() returns on success a B<OSSL_HTTP_REQ_CTX>, else NULL. |
266 | ||
8ccbf00d | 267 | OSSL_HTTP_proxy_connect() and OSSL_HTTP_set1_request() |
8f965908 DDO |
268 | return 1 on success, 0 on error. |
269 | ||
270 | On success, OSSL_HTTP_exchange(), OSSL_HTTP_get(), and OSSL_HTTP_transfer() | |
7d5019c1 DDO |
271 | return a memory BIO that buffers all the data received if an ASN.1-encoded |
272 | response is expected, otherwise a BIO that may support streaming. | |
be799eb7 | 273 | The BIO must be freed by the caller. |
8f965908 | 274 | On failure, they return NULL. |
6aab42c3 | 275 | Failure conditions include connection/transfer timeout, parse errors, etc. |
a26c089b | 276 | The caller is responsible for freeing the BIO pointer obtained. |
29f178bd | 277 | |
8f965908 | 278 | OSSL_HTTP_close() returns 0 if anything went wrong while disconnecting, else 1. |
29f178bd | 279 | |
d7fcee3b DDO |
280 | =head1 SEE ALSO |
281 | ||
119f8145 | 282 | L<OSSL_HTTP_parse_url(3)>, L<BIO_new_connect(3)>, |
8f965908 | 283 | L<ASN1_item_i2d_mem_bio(3)>, L<ASN1_item_d2i_bio(3)>, |
e8fdb060 DDO |
284 | L<OSSL_HTTP_is_alive(3)>, |
285 | L<OSSL_trace_enabled(3)> | |
d7fcee3b | 286 | |
29f178bd DDO |
287 | =head1 HISTORY |
288 | ||
8f965908 | 289 | All the functions described here were added in OpenSSL 3.0. |
29f178bd DDO |
290 | |
291 | =head1 COPYRIGHT | |
292 | ||
da1c088f | 293 | Copyright 2019-2023 The OpenSSL Project Authors. All Rights Reserved. |
29f178bd DDO |
294 | |
295 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
296 | this file except in compliance with the License. You can obtain a copy | |
297 | in the file LICENSE in the source distribution or at | |
298 | L<https://www.openssl.org/source/license.html>. | |
299 | ||
300 | =cut |