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