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