1OSSL_HTTP_REQ_CTX(3ossl)            OpenSSL           OSSL_HTTP_REQ_CTX(3ossl)
2
3
4

NAME

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

SYNOPSIS

16        #include <openssl/http.h>
17
18        typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX;
19
20        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
23        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
29        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
39        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
44        int OSSL_HTTP_is_alive(const OSSL_HTTP_REQ_CTX *rctx);
45

DESCRIPTION

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
51       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
55       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 includes an
62       internal memory BIO, which collects the HTTP request header lines.
63
64       OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context rctx.  The
65       rbio is not free'd, wbio will be free'd if free_wbio is set.
66
67       OSSL_HTTP_REQ_CTX_set_request_line() adds the HTTP request line to the
68       context.  The HTTP method is determined by method_POST, which should be
69       1 to indicate "POST" or 0 to indicate "GET".  server and port may be
70       set to indicate a proxy server and port that the request should go
71       through, otherwise they should be left NULL.  path is the HTTP request
72       path; if left NULL, "/" is used.
73
74       OSSL_HTTP_REQ_CTX_add1_header() adds header name with value value to
75       the context rctx. It can be called more than once to add multiple
76       header lines.  For example, to add a "Host" header for "example.com"
77       you would call:
78
79        OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
80
81       OSSL_HTTP_REQ_CTX_set_expected() optionally sets in rctx some
82       expectations of the HTTP client on the response.  Due to the structure
83       of an HTTP request, if the keep_alive argument is nonzero the function
84       must be used before calling OSSL_HTTP_REQ_CTX_set1_req().  If the
85       content_type parameter is not NULL then the client will check that the
86       given content type string is included in the HTTP header of the
87       response and return an error if not.  If the asn1 parameter is nonzero
88       a structure in ASN.1 encoding will be expected as the response content
89       and input streaming is disabled.  This means that an ASN.1 sequence
90       header is required, its length field is checked, and
91       OSSL_HTTP_REQ_CTX_get0_mem_bio() should be used to get the buffered
92       response.  Otherwise (by default) any input format is allowed without
93       length checks.  In this case the BIO given as rbio argument to
94       OSSL_HTTP_REQ_CTX_new() should be used directly to read the response
95       contents, which may support streaming.  If the timeout parameter is > 0
96       this indicates the maximum number of seconds the subsequent HTTP
97       transfer (sending the request and receiving a response) is allowed to
98       take.  timeout == 0 enables waiting indefinitely, i.e., no timeout can
99       occur.  This is the default.  timeout < 0 takes over any value set via
100       the overall_timeout argument of OSSL_HTTP_open(3) with the default
101       being 0, which means no timeout.  If the keep_alive parameter is 0,
102       which is the default, the connection is not kept open after receiving a
103       response. This is the default behavior for HTTP 1.0.  If the value is 1
104       or 2 then a persistent connection is requested.  If the value is 2 then
105       a persistent connection is required, i.e., an error occurs in case the
106       server does not grant it.
107
108       OSSL_HTTP_REQ_CTX_set1_req() finalizes the HTTP request context.  It is
109       needed if the method_POST parameter in the
110       OSSL_HTTP_REQ_CTX_set_request_line() call was 1 and an ASN.1-encoded
111       request should be sent.  It must also be used when requesting "keep-
112       alive", even if a GET request is going to be sent, in which case req
113       must be NULL.  Unless req is NULL, the function adds the DER encoding
114       of req using the ASN.1 template it to do the encoding (which does not
115       support streaming).  The HTTP header "Content-Length" is filled out
116       with the length of the request.  content_type must be NULL if req is
117       NULL.  If content_type isn't NULL, the HTTP header "Content-Type" is
118       also added with the given string value.  The header lines are added to
119       the internal memory BIO for the request header.
120
121       OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in rctx
122       and to gather the response via HTTP, using the wbio and rbio that were
123       given when calling OSSL_HTTP_REQ_CTX_new().  The function may need to
124       be called again if its result is -1, which indicates
125       BIO_should_retry(3).  In such a case it is advisable to sleep a little
126       in between, using BIO_wait(3) on the read BIO to prevent a busy loop.
127
128       OSSL_HTTP_REQ_CTX_nbio_d2i() is like OSSL_HTTP_REQ_CTX_nbio() but on
129       successs in addition parses the response, which must be a DER-encoded
130       ASN.1 structure, using the ASN.1 template it and places the result in
131       *pval.
132
133       OSSL_HTTP_REQ_CTX_exchange() calls OSSL_HTTP_REQ_CTX_nbio() as often as
134       needed in order to exchange a request and response or until a timeout
135       is reached.  On success it returns a pointer to the BIO that can be
136       used to read the result.  If an ASN.1-encoded response was expected,
137       this is the BIO returned by OSSL_HTTP_REQ_CTX_get0_mem_bio() when
138       called after the exchange.  This memory BIO does not support streaming.
139       Otherwise the returned BIO is the rbio given to
140       OSSL_HTTP_REQ_CTX_new(), which may support streaming.  When this BIO is
141       returned, it has been read past the end of the response header, such
142       that the actual response body can be read from it.  The returned BIO
143       pointer MUST NOT be freed by the caller.
144
145       OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory BIO.
146       Before the HTTP request is sent, this could be used to adapt its header
147       lines.  Use with caution!  After receiving a response via HTTP, the BIO
148       represents the current state of reading the response header. If the
149       response was expected to be ASN.1 encoded, its contents can be read via
150       this BIO, which does not support streaming.  The returned BIO pointer
151       must not be freed by the caller.
152
153       OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response
154       contents in rctx if provided by the server as <Content-Length> header
155       field, else 0.
156
157       OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed
158       response content length for rctx to len. If not set or len is 0 then
159       the OSSL_HTTP_DEFAULT_MAX_RESP_LEN is used, which currently is 100 KiB.
160       If the "Content-Length" header is present and exceeds this value or the
161       content is an ASN.1 encoded structure with a length exceeding this
162       value or both length indications are present but disagree then an error
163       occurs.
164
165       OSSL_HTTP_is_alive() can be used to query if the HTTP connection given
166       by rctx is still alive, i.e., has not been closed.  It returns 0 if
167       rctx is NULL.
168
169       If the client application requested or required a persistent connection
170       and this was granted by the server, it can keep rctx as long as it
171       wants to send further requests and OSSL_HTTP_is_alive() returns
172       nonzero, else it should call OSSL_HTTP_REQ_CTX_free(rctx) or
173       OSSL_HTTP_close(3).  In case the client application keeps rctx but the
174       connection then dies for any reason at the server side, it will notice
175       this obtaining an I/O error when trying to send the next request via
176       rctx.
177

