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