| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | OSSL_HTTP_adapt_proxy,
|
|---|
| 6 | OSSL_parse_url,
|
|---|
| 7 | OSSL_HTTP_parse_url,
|
|---|
| 8 | OCSP_parse_url
|
|---|
| 9 | - http utility functions
|
|---|
| 10 |
|
|---|
| 11 | =head1 SYNOPSIS
|
|---|
| 12 |
|
|---|
| 13 | #include <openssl/http.h>
|
|---|
| 14 |
|
|---|
| 15 | const char *OSSL_HTTP_adapt_proxy(const char *proxy, const char *no_proxy,
|
|---|
| 16 | const char *server, int use_ssl);
|
|---|
| 17 |
|
|---|
| 18 | int OSSL_parse_url(const char *url, char **pscheme, char **puser, char **phost,
|
|---|
| 19 | char **pport, int *pport_num,
|
|---|
| 20 | char **ppath, char **pquery, char **pfrag);
|
|---|
| 21 | int OSSL_HTTP_parse_url(const char *url,
|
|---|
| 22 | int *pssl, char **puser, char **phost,
|
|---|
| 23 | char **pport, int *pport_num,
|
|---|
| 24 | char **ppath, char **pquery, char **pfrag);
|
|---|
| 25 |
|
|---|
| 26 | The following functions have been deprecated since OpenSSL 3.0, and can be
|
|---|
| 27 | hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable version value,
|
|---|
| 28 | see L<openssl_user_macros(7)>:
|
|---|
| 29 |
|
|---|
| 30 | int OCSP_parse_url(const char *url, char **phost, char **pport, char **ppath,
|
|---|
| 31 | int *pssl);
|
|---|
| 32 |
|
|---|
| 33 | =head1 DESCRIPTION
|
|---|
| 34 |
|
|---|
| 35 | OSSL_HTTP_adapt_proxy() takes an optional proxy hostname I<proxy>
|
|---|
| 36 | and returns it transformed according to the optional I<no_proxy> parameter,
|
|---|
| 37 | I<server>, I<use_ssl>, and the applicable environment variable, as follows.
|
|---|
| 38 | If I<proxy> is NULL, take any default value from the C<http_proxy>
|
|---|
| 39 | environment variable, or from C<https_proxy> if I<use_ssl> is nonzero.
|
|---|
| 40 | If this still does not yield a proxy hostname,
|
|---|
| 41 | take any further default value from the C<HTTP_PROXY>
|
|---|
| 42 | environment variable, or from C<HTTPS_PROXY> if I<use_ssl> is nonzero.
|
|---|
| 43 | If I<no_proxy> is NULL, take any default exclusion value from the C<no_proxy>
|
|---|
| 44 | environment variable, or else from C<NO_PROXY>.
|
|---|
| 45 | Return the determined proxy hostname unless the exclusion contains I<server>.
|
|---|
| 46 | Otherwise return NULL.
|
|---|
| 47 |
|
|---|
| 48 | OSSL_parse_url() parses its input string I<url> as a URL of the form
|
|---|
| 49 | C<[scheme://][userinfo@]host[:port][/path][?query][#fragment]> and splits it up
|
|---|
| 50 | into scheme, userinfo, host, port, path, query, and fragment components.
|
|---|
| 51 | The host (or server) component may be a DNS name or an IP address
|
|---|
| 52 | where IPv6 addresses should be enclosed in square brackets C<[> and C<]>.
|
|---|
| 53 | The port component is optional and defaults to C<0>.
|
|---|
| 54 | If given, it must be in decimal form. If the I<pport_num> argument is not NULL
|
|---|
| 55 | the integer value of the port number is assigned to I<*pport_num> on success.
|
|---|
| 56 | The path component is also optional and defaults to C</>.
|
|---|
| 57 | Each non-NULL result pointer argument I<pscheme>, I<puser>, I<phost>, I<pport>,
|
|---|
| 58 | I<ppath>, I<pquery>, and I<pfrag>, is assigned the respective url component.
|
|---|
| 59 | On success, they are guaranteed to contain non-NULL string pointers, else NULL.
|
|---|
| 60 | It is the reponsibility of the caller to free them using L<OPENSSL_free(3)>.
|
|---|
| 61 | If I<pquery> is NULL, any given query component is handled as part of the path.
|
|---|
| 62 | A string returned via I<*ppath> is guaranteed to begin with a C</> character.
|
|---|
| 63 | For absent scheme, userinfo, port, query, and fragment components
|
|---|
| 64 | an empty string is provided.
|
|---|
| 65 |
|
|---|
| 66 | OSSL_HTTP_parse_url() is a special form of OSSL_parse_url()
|
|---|
| 67 | where the scheme, if given, must be C<http> or C<https>.
|
|---|
| 68 | If I<pssl> is not NULL, I<*pssl> is assigned 1 in case parsing was successful
|
|---|
| 69 | and the scheme is C<https>, else 0.
|
|---|
| 70 | The port component is optional and defaults to C<443> if the scheme is C<https>,
|
|---|
| 71 | else C<80>.
|
|---|
| 72 | Note that relative paths must be given with a leading C</>,
|
|---|
| 73 | otherwise the first path element is interpreted as the hostname.
|
|---|
| 74 |
|
|---|
| 75 | Calling the deprecated function OCSP_parse_url(url, host, port, path, ssl)
|
|---|
| 76 | is equivalent to
|
|---|
| 77 | OSSL_HTTP_parse_url(url, ssl, NULL, host, port, NULL, path, NULL, NULL).
|
|---|
| 78 |
|
|---|
| 79 | =head1 RETURN VALUES
|
|---|
| 80 |
|
|---|
| 81 | OSSL_HTTP_adapt_proxy() returns NULL if no proxy is to be used,
|
|---|
| 82 | otherwise a constant proxy hostname string,
|
|---|
| 83 | which is either the proxy name handed in or an environment variable value.
|
|---|
| 84 |
|
|---|
| 85 | OSSL_parse_url(), OSSL_HTTP_parse_url(), and OCSP_parse_url()
|
|---|
| 86 | return 1 on success, 0 on error.
|
|---|
| 87 |
|
|---|
| 88 | =head1 SEE ALSO
|
|---|
| 89 |
|
|---|
| 90 | L<OSSL_HTTP_transfer(3)>
|
|---|
| 91 |
|
|---|
| 92 | =head1 HISTORY
|
|---|
| 93 |
|
|---|
| 94 | OSSL_HTTP_adapt_proxy(),
|
|---|
| 95 | OSSL_parse_url() and OSSL_HTTP_parse_url() were added in OpenSSL 3.0.
|
|---|
| 96 | OCSP_parse_url() was deprecated in OpenSSL 3.0.
|
|---|
| 97 |
|
|---|
| 98 | =head1 COPYRIGHT
|
|---|
| 99 |
|
|---|
| 100 | Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 101 |
|
|---|
| 102 | Licensed under the Apache License 2.0 (the "License"). You may not use
|
|---|
| 103 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 104 | in the file LICENSE in the source distribution or at
|
|---|
| 105 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 106 |
|
|---|
| 107 | =cut
|
|---|
