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_set1_req,
  11 OSSL_HTTP_REQ_CTX_nbio,
  12 OSSL_HTTP_REQ_CTX_sendreq_d2i,
  13 OSSL_HTTP_REQ_CTX_get0_mem_bio,
  14 OSSL_HTTP_REQ_CTX_set_max_response_length
  15 - HTTP client low-level functions
  16
  17 =head1 SYNOPSIS
  18
  19  #include <openssl/http.h>
  20
  21  typedef struct ossl_http_req_ctx_st OSSL_HTTP_REQ_CTX;
  22
  23  OSSL_HTTP_REQ_CTX *OSSL_HTTP_REQ_CTX_new(BIO *wbio, BIO *rbio,
  24                                           int maxline, unsigned long max_resp_len,
  25                                           int timeout,
  26                                           const char *expected_content_type,
  27                                           int expect_asn1);
  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_set1_req(OSSL_HTTP_REQ_CTX *rctx, const char *content_type,
  37                                 const ASN1_ITEM *it, ASN1_VALUE *req);
  38  int OSSL_HTTP_REQ_CTX_nbio(OSSL_HTTP_REQ_CTX *rctx);
  39  ASN1_VALUE *OSSL_HTTP_REQ_CTX_sendreq_d2i(OSSL_HTTP_REQ_CTX *rctx,
  40                                            const ASN1_ITEM *it);
  41
  42  BIO *OSSL_HTTP_REQ_CTX_get0_mem_bio(const OSSL_HTTP_REQ_CTX *rctx);
  43  void OSSL_HTTP_REQ_CTX_set_max_response_length(OSSL_HTTP_REQ_CTX *rctx,
  44                                                 unsigned long len);
  45
  46 =head1 DESCRIPTION
  47
  48 B<OSSL_HTTP_REQ_CTX> is a context structure for an HTTP request, used to
  49 collect all the necessary data to perform that request.
  50
  51 This file documents low-level HTTP functions rarely used directly.  High-level
  52 HTTP client functions like L<OSSL_HTTP_get(3)> and L<OSSL_HTTP_transfer(3)>
  53 should be preferred.
  54
  55 OSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure,
  56 which gets populated with the B<BIO> to send the request to (I<wbio>),
  57 the B<BIO> to read the response from (I<rbio>, which may be equal to I<wbio>),
  58 the maximum expected response header line length (I<maxline>, where a value <= 0
  59 indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB should be used;
  60 this length is also used as the number of content bytes read at a time),
  61 the maximum allowed response content length (I<max_resp_len>, where 0 means
  62 that the B<HTTP_DEFAULT_MAX_RESP_LEN> is used, which currently is 100 KiB),
  63 a response timeout measure in seconds (I<timeout>,
  64 where 0 indicates no timeout, i.e., waiting indefinitely),
  65 the expected MIME content type of the response (I<expected_content_type>,
  66 which may be NULL for no expectation),
  67 and a flag indicating that the response is expected to be
  68 a DER encoded ASN.1 structure (I<expect_asn1>).
  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 The returned context should only be used for a single HTTP request/response.
  72
  73 OSSL_HTTP_REQ_CTX_free() frees up the HTTP request context I<rctx>.
  74 The I<wbio> and I<rbio> are not free'd and it is up to the application
  75 to do so.
  76
  77 OSSL_HTTP_REQ_CTX_set_request_line() adds the HTTP request line to the context.
  78 The HTTP method is determined by I<method_POST>,
  79 which should be 1 to indicate C<POST> or 0 to indicate C<GET>.
  80 I<server> and I<port> may be set to indicate a proxy server and port
  81 that the request should go through, otherwise they should be left NULL.
  82 I<path> is the HTTP request path; if left NULL, C</> is used.
  83
  84 OSSL_HTTP_REQ_CTX_add1_header() adds header I<name> with value I<value> to the
  85 context I<rctx>. It can be called more than once to add multiple headers.
  86 For example, to add a C<Host> header for C<example.com> you would call:
  87
  88  OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
  89
  90 OSSL_HTTP_REQ_CTX_set1_req() is to be used if and only if the I<method_POST>
  91 parameter in the OSSL_HTTP_REQ_CTX_set_request_line() call was 1.
  92 It finalizes the HTTP request context by adding the DER encoding of I<req>,
  93 using the ASN.1 template I<it> to do the encoding.
  94 The HTTP header C<Content-Length> is filled out with the length of the request.
  95 If I<content_type> isn't NULL,
  96 the HTTP header C<Content-Type> is also added with its content as value.
  97 All of this ends up in the internal memory B<BIO>.
  98
  99 OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared I<rctx>
 100 and gathering the response via HTTP, using the I<rbio> and I<wbio>
 101 that were given when calling OSSL_HTTP_REQ_CTX_new().
 102 When successful, the contents of the internal memory B<BIO> contains
 103 the contents of the HTTP response, without the response headers.
 104 It may need to be called again if its result is -1, which indicates
 105 L<BIO_should_retry(3)>.  In such a case it is advisable to sleep a little in
 106 between using L<BIO_wait(3)> on the read BIO to prevent a busy loop.
 107
 108 OSSL_HTTP_REQ_CTX_sendreq_d2i() calls OSSL_HTTP_REQ_CTX_nbio(), possibly
 109 several times until a timeout is reached, and DER decodes the received
 110 response using the ASN.1 template I<it>.
 111
 112 OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
 113 Before sending the request, this could used to modify the HTTP request text.
 114 I<Use with caution!>
 115 After receiving a response via HTTP, the BIO represents
 116 the current state of reading the response headers and contents.
 117
 118 OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed
 119 response content length for I<rctx> to I<len>. If not set or I<len> is 0
 120 then the B<HTTP_DEFAULT_MAX_RESP_LEN> is used, which currently is 100 KiB.
 121 If the C<Content-Length> header is present and exceeds this value or
 122 the content is an ASN.1 encoded structure with a length exceeding this value
 123 or both length indications are present but disagree then an error occurs.
 124
 125 =head1 WARNINGS
 126
 127 The server's response may be unexpected if the hostname that was used to
 128 create the I<wbio>, any C<Host> header, and the host specified in the
 129 request URL do not match.
 130
 131 Many of these functions must be called in a certain order.
 132
 133 First, the HTTP request context must be allocated:
 134 OSSL_HTTP_REQ_CTX_new().
 135
 136 Then, the HTTP request must be prepared with request data:
 137
 138 =over 4
 139
 140 =item 1.
 141
 142 Calling OSSL_HTTP_REQ_CTX_set_request_line().  This must be done exactly once.
 143
 144 =item 2.
 145
 146 Adding extra headers with OSSL_HTTP_REQ_CTX_add1_header().
 147 This is optional and may be done multiple times with different names.
 148
 149 =item 3.
 150
 151 Add C<POST> data with OSSL_HTTP_REQ_CTX_set1_req().  This may only be done if
 152 I<method_POST> was 1 in the OSSL_HTTP_REQ_CTX_set_request_line() call,
 153 and must be done exactly once in that case.
 154
 155 =back
 156
 157 When the request context is fully prepared, the HTTP exchange may be performed
 158 with OSSL_HTTP_REQ_CTX_nbio() or OSSL_HTTP_REQ_CTX_sendreq_d2i().
 159
 160 =head1 RETURN VALUES
 161
 162 OSSL_HTTP_REQ_CTX_new() returns a pointer to a B<OSSL_HTTP_REQ_CTX>, or NULL
 163 on error.
 164
 165 OSSL_HTTP_REQ_CTX_free() and OSSL_HTTP_REQ_CTX_set_max_response_length()
 166 do not return values.
 167
 168 OSSL_HTTP_REQ_CTX_set_request_line(), OSSL_HTTP_REQ_CTX_add1_header(),
 169 OSSL_HTTP_REQ_CTX_set1_req() and OSSL_HTTP_REQ_CTX_nbio
 170 return 1 for success and 0 for failure.
 171
 172 OSSL_HTTP_REQ_CTX_sendreq_d2i() returns a pointer to an B<ASN1_VALUE> for
 173 success and NULL for failure.
 174
 175 OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
 176
 177 =head1 SEE ALSO
 178
 179 L<BIO_should_retry(3)>,
 180 L<BIO_wait(3)>,
 181 L<OSSL_HTTP_get(3)>,
 182 L<OSSL_HTTP_transfer(3)>
 183
 184 =head1 COPYRIGHT
 185
 186 Copyright 2015-2021 The OpenSSL Project Authors. All Rights Reserved.
 187
 188 Licensed under the Apache License 2.0 (the "License").  You may not use
 189 this file except in compliance with the License.  You can obtain a copy
 190 in the file LICENSE in the source distribution or at
 191 L<https://www.openssl.org/source/license.html>.
 192
 193 =cut