Standard preamble:
========================================================================
..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. \*(C+ will
give a nicer C++. Capital omega is used to do unbreakable dashes and
therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
nothing in troff, for use with C<>.
.tr \(*W- . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\}
Escape single quotes in literal strings from groff's Unicode transform.
If the F register is >0, we'll generate index entries on stderr for
titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
entries marked with X<> in POD. Of course, you'll have to process the
output yourself in some meaningful fashion.
Avoid warning from groff about undefined register 'F'.
.. .nr rF 0 . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ========================================================================
Title "OSSL_HTTP_TRANSFER 3ossl"
way too many mistakes in technical documents.
Typically the OpenSSL build supports sockets and the bio parameter is \s-1NULL.\s0 In this case rbio must be \s-1NULL\s0 as well and the server must be non-NULL. The function creates a network \s-1BIO\s0 internally using BIO_new_connect\|(3) for connecting to the given server and the optionally given port, defaulting to 80 for \s-1HTTP\s0 or 443 for \s-1HTTPS.\s0 Then this internal \s-1BIO\s0 is used for setting up a connection and for exchanging one or more request and response. If bio is given and rbio is \s-1NULL\s0 then this bio is used instead. If both bio and rbio are given (which may be memory BIOs for instance) then no explicit connection is set up, but \fIbio is used for writing requests and rbio for reading responses. As soon as the client has flushed bio the server must be ready to provide a response or indicate a waiting condition via rbio.
If bio is given, it is an error to provide proxy or no_proxy arguments, while server and port arguments may be given to support diagnostic output. If bio is \s-1NULL\s0 the optional proxy parameter can be used to set an \s-1HTTP\s0(S) proxy to use (unless overridden by \*(L"no_proxy\*(R" settings). If \s-1TLS\s0 is not used this defaults to the environment variable \*(C`http_proxy\*(C' if set, else \*(C`HTTP_PROXY\*(C'. If use_ssl != 0 it defaults to \*(C`https_proxy\*(C' if set, else \*(C`HTTPS_PROXY\*(C'. An empty proxy string "" forbids using a proxy. Else the format is \f(CW\*(C`[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\*(C', where any userinfo, path, query, and fragment given is ignored. The default proxy port number is 80, or 443 in case \*(L"https:\*(R" is given. The \s-1HTTP\s0 client functions connect via the given proxy unless the server is found in the optional list no_proxy of proxy hostnames (if not \s-1NULL\s0; default is the environment variable \*(C`no_proxy\*(C' if set, else \*(C`NO_PROXY\*(C'). Proxying plain \s-1HTTP\s0 is supported directly, while using a proxy for \s-1HTTPS\s0 connections requires a suitable callback function such as OSSL_HTTP_proxy_connect(), described below.
If use_ssl is nonzero a \s-1TLS\s0 connection is requested and the bio_update_fn parameter must be provided.
The parameter bio_update_fn, which is optional if use_ssl is 0, may be used to modify the connection \s-1BIO\s0 used by the \s-1HTTP\s0 client, but cannot be used when both bio and rbio are given. \fIbio_update_fn is a \s-1BIO\s0 connect/disconnect callback function with prototype
.Vb 1 BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail) .Ve
The callback function may modify the \s-1BIO\s0 provided in the bio argument, whereby it may make use of a custom defined argument arg, which may for instance point to an \s-1SSL_CTX\s0 structure. During connection establishment, just after calling BIO_do_connect_retry(), the callback function is invoked with the connect argument being 1 and \fIdetail being 1 if use_ssl is nonzero (i.e., \s-1HTTPS\s0 is requested), else 0. On disconnect connect is 0 and detail is 1 if no error occurred, else 0. For instance, on connect the callback may push an \s-1SSL BIO\s0 to implement \s-1HTTPS\s0; after disconnect it may do some diagnostic output and pop and free the \s-1SSL BIO.\s0
The callback function must return either the potentially modified \s-1BIO\s0 bio. or \s-1NULL\s0 to indicate failure, in which case it should not modify the \s-1BIO.\s0
Here is a simple example that supports \s-1TLS\s0 connections (but not via a proxy):
.Vb 5 BIO *http_tls_cb(BIO *bio, void *arg, int connect, int detail) { if (connect && detail) { /* connecting with TLS */ SSL_CTX *ctx = (SSL_CTX *)arg; BIO *sbio = BIO_new_ssl(ctx, 1); \& bio = sbio != NULL ? BIO_push(sbio, bio) : NULL; } else if (!connect) { /* disconnecting */ BIO *hbio; \& if (!detail) { /* an error has occurred */ /* optionally add diagnostics here */ } BIO_ssl_shutdown(bio); hbio = BIO_pop(bio); BIO_free(bio); /* SSL BIO */ bio = hbio; } return bio; } .Ve
After disconnect the modified \s-1BIO\s0 will be deallocated using BIO_free_all().
The buf_size parameter specifies the response header maximum line length. A value <= 0 means that the \s-1OSSL_HTTP_DEFAULT_MAX_LINE_LEN\s0 (4KiB) is used. \fIbuf_size is also used as the number of content bytes that are read at a time.
If the overall_timeout parameter is > 0 this indicates the maximum number of seconds the overall \s-1HTTP\s0 transfer (i.e., connection setup if needed, sending requests, and receiving responses) is allowed to take until completion. A value <= 0 enables waiting indefinitely, i.e., no timeout.
\fBOSSL_HTTP_proxy_connect() may be used by an above \s-1BIO\s0 connect callback function to set up an \s-1SSL/TLS\s0 connection via an \s-1HTTPS\s0 proxy. It promotes the given \s-1BIO\s0 bio representing a connection pre-established with a \s-1TLS\s0 proxy using the \s-1HTTP CONNECT\s0 method, optionally using proxy client credentials proxyuser and proxypass, to connect with \s-1TLS\s0 protection ultimately to server and port. If the port argument is \s-1NULL\s0 or the empty string it defaults to \*(L"443\*(R". If the timeout parameter is > 0 this indicates the maximum number of seconds the connection setup is allowed to take. A value <= 0 enables waiting indefinitely, i.e., no timeout. Since this function is typically called by applications such as \fBopenssl-s_client\|(1) it uses the bio_err and prog parameters (unless \s-1NULL\s0) to print additional diagnostic information in a user-oriented way.
\fBOSSL_HTTP_set1_request() sets up in rctx the request header and content data and expectations on the response using the following parameters. If <rctx> indicates using a proxy for \s-1HTTP\s0 (but not \s-1HTTPS\s0), the server host (and optionally port) needs to be placed in the header; thus it must be present in rctx. For backward compatibility, the server (and optional port) may also be given in the path argument beginning with \*(C`http://\*(C' (thus giving an absoluteURI). If path is \s-1NULL\s0 it defaults to \*(L"/\*(R". If req is \s-1NULL\s0 the \s-1HTTP GET\s0 method will be used to send the request else \s-1HTTP POST\s0 with the contents of req and optional content_type, where the length of the data in req does not need to be determined in advance: the \s-1BIO\s0 will be read on-the-fly while sending the request, which supports streaming. The optional list headers may contain additional custom \s-1HTTP\s0 header lines. If the parameter expected_content_type is not \s-1NULL\s0 then the client will check that the given content type string is included in the \s-1HTTP\s0 header of the response and return an error if not. If the expect_asn1 parameter is nonzero, a structure in \s-1ASN.1\s0 encoding will be expected as response content. The max_resp_len parameter specifies the maximum allowed response content length, where the value 0 indicates no limit. If the timeout parameter is > 0 this indicates the maximum number of seconds the subsequent \s-1HTTP\s0 transfer (sending the request and receiving a response) is allowed to take. A value of 0 enables waiting indefinitely, i.e., no timeout. A value < 0 indicates that the overall_timeout parameter value given when opening the \s-1HTTP\s0 transfer will be used instead. If keep_alive is 0 the connection is not kept open after receiving a response, which is the default behavior for \s-1HTTP 1.0.\s0 If the value is 1 or 2 then a persistent connection is requested. If the value is 2 then a persistent connection is required, i.e., an error occurs in case the server does not grant it.
\fBOSSL_HTTP_exchange() exchanges any form of \s-1HTTP\s0 request and response as specified by rctx, which must include both connection and request data, typically set up using OSSL_HTTP_open() and OSSL_HTTP_set1_request(). It implements the core of the functions described below. If the \s-1HTTP\s0 method is \s-1GET\s0 and redirection_url is not \s-1NULL\s0 the latter pointer is used to provide any new location that the server may return with \s-1HTTP\s0 code 301 (\s-1MOVED_PERMANENTLY\s0) or 302 (\s-1FOUND\s0). In this case the function returns \s-1NULL\s0 and the caller is responsible for deallocating the \s-1URL\s0 with OPENSSL_free\|(3). If the response header contains one or more \*(L"Content-Length\*(R" header lines and/or an \s-1ASN\s0.1-encoded response is expected, which should include a total length, the length indications received are checked for consistency and for not exceeding any given maximum response length. If an \s-1ASN\s0.1-encoded response is expected, the function returns on success the contents buffered in a memory \s-1BIO,\s0 which does not support streaming. Otherwise it returns directly the read \s-1BIO\s0 that holds the response contents, which allows a response of indefinite length and may support streaming. The caller is responsible for freeing the \s-1BIO\s0 pointer obtained.
\fBOSSL_HTTP_get() uses \s-1HTTP GET\s0 to obtain data from bio if non-NULL, else from the server contained in the url, and returns it as a \s-1BIO.\s0 It supports redirection via \s-1HTTP\s0 status code 301 or 302. It is meant for transfers with a single round trip, so does not support persistent connections. If bio is non-NULL, any host and port components in the url are not used for connecting but the hostname is used, as usual, for the \*(C`Host\*(C' header. Any userinfo and fragment components in the url are ignored. Any query component is handled as part of the path component. If the scheme component of the url is \*(C`https\*(C' a \s-1TLS\s0 connection is requested and the bio_update_fn, as described for OSSL_HTTP_open(), must be provided. Also the remaining parameters are interpreted as described for OSSL_HTTP_open() and OSSL_HTTP_set1_request(), respectively. The caller is responsible for freeing the \s-1BIO\s0 pointer obtained.
\fBOSSL_HTTP_transfer() exchanges an \s-1HTTP\s0 request and response over a connection managed via prctx without supporting redirection. It combines OSSL_HTTP_open(), OSSL_HTTP_set1_request(), OSSL_HTTP_exchange(), and OSSL_HTTP_close(). If prctx is not \s-1NULL\s0 it reuses any open connection represented by a non-NULL \fI*prctx. It keeps the connection open if a persistent connection is requested or required and this was granted by the server, else it closes the connection and assigns \s-1NULL\s0 to *prctx. The remaining parameters are interpreted as described for OSSL_HTTP_open() and OSSL_HTTP_set1_request(), respectively. The caller is responsible for freeing the \s-1BIO\s0 pointer obtained.
\fBOSSL_HTTP_close() closes the connection and releases rctx. The ok parameter is passed to any \s-1BIO\s0 update function given during setup as described above for OSSL_HTTP_open(). It must be 1 if no error occurred during the \s-1HTTP\s0 transfer and 0 otherwise.
\fBOSSL_HTTP_proxy_connect() and OSSL_HTTP_set1_request() return 1 on success, 0 on error.
On success, OSSL_HTTP_exchange(), OSSL_HTTP_get(), and OSSL_HTTP_transfer() return a memory \s-1BIO\s0 that buffers all the data received if an \s-1ASN\s0.1-encoded response is expected, otherwise a \s-1BIO\s0 that may support streaming. The \s-1BIO\s0 must be freed by the caller. On failure, they return \s-1NULL.\s0 Failure conditions include connection/transfer timeout, parse errors, etc. The caller is responsible for freeing the \s-1BIO\s0 pointer obtained.
\fBOSSL_HTTP_close() returns 0 if anything went wrong while disconnecting, else 1.
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use this file except in compliance with the License. You can obtain a copy in the file \s-1LICENSE\s0 in the source distribution or at <https://www.openssl.org/source/license.html>.