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.2
12
13       package require http  ?2.0?
14
15       package require autoproxy  ?1.6?
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       This package uses the TLS package to handle the security for https urls
55       and other socket connections.
56
57       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
63       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
71
72                  package require tls
73                  tls::init -tls1 1 ;# forcibly activate support for the TLS1 protocol
74
75                  ... your own application code ...
76
77

COMMANDS

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
85       ::autoproxy::cget -option
86              Retrieve individual package configuration options. See OPTIONS.
87
88       ::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
93       ::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
99              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
102       ::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
107              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
110              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
114       ::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

OPTIONS

124       -host hostname
125
126       -proxy_host hostname
127              Set  the proxy hostname. This is normally set up by init but may
128              be configured here as well.
129
130       -port number
131
132       -proxy_port number
133              Set the proxy port number. This is  normally  set  up  by  init.
134              e.g. configure -port 3128
135
136       -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
143       -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
149       -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

BASIC AUTHENTICATION

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
164       The following options exists for this scheme:
165
166       -username name
167              The username required to authenticate with the configured proxy.
168
169       -password password
170              The password required for the username specified.
171
172       -realm realm
173              This option is not used by this  package  but  may  be  used  in
174              requesting authentication details from the user.
175
176       --     The  end-of-options  indicator  may  be  used alone to unset any
177              authentication details currently enabled.
178

EXAMPLES

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
186
187
188              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
195

REFERENCES

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

BUGS

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

AUTHORS

210       Pat Thoyts
211

BUGS, IDEAS, FEEDBACK

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
219       When proposing code changes, please provide unified diffs, i.e the out‐
220       put of diff -u.
221
222       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

SEE ALSO

228       http(n)
229

KEYWORDS

231       authentication, http, proxy
232

CATEGORY

234       Networking
235
236
237
238tcllib                                1.6                         autoproxy(n)
Impressum