e0adb2a1d149cc886856eefaf0778cfee511d7ef
[openssl.git] / doc / man3 / OSSL_HTTP_transfer.pod
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);
20  BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy,
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,
27                                 const char *proxy, const char *no_proxy,
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,
36                                  const char *proxy, const char *no_proxy,
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,
41                                  const ASN1_VALUE *req, const ASN1_ITEM *req_it,
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,
46                          int use_ssl, const char *proxy, const char *no_proxy,
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,
58                          char **ppath, int *pssl);
59
60 =head1 DESCRIPTION
61
62 OSSL_HTTP_get() uses HTTP GET to obtain data (of any type) from the given B<url>
63 and returns it as a memory BIO.
64
65 OSSL_HTTP_get_asn1() uses HTTP GET to obtain an ASN.1-encoded value
66 (e.g., an X.509 certificate) with the expected structure specified by B<it>
67 (e.g., I<ASN1_ITEM_rptr(X509)>) from the given B<url>
68 and returns it on success as a pointer to I<ASN1_VALUE>.
69
70 OSSL_HTTP_post_asn1() uses the HTTP POST method to send a request B<req>
71 with the ASN.1 structure defined in B<req_it> and the given B<content_type> to
72 the given B<server> and optional B<port> and B<path>.
73 If B<use_ssl> is nonzero a TLS connection is requested and the B<bio_update_fn>
74 parameter, described below, must be provided.
75 The optional list B<headers> may contain additional custom HTTP header lines.
76 The expected structure of the response is specified by B<rsp_it>.
77 On success it returns the response as a pointer to B<ASN1_VALUE>.
78
79 OSSL_HTTP_transfer() exchanges any form of HTTP request and response.
80 It implements the core of the functions described above.
81 If B<path> parameter is NULL it defaults to "/".
82 If B<use_ssl> is nonzero a TLS connection is requested
83 and the B<bio_update_fn> parameter, described below, must be provided.
84 If B<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 B<content_type>.
86 The optional list B<headers> may contain additional custom HTTP header lines.
87 If B<req_mem> is NULL (i.e., the HTTP method is GET) and B<redirection_url>
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
95 Typically the OpenSSL build supports sockets
96 and the B<bio> and B<rbio> parameters are both NULL.
97 In this case the client creates a network BIO internally
98 for connecting to the given B<server>
99 at the specified B<port> (if any, defaulting to 80 for HTTP or 443 for HTTPS),
100 optionally via a B<proxy> (respecting B<no_proxy>) as described below.
101 Then the client uses this internal BIO for exchanging the request and response.
102 If B<bio> is given and B<rbio> is NULL then the client uses this B<bio> instead.
103 If both B<bio> and B<rbio> are given (which may be memory BIOs for instance)
104 then no explicit connection is attempted,
105 B<bio> is used for writing the request, and B<rbio> for reading the response.
106 As soon as the client has flushed B<bio> the server must be ready to provide
107 a response or indicate a waiting condition via B<rbio>.
108
109 The optional B<proxy> parameter can be used to set the address of the an
110 HTTP(S) proxy to use (unless overridden by "no_proxy" settings).
111 If TLS is not used this defaults to the environment variable B<http_proxy>
112 if set, else B<HTTP_PROXY>.
113 If B<use_ssl> != 0 it defaults to B<https_proxy> if set, else B<HTTPS_PROXY>.
114 An empty proxy string specifies not to use a proxy.
115 Else the format is I<[http[s]://]address[:port][/path]>,
116 where any path given is ignored.
117 The default proxy port number is 80, or 443 in case "https:" is given.
118 The HTTP client functions connect via the given proxy unless the B<server>
119 is found in the optional list B<no_proxy> of proxy hostnames (if not NULL;
120 default is the environment variable B<no_proxy> if set, else B<NO_PROXY>).
121 Proxying plain HTTP is supported directly,
122 while using a proxy for HTTPS connections requires a suitable callback function
123 such as B<OSSL_HTTP_proxy_connect()>, described below.
124
125 The B<maxline> parameter specifies the response header maximum line length,
126 where 0 indicates the default value, which currently is 4k.
127 The B<max_resp_len> parameter specifies the maximum response length,
128 where 0 indicates the default value, which currently is 100k.
129
130 An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and
131 OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer()
132 this is only the case if the B<expect_asn1> parameter is nonzero.
133 If the response header contains one or more "Content-Length" header lines and/or
134 an ASN.1-encoded response is expected, which should include a total length,
135 the length indications received are checked for consistency
136 and for not exceeding the maximum response length.
137
138 If the parameter B<expected_content_type> (or B<expected_ct>, respectively)
139 is not NULL then the HTTP client checks that the given content type string
140 is included in the HTTP header of the response and returns an error if not.
141
142 If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
143 to wait until the transfer is complete.
144 A value of 0 enables waiting indefinitely,
145 while a value < 0 immediately leads to a timeout condition.
146
147 The optional parameter B<bio_update_fn> with its optional argument B<arg> may
148 be used to modify the connection BIO used by the HTTP client (and cannot be
149 used when both B<bio> and B<rbio> are given).
150 B<bio_update_fn> is a BIO connect/disconnect callback function with prototype
151
152  BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
153
154 The callback may modify the HTTP BIO provided in the B<bio> argument,
155 whereby it may make use of a custom defined argument B<arg>,
156 which may for instance refer to an I<SSL_CTX> structure.
157 During connection establishment, just after calling BIO_connect_retry(),
158 the function is invoked with the B<connect> argument being 1 and the B<detail>
159 argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled.
160 On disconnect B<connect> is 0 and B<detail> is 1 if no error occurred, else 0.
161 For instance, on connect the function may prepend a TLS BIO to implement HTTPS;
162 after disconnect it may do some diagnostic output and/or specific cleanup.
163 The function should return NULL to indicate failure.
164 Here is a simple example that supports TLS connections (but not via a proxy):
165
166  BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail)
167  {
168      SSL_CTX *ctx = (SSL_CTX *)arg;
169
170      if (connect && detail) { /* connecting with TLS */
171          BIO *sbio = BIO_new_ssl(ctx, 1);
172          hbio = sbio != NULL ? BIO_push(sbio, hbio) : NULL;
173      } else if (!connect && !detail) { /* disconnecting after error */
174          /* optionally add diagnostics here */
175      }
176      return hbio;
177  }
178
179 After disconnect the modified BIO will be deallocated using BIO_free_all().
180
181 OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function
182 to set up an SSL/TLS connection via an HTTPS proxy.
183 It promotes the given BIO B<bio> representing a connection
184 pre-established with a TLS proxy using the HTTP CONNECT method,
185 optionally using proxy client credentials B<proxyuser> and B<proxypass>,
186 to connect with TLS protection ultimately to B<server> and B<port>.
187 If the B<port> argument is NULL or the empty string it defaults to "443".
188 The B<timeout> parameter is used as described above.
189 Since this function is typically called by appplications such as
190 L<openssl-s_client(1)> it uses the B<bio_err> and B<prog> parameters (unless
191 NULL) to print additional diagnostic information in a user-oriented way.
192
193 OSSL_HTTP_parse_url() parses its input string B<url> as a URL and splits it up
194 into host, port and path components and a flag whether it begins with 'https'.
195 The host component may be a DNS name or an IPv4 or an IPv6 address.
196 The port component is optional and defaults to "443" for HTTPS, else "80".
197 The path component is also optional and defaults to "/".
198 As far as the result pointer arguments are not NULL it assigns via
199 them copies of the respective string components.
200 The strings returned this way must be deallocated by the caller using
201 L<OPENSSL_free(3)> unless they are NULL, which is their default value on error.
202
203 =head1 NOTES
204
205 The names of the environment variables used by this implementation:
206 B<http_proxy>, B<HTTP_PROXY>, B<https_proxy>, B<HTTPS_PROXY>, B<no_proxy>, and
207 B<NO_PROXY>, have been chosen for maximal compatibility with
208 other HTTP client implementations such as wget, curl, and git.
209
210 =head1 RETURN VALUES
211
212 OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
213 OSSL_HTTP_transfer() return on success the data received via HTTP, else NULL.
214 Error conditions include connection/transfer timeout, parse errors, etc.
215
216 OSSL_HTTP_proxy_connect() and OSSL_HTTP_parse_url()
217 return 1 on success, 0 on error.
218
219 =head1 HISTORY
220
221 OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(),
222 OSSL_HTTP_proxy_connect(), and OSSL_HTTP_parse_url() were added in OpenSSL 3.0.
223
224 =head1 COPYRIGHT
225
226 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
227
228 Licensed under the Apache License 2.0 (the "License").  You may not use
229 this file except in compliance with the License.  You can obtain a copy
230 in the file LICENSE in the source distribution or at
231 L<https://www.openssl.org/source/license.html>.
232
233 =cut