1OSSL_HTTP_REQ_CTX(3ossl) OpenSSL OSSL_HTTP_REQ_CTX(3ossl)
2
6 OSSL_HTTP_REQ_CTX, OSSL_HTTP_REQ_CTX_new, OSSL_HTTP_REQ_CTX_free,
7 OSSL_HTTP_REQ_CTX_set_request_line, OSSL_HTTP_REQ_CTX_add1_header,
8 OSSL_HTTP_REQ_CTX_set_expected, OSSL_HTTP_REQ_CTX_set1_req,
9 OSSL_HTTP_REQ_CTX_nbio, OSSL_HTTP_REQ_CTX_nbio_d2i,
10 OSSL_HTTP_REQ_CTX_exchange, OSSL_HTTP_REQ_CTX_get0_mem_bio,
11 OSSL_HTTP_REQ_CTX_get_resp_len,
12 OSSL_HTTP_REQ_CTX_set_max_response_length, OSSL_HTTP_is_alive - HTTP
13 client low-level functions
14
16 #include <openssl/http.h>
17 typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX;
19 OSSL_HTTP_REQ_CTX *OSSL_HTTP_REQ_CTX_new(BIO *wbio, BIO *rbio, int buf_size);
21 void OSSL_HTTP_REQ_CTX_free(OSSL_HTTP_REQ_CTX *rctx);
22 int OSSL_HTTP_REQ_CTX_set_request_line(OSSL_HTTP_REQ_CTX *rctx, int method_POST,
24 const char *server, const char *port,
25 const char *path);
26 int OSSL_HTTP_REQ_CTX_add1_header(OSSL_HTTP_REQ_CTX *rctx,
27 const char *name, const char *value);
28 int OSSL_HTTP_REQ_CTX_set_expected(OSSL_HTTP_REQ_CTX *rctx,
30 const char *content_type, int asn1,
31 int timeout, int keep_alive);
32 int OSSL_HTTP_REQ_CTX_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type,
33 const ASN1_ITEM *it, const ASN1_VALUE *req);
34 int OSSL_HTTP_REQ_CTX_nbio(OSSL_HTTP_REQ_CTX *rctx);
35 int OSSL_HTTP_REQ_CTX_nbio_d2i(OSSL_HTTP_REQ_CTX *rctx,
36 ASN1_VALUE **pval, const ASN1_ITEM *it);
37 BIO *OSSL_HTTP_REQ_CTX_exchange(OSSL_HTTP_REQ_CTX *rctx);
38 BIO *OSSL_HTTP_REQ_CTX_get0_mem_bio(const OSSL_HTTP_REQ_CTX *rctx);
40 size_t OSSL_HTTP_REQ_CTX_get_resp_len(const OSSL_HTTP_REQ_CTX *rctx);
41 void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx,
42 unsigned long len);
43 int OSSL_HTTP_is_alive(const OSSL_HTTP_REQ_CTX *rctx);
45
47 OSSL_HTTP_REQ_CTX is a context structure for an HTTP request and
48 response, used to collect all the necessary data to perform that
49 request.
50 This file documents low-level HTTP functions rarely used directly.
52 High-level HTTP client functions like OSSL_HTTP_get(3) and
53 OSSL_HTTP_transfer(3) should be preferred.
54 OSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure,
56 which gets populated with the BIO to write/send the request to (wbio),
57 the BIO to read/receive the response from (rbio, which may be equal to
58 wbio), and the maximum expected response header line length buf_size.
59 A value <= 0 indicates that the OSSL_HTTP_DEFAULT_MAX_LINE_LEN of 4KiB
60 should be used. buf_size is also used as the number of content bytes
61 that are read at a time. The allocated context structure is also
62 populated with an internal allocated memory BIO, which collects the
63 HTTP request and additional headers as text.
64 OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context rctx. The
66 rbio is not free'd, wbio will be free'd if free_wbio is set.
67 OSSL_HTTP_REQ_CTX_set_request_line() adds the HTTP request line to the
69 context. The HTTP method is determined by method_POST, which should be
70 1 to indicate "POST" or 0 to indicate "GET". server and port may be
71 set to indicate a proxy server and port that the request should go
72 through, otherwise they should be left NULL. path is the HTTP request
73 path; if left NULL, "/" is used.
74 OSSL_HTTP_REQ_CTX_add1_header() adds header name with value value to
76 the context rctx. It can be called more than once to add multiple
77 headers. For example, to add a "Host" header for "example.com" you
78 would call:
79 OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
81 OSSL_HTTP_REQ_CTX_set_expected() optionally sets in rctx some
83 expectations of the HTTP client on the response. Due to the structure
84 of an HTTP request, if the keep_alive argument is nonzero the function
85 must be used before calling OSSL_HTTP_REQ_CTX_set1_req(). If the
86 content_type parameter is not NULL then the client will check that the
87 given content type string is included in the HTTP header of the
88 response and return an error if not. If the asn1 parameter is nonzero
89 a structure in ASN.1 encoding will be expected as the response content
90 and input streaming is disabled. This means that an ASN.1 sequence
91 header is required, its length field is checked, and
92 OSSL_HTTP_REQ_CTX_get0_mem_bio() should be used to get the buffered
93 response. Otherwise any input format is allowed without length checks,
94 which is the default. In this case the BIO given as rbio argument to
95 OSSL_HTTP_REQ_CTX_new() should be used directly to read the response
96 contents, which may support streaming. If the timeout parameter is > 0
97 this indicates the maximum number of seconds the subsequent HTTP
98 transfer (sending the request and receiving a response) is allowed to
99 take. timeout == 0 enables waiting indefinitely, i.e., no timeout can
100 occur. This is the default. timeout < 0 takes over any value set via
101 the overall_timeout argument of OSSL_HTTP_open(3) with the default
102 being 0, which means no timeout. If the keep_alive parameter is 0,
103 which is the default, the connection is not kept open after receiving a
104 response. This is the default behavior for HTTP 1.0. If the value is 1
105 or 2 then a persistent connection is requested. If the value is 2 then
106 a persistent connection is required, i.e., an error occurs in case the
107 server does not grant it.
108 OSSL_HTTP_REQ_CTX_set1_req() finalizes the HTTP request context. It is
110 needed if the method_POST parameter in the
111 OSSL_HTTP_REQ_CTX_set_request_line() call was 1 and an ASN.1-encoded
112 request should be sent. It must also be used when requesting "keep-
113 alive", even if a GET request is going to be sent, in which case req
114 must be NULL. Unless req is NULL, the function adds the DER encoding
115 of req using the ASN.1 template it to do the encoding (which does not
116 support streaming). The HTTP header "Content-Length" is filled out
117 with the length of the request. content_type must be NULL if req is
118 NULL. If content_type isn't NULL, the HTTP header "Content-Type" is
119 also added with the given string value. All of this ends up in the
120 internal memory BIO.
121 OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in rctx
123 and to gather the response via HTTP, using the wbio and rbio that were
124 given when calling OSSL_HTTP_REQ_CTX_new(). The function may need to
125 be called again if its result is -1, which indicates
126 BIO_should_retry(3). In such a case it is advisable to sleep a little
127 in between, using BIO_wait(3) on the read BIO to prevent a busy loop.
128 OSSL_HTTP_REQ_CTX_nbio_d2i() is like OSSL_HTTP_REQ_CTX_nbio() but on
130 successs in addition parses the response, which must be a DER-encoded
131 ASN.1 structure, using the ASN.1 template it and places the result in
132 *pval.
133 OSSL_HTTP_REQ_CTX_exchange() calls OSSL_HTTP_REQ_CTX_nbio() as often as
135 needed in order to exchange a request and response or until a timeout
136 is reached. On success it returns a pointer to the BIO that can be
137 used to read the result. If an ASN.1-encoded response was expected,
138 this is the BIO returned by OSSL_HTTP_REQ_CTX_get0_mem_bio() when
139 called after the exchange. This memory BIO does not support streaming.
140 Otherwise it may be the rbio given when calling
141 OSSL_HTTP_REQ_CTX_new(), and this BIO has been read past the end of the
142 response headers, such that the actual response body can be read via
143 this BIO, which may support streaming. The returned BIO pointer must
144 not be freed by the caller.
145 OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory BIO.
147 Before sending the request, this could used to modify the HTTP request
148 text. Use with caution! After receiving a response via HTTP, the BIO
149 represents the current state of reading the response headers. If the
150 response was expected to be ASN.1 encoded, its contents can be read via
151 this BIO, which does not support streaming. The returned BIO pointer
152 must not be freed by the caller.
153 OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response
155 contents in rctx if provided by the server as <Content-Length> header
156 field, else 0.
157 OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed
159 response content length for rctx to len. If not set or len is 0 then
160 the OSSL_HTTP_DEFAULT_MAX_RESP_LEN is used, which currently is 100 KiB.
161 If the "Content-Length" header is present and exceeds this value or the
162 content is an ASN.1 encoded structure with a length exceeding this
163 value or both length indications are present but disagree then an error
164 occurs.
165 OSSL_HTTP_is_alive() can be used to query if the HTTP connection given
167 by rctx is still alive, i.e., has not been closed. It returns 0 if
168 rctx is NULL.
169 If the client application requested or required a persistent connection
171 and this was granted by the server, it can keep rctx as long as it
172 wants to send further requests and OSSL_HTTP_is_alive() returns
173 nonzero, else it should call OSSL_HTTP_REQ_CTX_free(rctx) or
174 OSSL_HTTP_close(3). In case the client application keeps rctx but the
175 connection then dies for any reason at the server side, it will notice
176 this obtaining an I/O error when trying to send the next request via
177 rctx.
178
180 The server's response may be unexpected if the hostname that was used
181 to create the wbio, any "Host" header, and the host specified in the
182 request URL do not match.
183 Many of these functions must be called in a certain order.
185 First, the HTTP request context must be allocated:
187 OSSL_HTTP_REQ_CTX_new().
188 Then, the HTTP request must be prepared with request data:
190 1. Calling OSSL_HTTP_REQ_CTX_set_request_line().
192 2. Adding extra headers with OSSL_HTTP_REQ_CTX_add1_header(). This is
194 optional and may be done multiple times with different names.
195 3. Finalize the request using OSSL_HTTP_REQ_CTX_set1_req(). This may
197 be omitted if the GET method is used and "keep-alive" is not
198 requested.
199 When the request context is fully prepared, the HTTP exchange may be
201 performed with OSSL_HTTP_REQ_CTX_nbio() or
202 OSSL_HTTP_REQ_CTX_exchange().
203
205 OSSL_HTTP_REQ_CTX_new() returns a pointer to a OSSL_HTTP_REQ_CTX, or
206 NULL on error.
207 OSSL_HTTP_REQ_CTX_free() and
209 OSSL_HTTP_REQ_CTX_set_max_response_length() do not return values.
210 OSSL_HTTP_REQ_CTX_set_request_line(), OSSL_HTTP_REQ_CTX_add1_header(),
212 OSSL_HTTP_REQ_CTX_set1_req(), and OSSL_HTTP_REQ_CTX_set_expected()
213 return 1 for success and 0 for failure.
214 OSSL_HTTP_REQ_CTX_nbio() and OSSL_HTTP_REQ_CTX_nbio_d2i() return 1 for
216 success, 0 on error or redirection, -1 if retry is needed.
217 OSSL_HTTP_REQ_CTX_exchange() and OSSL_HTTP_REQ_CTX_get0_mem_bio()
219 return a pointer to a BIO on success and NULL on failure. The returned
220 BIO must not be freed by the caller.
221 OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response
223 contents or 0 if not available or an error occurred.
224 OSSL_HTTP_is_alive() returns 1 if its argument is non-NULL and the
226 client requested a persistent connection and the server did not
227 disagree on keeping the connection open, else 0.
228
230 BIO_should_retry(3), BIO_wait(3), ASN1_item_d2i_bio(3),
231 ASN1_item_i2d_mem_bio(3), OSSL_HTTP_open(3), OSSL_HTTP_get(3),
232 OSSL_HTTP_transfer(3), OSSL_HTTP_close(3)
233
235 The functions described here were added in OpenSSL 3.0.
236
238 Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.
239 Licensed under the Apache License 2.0 (the "License"). You may not use
241 this file except in compliance with the License. You can obtain a copy
242 in the file LICENSE in the source distribution or at
243 <https://www.openssl.org/source/license.html>.
2443.0.5 2022-11-01 OSSL_HTTP_REQ_CTX(3ossl)