202 lines
8.8 KiB
Plaintext
202 lines
8.8 KiB
Plaintext
SocksiPy version 1.00
|
|
A Python SOCKS module.
|
|
(C) 2006 Dan-Haim. All rights reserved.
|
|
See LICENSE file for details.
|
|
|
|
|
|
WHAT IS A SOCKS PROXY?
|
|
A SOCKS proxy is a proxy server at the TCP level. In other words, it acts as
|
|
a tunnel, relaying all traffic going through it without modifying it.
|
|
SOCKS proxies can be used to relay traffic using any network protocol that
|
|
uses TCP.
|
|
|
|
WHAT IS SOCKSIPY?
|
|
This Python module allows you to create TCP connections through a SOCKS
|
|
proxy without any special effort.
|
|
|
|
PROXY COMPATIBILITY
|
|
SocksiPy is compatible with three different types of proxies:
|
|
1. SOCKS Version 4 (Socks4), including the Socks4a extension.
|
|
2. SOCKS Version 5 (Socks5).
|
|
3. HTTP Proxies which support tunneling using the CONNECT method.
|
|
|
|
SYSTEM REQUIREMENTS
|
|
Being written in Python, SocksiPy can run on any platform that has a Python
|
|
interpreter and TCP/IP support.
|
|
This module has been tested with Python 2.3 and should work with greater versions
|
|
just as well.
|
|
|
|
|
|
INSTALLATION
|
|
-------------
|
|
|
|
Simply copy the file "socks.py" to your Python's lib/site-packages directory,
|
|
and you're ready to go.
|
|
|
|
|
|
USAGE
|
|
------
|
|
|
|
First load the socks module with the command:
|
|
|
|
>>> import socks
|
|
>>>
|
|
|
|
The socks module provides a class called "socksocket", which is the base to
|
|
all of the module's functionality.
|
|
The socksocket object has the same initialization parameters as the normal socket
|
|
object to ensure maximal compatibility, however it should be noted that socksocket
|
|
will only function with family being AF_INET and type being SOCK_STREAM.
|
|
Generally, it is best to initialize the socksocket object with no parameters
|
|
|
|
>>> s = socks.socksocket()
|
|
>>>
|
|
|
|
The socksocket object has an interface which is very similiar to socket's (in fact
|
|
the socksocket class is derived from socket) with a few extra methods.
|
|
To select the proxy server you would like to use, use the setproxy method, whose
|
|
syntax is:
|
|
|
|
setproxy(proxytype, addr[, port[, rdns[, username[, password]]]])
|
|
|
|
Explaination of the parameters:
|
|
|
|
proxytype - The type of the proxy server. This can be one of three possible
|
|
choices: PROXY_TYPE_SOCKS4, PROXY_TYPE_SOCKS5 and PROXY_TYPE_HTTP for Socks4,
|
|
Socks5 and HTTP servers respectively.
|
|
|
|
addr - The IP address or DNS name of the proxy server.
|
|
|
|
port - The port of the proxy server. Defaults to 1080 for socks and 8080 for http.
|
|
|
|
rdns - This is a boolean flag than modifies the behavior regarding DNS resolving.
|
|
If it is set to True, DNS resolving will be preformed remotely, on the server.
|
|
If it is set to False, DNS resolving will be preformed locally. Please note that
|
|
setting this to True with Socks4 servers actually use an extension to the protocol,
|
|
called Socks4a, which may not be supported on all servers (Socks5 and http servers
|
|
always support DNS). The default is True.
|
|
|
|
username - For Socks5 servers, this allows simple username / password authentication
|
|
with the server. For Socks4 servers, this parameter will be sent as the userid.
|
|
This parameter is ignored if an HTTP server is being used. If it is not provided,
|
|
authentication will not be used (servers may accept unauthentication requests).
|
|
|
|
password - This parameter is valid only for Socks5 servers and specifies the
|
|
respective password for the username provided.
|
|
|
|
Example of usage:
|
|
|
|
>>> s.setproxy(socks.PROXY_TYPE_SOCKS5,"socks.example.com")
|
|
>>>
|
|
|
|
After the setproxy method has been called, simply call the connect method with the
|
|
traditional parameters to establish a connection through the proxy:
|
|
|
|
>>> s.connect(("www.sourceforge.net",80))
|
|
>>>
|
|
|
|
Connection will take a bit longer to allow negotiation with the proxy server.
|
|
Please note that calling connect without calling setproxy earlier will connect
|
|
without a proxy (just like a regular socket).
|
|
|
|
Errors: Any errors in the connection process will trigger exceptions. The exception
|
|
may either be generated by the underlying socket layer or may be custom module
|
|
exceptions, whose details follow:
|
|
|
|
class ProxyError - This is a base exception class. It is not raised directly but
|
|
rather all other exception classes raised by this module are derived from it.
|
|
This allows an easy way to catch all proxy-related errors.
|
|
|
|
class GeneralProxyError - When thrown, it indicates a problem which does not fall
|
|
into another category. The parameter is a tuple containing an error code and a
|
|
description of the error, from the following list:
|
|
1 - invalid data - This error means that unexpected data has been received from
|
|
the server. The most common reason is that the server specified as the proxy is
|
|
not really a Socks4/Socks5/HTTP proxy, or maybe the proxy type specified is wrong.
|
|
4 - bad proxy type - This will be raised if the type of the proxy supplied to the
|
|
setproxy function was not PROXY_TYPE_SOCKS4/PROXY_TYPE_SOCKS5/PROXY_TYPE_HTTP.
|
|
5 - bad input - This will be raised if the connect method is called with bad input
|
|
parameters.
|
|
|
|
class Socks5AuthError - This indicates that the connection through a Socks5 server
|
|
failed due to an authentication problem. The parameter is a tuple containing a
|
|
code and a description message according to the following list:
|
|
|
|
1 - authentication is required - This will happen if you use a Socks5 server which
|
|
requires authentication without providing a username / password at all.
|
|
2 - all offered authentication methods were rejected - This will happen if the proxy
|
|
requires a special authentication method which is not supported by this module.
|
|
3 - unknown username or invalid password - Self descriptive.
|
|
|
|
class Socks5Error - This will be raised for Socks5 errors which are not related to
|
|
authentication. The parameter is a tuple containing a code and a description of the
|
|
error, as given by the server. The possible errors, according to the RFC are:
|
|
|
|
1 - General SOCKS server failure - If for any reason the proxy server is unable to
|
|
fulfill your request (internal server error).
|
|
2 - connection not allowed by ruleset - If the address you're trying to connect to
|
|
is blacklisted on the server or requires authentication.
|
|
3 - Network unreachable - The target could not be contacted. A router on the network
|
|
had replied with a destination net unreachable error.
|
|
4 - Host unreachable - The target could not be contacted. A router on the network
|
|
had replied with a destination host unreachable error.
|
|
5 - Connection refused - The target server has actively refused the connection
|
|
(the requested port is closed).
|
|
6 - TTL expired - The TTL value of the SYN packet from the proxy to the target server
|
|
has expired. This usually means that there are network problems causing the packet
|
|
to be caught in a router-to-router "ping-pong".
|
|
7 - Command not supported - The client has issued an invalid command. When using this
|
|
module, this error should not occur.
|
|
8 - Address type not supported - The client has provided an invalid address type.
|
|
When using this module, this error should not occur.
|
|
|
|
class Socks4Error - This will be raised for Socks4 errors. The parameter is a tuple
|
|
containing a code and a description of the error, as given by the server. The
|
|
possible error, according to the specification are:
|
|
|
|
1 - Request rejected or failed - Will be raised in the event of an failure for any
|
|
reason other then the two mentioned next.
|
|
2 - request rejected because SOCKS server cannot connect to identd on the client -
|
|
The Socks server had tried an ident lookup on your computer and has failed. In this
|
|
case you should run an identd server and/or configure your firewall to allow incoming
|
|
connections to local port 113 from the remote server.
|
|
3 - request rejected because the client program and identd report different user-ids -
|
|
The Socks server had performed an ident lookup on your computer and has received a
|
|
different userid than the one you have provided. Change your userid (through the
|
|
username parameter of the setproxy method) to match and try again.
|
|
|
|
class HTTPError - This will be raised for HTTP errors. The parameter is a tuple
|
|
containing the HTTP status code and the description of the server.
|
|
|
|
|
|
After establishing the connection, the object behaves like a standard socket.
|
|
Call the close method to close the connection.
|
|
|
|
In addition to the socksocket class, an additional function worth mentioning is the
|
|
setdefaultproxy function. The parameters are the same as the setproxy method.
|
|
This function will set default proxy settings for newly created socksocket objects,
|
|
in which the proxy settings haven't been changed via the setproxy method.
|
|
This is quite useful if you wish to force 3rd party modules to use a socks proxy,
|
|
by overriding the socket object.
|
|
For example:
|
|
|
|
>>> socks.setdefaultproxy(socks.PROXY_TYPE_SOCKS5,"socks.example.com")
|
|
>>> socket.socket = socks.socksocket
|
|
>>> urllib.urlopen("http://www.sourceforge.net/")
|
|
|
|
|
|
PROBLEMS
|
|
---------
|
|
|
|
If you have any problems using this module, please first refer to the BUGS file
|
|
(containing current bugs and issues). If your problem is not mentioned you may
|
|
contact the author at the following E-Mail address:
|
|
|
|
negativeiq@users.sourceforge.net
|
|
|
|
Please allow some time for your question to be received and handled.
|
|
|
|
|
|
Dan-Haim,
|
|
Author.
|