WARNINGS

179       The server's response may be unexpected if the hostname that was used
180       to create the wbio, any "Host" header, and the host specified in the
181       request URL do not match.
182
183       Many of these functions must be called in a certain order.
184
185       First, the HTTP request context must be allocated:
186       OSSL_HTTP_REQ_CTX_new().
187
188       Then, the HTTP request must be prepared with request data:
189
190       1.  Calling OSSL_HTTP_REQ_CTX_set_request_line().
191
192       2.  Adding extra header lines with OSSL_HTTP_REQ_CTX_add1_header().
193           This is optional and may be done multiple times with different
194           names.
195
196       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
200       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

RETURN VALUES

205       OSSL_HTTP_REQ_CTX_new() returns a pointer to a OSSL_HTTP_REQ_CTX, or
206       NULL on error.
207
208       OSSL_HTTP_REQ_CTX_free() and
209       OSSL_HTTP_REQ_CTX_set_max_response_length() do not return values.
210
211       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
215       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
218       OSSL_HTTP_REQ_CTX_exchange() and OSSL_HTTP_REQ_CTX_get0_mem_bio()
219       return a pointer to a BIO on success as described above or NULL on
220       failure.  The returned BIO must not be freed by the caller.
221
222       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
225       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

SEE ALSO

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

HISTORY

235       The functions described here were added in OpenSSL 3.0.
236
238       Copyright 2015-2022 The OpenSSL Project Authors. All Rights Reserved.
239
240       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>.
244
245
246
2473.0.9                             2023-07-27          OSSL_HTTP_REQ_CTX(3ossl)
Impressum