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 The optional I<proxy> parameter can be used to set the address of the 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 specifies not to use a proxy.
 113 Else the format is C<[http[s]://]address[:port][/path]>,
 114 where any path given is ignored.
 115 The default proxy port number is 80, or 443 in case "https:" is given.
 116 The HTTP client functions connect via the given proxy unless the I<server>
 117 is found in the optional list I<no_proxy> of proxy hostnames (if not NULL;
 118 default is the environment variable C<no_proxy> if set, else C<NO_PROXY>).
 119 Proxying plain HTTP is supported directly,
 120 while using a proxy for HTTPS connections requires a suitable callback function
 121 such as OSSL_HTTP_proxy_connect(), described below.
 122
 123 The I<maxline> parameter specifies the response header maximum line length,
 124 where a value <= 0 indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB
 125 should be used.
 126 This length is also used as the number of content bytes that are read at a time.
 127 The I<max_resp_len> parameter specifies the maximum response length,
 128 where 0 indicates B<HTTP_DEFAULT_MAX_RESP_LEN>, which currently is 100 KiB.
 129
 130 An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and
 131 OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer()
 132 this is only the case if the I<expect_asn1> parameter is nonzero.
 133 If the response header contains one or more "Content-Length" header lines and/or
 134 an ASN.1-encoded response is expected, which should include a total length,
 135 the length indications received are checked for consistency
 136 and for not exceeding the maximum response length.
 137
 138 If the parameter I<expected_ct>
 139 is not NULL then the HTTP client checks that the given content type string
 140 is included in the HTTP header of the response and returns an error if not.
 141
 142 If the I<timeout> parameter is > 0 this indicates the maximum number of seconds
 143 to wait until the transfer is complete.
 144 A value of 0 enables waiting indefinitely,
 145 while a value < 0 immediately leads to a timeout condition.
 146
 147 The optional parameter I<bio_update_fn> with its optional argument I<arg> may
 148 be used to modify the connection BIO used by the HTTP client (and cannot be
 149 used when both I<bio> and I<rbio> are given).
 150 I<bio_update_fn> is a BIO connect/disconnect callback function with prototype
 151
 152  BIO *(*OSSL_HTTP_bio_cb_t)(BIO *bio, void *arg, int connect, int detail)
 153
 154 The callback may modify the HTTP BIO provided in the I<bio> argument,
 155 whereby it may make use of a custom defined argument I<arg>,
 156 which may for instance refer to an I<SSL_CTX> structure.
 157 During connection establishment, just after calling BIO_do_connect_retry(),
 158 the function is invoked with the I<connect> argument being 1 and the I<detail>
 159 argument being 1 if HTTPS is requested, i.e., SSL/TLS should be enabled.
 160 On disconnect I<connect> is 0 and I<detail> is 1 if no error occurred, else 0.
 161 For instance, on connect the function may prepend a TLS BIO to implement HTTPS;
 162 after disconnect it may do some diagnostic output and/or specific cleanup.
 163 The function should return NULL to indicate failure.
 164 Here is a simple example that supports TLS connections (but not via a proxy):
 165
 166  BIO *http_tls_cb(BIO *hbio, void *arg, int connect, int detail)
 167  {
 168      SSL_CTX *ctx = (SSL_CTX *)arg;
 169
 170      if (connect && detail) { /* connecting with TLS */
 171          BIO *sbio = BIO_new_ssl(ctx, 1);
 172          hbio = sbio != NULL ? BIO_push(sbio, hbio) : NULL;
 173      } else if (!connect && !detail) { /* disconnecting after error */
 174          /* optionally add diagnostics here */
 175      }
 176      return hbio;
 177  }
 178
 179 After disconnect the modified BIO will be deallocated using BIO_free_all().
 180
 181 OSSL_HTTP_proxy_connect() may be used by an above BIO connect callback function
 182 to set up an SSL/TLS connection via an HTTPS proxy.
 183 It promotes the given BIO I<bio> representing a connection
 184 pre-established with a TLS proxy using the HTTP CONNECT method,
 185 optionally using proxy client credentials I<proxyuser> and I<proxypass>,
 186 to connect with TLS protection ultimately to I<server> and I<port>.
 187 If the I<port> argument is NULL or the empty string it defaults to "443".
 188 The I<timeout> parameter is used as described above.
 189 Since this function is typically called by applications such as
 190 L<openssl-s_client(1)> it uses the I<bio_err> and I<prog> parameters (unless
 191 NULL) to print additional diagnostic information in a user-oriented way.
 192
 193 =head1 NOTES
 194
 195 The names of the environment variables used by this implementation:
 196 C<http_proxy>, C<HTTP_PROXY>, C<https_proxy>, C<HTTPS_PROXY>, C<no_proxy>, and
 197 C<NO_PROXY>, have been chosen for maximal compatibility with
 198 other HTTP client implementations such as wget, curl, and git.
 199
 200 =head1 RETURN VALUES
 201
 202 On success, OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
 203 OSSL_HTTP_transfer() return a memory BIO containing the data received via HTTP.
 204 This must be freed by the caller. On failure, NULL is returned.
 205 Failure conditions include connection/transfer timeout, parse errors, etc.
 206
 207 OSSL_HTTP_proxy_connect() returns 1 on success, 0 on error.
 208
 209 =head1 SEE ALSO
 210
 211 L<OSSL_HTTP_parse_url(3)>
 212 L<BIO_set_conn_port(3)>
 213
 214 =head1 HISTORY
 215
 216 OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(),
 217 OSSL_HTTP_transfer(), and OSSL_HTTP_proxy_connect()
 218 were added in OpenSSL 3.0.
 219
 220 =head1 COPYRIGHT
 221
 222 Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
 223
 224 Licensed under the Apache License 2.0 (the "License").  You may not use
 225 this file except in compliance with the License.  You can obtain a copy
 226 in the file LICENSE in the source distribution or at
 227 L<https://www.openssl.org/source/license.html>.
 228
 229 =cut