1autoproxy(n) HTTP protocol helper modules autoproxy(n)
2______________________________________________________________________________
6
8 autoproxy - Automatic HTTP proxy usage and authentication
9
11 package require Tcl 8.2
12 package require http ?2.0?
14 package require autoproxy ?1.6?
16 ::autoproxy::init
18 ::autoproxy::cget -option
20 ::autoproxy::configure ?-option value?
22 ::autoproxy::tls_connect args
24 ::autoproxy::tunnel_connect args
26 ::autoproxy::tls_socket args
28______________________________________________________________________________
30
32 This package attempts to automate the use of HTTP proxy servers in Tcl
33 HTTP client code. It tries to initialize the web access settings from
34 system standard locations and can be configured to negotiate authenti‐
35 cation with the proxy if required.
36 On Unix the standard for identifying the local HTTP proxy server seems
38 to be to use the environment variable http_proxy or ftp_proxy and
39 no_proxy to list those domains to be excluded from proxying. On Win‐
40 dows we can retrieve the Internet Settings values from the registry to
41 obtain pretty much the same information. With this information we can
42 setup a suitable filter procedure for the Tcl http package and arrange
43 for automatic use of the proxy.
44 There seem to be a number of ways that the http_proxy environment vari‐
46 able may be set up. Either a plain host:port or more commonly a URL and
47 sometimes the URL may contain authentication parameters or these may be
48 requested from the user or provided via http_proxy_user and
49 http_proxy_pass. This package attempts to deal with all these schemes.
50 It will do it's best to get the required parameters from the environ‐
51 ment or registry and if it fails can be reconfigured.
52
54 This package uses the TLS package to handle the security for https urls
55 and other socket connections.
56 Policy decisions like the set of protocols to support and what ciphers
58 to use are not the responsibility of TLS, nor of this package itself
59 however. Such decisions are the responsibility of whichever applica‐
60 tion is using the package, and are likely influenced by the set of
61 servers the application will talk to as well.
62 For example, in light of the recent POODLE attack [http://googleonli‐
64 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
65 ssl-30.html] discovered by Google many servers will disable support for
66 the SSLv3 protocol. To handle this change the applications using TLS
67 must be patched, and not this package, nor TLS itself. Such a patch
68 may be as simple as generally activating tls1 support, as shown in the
69 example below.
70 package require tls
73 tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
74 ... your own application code ...
76
79 ::autoproxy::init
80 Initialize the autoproxy package from system resources. Under
81 unix this means we look for environment variables. Under windows
82 we look for the same environment variables but also look at the
83 registry settings used by Internet Explorer.
84 ::autoproxy::cget -option
86 Retrieve individual package configuration options. See OPTIONS.
87 ::autoproxy::configure ?-option value?
89 Configure the autoproxy package. Calling configure with no
90 options will return a list of all option names and values. See
91 OPTIONS.
92 ::autoproxy::tls_connect args
94 Connect to a secure socket through a proxy. HTTP proxy servers
95 permit the use of the CONNECT HTTP command to open a link
96 through the proxy to the target machine. This function hides the
97 details. For use with the http package see tls_socket.
98 The args list may contain any of the tls package options but
100 must end with the host and port as the last two items.
101 ::autoproxy::tunnel_connect args
103 Connect to a target host throught a proxy. This uses the same
104 CONNECT HTTP command as the tls_connect but does not promote the
105 link security once the connection is established.
106 The args list may contain any of the tls package options but
108 must end with the host and port as the last two items.
109 Note that many proxy servers will permit CONNECT calls to a lim‐
111 ited set of ports - typically only port 443 (the secure HTTP
112 port).
113 ::autoproxy::tls_socket args
115 This function is to be used to register a proxy-aware secure
116 socket handler for the https protocol. It may only be used with
117 the Tcl http package and should be registered using the
118 http::register command (see the examples below). The job of
119 actually creating the tunnelled connection is done by the
120 tls_connect command and this may be used when not registering
121 with the http package.
122
124 -host hostname
125 -proxy_host hostname
127 Set the proxy hostname. This is normally set up by init but may
128 be configured here as well.
129 -port number
131 -proxy_port number
133 Set the proxy port number. This is normally set up by init.
134 e.g. configure -port 3128
135 -no_proxy list
137 You may manipulate the no_proxy list that was setup by init. The
138 value of this option is a tcl list of strings that are matched
139 against the http request host using the tcl string match com‐
140 mand. Therefore glob patterns are permitted. For instance, con‐
141 figure -no_proxy *.localdomain
142 -authProc procedure
144 This option may be used to set an application defined procedure
145 to be called when configure -basic is called with either no or
146 insufficient authentication details. This can be used to present
147 a dialog to the user to request the additional information.
148 -basic Following options are for configuring the Basic authentication
150 scheme parameters. See Basic Authentication. To unset the proxy
151 authentication information retained from a previous call of this
152 function either "--" or no additional parameters can be sup‐
153 plied. This will remove the existing authentication information.
154
156 Basic is the simplest and most commonly use HTTP proxy authentication
157 scheme. It is described in (1 section 11) and also in (2). It offers no
158 privacy whatsoever and its use should be discouraged in favour of more
159 secure alternatives like Digest. To perform Basic authentication the
160 client base64 encodes the username and plaintext password separated by
161 a colon. This encoded text is prefixed with the word "Basic" and a
162 space.
163 The following options exists for this scheme:
165 -username name
167 The username required to authenticate with the configured proxy.
168 -password password
170 The password required for the username specified.
171 -realm realm
173 This option is not used by this package but may be used in
174 requesting authentication details from the user.
175 -- The end-of-options indicator may be used alone to unset any
177 authentication details currently enabled.
178
180 package require autoproxy
181 autoproxy::init
182 autoproxy::configure -basic -username ME -password SEKRET
183 set tok [http::geturl http://wiki.tcl.tk/]
184 http::data $tok
185 package require http
189 package require tls
190 package require autoproxy
191 autoproxy::init
192 http::register https 443 autoproxy::tls_socket
193 set tok [http::geturl https://www.example.com/]
194
197 [1] Berners-Lee, T., Fielding R. and Frystyk, H. "Hypertext Trans‐
198 fer Protocol -- HTTP/1.0", RFC 1945, May 1996, (http://www.rfc-
199 editor.org/rfc/rfc1945.txt)
200 [2] Franks, J. et al. "HTTP Authentication: Basic and Digest Access
202 Authentication", RFC 2617, June 1999 (http://www.rfc-edi‐
203 tor.org/rfc/rfc2617.txt)
204
206 At this time only Basic authentication (1) (2) is supported. It is
207 planned to add support for Digest (2) and NTLM in the future.
208
210 Pat Thoyts
211
213 This document, and the package it describes, will undoubtedly contain
214 bugs and other problems. Please report such in the category http ::
215 autoproxy of the Tcllib Trackers
216 [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas
217 for enhancements you may have for either package and/or documentation.
218 When proposing code changes, please provide unified diffs, i.e the out‐
220 put of diff -u.
221 Note further that attachments are strongly preferred over inlined
223 patches. Attachments can be made by going to the Edit form of the
224 ticket immediately after its creation, and then using the left-most
225 button in the secondary navigation bar.
226
228 http(n)
229
231 authentication, http, proxy
232
234 Networking
235tcllib 1.6 autoproxy(n)