mirror of
https://github.com/opnsense/src.git
synced 2026-02-27 03:40:37 -05:00
b077aed33b
Migrate to OpenSSL 3.0 in advance of FreeBSD 14.0. OpenSSL 1.1.1 (the version we were previously using) will be EOL as of 2023-09-11. Most of the base system has already been updated for a seamless switch to OpenSSL 3.0. For many components we've added `-DOPENSSL_API_COMPAT=0x10100000L` to CFLAGS to specify the API version, which avoids deprecation warnings from OpenSSL 3.0. Changes have also been made to avoid OpenSSL APIs that were already deprecated in OpenSSL 1.1.1. The process of updating to contemporary APIs can continue after this merge. Additional changes are still required for libarchive and Kerberos- related libraries or tools; workarounds will immediately follow this commit. Fixes are in progress in the upstream projects and will be incorporated when those are next updated. There are some performance regressions in benchmarks (certain tests in `openssl speed`) and in some OpenSSL consumers in ports (e.g. haproxy). Investigation will continue for these. Netflix's testing showed no functional regression and a rather small, albeit statistically significant, increase in CPU consumption with OpenSSL 3.0. Thanks to ngie@ and des@ for updating base system components, to antoine@ and bofh@ for ports exp-runs and port fixes/workarounds, and to Netflix and everyone who tested prior to commit or contributed to this update in other ways. PR: 271615 PR: 271656 [exp-run] Relnotes: Yes Sponsored by: The FreeBSD Foundation
418 lines
20 KiB
Groff
418 lines
20 KiB
Groff
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" 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 C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. 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\}
|
|
.el\{\
|
|
. 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.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" 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'.
|
|
.de IX
|
|
..
|
|
.nr rF 0
|
|
.if \n(.g .if rF .nr rF 1
|
|
.if (\n(rF:(\n(.g==0)) \{\
|
|
. if \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. if !\nF==2 \{\
|
|
. nr % 0
|
|
. nr F 2
|
|
. \}
|
|
. \}
|
|
.\}
|
|
.rr rF
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. 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
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. 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
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "OSSL_HTTP_TRANSFER 3"
|
|
.TH OSSL_HTTP_TRANSFER 3 "2023-05-30" "3.0.9" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
OSSL_HTTP_open,
|
|
OSSL_HTTP_bio_cb_t,
|
|
OSSL_HTTP_proxy_connect,
|
|
OSSL_HTTP_set1_request,
|
|
OSSL_HTTP_exchange,
|
|
OSSL_HTTP_get,
|
|
OSSL_HTTP_transfer,
|
|
OSSL_HTTP_close
|
|
\&\- HTTP client high\-level functions
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/http.h>
|
|
\&
|
|
\& typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg,
|
|
\& int connect, int detail);
|
|
\& OSSL_HTTP_REQ_CTX *OSSL_HTTP_open(const char *server, const char *port,
|
|
\& const char *proxy, const char *no_proxy,
|
|
\& int use_ssl, BIO *bio, BIO *rbio,
|
|
\& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
|
|
\& int buf_size, int overall_timeout);
|
|
\& int OSSL_HTTP_proxy_connect(BIO *bio, const char *server, const char *port,
|
|
\& const char *proxyuser, const char *proxypass,
|
|
\& int timeout, BIO *bio_err, const char *prog);
|
|
\& int OSSL_HTTP_set1_request(OSSL_HTTP_REQ_CTX *rctx, const char *path,
|
|
\& const STACK_OF(CONF_VALUE) *headers,
|
|
\& const char *content_type, BIO *req,
|
|
\& const char *expected_content_type, int expect_asn1,
|
|
\& size_t max_resp_len, int timeout, int keep_alive);
|
|
\& BIO *OSSL_HTTP_exchange(OSSL_HTTP_REQ_CTX *rctx, char **redirection_url);
|
|
\& BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy,
|
|
\& BIO *bio, BIO *rbio,
|
|
\& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
|
|
\& int buf_size, const STACK_OF(CONF_VALUE) *headers,
|
|
\& const char *expected_content_type, int expect_asn1,
|
|
\& size_t max_resp_len, int timeout);
|
|
\& BIO *OSSL_HTTP_transfer(OSSL_HTTP_REQ_CTX **prctx,
|
|
\& const char *server, const char *port,
|
|
\& const char *path, int use_ssl,
|
|
\& const char *proxy, const char *no_proxy,
|
|
\& BIO *bio, BIO *rbio,
|
|
\& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
|
|
\& int buf_size, const STACK_OF(CONF_VALUE) *headers,
|
|
\& const char *content_type, BIO *req,
|
|
\& const char *expected_content_type, int expect_asn1,
|
|
\& size_t max_resp_len, int timeout, int keep_alive);
|
|
\& int OSSL_HTTP_close(OSSL_HTTP_REQ_CTX *rctx, int ok);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
\&\fBOSSL_HTTP_open()\fR initiates an \s-1HTTP\s0 session using the \fIbio\fR argument if not
|
|
\&\s-1NULL,\s0 else by connecting to a given \fIserver\fR optionally via a \fIproxy\fR.
|
|
.PP
|
|
Typically the OpenSSL build supports sockets and the \fIbio\fR parameter is \s-1NULL.\s0
|
|
In this case \fIrbio\fR must be \s-1NULL\s0 as well and the \fIserver\fR must be non-NULL.
|
|
The function creates a network \s-1BIO\s0 internally using \fBBIO_new_connect\fR\|(3)
|
|
for connecting to the given server and the optionally given \fIport\fR,
|
|
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 \fIbio\fR is given and \fIrbio\fR is \s-1NULL\s0 then this \fIbio\fR is used instead.
|
|
If both \fIbio\fR and \fIrbio\fR are given (which may be memory BIOs for instance)
|
|
then no explicit connection is set up, but
|
|
\&\fIbio\fR is used for writing requests and \fIrbio\fR for reading responses.
|
|
As soon as the client has flushed \fIbio\fR the server must be ready to provide
|
|
a response or indicate a waiting condition via \fIrbio\fR.
|
|
.PP
|
|
If \fIbio\fR is given, it is an error to provide \fIproxy\fR or \fIno_proxy\fR arguments,
|
|
while \fIserver\fR and \fIport\fR arguments may be given to support diagnostic output.
|
|
If \fIbio\fR is \s-1NULL\s0 the optional \fIproxy\fR 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 \f(CW\*(C`http_proxy\*(C'\fR
|
|
if set, else \f(CW\*(C`HTTP_PROXY\*(C'\fR.
|
|
If \fIuse_ssl\fR != 0 it defaults to \f(CW\*(C`https_proxy\*(C'\fR if set, else \f(CW\*(C`HTTPS_PROXY\*(C'\fR.
|
|
An empty proxy string \f(CW""\fR forbids using a proxy.
|
|
Else the format is
|
|
\&\f(CW\*(C`[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\*(C'\fR,
|
|
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 \fIserver\fR
|
|
is found in the optional list \fIno_proxy\fR of proxy hostnames (if not \s-1NULL\s0;
|
|
default is the environment variable \f(CW\*(C`no_proxy\*(C'\fR if set, else \f(CW\*(C`NO_PROXY\*(C'\fR).
|
|
Proxying plain \s-1HTTP\s0 is supported directly,
|
|
while using a proxy for \s-1HTTPS\s0 connections requires a suitable callback function
|
|
such as \fBOSSL_HTTP_proxy_connect()\fR, described below.
|
|
.PP
|
|
If \fIuse_ssl\fR is nonzero a \s-1TLS\s0 connection is requested
|
|
and the \fIbio_update_fn\fR parameter must be provided.
|
|
.PP
|
|
The parameter \fIbio_update_fn\fR, which is optional if \fIuse_ssl\fR 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 \fIbio\fR and \fIrbio\fR are given.
|
|
\&\fIbio_update_fn\fR is a \s-1BIO\s0 connect/disconnect callback function with prototype
|
|
.PP
|
|
.Vb 1
|
|
\& BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
|
|
.Ve
|
|
.PP
|
|
The callback function may modify the \s-1BIO\s0 provided in the \fIbio\fR argument,
|
|
whereby it may make use of a custom defined argument \fIarg\fR,
|
|
which may for instance point to an \fB\s-1SSL_CTX\s0\fR structure.
|
|
During connection establishment, just after calling \fBBIO_do_connect_retry()\fR, the
|
|
callback function is invoked with the \fIconnect\fR argument being 1 and
|
|
\&\fIdetail\fR being 1 if \fIuse_ssl\fR is nonzero (i.e., \s-1HTTPS\s0 is requested), else 0.
|
|
On disconnect \fIconnect\fR is 0 and \fIdetail\fR 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
|
|
.PP
|
|
The callback function must return either the potentially modified \s-1BIO\s0 \fIbio\fR.
|
|
or \s-1NULL\s0 to indicate failure, in which case it should not modify the \s-1BIO.\s0
|
|
.PP
|
|
Here is a simple example that supports \s-1TLS\s0 connections (but not via a proxy):
|
|
.PP
|
|
.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
|
|
.PP
|
|
After disconnect the modified \s-1BIO\s0 will be deallocated using \fBBIO_free_all()\fR.
|
|
.PP
|
|
The \fIbuf_size\fR parameter specifies the response header maximum line length.
|
|
A value <= 0 means that the \fB\s-1OSSL_HTTP_DEFAULT_MAX_LINE_LEN\s0\fR (4KiB) is used.
|
|
\&\fIbuf_size\fR is also used as the number of content bytes that are read at a time.
|
|
.PP
|
|
If the \fIoverall_timeout\fR 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.
|
|
.PP
|
|
\&\fBOSSL_HTTP_proxy_connect()\fR 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 \fIbio\fR representing a connection
|
|
pre-established with a \s-1TLS\s0 proxy using the \s-1HTTP CONNECT\s0 method,
|
|
optionally using proxy client credentials \fIproxyuser\fR and \fIproxypass\fR,
|
|
to connect with \s-1TLS\s0 protection ultimately to \fIserver\fR and \fIport\fR.
|
|
If the \fIport\fR argument is \s-1NULL\s0 or the empty string it defaults to \*(L"443\*(R".
|
|
If the \fItimeout\fR 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\fR\|(1) it uses the \fIbio_err\fR and \fIprog\fR parameters (unless
|
|
\&\s-1NULL\s0) to print additional diagnostic information in a user-oriented way.
|
|
.PP
|
|
\&\fBOSSL_HTTP_set1_request()\fR sets up in \fIrctx\fR 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 hostname
|
|
(and optionally port) needs to be placed in the header and thus must be present.
|
|
If \fIpath\fR is \s-1NULL\s0 it defaults to \*(L"/\*(R".
|
|
If \fIreq\fR 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 \fIreq\fR and optional \fIcontent_type\fR, where
|
|
the length of the data in \fIreq\fR 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 \fIheaders\fR may contain additional custom \s-1HTTP\s0 header lines.
|
|
If the parameter \fIexpected_content_type\fR
|
|
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 \fIexpect_asn1\fR parameter is nonzero,
|
|
a structure in \s-1ASN.1\s0 encoding will be expected as response content.
|
|
The \fImax_resp_len\fR parameter specifies the maximum allowed
|
|
response content length, where the value 0 indicates no limit.
|
|
If the \fItimeout\fR 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 \fIoverall_timeout\fR parameter value given
|
|
when opening the \s-1HTTP\s0 transfer will be used instead.
|
|
If \fIkeep_alive\fR 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.
|
|
.PP
|
|
\&\fBOSSL_HTTP_exchange()\fR exchanges any form of \s-1HTTP\s0 request and response
|
|
as specified by \fIrctx\fR, which must include both connection and request data,
|
|
typically set up using \fBOSSL_HTTP_open()\fR and \fBOSSL_HTTP_set1_request()\fR.
|
|
It implements the core of the functions described below.
|
|
If the \s-1HTTP\s0 method is \s-1GET\s0 and \fIredirection_url\fR
|
|
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 \fBOPENSSL_free\fR\|(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.
|
|
.PP
|
|
\&\fBOSSL_HTTP_get()\fR uses \s-1HTTP GET\s0 to obtain data from \fIbio\fR if non-NULL,
|
|
else from the server contained in the \fIurl\fR, 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 \fIbio\fR is non-NULL, any host and port components in the \fIurl\fR are not used
|
|
for connecting but the hostname is used, as usual, for the \f(CW\*(C`Host\*(C'\fR header.
|
|
Any userinfo and fragment components in the \fIurl\fR are ignored.
|
|
Any query component is handled as part of the path component.
|
|
If the scheme component of the \fIurl\fR is \f(CW\*(C`https\*(C'\fR a \s-1TLS\s0 connection is requested
|
|
and the \fIbio_update_fn\fR, as described for \fBOSSL_HTTP_open()\fR, must be provided.
|
|
Also the remaining parameters are interpreted as described for \fBOSSL_HTTP_open()\fR
|
|
and \fBOSSL_HTTP_set1_request()\fR, respectively.
|
|
The caller is responsible for freeing the \s-1BIO\s0 pointer obtained.
|
|
.PP
|
|
\&\fBOSSL_HTTP_transfer()\fR exchanges an \s-1HTTP\s0 request and response
|
|
over a connection managed via \fIprctx\fR without supporting redirection.
|
|
It combines \fBOSSL_HTTP_open()\fR, \fBOSSL_HTTP_set1_request()\fR, \fBOSSL_HTTP_exchange()\fR,
|
|
and \fBOSSL_HTTP_close()\fR.
|
|
If \fIprctx\fR is not \s-1NULL\s0 it reuses any open connection represented by a non-NULL
|
|
\&\fI*prctx\fR. 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 \fI*prctx\fR.
|
|
The remaining parameters are interpreted as described for \fBOSSL_HTTP_open()\fR
|
|
and \fBOSSL_HTTP_set1_request()\fR, respectively.
|
|
The caller is responsible for freeing the \s-1BIO\s0 pointer obtained.
|
|
.PP
|
|
\&\fBOSSL_HTTP_close()\fR closes the connection and releases \fIrctx\fR.
|
|
The \fIok\fR parameter is passed to any \s-1BIO\s0 update function
|
|
given during setup as described above for \fBOSSL_HTTP_open()\fR.
|
|
It must be 1 if no error occurred during the \s-1HTTP\s0 transfer and 0 otherwise.
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
The names of the environment variables used by this implementation:
|
|
\&\f(CW\*(C`http_proxy\*(C'\fR, \f(CW\*(C`HTTP_PROXY\*(C'\fR, \f(CW\*(C`https_proxy\*(C'\fR, \f(CW\*(C`HTTPS_PROXY\*(C'\fR, \f(CW\*(C`no_proxy\*(C'\fR, and
|
|
\&\f(CW\*(C`NO_PROXY\*(C'\fR, have been chosen for maximal compatibility with
|
|
other \s-1HTTP\s0 client implementations such as wget, curl, and git.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fBOSSL_HTTP_open()\fR returns on success a \fB\s-1OSSL_HTTP_REQ_CTX\s0\fR, else \s-1NULL.\s0
|
|
.PP
|
|
\&\fBOSSL_HTTP_proxy_connect()\fR and \fBOSSL_HTTP_set1_request()\fR
|
|
return 1 on success, 0 on error.
|
|
.PP
|
|
On success, \fBOSSL_HTTP_exchange()\fR, \fBOSSL_HTTP_get()\fR, and \fBOSSL_HTTP_transfer()\fR
|
|
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.
|
|
.PP
|
|
\&\fBOSSL_HTTP_close()\fR returns 0 if anything went wrong while disconnecting, else 1.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fBOSSL_HTTP_parse_url\fR\|(3), \fBBIO_new_connect\fR\|(3),
|
|
\&\fBASN1_item_i2d_mem_bio\fR\|(3), \fBASN1_item_d2i_bio\fR\|(3),
|
|
\&\fBOSSL_HTTP_is_alive\fR\|(3)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
All the functions described here were added in OpenSSL 3.0.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2019\-2022 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
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>.
|