1=pod 2 3=head1 NAME 4 5OSSL_HTTP_REQ_CTX, 6OSSL_HTTP_REQ_CTX_new, 7OSSL_HTTP_REQ_CTX_free, 8OSSL_HTTP_REQ_CTX_set_request_line, 9OSSL_HTTP_REQ_CTX_add1_header, 10OSSL_HTTP_REQ_CTX_set_expected, 11OSSL_HTTP_REQ_CTX_set1_req, 12OSSL_HTTP_REQ_CTX_nbio, 13OSSL_HTTP_REQ_CTX_nbio_d2i, 14OSSL_HTTP_REQ_CTX_exchange, 15OSSL_HTTP_REQ_CTX_get0_mem_bio, 16OSSL_HTTP_REQ_CTX_get_resp_len, 17OSSL_HTTP_REQ_CTX_set_max_response_length, 18OSSL_HTTP_is_alive, 19OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines 20- HTTP client low-level functions 21 22=head1 SYNOPSIS 23 24 #include <openssl/http.h> 25 26 typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX; 27 28 OSSL_HTTP_REQ_CTX *OSSL_HTTP_REQ_CTX_new(BIO *wbio, BIO *rbio, int buf_size); 29 void OSSL_HTTP_REQ_CTX_free(OSSL_HTTP_REQ_CTX *rctx); 30 31 int OSSL_HTTP_REQ_CTX_set_request_line(OSSL_HTTP_REQ_CTX *rctx, int method_POST, 32 const char *server, const char *port, 33 const char *path); 34 int OSSL_HTTP_REQ_CTX_add1_header(OSSL_HTTP_REQ_CTX *rctx, 35 const char *name, const char *value); 36 37 int OSSL_HTTP_REQ_CTX_set_expected(OSSL_HTTP_REQ_CTX *rctx, 38 const char *content_type, int asn1, 39 int timeout, int keep_alive); 40 int OSSL_HTTP_REQ_CTX_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type, 41 const ASN1_ITEM *it, const ASN1_VALUE *req); 42 int OSSL_HTTP_REQ_CTX_nbio(OSSL_HTTP_REQ_CTX *rctx); 43 int OSSL_HTTP_REQ_CTX_nbio_d2i(OSSL_HTTP_REQ_CTX *rctx, 44 ASN1_VALUE **pval, const ASN1_ITEM *it); 45 BIO *OSSL_HTTP_REQ_CTX_exchange(OSSL_HTTP_REQ_CTX *rctx); 46 47 BIO *OSSL_HTTP_REQ_CTX_get0_mem_bio(const OSSL_HTTP_REQ_CTX *rctx); 48 size_t OSSL_HTTP_REQ_CTX_get_resp_len(const OSSL_HTTP_REQ_CTX *rctx); 49 void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx, 50 unsigned long len); 51 52 int OSSL_HTTP_is_alive(const OSSL_HTTP_REQ_CTX *rctx); 53 54 void OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines(OSSL_HTTP_REQ_CTX *rctx, 55 size_t count); 56 57=head1 DESCRIPTION 58 59B<OSSL_HTTP_REQ_CTX> is a context structure for an HTTP request and response, 60used to collect all the necessary data to perform that request. 61 62This file documents low-level HTTP functions rarely used directly. High-level 63HTTP client functions like L<OSSL_HTTP_get(3)> and L<OSSL_HTTP_transfer(3)> 64should be preferred. 65 66OSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure, 67which gets populated with the B<BIO> to write/send the request to (I<wbio>), 68the B<BIO> to read/receive the response from (I<rbio>, which may be equal to 69I<wbio>), and the maximum expected response header line length I<buf_size>. 70A value <= 0 indicates that 71the B<OSSL_HTTP_DEFAULT_MAX_LINE_LEN> of 4KiB should be used. 72I<buf_size> is also used as the number of content bytes that are read at a time. 73The allocated context structure includes an internal memory B<BIO>, 74which collects the HTTP request header lines. 75 76OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I<rctx>. 77The I<rbio> is not free'd, I<wbio> will be free'd if I<free_wbio> is set. 78If the argument is NULL, nothing is done. 79 80OSSL_HTTP_REQ_CTX_set_request_line() adds the 1st HTTP request line to I<rctx>. 81The HTTP method is determined by I<method_POST>, 82which should be 1 to indicate C<POST> or 0 to indicate C<GET>. 83I<server> and I<port> may be set to give the server and the optional port that 84an HTTP proxy shall forward the request to, otherwise they must be left NULL. 85I<path> provides the HTTP request path; if left NULL, C</> is used. 86For backward compatibility, I<path> may begin with C<http://> and thus convey 87an absoluteURI. In this case it indicates HTTP proxy use and provides also the 88server (and optionally the port) that the proxy shall forward the request to. 89In this case the I<server> and I<port> arguments must be NULL. 90 91OSSL_HTTP_REQ_CTX_add1_header() adds header I<name> with value I<value> to the 92context I<rctx>. It can be called more than once to add multiple header lines. 93For example, to add a C<Host> header for C<example.com> you would call: 94 95 OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com"); 96 97OSSL_HTTP_REQ_CTX_set_expected() optionally sets in I<rctx> some expectations 98of the HTTP client on the response. 99Due to the structure of an HTTP request, if the I<keep_alive> argument is 100nonzero the function must be used before calling OSSL_HTTP_REQ_CTX_set1_req(). 101 102If the I<content_type> argument is not NULL, 103the client will check that the specified content-type string 104is included in the HTTP header of the response and return an error if not. 105In the content-type header line the specified string should be present either 106as a whole, or in case the specified string does not include a C<;> character, 107it is sufficient that the specified string appears as a prefix 108in the header line, followed by a C<;> character and any further text. 109For instance, if the I<content_type> argument specifies C<text/html>, 110this is matched by C<text/html>, C<text/html; charset=UTF-8>, etc. 111 112If the I<asn1> parameter is nonzero a structure in ASN.1 encoding will be 113expected as the response content and input streaming is disabled. This means 114that an ASN.1 sequence header is required, its length field is checked, and 115OSSL_HTTP_REQ_CTX_get0_mem_bio() should be used to get the buffered response. 116Otherwise (by default) any input format is allowed without length checks. 117In this case the BIO given as I<rbio> argument to OSSL_HTTP_REQ_CTX_new() should 118be used directly to read the response contents, which may support streaming. 119If the I<timeout> parameter is > 0 this indicates the maximum number of seconds 120the subsequent HTTP transfer (sending the request and receiving a response) 121is allowed to take. 122I<timeout> == 0 enables waiting indefinitely, i.e., no timeout can occur. 123This is the default. 124I<timeout> < 0 takes over any value set via the I<overall_timeout> argument of 125L<OSSL_HTTP_open(3)> with the default being 0, which means no timeout. 126If the I<keep_alive> parameter is 0, which is the default, the connection is not 127kept open after receiving a response. This is the default behavior for HTTP 1.0. 128If the value is 1 or 2 then a persistent connection is requested. 129If the value is 2 then a persistent connection is required, 130i.e., an error occurs in case the server does not grant it. 131 132OSSL_HTTP_REQ_CTX_set1_req() finalizes the HTTP request context. 133It is needed if the I<method_POST> parameter in the 134OSSL_HTTP_REQ_CTX_set_request_line() call was 1 135and an ASN.1-encoded request should be sent. 136It must also be used when requesting "keep-alive", 137even if a GET request is going to be sent, in which case I<req> must be NULL. 138Unless I<req> is NULL, the function adds the DER encoding of I<req> using 139the ASN.1 template I<it> to do the encoding (which does not support streaming). 140The HTTP header C<Content-Length> is filled out with the length of the request. 141I<content_type> must be NULL if I<req> is NULL. 142If I<content_type> isn't NULL, 143the HTTP header C<Content-Type> is also added with the given string value. 144The header lines are added to the internal memory B<BIO> for the request header. 145 146OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in I<rctx> 147and to gather the response via HTTP, using the I<wbio> and I<rbio> 148that were given when calling OSSL_HTTP_REQ_CTX_new(). 149The function may need to be called again if its result is -1, which indicates 150L<BIO_should_retry(3)>. In such a case it is advisable to sleep a little in 151between, using L<BIO_wait(3)> on the read BIO to prevent a busy loop. 152 153OSSL_HTTP_REQ_CTX_nbio_d2i() is like OSSL_HTTP_REQ_CTX_nbio() but on success 154in addition parses the response, which must be a DER-encoded ASN.1 structure, 155using the ASN.1 template I<it> and places the result in I<*pval>. 156 157OSSL_HTTP_REQ_CTX_exchange() calls OSSL_HTTP_REQ_CTX_nbio() as often as needed 158in order to exchange a request and response or until a timeout is reached. 159On success it returns a pointer to the BIO that can be used to read the result. 160If an ASN.1-encoded response was expected, this is the BIO 161returned by OSSL_HTTP_REQ_CTX_get0_mem_bio() when called after the exchange. 162This memory BIO does not support streaming. 163Otherwise the returned BIO is the I<rbio> given to OSSL_HTTP_REQ_CTX_new(), 164which may support streaming. 165When this BIO is returned, it has been read past the end of the response header, 166such that the actual response body can be read from it. 167The returned BIO pointer MUST NOT be freed by the caller. 168 169OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>. 170Before the HTTP request is sent, this could be used to adapt its header lines. 171I<Use with caution!> 172After receiving a response via HTTP, the BIO represents the current state of 173reading the response header. If the response was expected to be ASN.1 encoded, 174its contents can be read via this BIO, which does not support streaming. 175The returned BIO pointer must not be freed by the caller. 176 177OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents 178in I<rctx> if provided by the server as <Content-Length> header field, else 0. 179 180OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed 181response content length for I<rctx> to I<len>. If not set or I<len> is 0 182then the B<OSSL_HTTP_DEFAULT_MAX_RESP_LEN> is used, which currently is 100 KiB. 183If the C<Content-Length> header is present and exceeds this value or 184the content is an ASN.1 encoded structure with a length exceeding this value 185or both length indications are present but disagree then an error occurs. 186 187OSSL_HTTP_is_alive() can be used to query if the HTTP connection 188given by I<rctx> is still alive, i.e., has not been closed. 189It returns 0 if I<rctx> is NULL. 190 191If the client application requested or required a persistent connection 192and this was granted by the server, it can keep I<rctx> as long as it wants 193to send further requests and OSSL_HTTP_is_alive() returns nonzero, 194else it should call I<OSSL_HTTP_REQ_CTX_free(rctx)> or L<OSSL_HTTP_close(3)>. 195In case the client application keeps I<rctx> but the connection then dies 196for any reason at the server side, it will notice this obtaining an 197I/O error when trying to send the next request via I<rctx>. 198 199The OSSL_HTTP_REQ_CTX_set_max_response_hdr_lines() function changes the limit 200for the number of HTTP headers which can be received in a response. The default 201value is 256. If the number of HTTP headers in a response exceeds the limit, 202then the HTTP_R_RESPONSE_TOO_MANY_HDRLINES error is indicated. Setting the 203limit to 0 disables the check. 204 205=head1 WARNINGS 206 207The server's response may be unexpected if the hostname that was used to 208create the I<wbio>, any C<Host> header, and the host specified in the 209request URL do not match. 210 211Many of these functions must be called in a certain order. 212 213First, the HTTP request context must be allocated: 214OSSL_HTTP_REQ_CTX_new(). 215 216Then, the HTTP request must be prepared with request data: 217 218=over 4 219 220=item 1. 221 222Calling OSSL_HTTP_REQ_CTX_set_request_line(). 223 224=item 2. 225 226Adding extra header lines with OSSL_HTTP_REQ_CTX_add1_header(). 227This is optional and may be done multiple times with different names. 228 229=item 3. 230 231Finalize the request using OSSL_HTTP_REQ_CTX_set1_req(). 232This may be omitted if the GET method is used and "keep-alive" is not requested. 233 234=back 235 236When the request context is fully prepared, the HTTP exchange may be performed 237with OSSL_HTTP_REQ_CTX_nbio() or OSSL_HTTP_REQ_CTX_exchange(). 238 239=head1 NOTES 240 241When built with tracing enabled, OSSL_HTTP_REQ_CTX_nbio() and all functions 242using it, such as OSSL_HTTP_REQ_CTX_exchange() and L<OSSL_HTTP_transfer(3)>, 243may be traced using B<OSSL_TRACE_CATEGORY_HTTP>. 244See also L<OSSL_trace_enabled(3)> and L<openssl-env(7)>. 245 246=head1 RETURN VALUES 247 248OSSL_HTTP_REQ_CTX_new() returns a pointer to a B<OSSL_HTTP_REQ_CTX>, or NULL 249on error. 250 251OSSL_HTTP_REQ_CTX_free() and OSSL_HTTP_REQ_CTX_set_max_response_length() 252do not return values. 253 254OSSL_HTTP_REQ_CTX_set_request_line(), OSSL_HTTP_REQ_CTX_add1_header(), 255OSSL_HTTP_REQ_CTX_set1_req(), and OSSL_HTTP_REQ_CTX_set_expected() 256return 1 for success and 0 for failure. 257 258OSSL_HTTP_REQ_CTX_nbio() and OSSL_HTTP_REQ_CTX_nbio_d2i() 259return 1 for success, 0 on error or redirection, -1 if retry is needed. 260 261OSSL_HTTP_REQ_CTX_exchange() and OSSL_HTTP_REQ_CTX_get0_mem_bio() 262return a pointer to a B<BIO> on success as described above or NULL on failure. 263The returned BIO must not be freed by the caller. 264 265OSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents 266or 0 if not available or an error occurred. 267 268OSSL_HTTP_is_alive() returns 1 if its argument is non-NULL 269and the client requested a persistent connection 270and the server did not disagree on keeping the connection open, else 0. 271 272=head1 SEE ALSO 273 274L<BIO_should_retry(3)>, 275L<BIO_wait(3)>, 276L<ASN1_item_d2i_bio(3)>, 277L<ASN1_item_i2d_mem_bio(3)>, 278L<OSSL_HTTP_open(3)>, 279L<OSSL_HTTP_get(3)>, 280L<OSSL_HTTP_transfer(3)>, 281L<OSSL_HTTP_close(3)>, 282L<OSSL_trace_enabled(3)>, and L<openssl-env(7)>. 283 284=head1 HISTORY 285 286The functions described here were added in OpenSSL 3.0. 287 288=head1 COPYRIGHT 289 290Copyright 2015-2024 The OpenSSL Project Authors. All Rights Reserved. 291 292Licensed under the Apache License 2.0 (the "License"). You may not use 293this file except in compliance with the License. You can obtain a copy 294in the file LICENSE in the source distribution or at 295L<https://www.openssl.org/source/license.html>. 296 297=cut 298
