Debian Codegraph @

upstream/debian-unstable/man3/OSSL_HTTP_REQ_CTX.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_REQ_CTX 3SSL"
58 .TH OSSL_HTTP_REQ_CTX 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_REQ_CTX,
65 OSSL_HTTP_REQ_CTX_new,
66 OSSL_HTTP_REQ_CTX_free,
67 OSSL_HTTP_REQ_CTX_set_request_line,
68 OSSL_HTTP_REQ_CTX_add1_header,
69 OSSL_HTTP_REQ_CTX_set_expected,
70 OSSL_HTTP_REQ_CTX_set1_req,
71 OSSL_HTTP_REQ_CTX_nbio,
72 OSSL_HTTP_REQ_CTX_nbio_d2i,
73 OSSL_HTTP_REQ_CTX_exchange,
74 OSSL_HTTP_REQ_CTX_get0_mem_bio,
75 OSSL_HTTP_REQ_CTX_get_resp_len,
76 OSSL_HTTP_REQ_CTX_set_max_response_length,
77 OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines,
78 OSSL_HTTP_is_alive
79 \&\- HTTP client low\-level functions
80 .SH SYNOPSIS
81 .IX Header "SYNOPSIS"
82 .Vb 1
83 \& #include <openssl/http.h>
84 \&
85 \& typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX;
86 \&
87 \& OSSL_HTTP_REQ_CTX *OSSL_HTTP_REQ_CTX_new(BIO *wbio, BIO *rbio, int buf_size);
88 \& void OSSL_HTTP_REQ_CTX_free(OSSL_HTTP_REQ_CTX *rctx);
89 \&
90 \& int OSSL_HTTP_REQ_CTX_set_request_line(OSSL_HTTP_REQ_CTX *rctx, int method_POST,
91 \& const char *server, const char *port,
92 \& const char *path);
93 \& int OSSL_HTTP_REQ_CTX_add1_header(OSSL_HTTP_REQ_CTX *rctx,
94 \& const char *name, const char *value);
95 \&
96 \& int OSSL_HTTP_REQ_CTX_set_expected(OSSL_HTTP_REQ_CTX *rctx,
97 \& const char *expected_content_type, int expect_asn1,
98 \& int timeout, int keep_alive);
99 \& int OSSL_HTTP_REQ_CTX_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type,
100 \& const ASN1_ITEM *it, const ASN1_VALUE *req);
101 \& int OSSL_HTTP_REQ_CTX_nbio(OSSL_HTTP_REQ_CTX *rctx);
102 \& int OSSL_HTTP_REQ_CTX_nbio_d2i(OSSL_HTTP_REQ_CTX *rctx,
103 \& ASN1_VALUE **pval, const ASN1_ITEM *it);
104 \& BIO *OSSL_HTTP_REQ_CTX_exchange(OSSL_HTTP_REQ_CTX *rctx);
105 \&
106 \& BIO *OSSL_HTTP_REQ_CTX_get0_mem_bio(const OSSL_HTTP_REQ_CTX *rctx);
107 \& size_t OSSL_HTTP_REQ_CTX_get_resp_len(const OSSL_HTTP_REQ_CTX *rctx);
108 \& void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx,
109 \& unsigned long len);
110 \& void OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines(OSSL_HTTP_REQ_CTX *rctx,
111 \& size_t count);
112 \&
113 \& int OSSL_HTTP_is_alive(const OSSL_HTTP_REQ_CTX *rctx);
114 .Ve
115 .SH DESCRIPTION
116 .IX Header "DESCRIPTION"
117 \&\fBOSSL_HTTP_REQ_CTX\fR is a context structure for an HTTP request and response,
118 used to collect all the necessary data to perform that request.
119 .PP
120 This file documents low-level HTTP functions rarely used directly. High-level
121 HTTP client functions like \fBOSSL_HTTP_get\fR\|(3) and \fBOSSL_HTTP_transfer\fR\|(3)
122 should be preferred.
123 .PP
124 \&\fBOSSL_HTTP_REQ_CTX_new()\fR allocates a new HTTP request context structure,
125 which gets populated with the \fBBIO\fR to write/send the request to (\fIwbio\fR),
126 the \fBBIO\fR to read/receive the response from (\fIrbio\fR, which may be equal to
127 \&\fIwbio\fR), and the maximum expected response header line length \fIbuf_size\fR.
128 A value <= 0 indicates that
129 the \fBOSSL_HTTP_DEFAULT_MAX_LINE_LEN\fR of 4KiB should be used.
130 \&\fIbuf_size\fR is also used as the number of content bytes that are read at a time.
131 The allocated context structure includes an internal memory \fBBIO\fR,
132 which collects the HTTP request header lines.
133 .PP
134 \&\fBOSSL_HTTP_REQ_CTX_free()\fR frees up the HTTP request context \fIrctx\fR.
135 The \fIrbio\fR is not free'd, \fIwbio\fR will be free'd if \fIfree_wbio\fR is set.
136 If the argument is NULL, nothing is done.
137 .PP
138 \&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR adds the 1st HTTP request line to \fIrctx\fR.
139 The HTTP method is determined by \fImethod_POST\fR,
140 which should be 1 to indicate \f(CW\*(C`POST\*(C'\fR or 0 to indicate \f(CW\*(C`GET\*(C'\fR.
141 \&\fIserver\fR and \fIport\fR may be set to give the server and the optional port that
142 an HTTP proxy shall forward the request to, otherwise they must be left NULL.
143 \&\fIpath\fR provides the HTTP request path; if left NULL, \f(CW\*(C`/\*(C'\fR is used.
144 For backward compatibility, \fIpath\fR may begin with \f(CW\*(C`http://\*(C'\fR and thus convey
145 an absoluteURI. In this case it indicates HTTP proxy use and provides also the
146 server (and optionally the port) that the proxy shall forward the request to.
147 In this case the \fIserver\fR and \fIport\fR arguments must be NULL.
148 .PP
149 \&\fBOSSL_HTTP_REQ_CTX_add1_header()\fR adds header \fIname\fR with value \fIvalue\fR to the
150 context \fIrctx\fR. It can be called more than once to add multiple header lines.
151 For example, to add a \f(CW\*(C`Host\*(C'\fR header for \f(CW\*(C`example.com\*(C'\fR you would call:
152 .PP
153 .Vb 1
154 \& OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
155 .Ve
156 .PP
157 \&\fBOSSL_HTTP_REQ_CTX_set_expected()\fR optionally sets in \fIrctx\fR some expectations
158 of the HTTP client on the response.
159 Due to the structure of an HTTP request, if the \fIkeep_alive\fR argument is
160 nonzero the function must be used before calling \fBOSSL_HTTP_REQ_CTX_set1_req()\fR.
161 .PP
162 If the \fIexpected_content_type\fR argument is not NULL, the client will
163 check in a case-insensitive way that the specified \f(CW\*(C`Content\-Type\*(C'\fR string value
164 is included in the HTTP header of the response and return an error if not.
165 In the \f(CW\*(C`Content\-Type\*(C'\fR header line the specified string should be present either
166 as a whole, or in case the specified string does not include a \f(CW\*(C`;\*(C'\fR character,
167 it is sufficient that the specified string appears as a prefix
168 in the header line, followed by a \f(CW\*(C`;\*(C'\fR character and any further text.
169 For instance, if the \fIexpected_content_type\fR argument specifies \f(CW\*(C`text/html\*(C'\fR,
170 this is matched by \f(CW\*(C`Text/HTML\*(C'\fR, \f(CW\*(C`text/html; charset=UTF\-8\*(C'\fR, etc.
171 .PP
172 If the \fIexpect_asn1\fR parameter is nonzero a structure in ASN.1 encoding will be
173 expected as the response content and input streaming is disabled. This means
174 that an ASN.1 sequence header is required, its length field is checked, and
175 \&\fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR should be used to get the buffered response.
176 Otherwise (by default) any input format is allowed,
177 with body length checks being performed on error messages only.
178 In this case the BIO given as \fIrbio\fR argument to \fBOSSL_HTTP_REQ_CTX_new()\fR should
179 be used directly to read the response contents, which may support streaming.
180 .PP
181 If the \fItimeout\fR parameter is > 0 this indicates the maximum number of seconds
182 the subsequent HTTP transfer (sending the request and receiving a response)
183 is allowed to take.
184 \&\fItimeout\fR == 0 enables waiting indefinitely, i.e., no timeout can occur.
185 This is the default.
186 \&\fItimeout\fR < 0 takes over any value set via the \fIoverall_timeout\fR argument of
187 \&\fBOSSL_HTTP_open\fR\|(3) with the default being 0, which means no timeout.
188 .PP
189 If the \fIkeep_alive\fR parameter is 0, which is the default, the connection is not
190 kept open after receiving a response. This is the default behavior for HTTP 1.0.
191 If the value is 1 or 2 then a persistent connection is requested.
192 If the value is 2 then a persistent connection is required,
193 i.e., an error occurs in case the server does not grant it.
194 .PP
195 \&\fBOSSL_HTTP_REQ_CTX_set1_req()\fR finalizes the HTTP request context.
196 It is needed if the \fImethod_POST\fR parameter in the
197 \&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR call was 1
198 and an ASN.1\-encoded request should be sent.
199 It must also be used when requesting "keep-alive",
200 even if a GET request is going to be sent, in which case \fIreq\fR must be NULL.
201 Unless \fIreq\fR is NULL, the function adds the DER encoding of \fIreq\fR using
202 the ASN.1 template \fIit\fR to do the encoding (which does not support streaming).
203 The HTTP header \f(CW\*(C`Content\-Length\*(C'\fR is filled out with the length of the request.
204 \&\fIcontent_type\fR must be NULL if \fIreq\fR is NULL.
205 If \fIcontent_type\fR isn't NULL,
206 the HTTP header \f(CW\*(C`Content\-Type\*(C'\fR is also added with the given string value.
207 The header lines are added to the internal memory \fBBIO\fR for the request header.
208 .PP
209 \&\fBOSSL_HTTP_REQ_CTX_nbio()\fR attempts to send the request prepared in \fIrctx\fR
210 and to gather the response via HTTP, using the \fIwbio\fR and \fIrbio\fR
211 that were given when calling \fBOSSL_HTTP_REQ_CTX_new()\fR.
212 The function may need to be called again if its result is \-1, which indicates
213 \&\fBBIO_should_retry\fR\|(3). In such a case it is advisable to sleep a little in
214 between, using \fBBIO_wait\fR\|(3) on the read BIO to prevent a busy loop.
215 See \fBOSSL_HTTP_REQ_CTX_set_expected()\fR how the response content type,
216 the response body, the HTTP transfer timeout, and "keep-alive" are treated.
217 Any error message body is consumed
218 if a \f(CW\*(C`Content\-Type\*(C'\fR header is not included or its value starts with \f(CW\*(C`text/\*(C'\fR.
219 This is used for tracing the body contents if HTTP tracing is enabled.
220 If the \f(CW\*(C`Content\-Length\*(C'\fR header is present in the response
221 and its value exceeds the maximum allowed response content length
222 or the response is an error message with its body length exceeding this value
223 or the content is an ASN.1\-encoded structure with a length exceeding this value
224 or both length indications are present but disagree then an error occurs.
225 .PP
226 \&\fBOSSL_HTTP_REQ_CTX_nbio_d2i()\fR is like \fBOSSL_HTTP_REQ_CTX_nbio()\fR but on success
227 in addition parses the response, which must be a DER-encoded ASN.1 structure,
228 using the ASN.1 template \fIit\fR and places the result in \fI*pval\fR.
229 .PP
230 \&\fBOSSL_HTTP_REQ_CTX_exchange()\fR calls \fBOSSL_HTTP_REQ_CTX_nbio()\fR as often as needed
231 in order to exchange a request and response or until a timeout is reached.
232 On success it returns a pointer to the BIO that can be used to read the result.
233 If an ASN.1\-encoded response was expected, this is the BIO
234 returned by \fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR when called after the exchange.
235 This memory BIO does not support streaming.
236 Otherwise the returned BIO is the \fIrbio\fR given to \fBOSSL_HTTP_REQ_CTX_new()\fR,
237 which may support streaming.
238 When this BIO is returned, it has been read past the end of the response header,
239 such that the actual response body can be read from it.
240 The returned BIO pointer MUST NOT be freed by the caller.
241 .PP
242 \&\fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR returns the internal memory \fBBIO\fR.
243 Before the HTTP request is sent, this could be used to adapt its header lines.
244 \&\fIUse with caution!\fR
245 After receiving a response via HTTP, the BIO represents the current state of
246 reading the response header. If the response was expected to be ASN.1 encoded,
247 its contents can be read via this BIO, which does not support streaming.
248 The returned BIO pointer must not be freed by the caller.
249 .PP
250 \&\fBOSSL_HTTP_REQ_CTX_get_resp_len()\fR returns the size of the response contents
251 in \fIrctx\fR if provided by the server as \f(CW\*(C`Content\-Length\*(C'\fR header field, else 0.
252 .PP
253 \&\fBOSSL_HTTP_REQ_CTX_set_max_response_length()\fR sets the maximum allowed
254 response content length for \fIrctx\fR to \fIlen\fR. If not set or \fIlen\fR is 0
255 then the \fBOSSL_HTTP_DEFAULT_MAX_RESP_LEN\fR is used, which currently is 100 KiB.
256 .PP
257 \&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR changes the limit for
258 the number of HTTP header lines allowed to be received in a response.
259 The default limit is \fBOSSL_HTTP_DEFAULT_MAX_RESP_HDR_LINES\fR, currently 256.
260 If the limit is not 0 and the number of lines exceeds the limit,
261 then the HTTP_R_RESPONSE_TOO_MANY_HDRLINES error is indicated.
262 Setting the limit to 0 disables the check.
263 .PP
264 \&\fBOSSL_HTTP_is_alive()\fR can be used to query if the HTTP connection
265 given by \fIrctx\fR is still alive, i.e., has not been closed.
266 It returns 0 if \fIrctx\fR is NULL.
267 .PP
268 If the client application requested or required a persistent connection
269 and this was granted by the server, it can keep \fIrctx\fR as long as it wants
270 to send further requests and \fBOSSL_HTTP_is_alive()\fR returns nonzero,
271 else it should call \fIOSSL_HTTP_REQ_CTX_free(rctx)\fR or \fBOSSL_HTTP_close\fR\|(3).
272 In case the client application keeps \fIrctx\fR but the connection then dies
273 for any reason at the server side, it will notice this obtaining an
274 I/O error when trying to send the next request via \fIrctx\fR.
275 .SH WARNINGS
276 .IX Header "WARNINGS"
277 The server's response may be unexpected if the hostname that was used to
278 create the \fIwbio\fR, any \f(CW\*(C`Host\*(C'\fR header, and the host specified in the
279 request URL do not match.
280 .PP
281 Many of these functions must be called in a certain order.
282 .PP
283 First, the HTTP request context must be allocated:
284 \&\fBOSSL_HTTP_REQ_CTX_new()\fR.
285 .PP
286 Then, the HTTP request must be prepared with request data:
287 .IP 1. 4
288 Calling \fBOSSL_HTTP_REQ_CTX_set_request_line()\fR.
289 .IP 2. 4
290 Adding extra header lines with \fBOSSL_HTTP_REQ_CTX_add1_header()\fR.
291 This is optional and may be done multiple times with different names.
292 .IP 3. 4
293 Finalize the request using \fBOSSL_HTTP_REQ_CTX_set1_req()\fR.
294 This may be omitted if the GET method is used and "keep-alive" is not requested.
295 .PP
296 When the request context is fully prepared, the HTTP exchange may be performed
297 with \fBOSSL_HTTP_REQ_CTX_nbio()\fR or \fBOSSL_HTTP_REQ_CTX_exchange()\fR.
298 .SH NOTES
299 .IX Header "NOTES"
300 When built with tracing enabled, \fBOSSL_HTTP_REQ_CTX_nbio()\fR and all functions
301 using it, such as \fBOSSL_HTTP_REQ_CTX_exchange()\fR and \fBOSSL_HTTP_transfer\fR\|(3),
302 may be traced using \fBOSSL_TRACE_CATEGORY_HTTP\fR.
303 See also \fBOSSL_trace_enabled\fR\|(3) and \fBopenssl\-env\fR\|(7).
304 .SH "RETURN VALUES"
305 .IX Header "RETURN VALUES"
306 \&\fBOSSL_HTTP_REQ_CTX_new()\fR returns a pointer to a \fBOSSL_HTTP_REQ_CTX\fR, or NULL
307 on error.
308 .PP
309 \&\fBOSSL_HTTP_REQ_CTX_free()\fR, \fBOSSL_HTTP_REQ_CTX_set_max_response_length()\fR, and
310 \&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR do not return values.
311 .PP
312 \&\fBOSSL_HTTP_REQ_CTX_set_request_line()\fR, \fBOSSL_HTTP_REQ_CTX_add1_header()\fR,
313 \&\fBOSSL_HTTP_REQ_CTX_set1_req()\fR, and \fBOSSL_HTTP_REQ_CTX_set_expected()\fR
314 return 1 for success and 0 for failure.
315 .PP
316 \&\fBOSSL_HTTP_REQ_CTX_nbio()\fR and \fBOSSL_HTTP_REQ_CTX_nbio_d2i()\fR
317 return 1 for success, 0 on error or redirection, \-1 if retry is needed.
318 .PP
319 \&\fBOSSL_HTTP_REQ_CTX_exchange()\fR and \fBOSSL_HTTP_REQ_CTX_get0_mem_bio()\fR
320 return a pointer to a \fBBIO\fR on success as described above or NULL on failure.
321 The returned BIO must not be freed by the caller.
322 .PP
323 \&\fBOSSL_HTTP_REQ_CTX_get_resp_len()\fR returns the size of the response contents
324 or 0 if not available or an error occurred.
325 .PP
326 \&\fBOSSL_HTTP_is_alive()\fR returns 1 if its argument is non-NULL
327 and the client requested a persistent connection
328 and the server did not disagree on keeping the connection open, else 0.
329 .SH "SEE ALSO"
330 .IX Header "SEE ALSO"
331 \&\fBBIO_should_retry\fR\|(3),
332 \&\fBBIO_wait\fR\|(3),
333 \&\fBASN1_item_d2i_bio\fR\|(3),
334 \&\fBASN1_item_i2d_mem_bio\fR\|(3),
335 \&\fBOSSL_HTTP_open\fR\|(3),
336 \&\fBOSSL_HTTP_get\fR\|(3),
337 \&\fBOSSL_HTTP_transfer\fR\|(3),
338 \&\fBOSSL_HTTP_close\fR\|(3),
339 \&\fBOSSL_trace_enabled\fR\|(3), and \fBopenssl\-env\fR\|(7).
340 .SH HISTORY
341 .IX Header "HISTORY"
342 \&\fBOSSL_HTTP_REQ_CTX_set_max_response_hdr_lines()\fR was added in OpenSSL 3.3.
343 .PP
344 All other functions described here were added in OpenSSL 3.0.
345 .SH COPYRIGHT
346 .IX Header "COPYRIGHT"
347 Copyright 2015\-2025 The OpenSSL Project Authors. All Rights Reserved.
348 .PP
349 Licensed under the Apache License 2.0 (the "License"). You may not use
350 this file except in compliance with the License. You can obtain a copy
351 in the file LICENSE in the source distribution or at
352 <https://www.openssl.org/source/license.html>.