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