]>
Commit | Line | Data |
---|---|---|
7932982b DDO |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
ab9d67ef | 5 | OSSL_HTTP_adapt_proxy, |
d546e8e2 | 6 | OSSL_parse_url, |
7932982b DDO |
7 | OSSL_HTTP_parse_url, |
8 | OCSP_parse_url | |
9 | - http utility functions | |
10 | ||
11 | =head1 SYNOPSIS | |
12 | ||
13 | #include <openssl/http.h> | |
14 | ||
ab9d67ef DDO |
15 | const char *OSSL_HTTP_adapt_proxy(const char *proxy, const char *no_proxy, |
16 | const char *server, int use_ssl); | |
17 | ||
d546e8e2 DDO |
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); | |
7932982b DDO |
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 | ||
3dbf8243 MC |
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)>: | |
7932982b DDO |
29 | |
30 | int OCSP_parse_url(const char *url, char **phost, char **pport, char **ppath, | |
31 | int *pssl); | |
32 | ||
33 | =head1 DESCRIPTION | |
34 | ||
ab9d67ef DDO |
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 | ||
d546e8e2 DDO |
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. | |
22fe2b12 | 51 | The host (or server) component may be a DNS name or an IP address |
7932982b | 52 | where IPv6 addresses should be enclosed in square brackets C<[> and C<]>. |
d546e8e2 | 53 | The port component is optional and defaults to C<0>. |
7932982b DDO |
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</>. | |
d546e8e2 DDO |
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. | |
7932982b | 59 | On success, they are guaranteed to contain non-NULL string pointers, else NULL. |
e304aa87 | 60 | It is the responsibility of the caller to free them using L<OPENSSL_free(3)>. |
7932982b DDO |
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. | |
d546e8e2 DDO |
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>. | |
22fe2b12 DDO |
72 | Note that relative paths must be given with a leading C</>, |
73 | otherwise the first path element is interpreted as the hostname. | |
7932982b | 74 | |
d546e8e2 DDO |
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). | |
7932982b DDO |
78 | |
79 | =head1 RETURN VALUES | |
80 | ||
ab9d67ef DDO |
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 | ||
22fe2b12 | 85 | OSSL_parse_url(), OSSL_HTTP_parse_url(), and OCSP_parse_url() |
7932982b DDO |
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 | ||
ab9d67ef | 94 | OSSL_HTTP_adapt_proxy(), |
22fe2b12 | 95 | OSSL_parse_url() and OSSL_HTTP_parse_url() were added in OpenSSL 3.0. |
7932982b DDO |
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 |