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