1*66bae5e7Schristos=pod 2*66bae5e7Schristos 3*66bae5e7Schristos=head1 NAME 4*66bae5e7Schristos 5*66bae5e7SchristosOSSL_HTTP_REQ_CTX, 6*66bae5e7SchristosOSSL_HTTP_REQ_CTX_new, 7*66bae5e7SchristosOSSL_HTTP_REQ_CTX_free, 8*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set_request_line, 9*66bae5e7SchristosOSSL_HTTP_REQ_CTX_add1_header, 10*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set_expected, 11*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set1_req, 12*66bae5e7SchristosOSSL_HTTP_REQ_CTX_nbio, 13*66bae5e7SchristosOSSL_HTTP_REQ_CTX_nbio_d2i, 14*66bae5e7SchristosOSSL_HTTP_REQ_CTX_exchange, 15*66bae5e7SchristosOSSL_HTTP_REQ_CTX_get0_mem_bio, 16*66bae5e7SchristosOSSL_HTTP_REQ_CTX_get_resp_len, 17*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set_max_response_length, 18*66bae5e7SchristosOSSL_HTTP_is_alive 19*66bae5e7Schristos- HTTP client low-level functions 20*66bae5e7Schristos 21*66bae5e7Schristos=head1 SYNOPSIS 22*66bae5e7Schristos 23*66bae5e7Schristos #include <openssl/http.h> 24*66bae5e7Schristos 25*66bae5e7Schristos typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX; 26*66bae5e7Schristos 27*66bae5e7Schristos OSSL_HTTP_REQ_CTX *OSSL_HTTP_REQ_CTX_new(BIO *wbio, BIO *rbio, int buf_size); 28*66bae5e7Schristos void OSSL_HTTP_REQ_CTX_free(OSSL_HTTP_REQ_CTX *rctx); 29*66bae5e7Schristos 30*66bae5e7Schristos int OSSL_HTTP_REQ_CTX_set_request_line(OSSL_HTTP_REQ_CTX *rctx, int method_POST, 31*66bae5e7Schristos const char *server, const char *port, 32*66bae5e7Schristos const char *path); 33*66bae5e7Schristos int OSSL_HTTP_REQ_CTX_add1_header(OSSL_HTTP_REQ_CTX *rctx, 34*66bae5e7Schristos const char *name, const char *value); 35*66bae5e7Schristos 36*66bae5e7Schristos int OSSL_HTTP_REQ_CTX_set_expected(OSSL_HTTP_REQ_CTX *rctx, 37*66bae5e7Schristos const char *content_type, int asn1, 38*66bae5e7Schristos int timeout, int keep_alive); 39*66bae5e7Schristos int OSSL_HTTP_REQ_CTX_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type, 40*66bae5e7Schristos const ASN1_ITEM *it, const ASN1_VALUE *req); 41*66bae5e7Schristos int OSSL_HTTP_REQ_CTX_nbio(OSSL_HTTP_REQ_CTX *rctx); 42*66bae5e7Schristos int OSSL_HTTP_REQ_CTX_nbio_d2i(OSSL_HTTP_REQ_CTX *rctx, 43*66bae5e7Schristos ASN1_VALUE **pval, const ASN1_ITEM *it); 44*66bae5e7Schristos BIO *OSSL_HTTP_REQ_CTX_exchange(OSSL_HTTP_REQ_CTX *rctx); 45*66bae5e7Schristos 46*66bae5e7Schristos BIO *OSSL_HTTP_REQ_CTX_get0_mem_bio(const OSSL_HTTP_REQ_CTX *rctx); 47*66bae5e7Schristos size_t OSSL_HTTP_REQ_CTX_get_resp_len(const OSSL_HTTP_REQ_CTX *rctx); 48*66bae5e7Schristos void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx, 49*66bae5e7Schristos unsigned long len); 50*66bae5e7Schristos 51*66bae5e7Schristos int OSSL_HTTP_is_alive(const OSSL_HTTP_REQ_CTX *rctx); 52*66bae5e7Schristos 53*66bae5e7Schristos=head1 DESCRIPTION 54*66bae5e7Schristos 55*66bae5e7SchristosB<OSSL_HTTP_REQ_CTX> is a context structure for an HTTP request and response, 56*66bae5e7Schristosused to collect all the necessary data to perform that request. 57*66bae5e7Schristos 58*66bae5e7SchristosThis file documents low-level HTTP functions rarely used directly. High-level 59*66bae5e7SchristosHTTP client functions like L<OSSL_HTTP_get(3)> and L<OSSL_HTTP_transfer(3)> 60*66bae5e7Schristosshould be preferred. 61*66bae5e7Schristos 62*66bae5e7SchristosOSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure, 63*66bae5e7Schristoswhich gets populated with the B<BIO> to write/send the request to (I<wbio>), 64*66bae5e7Schristosthe B<BIO> to read/receive the response from (I<rbio>, which may be equal to 65*66bae5e7SchristosI<wbio>), and the maximum expected response header line length I<buf_size>. 66*66bae5e7SchristosA value <= 0 indicates that 67*66bae5e7Schristosthe B<OSSL_HTTP_DEFAULT_MAX_LINE_LEN> of 4KiB should be used. 68*66bae5e7SchristosI<buf_size> is also used as the number of content bytes that are read at a time. 69*66bae5e7SchristosThe allocated context structure includes an internal memory B<BIO>, 70*66bae5e7Schristoswhich collects the HTTP request header lines. 71*66bae5e7Schristos 72*66bae5e7SchristosOSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I<rctx>. 73*66bae5e7SchristosThe I<rbio> is not free'd, I<wbio> will be free'd if I<free_wbio> is set. 74*66bae5e7Schristos 75*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set_request_line() adds the HTTP request line to the context. 76*66bae5e7SchristosThe HTTP method is determined by I<method_POST>, 77*66bae5e7Schristoswhich should be 1 to indicate C<POST> or 0 to indicate C<GET>. 78*66bae5e7SchristosI<server> and I<port> may be set to indicate a proxy server and port 79*66bae5e7Schristosthat the request should go through, otherwise they should be left NULL. 80*66bae5e7SchristosI<path> is the HTTP request path; if left NULL, C</> is used. 81*66bae5e7Schristos 82*66bae5e7SchristosOSSL_HTTP_REQ_CTX_add1_header() adds header I<name> with value I<value> to the 83*66bae5e7Schristoscontext I<rctx>. It can be called more than once to add multiple header lines. 84*66bae5e7SchristosFor example, to add a C<Host> header for C<example.com> you would call: 85*66bae5e7Schristos 86*66bae5e7Schristos OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com"); 87*66bae5e7Schristos 88*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set_expected() optionally sets in I<rctx> some expectations 89*66bae5e7Schristosof the HTTP client on the response. 90*66bae5e7SchristosDue to the structure of an HTTP request, if the I<keep_alive> argument is 91*66bae5e7Schristosnonzero the function must be used before calling OSSL_HTTP_REQ_CTX_set1_req(). 92*66bae5e7SchristosIf the I<content_type> parameter 93*66bae5e7Schristosis not NULL then the client will check that the given content type string 94*66bae5e7Schristosis included in the HTTP header of the response and return an error if not. 95*66bae5e7SchristosIf the I<asn1> parameter is nonzero a structure in ASN.1 encoding will be 96*66bae5e7Schristosexpected as the response content and input streaming is disabled. This means 97*66bae5e7Schristosthat an ASN.1 sequence header is required, its length field is checked, and 98*66bae5e7SchristosOSSL_HTTP_REQ_CTX_get0_mem_bio() should be used to get the buffered response. 99*66bae5e7SchristosOtherwise (by default) any input format is allowed without length checks. 100*66bae5e7SchristosIn this case the BIO given as I<rbio> argument to OSSL_HTTP_REQ_CTX_new() should 101*66bae5e7Schristosbe used directly to read the response contents, which may support streaming. 102*66bae5e7SchristosIf the I<timeout> parameter is > 0 this indicates the maximum number of seconds 103*66bae5e7Schristosthe subsequent HTTP transfer (sending the request and receiving a response) 104*66bae5e7Schristosis allowed to take. 105*66bae5e7SchristosI<timeout> == 0 enables waiting indefinitely, i.e., no timeout can occur. 106*66bae5e7SchristosThis is the default. 107*66bae5e7SchristosI<timeout> < 0 takes over any value set via the I<overall_timeout> argument of 108*66bae5e7SchristosL<OSSL_HTTP_open(3)> with the default being 0, which means no timeout. 109*66bae5e7SchristosIf the I<keep_alive> parameter is 0, which is the default, the connection is not 110*66bae5e7Schristoskept open after receiving a response. This is the default behavior for HTTP 1.0. 111*66bae5e7SchristosIf the value is 1 or 2 then a persistent connection is requested. 112*66bae5e7SchristosIf the value is 2 then a persistent connection is required, 113*66bae5e7Schristosi.e., an error occurs in case the server does not grant it. 114*66bae5e7Schristos 115*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set1_req() finalizes the HTTP request context. 116*66bae5e7SchristosIt is needed if the I<method_POST> parameter in the 117*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set_request_line() call was 1 118*66bae5e7Schristosand an ASN.1-encoded request should be sent. 119*66bae5e7SchristosIt must also be used when requesting "keep-alive", 120*66bae5e7Schristoseven if a GET request is going to be sent, in which case I<req> must be NULL. 121*66bae5e7SchristosUnless I<req> is NULL, the function adds the DER encoding of I<req> using 122*66bae5e7Schristosthe ASN.1 template I<it> to do the encoding (which does not support streaming). 123*66bae5e7SchristosThe HTTP header C<Content-Length> is filled out with the length of the request. 124*66bae5e7SchristosI<content_type> must be NULL if I<req> is NULL. 125*66bae5e7SchristosIf I<content_type> isn't NULL, 126*66bae5e7Schristosthe HTTP header C<Content-Type> is also added with the given string value. 127*66bae5e7SchristosThe header lines are added to the internal memory B<BIO> for the request header. 128*66bae5e7Schristos 129*66bae5e7SchristosOSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared in I<rctx> 130*66bae5e7Schristosand to gather the response via HTTP, using the I<wbio> and I<rbio> 131*66bae5e7Schristosthat were given when calling OSSL_HTTP_REQ_CTX_new(). 132*66bae5e7SchristosThe function may need to be called again if its result is -1, which indicates 133*66bae5e7SchristosL<BIO_should_retry(3)>. In such a case it is advisable to sleep a little in 134*66bae5e7Schristosbetween, using L<BIO_wait(3)> on the read BIO to prevent a busy loop. 135*66bae5e7Schristos 136*66bae5e7SchristosOSSL_HTTP_REQ_CTX_nbio_d2i() is like OSSL_HTTP_REQ_CTX_nbio() but on successs 137*66bae5e7Schristosin addition parses the response, which must be a DER-encoded ASN.1 structure, 138*66bae5e7Schristosusing the ASN.1 template I<it> and places the result in I<*pval>. 139*66bae5e7Schristos 140*66bae5e7SchristosOSSL_HTTP_REQ_CTX_exchange() calls OSSL_HTTP_REQ_CTX_nbio() as often as needed 141*66bae5e7Schristosin order to exchange a request and response or until a timeout is reached. 142*66bae5e7SchristosOn success it returns a pointer to the BIO that can be used to read the result. 143*66bae5e7SchristosIf an ASN.1-encoded response was expected, this is the BIO 144*66bae5e7Schristosreturned by OSSL_HTTP_REQ_CTX_get0_mem_bio() when called after the exchange. 145*66bae5e7SchristosThis memory BIO does not support streaming. 146*66bae5e7SchristosOtherwise the returned BIO is the I<rbio> given to OSSL_HTTP_REQ_CTX_new(), 147*66bae5e7Schristoswhich may support streaming. 148*66bae5e7SchristosWhen this BIO is returned, it has been read past the end of the response header, 149*66bae5e7Schristossuch that the actual response body can be read from it. 150*66bae5e7SchristosThe returned BIO pointer MUST NOT be freed by the caller. 151*66bae5e7Schristos 152*66bae5e7SchristosOSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>. 153*66bae5e7SchristosBefore the HTTP request is sent, this could be used to adapt its header lines. 154*66bae5e7SchristosI<Use with caution!> 155*66bae5e7SchristosAfter receiving a response via HTTP, the BIO represents the current state of 156*66bae5e7Schristosreading the response header. If the response was expected to be ASN.1 encoded, 157*66bae5e7Schristosits contents can be read via this BIO, which does not support streaming. 158*66bae5e7SchristosThe returned BIO pointer must not be freed by the caller. 159*66bae5e7Schristos 160*66bae5e7SchristosOSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents 161*66bae5e7Schristosin I<rctx> if provided by the server as <Content-Length> header field, else 0. 162*66bae5e7Schristos 163*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed 164*66bae5e7Schristosresponse content length for I<rctx> to I<len>. If not set or I<len> is 0 165*66bae5e7Schristosthen the B<OSSL_HTTP_DEFAULT_MAX_RESP_LEN> is used, which currently is 100 KiB. 166*66bae5e7SchristosIf the C<Content-Length> header is present and exceeds this value or 167*66bae5e7Schristosthe content is an ASN.1 encoded structure with a length exceeding this value 168*66bae5e7Schristosor both length indications are present but disagree then an error occurs. 169*66bae5e7Schristos 170*66bae5e7SchristosOSSL_HTTP_is_alive() can be used to query if the HTTP connection 171*66bae5e7Schristosgiven by I<rctx> is still alive, i.e., has not been closed. 172*66bae5e7SchristosIt returns 0 if I<rctx> is NULL. 173*66bae5e7Schristos 174*66bae5e7SchristosIf the client application requested or required a persistent connection 175*66bae5e7Schristosand this was granted by the server, it can keep I<rctx> as long as it wants 176*66bae5e7Schristosto send further requests and OSSL_HTTP_is_alive() returns nonzero, 177*66bae5e7Schristoselse it should call I<OSSL_HTTP_REQ_CTX_free(rctx)> or L<OSSL_HTTP_close(3)>. 178*66bae5e7SchristosIn case the client application keeps I<rctx> but the connection then dies 179*66bae5e7Schristosfor any reason at the server side, it will notice this obtaining an 180*66bae5e7SchristosI/O error when trying to send the next request via I<rctx>. 181*66bae5e7Schristos 182*66bae5e7Schristos=head1 WARNINGS 183*66bae5e7Schristos 184*66bae5e7SchristosThe server's response may be unexpected if the hostname that was used to 185*66bae5e7Schristoscreate the I<wbio>, any C<Host> header, and the host specified in the 186*66bae5e7Schristosrequest URL do not match. 187*66bae5e7Schristos 188*66bae5e7SchristosMany of these functions must be called in a certain order. 189*66bae5e7Schristos 190*66bae5e7SchristosFirst, the HTTP request context must be allocated: 191*66bae5e7SchristosOSSL_HTTP_REQ_CTX_new(). 192*66bae5e7Schristos 193*66bae5e7SchristosThen, the HTTP request must be prepared with request data: 194*66bae5e7Schristos 195*66bae5e7Schristos=over 4 196*66bae5e7Schristos 197*66bae5e7Schristos=item 1. 198*66bae5e7Schristos 199*66bae5e7SchristosCalling OSSL_HTTP_REQ_CTX_set_request_line(). 200*66bae5e7Schristos 201*66bae5e7Schristos=item 2. 202*66bae5e7Schristos 203*66bae5e7SchristosAdding extra header lines with OSSL_HTTP_REQ_CTX_add1_header(). 204*66bae5e7SchristosThis is optional and may be done multiple times with different names. 205*66bae5e7Schristos 206*66bae5e7Schristos=item 3. 207*66bae5e7Schristos 208*66bae5e7SchristosFinalize the request using OSSL_HTTP_REQ_CTX_set1_req(). 209*66bae5e7SchristosThis may be omitted if the GET method is used and "keep-alive" is not requested. 210*66bae5e7Schristos 211*66bae5e7Schristos=back 212*66bae5e7Schristos 213*66bae5e7SchristosWhen the request context is fully prepared, the HTTP exchange may be performed 214*66bae5e7Schristoswith OSSL_HTTP_REQ_CTX_nbio() or OSSL_HTTP_REQ_CTX_exchange(). 215*66bae5e7Schristos 216*66bae5e7Schristos=head1 RETURN VALUES 217*66bae5e7Schristos 218*66bae5e7SchristosOSSL_HTTP_REQ_CTX_new() returns a pointer to a B<OSSL_HTTP_REQ_CTX>, or NULL 219*66bae5e7Schristoson error. 220*66bae5e7Schristos 221*66bae5e7SchristosOSSL_HTTP_REQ_CTX_free() and OSSL_HTTP_REQ_CTX_set_max_response_length() 222*66bae5e7Schristosdo not return values. 223*66bae5e7Schristos 224*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set_request_line(), OSSL_HTTP_REQ_CTX_add1_header(), 225*66bae5e7SchristosOSSL_HTTP_REQ_CTX_set1_req(), and OSSL_HTTP_REQ_CTX_set_expected() 226*66bae5e7Schristosreturn 1 for success and 0 for failure. 227*66bae5e7Schristos 228*66bae5e7SchristosOSSL_HTTP_REQ_CTX_nbio() and OSSL_HTTP_REQ_CTX_nbio_d2i() 229*66bae5e7Schristosreturn 1 for success, 0 on error or redirection, -1 if retry is needed. 230*66bae5e7Schristos 231*66bae5e7SchristosOSSL_HTTP_REQ_CTX_exchange() and OSSL_HTTP_REQ_CTX_get0_mem_bio() 232*66bae5e7Schristosreturn a pointer to a B<BIO> on success as described above or NULL on failure. 233*66bae5e7SchristosThe returned BIO must not be freed by the caller. 234*66bae5e7Schristos 235*66bae5e7SchristosOSSL_HTTP_REQ_CTX_get_resp_len() returns the size of the response contents 236*66bae5e7Schristosor 0 if not available or an error occurred. 237*66bae5e7Schristos 238*66bae5e7SchristosOSSL_HTTP_is_alive() returns 1 if its argument is non-NULL 239*66bae5e7Schristosand the client requested a persistent connection 240*66bae5e7Schristosand the server did not disagree on keeping the connection open, else 0. 241*66bae5e7Schristos 242*66bae5e7Schristos=head1 SEE ALSO 243*66bae5e7Schristos 244*66bae5e7SchristosL<BIO_should_retry(3)>, 245*66bae5e7SchristosL<BIO_wait(3)>, 246*66bae5e7SchristosL<ASN1_item_d2i_bio(3)>, 247*66bae5e7SchristosL<ASN1_item_i2d_mem_bio(3)>, 248*66bae5e7SchristosL<OSSL_HTTP_open(3)>, 249*66bae5e7SchristosL<OSSL_HTTP_get(3)>, 250*66bae5e7SchristosL<OSSL_HTTP_transfer(3)>, 251*66bae5e7SchristosL<OSSL_HTTP_close(3)> 252*66bae5e7Schristos 253*66bae5e7Schristos=head1 HISTORY 254*66bae5e7Schristos 255*66bae5e7SchristosThe functions described here were added in OpenSSL 3.0. 256*66bae5e7Schristos 257*66bae5e7Schristos=head1 COPYRIGHT 258*66bae5e7Schristos 259*66bae5e7SchristosCopyright 2015-2022 The OpenSSL Project Authors. All Rights Reserved. 260*66bae5e7Schristos 261*66bae5e7SchristosLicensed under the Apache License 2.0 (the "License"). You may not use 262*66bae5e7Schristosthis file except in compliance with the License. You can obtain a copy 263*66bae5e7Schristosin the file LICENSE in the source distribution or at 264*66bae5e7SchristosL<https://www.openssl.org/source/license.html>. 265*66bae5e7Schristos 266*66bae5e7Schristos=cut 267