1autoproxy(n) HTTP protocol helper modules autoproxy(n)
2______________________________________________________________________________
6
8 autoproxy - Automatic HTTP proxy usage and authentication
9
11 package require Tcl 8.5
12 package require http ?2.0?
14 package require autoproxy ?1.7?
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 Note This section only applies if TLS support is provided by the TLS
55 package. It does not apply when autoproxy was configured to use some
56 other package which can provide the same (i.e twapi), via the
57 -tls_package configuration option.
58 This package uses the TLS package to handle the security for https urls
60 and other socket connections.
61 Policy decisions like the set of protocols to support and what ciphers
63 to use are not the responsibility of TLS, nor of this package itself
64 however. Such decisions are the responsibility of whichever applica‐
65 tion is using the package, and are likely influenced by the set of
66 servers the application will talk to as well.
67 For example, in light of the recent POODLE attack [http://googleonli‐
69 nesecurity.blogspot.co.uk/2014/10/this-poodle-bites-exploiting-
70 ssl-30.html] discovered by Google many servers will disable support for
71 the SSLv3 protocol. To handle this change the applications using TLS
72 must be patched, and not this package, nor TLS itself. Such a patch
73 may be as simple as generally activating tls1 support, as shown in the
74 example below.
75 package require tls
78 tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
79 ... your own application code ...
81
84 ::autoproxy::init
85 Initialize the autoproxy package from system resources. Under
86 unix this means we look for environment variables. Under windows
87 we look for the same environment variables but also look at the
88 registry settings used by Internet Explorer.
89 ::autoproxy::cget -option
91 Retrieve individual package configuration options. See OPTIONS.
92 ::autoproxy::configure ?-option value?
94 Configure the autoproxy package. Calling configure with no op‐
95 tions will return a list of all option names and values. See
96 OPTIONS.
97 ::autoproxy::tls_connect args
99 Connect to a secure socket through a proxy. HTTP proxy servers
100 permit the use of the CONNECT HTTP command to open a link
101 through the proxy to the target machine. This function hides the
102 details. For use with the http package see tls_socket.
103 The args list may contain any of the options supported by the
105 specific TLS package that is in use but must end with the host
106 and port as the last two items.
107 ::autoproxy::tunnel_connect args
109 Connect to a target host throught a proxy. This uses the same
110 CONNECT HTTP command as the tls_connect but does not promote the
111 link security once the connection is established.
112 The args list may contain any of the options supported by the
114 specific TLS package that is in use but must end with the host
115 and port as the last two items.
116 Note that many proxy servers will permit CONNECT calls to a lim‐
118 ited set of ports - typically only port 443 (the secure HTTP
119 port).
120 ::autoproxy::tls_socket args
122 This function is to be used to register a proxy-aware secure
123 socket handler for the https protocol. It may only be used with
124 the Tcl http package and should be registered using the
125 http::register command (see the examples below). The job of ac‐
126 tually creating the tunnelled connection is done by the tls_con‐
127 nect command and this may be used when not registering with the
128 http package.
129
131 -host hostname
132 -proxy_host hostname
134 Set the proxy hostname. This is normally set up by init but may
135 be configured here as well.
136 -port number
138 -proxy_port number
140 Set the proxy port number. This is normally set up by init.
141 e.g. configure -port 3128
142 -no_proxy list
144 You may manipulate the no_proxy list that was setup by init. The
145 value of this option is a tcl list of strings that are matched
146 against the http request host using the tcl string match com‐
147 mand. Therefore glob patterns are permitted. For instance, con‐
148 figure -no_proxy *.localdomain
149 -authProc procedure
151 This option may be used to set an application defined procedure
152 to be called when configure -basic is called with either no or
153 insufficient authentication details. This can be used to present
154 a dialog to the user to request the additional information.
155 -basic Following options are for configuring the Basic authentication
157 scheme parameters. See Basic Authentication. To unset the proxy
158 authentication information retained from a previous call of this
159 function either "--" or no additional parameters can be sup‐
160 plied. This will remove the existing authentication information.
161 -tls_package packagename
163 This option may be used to configure the Tcl package to use for
164 TLS support. Valid package names are tls (default) and twapi.
165
167 Basic is the simplest and most commonly use HTTP proxy authentication
168 scheme. It is described in (1 section 11) and also in (2). It offers no
169 privacy whatsoever and its use should be discouraged in favour of more
170 secure alternatives like Digest. To perform Basic authentication the
171 client base64 encodes the username and plaintext password separated by
172 a colon. This encoded text is prefixed with the word "Basic" and a
173 space.
174 The following options exists for this scheme:
176 -username name
178 The username required to authenticate with the configured proxy.
179 -password password
181 The password required for the username specified.
182 -realm realm
184 This option is not used by this package but may be used in re‐
185 questing authentication details from the user.
186 -- The end-of-options indicator may be used alone to unset any au‐
188 thentication details currently enabled.
189
191 package require autoproxy
192 autoproxy::init
193 autoproxy::configure -basic -username ME -password SEKRET
194 set tok [http::geturl http://wiki.tcl.tk/]
195 http::data $tok
196 package require http
200 package require tls
201 package require autoproxy
202 autoproxy::init
203 http::register https 443 autoproxy::tls_socket
204 set tok [http::geturl https://www.example.com/]
205
208 [1] Berners-Lee, T., Fielding R. and Frystyk, H. "Hypertext Trans‐
209 fer Protocol -- HTTP/1.0", RFC 1945, May 1996, (http://www.rfc-
210 editor.org/rfc/rfc1945.txt)
211 [2] Franks, J. et al. "HTTP Authentication: Basic and Digest Access
213 Authentication", RFC 2617, June 1999 (http://www.rfc-edi‐
214 tor.org/rfc/rfc2617.txt)
215
217 At this time only Basic authentication (1) (2) is supported. It is
218 planned to add support for Digest (2) and NTLM in the future.
219
221 Pat Thoyts
222
224 This document, and the package it describes, will undoubtedly contain
225 bugs and other problems. Please report such in the category http ::
226 autoproxy of the Tcllib Trackers [http://core.tcl.tk/tcllib/re‐
227 portlist]. Please also report any ideas for enhancements you may have
228 for either package and/or documentation.
229 When proposing code changes, please provide unified diffs, i.e the out‐
231 put of diff -u.
232 Note further that attachments are strongly preferred over inlined
234 patches. Attachments can be made by going to the Edit form of the
235 ticket immediately after its creation, and then using the left-most
236 button in the secondary navigation bar.
237
239 http(n)
240
242 authentication, http, proxy
243
245 Networking
246tcllib 1.7 autoproxy(n)