OSSL_HTTP_REQ_CTX.pod 12 KB

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