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