Debian Codegraph @

upstream/debian-unstable/man3/OSSL_HTTP_transfer.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OSSL_HTTP_TRANSFER 3SSL"
58 .TH OSSL_HTTP_TRANSFER 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 OSSL_HTTP_open,
65 OSSL_HTTP_bio_cb_t,
66 OSSL_HTTP_proxy_connect,
67 OSSL_HTTP_set1_request,
68 OSSL_HTTP_exchange,
69 OSSL_HTTP_get,
70 OSSL_HTTP_transfer,
71 OSSL_HTTP_close
72 \&\- HTTP client high\-level functions
73 .SH SYNOPSIS
74 .IX Header "SYNOPSIS"
75 .Vb 1
76 \& #include <openssl/http.h>
77 \&
78 \& typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg,
79 \& int connect, int detail);
80 \& OSSL_HTTP_REQ_CTX *OSSL_HTTP_open(const char *server, const char *port,
81 \& const char *proxy, const char *no_proxy,
82 \& int use_ssl, BIO *bio, BIO *rbio,
83 \& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
84 \& int buf_size, int overall_timeout);
85 \& int OSSL_HTTP_proxy_connect(BIO *bio, const char *server, const char *port,
86 \& const char *proxyuser, const char *proxypass,
87 \& int timeout, BIO *bio_err, const char *prog);
88 \& int OSSL_HTTP_set1_request(OSSL_HTTP_REQ_CTX *rctx, const char *path,
89 \& const STACK_OF(CONF_VALUE) *headers,
90 \& const char *content_type, BIO *req,
91 \& const char *expected_content_type, int expect_asn1,
92 \& size_t max_resp_len, int timeout, int keep_alive);
93 \& BIO *OSSL_HTTP_exchange(OSSL_HTTP_REQ_CTX *rctx, char **redirection_url);
94 \& BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *no_proxy,
95 \& BIO *bio, BIO *rbio,
96 \& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
97 \& int buf_size, const STACK_OF(CONF_VALUE) *headers,
98 \& const char *expected_content_type, int expect_asn1,
99 \& size_t max_resp_len, int timeout);
100 \& BIO *OSSL_HTTP_transfer(OSSL_HTTP_REQ_CTX **prctx,
101 \& const char *server, const char *port,
102 \& const char *path, int use_ssl,
103 \& const char *proxy, const char *no_proxy,
104 \& BIO *bio, BIO *rbio,
105 \& OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
106 \& int buf_size, const STACK_OF(CONF_VALUE) *headers,
107 \& const char *content_type, BIO *req,
108 \& const char *expected_content_type, int expect_asn1,
109 \& size_t max_resp_len, int timeout, int keep_alive);
110 \& int OSSL_HTTP_close(OSSL_HTTP_REQ_CTX *rctx, int ok);
111 .Ve
112 .SH DESCRIPTION
113 .IX Header "DESCRIPTION"
114 \&\fBOSSL_HTTP_open()\fR initiates an HTTP session using the \fIbio\fR argument if not
115 NULL, else by connecting to a given \fIserver\fR optionally via a \fIproxy\fR.
116 .PP
117 Typically the OpenSSL build supports sockets and the \fIbio\fR parameter is NULL.
118 In this case \fIrbio\fR must be NULL as well and the \fIserver\fR must be non-NULL.
119 The function creates a network BIO internally using \fBBIO_new_connect\fR\|(3)
120 for connecting to the given server and the optionally given \fIport\fR,
121 defaulting to 80 for HTTP or 443 for HTTPS.
122 Then this internal BIO is used for setting up a connection
123 and for exchanging one or more request and response.
124 .PP
125 If \fIbio\fR is given and \fIrbio\fR is NULL then this \fIbio\fR is used instead.
126 If both \fIbio\fR and \fIrbio\fR are given (which may be memory BIOs for instance)
127 then no explicit connection is set up, but
128 \&\fIbio\fR is used for writing requests and \fIrbio\fR for reading responses.
129 As soon as the client has flushed \fIbio\fR the server must be ready to provide
130 a response or indicate a waiting condition via \fIrbio\fR.
131 .PP
132 If \fIbio\fR is given,
133 it is an error to provide non-NULL \fIproxy\fR or \fIno_proxy\fR arguments,
134 while \fIserver\fR and \fIport\fR arguments may be given to support diagnostic output.
135 If \fIbio\fR is NULL the optional \fIproxy\fR parameter can be used to set an
136 HTTP(S) proxy to use (unless overridden by "no_proxy" settings).
137 If TLS is not used this defaults to the environment variable \f(CW\*(C`http_proxy\*(C'\fR
138 if set, else \f(CW\*(C`HTTP_PROXY\*(C'\fR.
139 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.
140 An empty proxy string \f(CW""\fR forbids using a proxy.
141 Otherwise, the format is
142 \&\f(CW\*(C`[http[s]://][userinfo@]host[:port][/path][?query][#fragment]\*(C'\fR,
143 where any userinfo, path, query, and fragment given is ignored.
144 If the host string is an IPv6 address, it must be enclosed in \f(CW\*(C`[\*(C'\fR and \f(CW\*(C`]\*(C'\fR.
145 The default proxy port number is 80, or 443 in case "https:" is given.
146 The HTTP client functions connect via the given proxy unless the \fIserver\fR
147 is found in the optional list \fIno_proxy\fR of proxy hostnames or IP addresses
148 separated by \f(CW\*(C`,\*(C'\fR and/or whitespace (if not NULL;
149 default is the environment variable \f(CW\*(C`no_proxy\*(C'\fR if set, else \f(CW\*(C`NO_PROXY\*(C'\fR).
150 Proxying plain HTTP is supported directly,
151 while using a proxy for HTTPS connections requires a suitable callback function
152 such as \fBOSSL_HTTP_proxy_connect()\fR, described below.
153 .PP
154 If \fIuse_ssl\fR is nonzero a TLS connection is requested
155 and the \fIbio_update_fn\fR parameter must be provided.
156 .PP
157 The parameter \fIbio_update_fn\fR, which is optional if \fIuse_ssl\fR is 0,
158 may be used to modify the connection BIO used by the HTTP client,
159 but cannot be used when both \fIbio\fR and \fIrbio\fR are given.
160 \&\fIbio_update_fn\fR is a BIO connect/disconnect callback function with prototype
161 .PP
162 .Vb 1
163 \& BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
164 .Ve
165 .PP
166 The callback function may modify the BIO provided in the \fIbio\fR argument,
167 whereby it may use an optional custom defined argument \fIarg\fR,
168 which can for instance point to an \fBSSL_CTX\fR structure.
169 During connection establishment, just after calling \fBBIO_do_connect_retry()\fR, the
170 callback function is invoked with the \fIconnect\fR argument being 1 and
171 \&\fIdetail\fR being 1 if \fIuse_ssl\fR is nonzero (i.e., HTTPS is requested), else 0.
172 On disconnect \fIconnect\fR is 0 and \fIdetail\fR is 1 if no error occurred, else 0.
173 For instance, on connect the callback may push an SSL BIO to implement HTTPS;
174 after disconnect it may do some diagnostic output and pop and free the SSL BIO.
175 .PP
176 The callback function must return either the potentially modified BIO \fIbio\fR
177 or NULL to indicate failure, in which case it should not modify the BIO.
178 .PP
179 Here is a simple example that supports TLS connections (but not via a proxy):
180 .PP
181 .Vb 5
182 \& BIO *http_tls_cb(BIO *bio, void *arg, int connect, int detail)
183 \& {
184 \& if (connect && detail) { /* connecting with TLS */
185 \& SSL_CTX *ctx = (SSL_CTX *)arg;
186 \& BIO *sbio = BIO_new_ssl(ctx, 1);
187 \&
188 \& bio = sbio != NULL ? BIO_push(sbio, bio) : NULL;
189 \& } else if (!connect) { /* disconnecting */
190 \& BIO *hbio;
191 \&
192 \& if (!detail) { /* an error has occurred */
193 \& /* optionally add diagnostics here */
194 \& }
195 \& BIO_ssl_shutdown(bio);
196 \& hbio = BIO_pop(bio);
197 \& BIO_free(bio); /* SSL BIO */
198 \& bio = hbio;
199 \& }
200 \& return bio;
201 \& }
202 .Ve
203 .PP
204 After disconnect the modified BIO will be deallocated using \fBBIO_free_all()\fR.
205 The optional callback function argument \fIarg\fR is not consumed,
206 so must be freed by the caller when not needed any more.
207 .PP
208 The \fIbuf_size\fR parameter specifies the response header maximum line length.
209 A value <= 0 means that the \fBOSSL_HTTP_DEFAULT_MAX_LINE_LEN\fR (4KiB) is used.
210 \&\fIbuf_size\fR is also used as the number of content bytes that are read at a time.
211 .PP
212 If the \fIoverall_timeout\fR parameter is > 0 this indicates the maximum number of
213 seconds the overall HTTP transfer (i.e., connection setup if needed,
214 sending requests, and receiving responses) is allowed to take until completion.
215 A value <= 0 enables waiting indefinitely, i.e., no timeout.
216 .PP
217 \&\fBOSSL_HTTP_proxy_connect()\fR may be used by an above BIO connect callback function
218 to set up an SSL/TLS connection via an HTTPS proxy.
219 It promotes the given BIO \fIbio\fR representing a connection
220 pre-established with a TLS proxy using the HTTP CONNECT method,
221 optionally using proxy client credentials \fIproxyuser\fR and \fIproxypass\fR,
222 to connect with TLS protection ultimately to \fIserver\fR and \fIport\fR.
223 If the \fIport\fR argument is NULL or the empty string it defaults to "443".
224 If the \fItimeout\fR parameter is > 0 this indicates the maximum number of
225 seconds the connection setup is allowed to take.
226 A value <= 0 enables waiting indefinitely, i.e., no timeout.
227 Since this function is typically called by applications such as
228 \&\fBopenssl\-s_client\fR\|(1) it uses the \fIbio_err\fR and \fIprog\fR parameters (unless
229 NULL) to print additional diagnostic information in a user-oriented way.
230 .PP
231 \&\fBOSSL_HTTP_set1_request()\fR sets up in \fIrctx\fR the request header and content data
232 and expectations on the response using the following parameters.
233 If <rctx> indicates using a proxy for HTTP (but not HTTPS), the server host
234 (and optionally port) needs to be placed in the header; thus it must be present
235 in \fIrctx\fR.
236 For backward compatibility, the server (and optional port) may also be given in
237 the \fIpath\fR argument beginning with \f(CW\*(C`http://\*(C'\fR (thus giving an absoluteURI).
238 If \fIpath\fR is NULL it defaults to "/".
239 If \fIreq\fR is NULL the HTTP GET method will be used to send the request
240 else HTTP POST with the contents of \fIreq\fR and optional \fIcontent_type\fR, where
241 the length of the data in \fIreq\fR does not need to be determined in advance: the
242 BIO will be read on-the-fly while sending the request, which supports streaming.
243 The optional list \fIheaders\fR may contain additional custom HTTP header lines.
244 The \fImax_resp_len\fR parameter specifies the maximum allowed
245 response content length, where the value 0 indicates no limit.
246 For the meaning of the \fIexpected_content_type\fR, \fIexpect_asn1\fR, \fItimeout\fR,
247 and \fIkeep_alive\fR parameters, see \fBOSSL_HTTP_REQ_CTX_set_expected\fR\|(3).
248 .PP
249 \&\fBOSSL_HTTP_exchange()\fR exchanges any form of HTTP request and response
250 as specified by \fIrctx\fR, which must include both connection and request data,
251 typically set up using \fBOSSL_HTTP_open()\fR and \fBOSSL_HTTP_set1_request()\fR.
252 It implements the core of the functions described below.
253 If the HTTP method is GET and \fIredirection_url\fR
254 is not NULL the latter pointer is used to provide any new location that
255 the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND).
256 In this case the function returns NULL and the caller is
257 responsible for deallocating the URL with \fBOPENSSL_free\fR\|(3).
258 If the response header contains one or more \f(CW\*(C`Content\-Length\*(C'\fR lines and/or
259 an ASN.1\-encoded response is expected, which should include a total length,
260 the length indications received are checked for consistency
261 and for not exceeding any given maximum response length.
262 If an ASN.1\-encoded response is expected, the function returns on success
263 the contents buffered in a memory BIO, which does not support streaming.
264 Otherwise it returns directly the read BIO that holds the response contents,
265 which allows a response of indefinite length and may support streaming.
266 The caller is responsible for freeing the BIO pointer obtained.
267 .PP
268 \&\fBOSSL_HTTP_get()\fR uses HTTP GET to obtain data from \fIbio\fR if non-NULL,
269 else from the server contained in the \fIurl\fR, and returns it as a BIO.
270 It supports redirection via HTTP status code 301 or 302. It is meant for
271 transfers with a single round trip, so does not support persistent connections.
272 If \fIbio\fR is non-NULL, any host and port components in the \fIurl\fR are not used
273 for connecting but the hostname is used, as usual, for the \f(CW\*(C`Host\*(C'\fR header.
274 Any userinfo and fragment components in the \fIurl\fR are ignored.
275 Any query component is handled as part of the path component.
276 If the scheme component of the \fIurl\fR is \f(CW\*(C`https\*(C'\fR a TLS connection is requested
277 and the \fIbio_update_fn\fR, as described for \fBOSSL_HTTP_open()\fR, must be provided.
278 Also the remaining parameters are interpreted as described for \fBOSSL_HTTP_open()\fR
279 and \fBOSSL_HTTP_set1_request()\fR, respectively.
280 The caller is responsible for freeing the BIO pointer obtained.
281 .PP
282 \&\fBOSSL_HTTP_transfer()\fR exchanges an HTTP request and response
283 over a connection managed via \fIprctx\fR without supporting redirection.
284 It combines \fBOSSL_HTTP_open()\fR, \fBOSSL_HTTP_set1_request()\fR, \fBOSSL_HTTP_exchange()\fR,
285 and \fBOSSL_HTTP_close()\fR.
286 If \fIprctx\fR is not NULL it reuses any open connection represented by a non-NULL
287 \&\fI*prctx\fR. It keeps the connection open if a persistent connection is requested
288 or required and this was granted by the server, else it closes the connection
289 and assigns NULL to \fI*prctx\fR.
290 The remaining parameters are interpreted as described for \fBOSSL_HTTP_open()\fR
291 and \fBOSSL_HTTP_set1_request()\fR, respectively.
292 The caller is responsible for freeing the BIO pointer obtained.
293 .PP
294 \&\fBOSSL_HTTP_close()\fR closes the connection and releases \fIrctx\fR.
295 The \fIok\fR parameter is passed to any BIO update function
296 given during setup as described above for \fBOSSL_HTTP_open()\fR.
297 It must be 1 if no error occurred during the HTTP transfer and 0 otherwise.
298 .SH NOTES
299 .IX Header "NOTES"
300 The names of the environment variables used by this implementation:
301 \&\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
302 \&\f(CW\*(C`NO_PROXY\*(C'\fR, have been chosen for maximal compatibility with
303 other HTTP client implementations such as wget, curl, and git.
304 .PP
305 When built with tracing enabled, \fBOSSL_HTTP_transfer()\fR and all functions using it
306 may be traced using \fBOSSL_TRACE_CATEGORY_HTTP\fR.
307 See also \fBOSSL_trace_enabled\fR\|(3) and \fBopenssl\-env\fR\|(7).
308 .SH "RETURN VALUES"
309 .IX Header "RETURN VALUES"
310 \&\fBOSSL_HTTP_open()\fR returns on success a \fBOSSL_HTTP_REQ_CTX\fR, else NULL.
311 .PP
312 \&\fBOSSL_HTTP_proxy_connect()\fR and \fBOSSL_HTTP_set1_request()\fR
313 return 1 on success, 0 on error.
314 .PP
315 On success, \fBOSSL_HTTP_exchange()\fR, \fBOSSL_HTTP_get()\fR, and \fBOSSL_HTTP_transfer()\fR
316 return a memory BIO that buffers all the data received if an ASN.1\-encoded
317 response is expected, otherwise a BIO that may support streaming.
318 The BIO must be freed by the caller.
319 On failure, they return NULL.
320 Failure conditions include connection/transfer timeout, parse errors, etc.
321 The caller is responsible for freeing the BIO pointer obtained.
322 .PP
323 \&\fBOSSL_HTTP_close()\fR returns 0 if anything went wrong while disconnecting, else 1.
324 .SH "SEE ALSO"
325 .IX Header "SEE ALSO"
326 \&\fBOSSL_HTTP_parse_url\fR\|(3), \fBBIO_new_connect\fR\|(3),
327 \&\fBASN1_item_i2d_mem_bio\fR\|(3), \fBASN1_item_d2i_bio\fR\|(3),
328 \&\fBOSSL_HTTP_REQ_CTX_set_expected\fR\|(3),
329 \&\fBOSSL_HTTP_is_alive\fR\|(3),
330 \&\fBOSSL_trace_enabled\fR\|(3), and \fBopenssl\-env\fR\|(7).
331 .SH HISTORY
332 .IX Header "HISTORY"
333 All the functions described here were added in OpenSSL 3.0.
334 .SH COPYRIGHT
335 .IX Header "COPYRIGHT"
336 Copyright 2019\-2025 The OpenSSL Project Authors. All Rights Reserved.
337 .PP
338 Licensed under the Apache License 2.0 (the "License"). You may not use
339 this file except in compliance with the License. You can obtain a copy
340 in the file LICENSE in the source distribution or at
341 <https://www.openssl.org/source/license.html>.