1autoproxy(n)             HTTP protocol helper modules             autoproxy(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       autoproxy - Automatic HTTP proxy usage and authentication
9

SYNOPSIS

11       package require Tcl  8.5
12
13       package require http  ?2.0?
14
15       package require autoproxy  ?1.7?
16
17       ::autoproxy::init
18
19       ::autoproxy::cget -option
20
21       ::autoproxy::configure ?-option value?
22
23       ::autoproxy::tls_connect args
24
25       ::autoproxy::tunnel_connect args
26
27       ::autoproxy::tls_socket args
28
29______________________________________________________________________________
30

DESCRIPTION

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
37       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
45       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

TLS SECURITY CONSIDERATIONS

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
59       This package uses the TLS package to handle the security for https urls
60       and other socket connections.
61
62       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
68       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
76
77                  package require tls
78                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
79
80                  ... your own application code ...
81
82

COMMANDS

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
90       ::autoproxy::cget -option
91              Retrieve individual package configuration options. See OPTIONS.
92
93       ::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
98       ::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
104              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
108       ::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
113              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
117              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
121       ::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

OPTIONS

131       -host hostname
132
133       -proxy_host hostname
134              Set the proxy hostname. This is normally set up by init but  may
135              be configured here as well.
136
137       -port number
138
139       -proxy_port number
140              Set  the  proxy  port  number.  This is normally set up by init.
141              e.g. configure -port 3128
142
143       -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
150       -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
156       -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
162       -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

BASIC AUTHENTICATION

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
175       The following options exists for this scheme:
176
177       -username name
178              The username required to authenticate with the configured proxy.
179
180       -password password
181              The password required for the username specified.
182
183       -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
187       --     The  end-of-options indicator may be used alone to unset any au‐
188              thentication details currently enabled.
189

EXAMPLES

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
197
198
199              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
206

REFERENCES

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
212       [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

BUGS

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

AUTHORS

221       Pat Thoyts
222

BUGS, IDEAS, FEEDBACK

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
230       When proposing code changes, please provide unified diffs, i.e the out‐
231       put of diff -u.
232
233       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

SEE ALSO

239       http(n)
240

KEYWORDS

242       authentication, http, proxy
243

CATEGORY

245       Networking
246
247
248
249tcllib                                1.7                         autoproxy(n)
Impressum