This package attempts to automate the use of HTTP proxy servers
in Tcl HTTP client code. It tries to initialize the web access
settings from system standard locations and can be configured to
negotiate authentication with the proxy if required.

On Unix the standard for identifying the local HTTP proxy server
seems to be to use the environment variable http_proxy or ftp_proxy
and no_proxy to list those domains to be excluded from proxying. On
Windows we can retrieve the Internet Settings values from the
registry to obtain pretty much the same information. With this
information we can setup a suitable filter procedure for the Tcl
http package and arrange for automatic use of the proxy.

There seem to be a number of ways that the http_proxy
environment variable may be set up. Either a plain host:port or
more commonly a URL and sometimes the URL may contain
authentication parameters or these may be requested from the user
or provided via http_proxy_user and http_proxy_pass. This package
attempts to deal with all these schemes. It will do it's best to
get the required parameters from the environment or registry and if
it fails can be reconfigured.

This package uses the TLS package to handle the security
for https urls and other socket
connections.

Policy decisions like the set of protocols to support and what
ciphers to use are not the responsibility of TLS, nor of this package itself
however. Such decisions are the responsibility of whichever
application is using the package, and are likely influenced by the
set of servers the application will talk to as well.

For example, in light of the recent
POODLE attack discovered by Google many servers will disable
support for the SSLv3 protocol. To handle this change the
applications using TLS must be patched, and not this
package, nor TLS itself. Such a patch may be as
simple as generally activating tls1 support,
as shown in the example below.

Initialize the autoproxy package from system resources. Under
unix this means we look for environment variables. Under windows we
look for the same environment variables but also look at the
registry settings used by Internet Explorer.

Connect to a secure socket through a proxy. HTTP proxy servers
permit the use of the CONNECT HTTP command to open a link through
the proxy to the target machine. This function hides the details.
For use with the http package see tls_socket.

The args list may contain any of the tls package
options but must end with the host and port as the last two
items.

This function is to be used to register a proxy-aware secure
socket handler for the https protocol. It may only be used with the
Tcl http package and should be registered using the http::register
command (see the examples below). The job of actually creating the
tunnelled connection is done by the tls_connect command and this
may be used when not registering with the http package.

Set the proxy hostname. This is normally set up by init but may be configured here as well.

-port number

-proxy_port number

Set the proxy port number. This is normally set up by init. e.g. configure-port3128

-no_proxy list

You may manipulate the no_proxy list that
was setup by init. The value of this option is a
tcl list of strings that are matched against the http request host
using the tcl string match command. Therefore
glob patterns are permitted. For instance, configure-no_proxy*.localdomain

-authProc procedure

This option may be used to set an application defined procedure
to be called when configure-basic is called with either no or insufficient
authentication details. This can be used to present a dialog to the
user to request the additional information.

-basic

Following options are for configuring the Basic authentication
scheme parameters. See Basic Authentication.

Basic is the simplest and most commonly use HTTP proxy
authentication scheme. It is described in (1 section 11) and also
in (2). It offers no privacy whatsoever and its use should be
discouraged in favour of more secure alternatives like Digest. To
perform Basic authentication the client base64 encodes the username
and plaintext password separated by a colon. This encoded text is
prefixed with the word "Basic" and a space.

This document, and the package it describes, will undoubtedly
contain bugs and other problems. Please report such in the category
http :: autoproxy of the Tcllib Trackers. Please
also report any ideas for enhancements you may have for either
package and/or documentation.