doc/man3/OSSL_HTTP_transfer.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 OSSL_HTTP_get,
   6 OSSL_HTTP_get_asn1,
   7 OSSL_HTTP_post_asn1,
   8 OSSL_HTTP_transfer,
   9 OSSL_HTTP_bio_cb_t,
  10 OSSL_HTTP_proxy_connect,
  11 OSSL_HTTP_parse_url
  12 - http client functions
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/http.h>
  17
  18  typedef BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg,
  19                                     int connect, int detail);
  20  BIO *OSSL_HTTP_get(const char *url, const char *proxy, const char *proxy_port,
  21                     BIO *bio, BIO *rbio,
  22                     OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
  23                     const STACK_OF(CONF_VALUE) *headers,
  24                     int maxline, unsigned long max_resp_len, int timeout,
  25                     const char *expected_content_type, int expect_asn1);
  26  ASN1_VALUE *OSSL_HTTP_get_asn1(const char *url,
  27                                 const char *proxy, const char *proxy_port,
  28                                 BIO *bio, BIO *rbio,
  29                                 OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
  30                                 const STACK_OF(CONF_VALUE) *headers,
  31                                 int maxline, unsigned long max_resp_len,
  32                                 int timeout, const char *expected_content_type,
  33                                 const ASN1_ITEM *it);
  34  ASN1_VALUE *OSSL_HTTP_post_asn1(const char *server, const char *port,
  35                                  const char *path, int use_ssl,
  36                                  const char *proxy, const char *proxy_port,
  37                                  BIO *bio, BIO *rbio,
  38                                  OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
  39                                  const STACK_OF(CONF_VALUE) *headers,
  40                                  const char *content_type,
  41                                  ASN1_VALUE *req, const ASN1_ITEM *req_it,
  42                                  int maxline, unsigned long max_resp_len,
  43                                  int timeout, const char *expected_ct,
  44                                  const ASN1_ITEM *rsp_it);
  45  BIO *OSSL_HTTP_transfer(const char *server, const char *port, const char *path,
  46                          int use_ssl, const char *proxy, const char *proxy_port,
  47                          BIO *bio, BIO *rbio,
  48                          OSSL_HTTP_bio_cb_t bio_update_fn, void *arg,
  49                          const STACK_OF(CONF_VALUE) *headers,
  50                          const char *content_type, BIO *req_mem,
  51                          int maxline, unsigned long max_resp_len, int timeout,
  52                          const char *expected_ct, int expect_asn1,
  53                          char **redirection_url);
  54  int OSSL_HTTP_proxy_connect(BIO *bio, const char *server, const char *port,
  55                              const char *proxyuser, const char *proxypass,
  56                              int timeout, BIO *bio_err, const char *prog);
  57  int OSSL_HTTP_parse_url(const char *url, char **phost, char **pport,
  58                          char **ppath, int *pssl);
  59
  60 =head1 DESCRIPTION
  61
  62 OSSL_HTTP_get() uses HTTP GET to obtain data (of any type) from the given B<url>
  63 and returns it as a memory BIO.
  64
  65 OSSL_HTTP_get_asn1() uses HTTP GET to obtain an ASN.1-encoded value
  66 (e.g., an X.509 certificate) with the expected structure specified by B<it>
  67 (e.g., I<ASN1_ITEM_rptr(X509)>) from the given B<url>
  68 and returns it on success as a pointer to I<ASN1_VALUE>.
  69
  70 OSSL_HTTP_post_asn1() uses the HTTP POST method to send a request B<req>
  71 with the ASN.1 structure defined in B<req_it> and the given B<content_type> to
  72 the given B<server> and optional B<port> and B<path>, which defaults to "/".
  73 If B<use_ssl> is nonzero a TLS connection is requested and the B<bio_update_fn>
  74 parameter, described below, must be provided.
  75 The optional list B<headers> may contain additional custom HTTP header lines.
  76 The expected structure of the response is specified by B<rsp_it>.
  77 On success it returns the response as a pointer to B<ASN1_VALUE>.
  78
  79 OSSL_HTTP_transfer() exchanges an HTTP request and response with
  80 the given B<server> and optional B<port> and B<path>, which defaults to "/".
  81 If B<use_ssl> is nonzero a TLS connection is requested and the B<bio_update_fn>
  82 parameter, described below, must be provided.
  83 If B<req_mem> is NULL it uses the HTTP GET method, else it uses HTTP POST to
  84 send a request with the contents of the memory BIO and optional B<content_type>.
  85 The optional list B<headers> may contain additional custom HTTP header lines.
  86 If B<req_mem> is NULL (i.e., the HTTP method is GET) and B<redirection_url>
  87 is not NULL the latter pointer is used to provide any new location that
  88 the server may return with HTTP code 301 (MOVED_PERMANENTLY) or 302 (FOUND).
  89 In this case the caller is responsible for deallocating this URL with
  90 L<OPENSSL_free(3)>.
  91
  92 The above functions have the following parameters in common.
  93
  94 If the B<proxy> parameter is not NULL the HTTP client functions connect
  95 via the given proxy and the optionally given B<proxy_port>.
  96 Proxying plain HTTP is supported directly,
  97 while using a proxy for HTTPS connections requires a suitable callback function
  98 such as OSSL_HTTP_proxy_connect(), described below.
  99
 100 Typically the B<bio> and B<rbio> parameters are NULL and the client creates a
 101 network BIO internally for connecting to the given server and port (optionally
 102 via a proxy and its port), and uses it for exchanging the request and response.
 103 If B<bio> is given and B<rbio> is NULL then the client uses this BIO instead.
 104 If both B<bio> and B<rbio> are given (which may be memory BIOs for instance)
 105 then no explicit connection is attempted,
 106 B<bio> is used for writing the request, and B<rbio> for reading the response.
 107 As soon as the client has flushed B<bio> the server must be ready to provide
 108 a response or indicate a waiting condition via B<rbio>.
 109
 110 The B<maxline> parameter specifies the response header maximum line length,
 111 where 0 indicates the default value, which currently is 4k.
 112 The B<max_resp_len> parameter specifies the maximum response length,
 113 where 0 indicates the default value, which currently is 100k.
 114
 115 An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and
 116 OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer()
 117 this is only the case if the B<expect_asn1> parameter is nonzero.
 118 If the response header contains one or more Content-Length header lines and/or
 119 an ASN.1-encoded response is expected, which should include a total length,
 120 the length indications received are checked for consistency
 121 and for not exceeding the maximum response length.
 122
 123 If the parameter B<expected_content_type> (or B<expected_ct>, respectively)
 124 is not NULL then the HTTP client checks that the given content type string
 125 is included in the HTTP header of the response and returns an error if not.
 126
 127 If the B<timeout> parameter is > 0 this indicates the maximum number of seconds
 128 to wait until the transfer is complete.
 129 A value of 0 enables waiting indefinitely,
 130 while a value < 0 immediately leads to a timeout condition.
 131
 132 The optional parameter B<bio_update_fn> with its optional argument B<arg> may
 133 be used to modify the connection BIO used by the HTTP client (and cannot be
 134 used when both B<bio> and B<rbio> are given).
 135 B<bio_update_fn> is a BIO connect/disconnect callback function with prototype
 136
 137  BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
 138
 139 The callback may modify the HTTP BIO provided in the B<bio> argument,
 140 whereby it may make use of a custom defined argument B<arg>,
 141 which may for instance refer to an I<SSL_CTX> structure.
 142 During connection establishment, just after calling BIO_connect_retry(),
 143 the function is invoked with the B<connect> argument being 1 and the B<detail>
 144 argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled.
 145 On disconnect B<connect> is 0 and B<detail> is 1 if no error occurred, else 0.
 146 For instance, on connect the function may prepend a TLS BIO to implement HTTPS;
 147 after disconnect it may do some diagnostic output and/or specific cleanup.
 148 The function should return NULL to indicate failure.
 149 Here is a simple example that supports TLS connections (but not via a proxy):
 150
 151  BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail)
 152  {
 153      SSL_CTX *ctx = (SSL_CTX *)arg;
 154
 155      if (connect && detail) { /* connecting with TLS */
 156          BIO *sbio = BIO_new_ssl(ctx, 1);
 157          hbio = sbio != NULL ? BIO_push(sbio, hbio) : NULL;
 158      } else if (!connect && !detail) { /* disconnecting after error */
 159          /* optionally add diagnostics here */
 160      }
 161      return hbio;
 162  }
 163
 164 After disconnect the modified BIO will be deallocated using BIO_free_all().
 165
 166 OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function
 167 to set up an SSL/TLS connection via an HTTP proxy.
 168 It promotes the given BIO B<bio> representing a connection
 169 pre-established with a TLS proxy using the HTTP CONNECT method,
 170 optionally using proxy client credentials B<proxyuser> and B<proxypass>,
 171 to connect with TLS protection ultimately to B<server> and B<port>.
 172 The B<timeout> parameter is used as described above.
 173 Since this function is typically called by appplications such as
 174 L<openssl-s_client(1)> it uses the B<bio_err> and B<prog> parameters (unless
 175 NULL) to print additional diagnostic information in a user-oriented way.
 176
 177 OSSL_HTTP_parse_url() parses its input string B<url> as a URL and splits it up
 178 into host, port and path components and a flag whether it begins with 'https'.
 179 The host component may be a DNS name or an IPv4 or an IPv6 address.
 180 The port component is optional and defaults to "443" for HTTPS, else "80".
 181 The path component is also optional and defaults to "/".
 182 As far as the result pointer arguments are not NULL it assigns via
 183 them copies of the respective string components.
 184 The strings returned this way must be deallocated by the caller using
 185 L<OPENSSL_free(3)> unless they are NULL, which is their default value on error.
 186
 187 =head1 RETURN VALUES
 188
 189 OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
 190 OSSL_HTTP_transfer() return on success the data received via HTTP, else NULL.
 191 Error conditions include connection/transfer timeout, parse errors, etc.
 192
 193 OSSL_HTTP_proxy_connect() and OSSL_HTTP_parse_url()
 194 return 1 on success, 0 on error.
 195
 196 =head1 HISTORY
 197
 198 OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(),
 199 OSSL_HTTP_proxy_connect(), and OSSL_HTTP_parse_url() were added in OpenSSL 3.0.
 200
 201 =head1 COPYRIGHT
 202
 203 Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved.
 204
 205 Licensed under the Apache License 2.0 (the "License").  You may not use
 206 this file except in compliance with the License.  You can obtain a copy
 207 in the file LICENSE in the source distribution or at
 208 L<https://www.openssl.org/source/license.html>.
 209
 210 =cut