]>
Commit | Line | Data |
---|---|---|
29f178bd DDO |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | OSSL_HTTP_get, | |
6 | OSSL_HTTP_get_asn1, | |
7 | OSSL_HTTP_post_asn1, | |
8 | OSSL_HTTP_transfer, | |
9 | OSSL_HTTP_bio_cb_t, | |
10 | OSSL_HTTP_proxy_connect, | |
11 | OSSL_HTTP_parse_url | |
12 | - http client functions | |
13 | ||
14 | =head1 SYNOPSIS | |
15 | ||
16 | #include <openssl/http.h> | |
17 | ||
18 | typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, | |
19 | int connect, int detail); | |
afe554c2 | 20 | BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy, |
29f178bd DDO |
21 | BIO *bio, BIO *rbio, |
22 | OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, | |
23 | const STACK_OF(CONF_VALUE) *headers, | |
24 | int maxline, unsigned long max_resp_len, int timeout, | |
25 | const char *expected_content_type, int expect_asn1); | |
26 | ASN1_VALUE *OSSL_HTTP_get_asn1(const char *url, | |
afe554c2 | 27 | const char *proxy, const char *no_proxy, |
29f178bd DDO |
28 | BIO *bio, BIO *rbio, |
29 | OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, | |
30 | const STACK_OF(CONF_VALUE) *headers, | |
31 | int maxline, unsigned long max_resp_len, | |
32 | int timeout, const char *expected_content_type, | |
33 | const ASN1_ITEM *it); | |
34 | ASN1_VALUE *OSSL_HTTP_post_asn1(const char *server, const char *port, | |
35 | const char *path, int use_ssl, | |
afe554c2 | 36 | const char *proxy, const char *no_proxy, |
29f178bd DDO |
37 | BIO *bio, BIO *rbio, |
38 | OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, | |
39 | const STACK_OF(CONF_VALUE) *headers, | |
40 | const char *content_type, | |
9253f834 | 41 | const ASN1_VALUE *req, const ASN1_ITEM *req_it, |
29f178bd DDO |
42 | int maxline, unsigned long max_resp_len, |
43 | int timeout, const char *expected_ct, | |
44 | const ASN1_ITEM *rsp_it); | |
45 | BIO *OSSL_HTTP_transfer(const char *server, const char *port, const char *path, | |
afe554c2 | 46 | int use_ssl, const char *proxy, const char *no_proxy, |
29f178bd DDO |
47 | BIO *bio, BIO *rbio, |
48 | OSSL_HTTP_bio_cb_t bio_update_fn, void *arg, | |
49 | const STACK_OF(CONF_VALUE) *headers, | |
50 | const char *content_type, BIO *req_mem, | |
51 | int maxline, unsigned long max_resp_len, int timeout, | |
52 | const char *expected_ct, int expect_asn1, | |
53 | char **redirection_url); | |
54 | int OSSL_HTTP_proxy_connect(BIO *bio, const char *server, const char *port, | |
55 | const char *proxyuser, const char *proxypass, | |
56 | int timeout, BIO *bio_err, const char *prog); | |
57 | int OSSL_HTTP_parse_url(const char *url, char **phost, char **pport, | |
d7fcee3b | 58 | int *pport_num, char **ppath, int *pssl); |
29f178bd DDO |
59 | |
60 | =head1 DESCRIPTION | |
61 | ||
d7fcee3b | 62 | OSSL_HTTP_get() uses HTTP GET to obtain data (of any type) from the given I<url> |
29f178bd DDO |
63 | and returns it as a memory BIO. |
64 | ||
65 | OSSL_HTTP_get_asn1() uses HTTP GET to obtain an ASN.1-encoded value | |
d7fcee3b DDO |
66 | (e.g., an X.509 certificate) with the expected structure specified by I<it> |
67 | (e.g., I<ASN1_ITEM_rptr(X509)>) from the given I<url> | |
29f178bd DDO |
68 | and returns it on success as a pointer to I<ASN1_VALUE>. |
69 | ||
d7fcee3b DDO |
70 | OSSL_HTTP_post_asn1() uses the HTTP POST method to send a request I<req> |
71 | with the ASN.1 structure defined in I<req_it> and the given I<content_type> to | |
72 | the given I<server> and optional I<port> and I<path>. | |
73 | If I<use_ssl> is nonzero a TLS connection is requested and the I<bio_update_fn> | |
29f178bd | 74 | parameter, described below, must be provided. |
d7fcee3b DDO |
75 | The optional list I<headers> may contain additional custom HTTP header lines. |
76 | The expected structure of the response is specified by I<rsp_it>. | |
29f178bd DDO |
77 | On success it returns the response as a pointer to B<ASN1_VALUE>. |
78 | ||
4b1fe471 DDO |
79 | OSSL_HTTP_transfer() exchanges any form of HTTP request and response. |
80 | It implements the core of the functions described above. | |
d7fcee3b DDO |
81 | If I<path> parameter is NULL it defaults to "/". |
82 | If I<use_ssl> is nonzero a TLS connection is requested | |
83 | and the I<bio_update_fn> parameter, described below, must be provided. | |
84 | If I<req_mem> is NULL it uses the HTTP GET method, else it uses HTTP POST to | |
85 | send a request with the contents of the memory BIO and optional I<content_type>. | |
86 | The optional list I<headers> may contain additional custom HTTP header lines. | |
87 | If I<req_mem> is NULL (i.e., the HTTP method is GET) and I<redirection_url> | |
29f178bd DDO |
88 | is not NULL the latter pointer is used to provide any new location that |
89 | the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND). | |
90 | In this case the caller is responsible for deallocating this URL with | |
91 | L<OPENSSL_free(3)>. | |
92 | ||
93 | The above functions have the following parameters in common. | |
94 | ||
4b1fe471 | 95 | Typically the OpenSSL build supports sockets |
d7fcee3b | 96 | and the I<bio> and I<rbio> parameters are both NULL. |
4b1fe471 | 97 | In this case the client creates a network BIO internally |
d7fcee3b DDO |
98 | for connecting to the given I<server> |
99 | at the specified I<port> (if any, defaulting to 80 for HTTP or 443 for HTTPS), | |
100 | optionally via a I<proxy> (respecting I<no_proxy>) as described below. | |
4b1fe471 | 101 | Then the client uses this internal BIO for exchanging the request and response. |
d7fcee3b DDO |
102 | If I<bio> is given and I<rbio> is NULL then the client uses this I<bio> instead. |
103 | If both I<bio> and I<rbio> are given (which may be memory BIOs for instance) | |
29f178bd | 104 | then no explicit connection is attempted, |
d7fcee3b DDO |
105 | I<bio> is used for writing the request, and I<rbio> for reading the response. |
106 | As soon as the client has flushed I<bio> the server must be ready to provide | |
107 | a response or indicate a waiting condition via I<rbio>. | |
29f178bd | 108 | |
d7fcee3b | 109 | The optional I<proxy> parameter can be used to set the address of the an |
4b1fe471 | 110 | HTTP(S) proxy to use (unless overridden by "no_proxy" settings). |
d7fcee3b DDO |
111 | If TLS is not used this defaults to the environment variable C<http_proxy> |
112 | if set, else C<HTTP_PROXY>. | |
113 | If I<use_ssl> != 0 it defaults to C<https_proxy> if set, else C<HTTPS_PROXY>. | |
4b1fe471 | 114 | An empty proxy string specifies not to use a proxy. |
d7fcee3b | 115 | Else the format is C<[http[s]://]address[:port][/path]>, |
4b1fe471 DDO |
116 | where any path given is ignored. |
117 | The default proxy port number is 80, or 443 in case "https:" is given. | |
d7fcee3b DDO |
118 | The HTTP client functions connect via the given proxy unless the I<server> |
119 | is found in the optional list I<no_proxy> of proxy hostnames (if not NULL; | |
120 | default is the environment variable C<no_proxy> if set, else C<NO_PROXY>). | |
4b1fe471 DDO |
121 | Proxying plain HTTP is supported directly, |
122 | while using a proxy for HTTPS connections requires a suitable callback function | |
d7fcee3b | 123 | such as OSSL_HTTP_proxy_connect(), described below. |
4b1fe471 | 124 | |
d7fcee3b | 125 | The I<maxline> parameter specifies the response header maximum line length, |
6aab42c3 DDO |
126 | where a value <= 0 indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB |
127 | should be used. | |
128 | This length is also used as the number of content bytes that are read at a time. | |
d7fcee3b | 129 | The I<max_resp_len> parameter specifies the maximum response length, |
6aab42c3 | 130 | where 0 indicates B<HTTP_DEFAULT_MAX_RESP_LEN>, which currently is 100 KiB. |
29f178bd DDO |
131 | |
132 | An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and | |
133 | OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer() | |
d7fcee3b | 134 | this is only the case if the I<expect_asn1> parameter is nonzero. |
4b1fe471 | 135 | If the response header contains one or more "Content-Length" header lines and/or |
29f178bd DDO |
136 | an ASN.1-encoded response is expected, which should include a total length, |
137 | the length indications received are checked for consistency | |
138 | and for not exceeding the maximum response length. | |
139 | ||
d7fcee3b | 140 | If the parameter I<expected_content_type> (or I<expected_ct>, respectively) |
29f178bd DDO |
141 | is not NULL then the HTTP client checks that the given content type string |
142 | is included in the HTTP header of the response and returns an error if not. | |
143 | ||
d7fcee3b | 144 | If the I<timeout> parameter is > 0 this indicates the maximum number of seconds |
29f178bd DDO |
145 | to wait until the transfer is complete. |
146 | A value of 0 enables waiting indefinitely, | |
147 | while a value < 0 immediately leads to a timeout condition. | |
148 | ||
d7fcee3b | 149 | The optional parameter I<bio_update_fn> with its optional argument I<arg> may |
29f178bd | 150 | be used to modify the connection BIO used by the HTTP client (and cannot be |
d7fcee3b DDO |
151 | used when both I<bio> and I<rbio> are given). |
152 | I<bio_update_fn> is a BIO connect/disconnect callback function with prototype | |
29f178bd DDO |
153 | |
154 | BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail) | |
155 | ||
d7fcee3b DDO |
156 | The callback may modify the HTTP BIO provided in the I<bio> argument, |
157 | whereby it may make use of a custom defined argument I<arg>, | |
29f178bd | 158 | which may for instance refer to an I<SSL_CTX> structure. |
e98c7350 | 159 | During connection establishment, just after calling BIO_do_connect_retry(), |
d7fcee3b | 160 | the function is invoked with the I<connect> argument being 1 and the I<detail> |
29f178bd | 161 | argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled. |
d7fcee3b | 162 | On disconnect I<connect> is 0 and I<detail> is 1 if no error occurred, else 0. |
29f178bd DDO |
163 | For instance, on connect the function may prepend a TLS BIO to implement HTTPS; |
164 | after disconnect it may do some diagnostic output and/or specific cleanup. | |
165 | The function should return NULL to indicate failure. | |
166 | Here is a simple example that supports TLS connections (but not via a proxy): | |
167 | ||
168 | BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail) | |
169 | { | |
170 | SSL_CTX *ctx = (SSL_CTX *)arg; | |
171 | ||
172 | if (connect && detail) { /* connecting with TLS */ | |
173 | BIO *sbio = BIO_new_ssl(ctx, 1); | |
174 | hbio = sbio != NULL ? BIO_push(sbio, hbio) : NULL; | |
175 | } else if (!connect && !detail) { /* disconnecting after error */ | |
176 | /* optionally add diagnostics here */ | |
177 | } | |
178 | return hbio; | |
179 | } | |
180 | ||
181 | After disconnect the modified BIO will be deallocated using BIO_free_all(). | |
182 | ||
183 | OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function | |
4b1fe471 | 184 | to set up an SSL/TLS connection via an HTTPS proxy. |
d7fcee3b | 185 | It promotes the given BIO I<bio> representing a connection |
29f178bd | 186 | pre-established with a TLS proxy using the HTTP CONNECT method, |
d7fcee3b DDO |
187 | optionally using proxy client credentials I<proxyuser> and I<proxypass>, |
188 | to connect with TLS protection ultimately to I<server> and I<port>. | |
189 | If the I<port> argument is NULL or the empty string it defaults to "443". | |
190 | The I<timeout> parameter is used as described above. | |
bb361a27 | 191 | Since this function is typically called by applications such as |
d7fcee3b | 192 | L<openssl-s_client(1)> it uses the I<bio_err> and I<prog> parameters (unless |
29f178bd DDO |
193 | NULL) to print additional diagnostic information in a user-oriented way. |
194 | ||
d7fcee3b DDO |
195 | OSSL_HTTP_parse_url() parses its input string I<url> as a URL |
196 | of the form C<[http[s]://]address[:port][/path]> and splits it up into host, | |
197 | port, and path components and a flag indicating whether it begins with 'https'. | |
198 | The host component may be a DNS name or an IP address | |
199 | where IPv6 addresses should be enclosed in square brackets C<[> and C<]>. | |
29f178bd | 200 | The port component is optional and defaults to "443" for HTTPS, else "80". |
d7fcee3b DDO |
201 | If the I<pport_num> argument is NULL the port specification |
202 | can be in mnemonic form such as "http" like with L<BIO_set_conn_port(3)>, else | |
ad2cc1a0 | 203 | it must be in numerical form and its integer value is assigned to I<*pport_num>. |
29f178bd | 204 | The path component is also optional and defaults to "/". |
d7fcee3b DDO |
205 | On success the function assigns via each non-NULL result pointer argument |
206 | I<phost>, I<pport>, I<pport_num>, I<ppath>, and I<pssl> | |
207 | the respective url component. | |
ad2cc1a0 | 208 | On error, I<*phost>, I<*pport>, and I<*ppath> are assigned to NULL, |
d7fcee3b DDO |
209 | else they are guaranteed to contain non-NULL string pointers. |
210 | It is the reponsibility of the caller to free them using L<OPENSSL_free(3)>. | |
ad2cc1a0 | 211 | A string returned via I<*ppath> is guaranteed to begin with a C</> character. |
29f178bd | 212 | |
4b1fe471 DDO |
213 | =head1 NOTES |
214 | ||
215 | The names of the environment variables used by this implementation: | |
d7fcee3b DDO |
216 | C<http_proxy>, C<HTTP_PROXY>, C<https_proxy>, C<HTTPS_PROXY>, C<no_proxy>, and |
217 | C<NO_PROXY>, have been chosen for maximal compatibility with | |
4b1fe471 DDO |
218 | other HTTP client implementations such as wget, curl, and git. |
219 | ||
29f178bd DDO |
220 | =head1 RETURN VALUES |
221 | ||
6aab42c3 DDO |
222 | On success, OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and |
223 | OSSL_HTTP_transfer() return a memory BIO containing the data received via HTTP. | |
224 | This must be freed by the caller. On failure, NULL is returned. | |
225 | Failure conditions include connection/transfer timeout, parse errors, etc. | |
29f178bd DDO |
226 | |
227 | OSSL_HTTP_proxy_connect() and OSSL_HTTP_parse_url() | |
228 | return 1 on success, 0 on error. | |
229 | ||
d7fcee3b DDO |
230 | =head1 SEE ALSO |
231 | ||
232 | L<BIO_set_conn_port(3)> | |
233 | ||
29f178bd DDO |
234 | =head1 HISTORY |
235 | ||
236 | OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), | |
237 | OSSL_HTTP_proxy_connect(), and OSSL_HTTP_parse_url() were added in OpenSSL 3.0. | |
238 | ||
239 | =head1 COPYRIGHT | |
240 | ||
4333b89f | 241 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. |
29f178bd DDO |
242 | |
243 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
244 | this file except in compliance with the License. You can obtain a copy | |
245 | in the file LICENSE in the source distribution or at | |
246 | L<https://www.openssl.org/source/license.html>. | |
247 | ||
248 | =cut |