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