]>
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, | |
8 | OSSL_HTTP_set_request, | |
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); | |
29 | int OSSL_HTTP_set_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); | |
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 | ||
8f965908 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 DDO |
58 | Typically the OpenSSL build supports sockets and the I<bio> parameter is NULL. |
59 | In this case I<rbio> must be NULL as well, and the | |
60 | library creates a network BIO internally for connecting to the given I<server> | |
61 | at the specified I<port> if any, defaulting to 80 for HTTP or 443 for HTTPS. | |
62 | Then this internal BIO is used for setting up a connection | |
63 | and for exchanging one or more request and response. | |
64 | If I<bio> is given and I<rbio> is NULL then this I<bio> is used instead. | |
d7fcee3b | 65 | If both I<bio> and I<rbio> are given (which may be memory BIOs for instance) |
8f965908 DDO |
66 | then no explicit connection is set up, but |
67 | I<bio> is used for writing requests and I<rbio> for reading responses. | |
d7fcee3b DDO |
68 | As soon as the client has flushed I<bio> the server must be ready to provide |
69 | a response or indicate a waiting condition via I<rbio>. | |
29f178bd | 70 | |
79a2bccd | 71 | If I<bio> is NULL the optional I<proxy> parameter can be used to set an |
4b1fe471 | 72 | HTTP(S) proxy to use (unless overridden by "no_proxy" settings). |
d7fcee3b DDO |
73 | If TLS is not used this defaults to the environment variable C<http_proxy> |
74 | if set, else C<HTTP_PROXY>. | |
75 | If I<use_ssl> != 0 it defaults to C<https_proxy> if set, else C<HTTPS_PROXY>. | |
79a2bccd DDO |
76 | An empty proxy string C<""> forbids using a proxy. |
77 | Else the format is | |
78 | C<[http[s]://][userinfo@]host[:port][/path][?query][#fragment]>, | |
79 | where any userinfo, path, query, and fragment given is ignored. | |
4b1fe471 | 80 | The default proxy port number is 80, or 443 in case "https:" is given. |
d7fcee3b DDO |
81 | The HTTP client functions connect via the given proxy unless the I<server> |
82 | is found in the optional list I<no_proxy> of proxy hostnames (if not NULL; | |
83 | default is the environment variable C<no_proxy> if set, else C<NO_PROXY>). | |
4b1fe471 DDO |
84 | Proxying plain HTTP is supported directly, |
85 | while using a proxy for HTTPS connections requires a suitable callback function | |
d7fcee3b | 86 | such as OSSL_HTTP_proxy_connect(), described below. |
4b1fe471 | 87 | |
8f965908 DDO |
88 | If I<use_ssl> is nonzero a TLS connection is requested |
89 | and the I<bio_update_fn> parameter must be provided. | |
29f178bd | 90 | |
8f965908 DDO |
91 | The parameter I<bio_update_fn>, which is optional if I<use_ssl> is 0, |
92 | may be used to modify the connection BIO used by the HTTP client, | |
93 | but cannot be used when both I<bio> and I<rbio> are given. | |
d7fcee3b | 94 | I<bio_update_fn> is a BIO connect/disconnect callback function with prototype |
29f178bd DDO |
95 | |
96 | BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail) | |
97 | ||
d7fcee3b DDO |
98 | The callback may modify the HTTP BIO provided in the I<bio> argument, |
99 | whereby it may make use of a custom defined argument I<arg>, | |
29f178bd | 100 | which may for instance refer to an I<SSL_CTX> structure. |
e98c7350 | 101 | During connection establishment, just after calling BIO_do_connect_retry(), |
d7fcee3b | 102 | the function is invoked with the I<connect> argument being 1 and the I<detail> |
8f965908 | 103 | argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled, else 0. |
d7fcee3b | 104 | On disconnect I<connect> is 0 and I<detail> is 1 if no error occurred, else 0. |
29f178bd DDO |
105 | For instance, on connect the function may prepend a TLS BIO to implement HTTPS; |
106 | after disconnect it may do some diagnostic output and/or specific cleanup. | |
107 | The function should return NULL to indicate failure. | |
108 | Here is a simple example that supports TLS connections (but not via a proxy): | |
109 | ||
110 | BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail) | |
111 | { | |
29f178bd | 112 | if (connect && detail) { /* connecting with TLS */ |
8f965908 | 113 | SSL_CTX *ctx = (SSL_CTX *)arg; |
29f178bd | 114 | BIO *sbio = BIO_new_ssl(ctx, 1); |
8f965908 | 115 | |
29f178bd DDO |
116 | hbio = sbio != NULL ? BIO_push(sbio, hbio) : NULL; |
117 | } else if (!connect && !detail) { /* disconnecting after error */ | |
118 | /* optionally add diagnostics here */ | |
119 | } | |
120 | return hbio; | |
121 | } | |
122 | ||
123 | After disconnect the modified BIO will be deallocated using BIO_free_all(). | |
124 | ||
8f965908 DDO |
125 | The I<buf_size> parameter specifies the response header maximum line length. |
126 | A value <= 0 indicates that | |
127 | the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB should be used. | |
128 | I<buf_size> is also used as the number of content bytes that are read at a time. | |
129 | ||
130 | If the I<overall_timeout> parameter is > 0 this indicates the maximum number of | |
131 | seconds the overall HTTP transfer (i.e., connection setup if needed, | |
132 | sending requests, and receiving responses) is allowed to take until completion. | |
133 | A value <= 0 enables waiting indefinitely, i.e., no timeout. | |
134 | ||
29f178bd | 135 | OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function |
4b1fe471 | 136 | to set up an SSL/TLS connection via an HTTPS proxy. |
d7fcee3b | 137 | It promotes the given BIO I<bio> representing a connection |
29f178bd | 138 | pre-established with a TLS proxy using the HTTP CONNECT method, |
d7fcee3b DDO |
139 | optionally using proxy client credentials I<proxyuser> and I<proxypass>, |
140 | to connect with TLS protection ultimately to I<server> and I<port>. | |
141 | If the I<port> argument is NULL or the empty string it defaults to "443". | |
8f965908 DDO |
142 | If the I<timeout> parameter is > 0 this indicates the maximum number of |
143 | seconds the connection setup is allowed to take. | |
144 | A value <= 0 enables waiting indefinitely, i.e., no timeout. | |
bb361a27 | 145 | Since this function is typically called by applications such as |
d7fcee3b | 146 | L<openssl-s_client(1)> it uses the I<bio_err> and I<prog> parameters (unless |
29f178bd DDO |
147 | NULL) to print additional diagnostic information in a user-oriented way. |
148 | ||
8f965908 DDO |
149 | OSSL_HTTP_set_request() sets up in I<rctx> the request header and content data |
150 | and expectations on the response using the following parameters. | |
151 | If I<path> is NULL it defaults to "/". | |
152 | If I<req> is NULL the HTTP GET method will be used to send the request | |
153 | else HTTP POST with the contents of I<req> and optional I<content_type>, where | |
154 | the length of the data in I<req> does not need to be determined in advance: the | |
155 | BIO will be read on-the-fly while sending the request, which supports streaming. | |
156 | The optional list I<headers> may contain additional custom HTTP header lines. | |
157 | If the parameter I<expected_content_type> | |
158 | is not NULL then the client will check that the given content type string | |
159 | is included in the HTTP header of the response and return an error if not. | |
160 | If the I<expect_asn1> parameter is nonzero, | |
161 | a structure in ASN.1 encoding will be expected as response content. | |
162 | The I<max_resp_len> parameter specifies the maximum allowed | |
163 | response content length, where the value 0 indicates no limit. | |
164 | If the I<timeout> parameter is > 0 this indicates the maximum number of seconds | |
165 | the subsequent HTTP transfer (sending the request and receiving a response) | |
166 | is allowed to take. | |
167 | A value of 0 enables waiting indefinitely, i.e., no timeout. | |
168 | A value < 0 indicates that the I<overall_timeout> parameter value given | |
169 | when opening the HTTP transfer will be used instead. | |
170 | If I<keep_alive> is 0 the connection is not kept open | |
171 | after receiving a response, which is the default behavior for HTTP 1.0. | |
172 | If the value is 1 or 2 then a persistent connection is requested. | |
173 | If the value is 2 then a persistent connection is required, | |
174 | i.e., an error occurs in case the server does not grant it. | |
175 | ||
176 | OSSL_HTTP_exchange() exchanges any form of HTTP request and response | |
177 | as specified by I<rctx>, which must include both connection and request data, | |
178 | typically set up using OSSL_HTTP_open() and OSSL_HTTP_set_request(). | |
179 | It implements the core of the functions described below. | |
180 | If the HTTP method is GET and I<redirection_url> | |
181 | is not NULL the latter pointer is used to provide any new location that | |
182 | the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND). | |
183 | In this case the function returns NULL and the caller is | |
184 | responsible for deallocating the URL with L<OPENSSL_free(3)>. | |
185 | If the response header contains one or more "Content-Length" header lines and/or | |
186 | an ASN.1-encoded response is expected, which should include a total length, | |
187 | the length indications received are checked for consistency | |
188 | and for not exceeding any given maximum response length. | |
189 | On receiving a response, the function returns the contents as a memory BIO, | |
190 | which does not support streaming, in case an ASN.1-encoded response is expected. | |
191 | Else it returns directly the read BIO that holds the response contents, | |
192 | which allows a response of indefinite length and may support streaming. | |
193 | ||
194 | OSSL_HTTP_get() uses HTTP GET to obtain data from I<bio> if non-NULL, | |
195 | else from the server contained in the I<url>, and returns it as a BIO. | |
196 | It supports redirection via HTTP status code 301 or 302. It is meant for | |
197 | transfers with a single round trip, so does not support persistent connections. | |
198 | If I<bio> is non-NULL, any host and port components in the I<url> are not used | |
199 | for connecting but the hostname is used, as usual, for the C<Host> header. | |
200 | Any userinfo and fragment components in the I<url> are ignored. | |
201 | Any query component is handled as part of the path component. | |
202 | If the scheme component of the I<url> is C<https> a TLS connection is requested | |
203 | and the I<bio_update_fn>, as described for OSSL_HTTP_open(), must be provided. | |
204 | Also the remaining parameters are interpreted as described for OSSL_HTTP_open() | |
205 | and OSSL_HTTP_set_request(), respectively. | |
206 | ||
207 | OSSL_HTTP_transfer() exchanges an HTTP request and response | |
208 | over a connection managed via I<prctx> without supporting redirection. | |
209 | It combines OSSL_HTTP_open(), OSSL_HTTP_set_request(), OSSL_HTTP_exchange(), | |
210 | and OSSL_HTTP_close(). | |
211 | If I<prctx> is not NULL it reuses any open connection represented by a non-NULL | |
212 | I<*prctx>. It keeps the connection open if a persistent connection is requested | |
213 | or required and this was granted by the server, else it closes the connection | |
214 | and assigns NULL to I<*prctx>. | |
215 | The remaining parameters are interpreted as described for OSSL_HTTP_open() | |
216 | and OSSL_HTTP_set_request(), respectively. | |
217 | ||
218 | OSSL_HTTP_close() closes the connection and releases I<rctx>. | |
219 | The I<ok> parameter is passed to any BIO update function | |
220 | given during setup as described above for OSSL_HTTP_open(). | |
221 | ||
4b1fe471 DDO |
222 | =head1 NOTES |
223 | ||
224 | The names of the environment variables used by this implementation: | |
d7fcee3b DDO |
225 | C<http_proxy>, C<HTTP_PROXY>, C<https_proxy>, C<HTTPS_PROXY>, C<no_proxy>, and |
226 | C<NO_PROXY>, have been chosen for maximal compatibility with | |
4b1fe471 DDO |
227 | other HTTP client implementations such as wget, curl, and git. |
228 | ||
29f178bd DDO |
229 | =head1 RETURN VALUES |
230 | ||
8f965908 DDO |
231 | OSSL_HTTP_open() returns on success a B<OSSL_HTTP_REQ_CTX>, else NULL. |
232 | ||
233 | OSSL_HTTP_proxy_connect() and OSSL_HTTP_set_request() | |
234 | return 1 on success, 0 on error. | |
235 | ||
236 | On success, OSSL_HTTP_exchange(), OSSL_HTTP_get(), and OSSL_HTTP_transfer() | |
237 | return a memory BIO containing the data received if an ASN.1-encoded response | |
238 | is expected, else a BIO that may support streaming. | |
239 | The BIO must be freed by the caller. | |
240 | On failure, they return NULL. | |
6aab42c3 | 241 | Failure conditions include connection/transfer timeout, parse errors, etc. |
29f178bd | 242 | |
8f965908 | 243 | OSSL_HTTP_close() returns 0 if anything went wrong while disconnecting, else 1. |
29f178bd | 244 | |
d7fcee3b DDO |
245 | =head1 SEE ALSO |
246 | ||
8f965908 DDO |
247 | L<OSSL_HTTP_parse_url(3)>, L<BIO_set_conn_port(3)> |
248 | L<ASN1_item_i2d_mem_bio(3)>, L<ASN1_item_d2i_bio(3)>, | |
249 | L<OSSL_HTTP_is_alive(3)> | |
d7fcee3b | 250 | |
29f178bd DDO |
251 | =head1 HISTORY |
252 | ||
8f965908 | 253 | All the functions described here were added in OpenSSL 3.0. |
29f178bd DDO |
254 | |
255 | =head1 COPYRIGHT | |
256 | ||
4333b89f | 257 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
29f178bd DDO |
258 | |
259 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
260 | this file except in compliance with the License. You can obtain a copy | |
261 | in the file LICENSE in the source distribution or at | |
262 | L<https://www.openssl.org/source/license.html>. | |
263 | ||
264 | =cut |