doc/man3/OSSL_HTTP_REQ_CTX.pod

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