1IO::Socket::Socks(3)  User Contributed Perl Documentation IO::Socket::Socks(3)
2
3
4

NAME

6       IO::Socket::Socks - Provides a way to create socks client or server
7       both 4 and 5 version.
8

SYNOPSIS

10   Client
11         use IO::Socket::Socks;
12
13         my $socks_client = IO::Socket::Socks->new(
14           ProxyAddr   => "proxy host",
15           ProxyPort   => "proxy port",
16           ConnectAddr => "remote host",
17           ConnectPort => "remote port",
18         ) or die $SOCKS_ERROR;
19
20         print $socks_client "foo\n";
21         $socks_client->close();
22
23   Server
24         use IO::Socket::Socks ':constants';
25
26         my $socks_server = IO::Socket::Socks->new(
27           ProxyAddr   => "localhost",
28           ProxyPort   => 8000,
29           Listen      => 1,
30           UserAuth    => \&auth,
31           RequireAuth => 1
32         ) or die $SOCKS_ERROR;
33
34         while(1) {
35           my $client = $socks_server->accept();
36
37           unless ($client) {
38             print "ERROR: $SOCKS_ERROR\n";
39             next;
40           }
41
42           my $command = $client->command();
43           if ($command->[0] == CMD_CONNECT) {
44              # Handle the CONNECT
45              $client->command_reply(REPLY_SUCCESS, addr, port);
46           }
47
48           ...
49           #read from the client and send to the CONNECT address
50           ...
51
52           $client->close();
53         }
54
55         sub auth {
56           my ($user, $pass) = @_;
57
58           return 1 if $user eq "foo" && $pass eq "bar";
59           return 0;
60         }
61

DESCRIPTION

63       "IO::Socket::Socks" connects to a SOCKS proxy, tells it to open a
64       connection to a remote host/port when the object is created.  The
65       object you receive can be used directly as a socket (with "IO::Socket"
66       interface) for sending and receiving data from the remote host. In
67       addition to create socks client this module could be used to create
68       socks server. See examples below.
69

EXAMPLES

71       For complete examples of socks 4/5 client and server see `examples'
72       subdirectory in the distribution.
73

METHODS

75   Socks Client
76       new( %cfg )
77
78       new_from_socket($socket, %cfg)
79
80       new_from_fd($socket, %cfg)
81
82       Creates a new IO::Socket::Socks client object.  new_from_socket() is
83       the same as new(), but allows one to create object from an existing and
84       not connected socket (new_from_fd is new_from_socket alias). To make
85       IO::Socket::Socks object from connected socket see "start_SOCKS"
86
87       Both takes the following config hash:
88
89         SocksVersion => 4 or 5. Default is 5
90
91         Timeout => connect/accept timeout
92
93         Blocking => Since IO::Socket::Socks version 0.5 you can perform non-blocking connect/bind by
94                     passing false value for this option. Default is true - blocking. See ready()
95                     below for more details.
96
97         SocksResolve => resolve host name to ip by proxy server or
98                         not (will resolve by client). This
99                         overrides value of $SOCKS4_RESOLVE or $SOCKS5_RESOLVE
100                         variable. Boolean.
101
102         SocksDebug => This will cause all of the SOCKS traffic to
103                       be presented on the command line in a form
104                       similar to the tables in the RFCs. This overrides value
105                       of $SOCKS_DEBUG variable. Boolean.
106
107         ProxyAddr => Hostname of the proxy
108
109         ProxyPort => Port of the proxy
110
111         ConnectAddr => Hostname of the remote machine
112
113         ConnectPort => Port of the remote machine
114
115         BindAddr => Hostname of the remote machine which will
116                     connect to the proxy server after bind request
117
118         BindPort => Port of the remote machine which will
119                     connect to the proxy server after bind request
120
121         UdpAddr => Expected address where datagrams will be sent. Fill it with address
122                    of all zeros if address is not known at this moment.
123                    Proxy server may use this information to limit access to the association.
124
125         UdpPort => Expected port where datagrams will be sent. Use zero port
126                    if port is not known at this moment. Proxy server may use this
127                    information to limit access to the association.
128
129         AuthType => What kind of authentication to support:
130                     none       - no authentication (default)
131                     userpass  - Username/Password. For socks5
132                     proxy only.
133
134         RequireAuth => Do not send ANON as a valid auth mechanism.
135                        For socks5 proxy only
136
137         Username => For socks5 if AuthType is set to userpass, then
138                     you must provide a username. For socks4 proxy with
139                     this option you can specify userid.
140
141         Password => If AuthType is set to userpass, then you must
142                     provide a password. For socks5 proxy only.
143
144       The following options should be specified:
145
146         (ProxyAddr and ProxyPort)
147         (ConnectAddr and ConnectPort) or (BindAddr and BindPort) or (UdpAddr and UdpPort)
148
149       Other options are facultative.
150
151        start_SOCKS($socket, %cfg)
152
153       This is a class method to start socks handshake on already connected
154       socket. This will bless passed $socket to IO::Socket::Socks class. %cfg
155       is like hash in the constructor.  Only options listed below makes
156       sence:
157
158         Timeout
159         ConnectAddr
160         ConnectPort
161         BindAddr
162         BindPort
163         UdpAddr
164         UdpPort
165         SocksVersion
166         SocksDebug
167         SocksResolve
168         AuthType
169         RequireAuth
170         Username
171         Password
172         AuthMethods
173
174       On success this method will return same $socket, but as
175       IO::Socket::Socks object. On failure it will return undef (but socket
176       will be still blessed to IO::Socket::Socks class). See example:
177
178         use IO::Socket;
179         use IO::Socket::Socks;
180
181         my $sock = IO::Socket::INET->new("$proxy_host:$proxy_port") or die $@;
182         $sock = IO::Socket::Socks->start_SOCKS($sock, ConnectAddr => "google.com", ConnectPort => 80) or die $SOCKS_ERROR;
183
184        version( )
185
186       Returns socks version for this socket
187
188        ready( )
189
190       Returns true when socket becomes ready to transfer data (socks
191       handshake done), false otherwise. This is useful for non-blocking
192       connect/bind. When this method returns false value you can determine
193       what socks handshake need for with $SOCKS_ERROR variable. It may need
194       for read, then $SOCKS_ERROR will be SOCKS_WANT_READ or need for write,
195       then it will be SOCKS_WANT_WRITE.
196
197       Example:
198
199           use IO::Socket::Socks;
200           use IO::Select;
201
202           my $sock = IO::Socket::Socks->new(
203               ProxyAddr => 'localhost', ProxyPort => 1080, ConnectAddr => 'mail.com', ConnectPort => 80, Blocking => 0
204           ) or die $SOCKS_ERROR;
205
206           my $sel = IO::Select->new($sock);
207           until ($sock->ready) {
208               if ($SOCKS_ERROR == SOCKS_WANT_READ) {
209                   $sel->can_read();
210               }
211               elsif ($SOCKS_ERROR == SOCKS_WANT_WRITE) {
212                   $sel->can_write();
213               }
214               else {
215                   die $SOCKS_ERROR;
216               }
217
218               # NOTE: when base class ($IO::Socket::Socks::SOCKET_CLASS) is IO::Socket::IP
219               # and you are using kqueue or epoll to check for readable/writable sockets
220               # you need to readd $sock to kqueue/epoll after each call to ready() (actually until socket will be connected to proxy server),
221               # because IO::Socket::IP may change internal socket of $sock for milti-homed hosts.
222               # There is no such problem when you are using select/poll
223           }
224
225           # you may want to return socket to blocking state by $sock->blocking(1)
226           $sock->syswrite("I am ready");
227
228        accept( )
229
230       Accept an incoming connection after bind request. On failed returns
231       undef.  On success returns socket. No new socket created, returned
232       socket is same on which this method was called. Because accept(2) is
233       not invoked on the client side, socks server calls accept(2) and
234       proxify all traffic via socket opened by client bind request. You can
235       call accept only once on IO::Socket::Socks client socket.
236
237        command( %cfg )
238
239       Allows one to execute socks command on already opened socket. Thus you
240       can create socks chain. For example see "EXAMPLES" section.
241
242       %cfg is like hash in the constructor. Only options listed below makes
243       sence:
244
245         ConnectAddr
246         ConnectPort
247         BindAddr
248         BindPort
249         UdpAddr
250         UdpPort
251         SocksVersion
252         SocksDebug
253         SocksResolve
254         AuthType
255         RequireAuth
256         Username
257         Password
258         AuthMethods
259
260       Values of the other options (Timeout for example) inherited from the
261       constructor.  Options like ProxyAddr and ProxyPort are not included.
262
263        dst( )
264
265       Return (host, port, address_type) of the remote host after
266       connect/accept or socks server (host, port, address_type) after
267       bind/udpassoc.
268
269   Socks Server
270       new( %cfg )
271
272       new_from_socket($socket, %cfg)
273
274       new_from_fd($socket, %cfg)
275
276       Creates a new IO::Socket::Socks server object. new_from_socket() is the
277       same as new(), but allows one to create object from an existing socket
278       (new_from_fd is new_from_socket alias).  Both takes the following
279       config hash:
280
281         SocksVersion => 4 for socks4, 5 for socks5 or [4,5] if you want accept both 4 and 5. Default is 5
282
283         Timeout => Timeout value for various operations
284
285         Blocking => Since IO::Socket::Socks version 0.6 you can perform non-blocking accept by
286                     passing false value for this option. Default is true - blocking. See ready()
287                     below for more details.
288
289         SocksResolve => For socks v5: return destination address to the client
290                         in form of 4 bytes if true, otherwise in form of host
291                         length and host name.
292                         For socks v4: allow use socks4a protocol extension if
293                         true and not otherwise.
294                         This overrides value of $SOCKS4_RESOLVE or $SOCKS5_RESOLVE.
295                         See also command_reply().
296
297         SocksDebug => This will cause all of the SOCKS traffic to
298                       be presented on the command line in a form
299                       similar to the tables in the RFCs. This overrides value
300                       of $SOCKS_DEBUG variable. Boolean.
301
302         ProxyAddr => Local host bind address
303
304         ProxyPort => Local host bind port
305
306         UserAuth => Reference to a function that returns 1 if client
307                     allowed to use socks server, 0 otherwise. For
308                     socks5 proxy it takes login and password as
309                     arguments. For socks4 argument is userid.
310
311         RequireAuth => Not allow anonymous access for socks5 proxy.
312
313         Listen => Same as IO::Socket::INET listen option. Should be
314                   specified as number > 0.
315
316       The following options should be specified:
317
318         Listen
319         ProxyAddr
320         ProxyPort
321
322       Other options are facultative.
323
324       accept( )
325
326       Accept an incoming connection and return a new IO::Socket::Socks object
327       that represents that connection.  You must call command() on this to
328       find out what the incoming connection wants you to do, and then call
329       command_reply() to send back the reply.
330
331       version( )
332
333       Returns socks version for socket. It is useful when your server accepts
334       both 4 and 5 version. Then you should know socks version to make proper
335       response. Just call "version()" on socket received after "accept()".
336
337       ready( )
338
339       After non-blocking accept you will get new client socket object, which
340       may be not ready to transfer data (if socks handshake is not done yet).
341       ready() will return true value when handshake will be done successfully
342       and false otherwise. Note, socket returned by accept() call will be
343       always in blocking mode. So if your program can't block you should set
344       non-blocking mode for this socket before ready() call:
345       $socket->blocking(0).  When ready() returns false value you can
346       determine what socks handshake needs for with $SOCKS_ERROR variable. It
347       may need for read, then $SOCKS_ERROR will be SOCKS_WANT_READ or need
348       for write, then it will be SOCKS_WANT_WRITE.
349
350       Example:
351
352         use IO::Socket::Socks;
353         use IO::Select;
354
355         my $server = IO::Socket::Socks->new(ProxyAddr => 'localhost', ProxyPort => 1080, Blocking => 0)
356             or die $@;
357         my $select = IO::Select->new($server);
358         $select->can_read(); # wait for client
359
360         my $client = $server->accept()
361           or die "accept(): $! ($SOCKS_ERROR)";
362         $client->blocking(0); # !!!
363         $select->add($client);
364         $select->remove($server); # no more connections
365
366         while (1) {
367             if ($client->ready) {
368                 my $command = $client->command;
369
370                 ... # do client command
371
372                 $client->command_reply(IO::Socket::Socks::REPLY_SUCCESS, $command->[1], $command->[2]);
373
374                 ... # transfer traffic
375
376                 last;
377             }
378             elsif ($SOCKS_ERROR == SOCKS_WANT_READ) {
379                 $select->can_read();
380             }
381             elsif ($SOCKS_ERROR == SOCKS_WANT_WRITE) {
382                 $select->can_write();
383             }
384             else {
385                 die "Unexpected error: $SOCKS_ERROR";
386             }
387         }
388
389       command( )
390
391       After you call accept() the client has sent the command they want you
392       to process.  This function should be called on the socket returned by
393       accept(). It returns a reference to an array with the following format:
394
395         [ COMMAND, ADDRESS, PORT, ADDRESS TYPE ]
396
397       command_reply( REPLY CODE, ADDRESS, PORT )
398
399       After you call command() the client needs to be told what the result
400       is.  The REPLY CODE is one of the constants as follows (integer value):
401
402         For socks v4
403         REQUEST_GRANTED(90): request granted
404         REQUEST_FAILED(91): request rejected or failed
405         REQUEST_REJECTED_IDENTD(92): request rejected because SOCKS server cannot connect to identd on the client
406         REQUEST_REJECTED_USERID(93): request rejected because the client program and identd report different user-ids
407
408         For socks v5
409         REPLY_SUCCESS(0): Success
410         REPLY_GENERAL_FAILURE(1): General Failure
411         REPLY_CONN_NOT_ALLOWED(2): Connection Not Allowed
412         REPLY_NETWORK_UNREACHABLE(3): Network Unreachable
413         REPLY_HOST_UNREACHABLE(4): Host Unreachable
414         REPLY_CONN_REFUSED(5): Connection Refused
415         REPLY_TTL_EXPIRED(6): TTL Expired
416         REPLY_CMD_NOT_SUPPORTED(7): Command Not Supported
417         REPLY_ADDR_NOT_SUPPORTED(8): Address Not Supported
418
419       HOST and PORT are the resulting host and port (where server socket
420       responsible for this command bound).
421
422       Note: for 5 version "command_reply" will try to resolve passed address
423       if "SocksResolve" has true value and passed address is domain name. To
424       avoid this just pass ip address ("$socket->sockhost") instead of host
425       name or turn off "SocksResolve" for this server. For version 4 passed
426       host name will always be resolved to ip address even if "SocksResolve"
427       has false value. Because this version doesn't support "ADDRESS" as
428       domain name.
429

VARIABLES

431   $SOCKS_ERROR
432       This scalar behaves like $! in that if undef is returned. $SOCKS_ERROR
433       is IO::Socket::Socks::Error object with some overloaded operators. In
434       string context this variable should contain a string reason for the
435       error. In numeric context it contains error code.
436
437   $SOCKS4_RESOLVE
438       If this variable has true value resolving of host names will be done by
439       proxy server, otherwise resolving will be done locally. Resolving host
440       by socks proxy version 4 is extension to the protocol also known as
441       socks4a. So, only socks4a proxy  supports resolving of hostnames.
442       Default value of this variable is false. This variable is not
443       importable.  See also `SocksResolve' parameter in the constructor.
444
445   $SOCKS5_RESOLVE
446       If this variable has true value resolving of host names will be done by
447       proxy server, otherwise resolving will be done locally. Note: some
448       bugous socks5 servers doesn't support resolving of host names. Default
449       value is true. This variable is not importable.  See also
450       `SocksResolve' parameter in the constructor.
451
452   $SOCKS_DEBUG
453       Default value is $ENV{SOCKS_DEBUG}. If this variable has true value and
454       no SocksDebug option in the constructor specified, then SocksDebug will
455       has true value. This variable is not importable.
456
457   $SOCKET_CLASS
458       With this variable you can get/set base socket class for
459       "IO::Socket::Socks".  By default it tries to use "IO::Socket::IP" 0.36+
460       as socket class. And falls back to "IO::Socket::INET" if not available.
461       You can set $IO::Socket::Socks::SOCKET_CLASS before loading of
462       "IO::Socket::Socks" and then it will not try to detect proper base
463       class itself. You can also set it after loading of "IO::Socket::Socks"
464       and this will automatically update @ISA, so you shouldn't worry about
465       inheritance.
466

CONSTANTS

468       The following constants could be imported manually or using
469       `:constants' tag:
470
471         SOCKS5_VER
472         SOCKS4_VER
473         ADDR_IPV4
474         ADDR_DOMAINNAME
475         ADDR_IPV6
476         CMD_CONNECT
477         CMD_BIND
478         CMD_UDPASSOC
479         AUTHMECH_ANON
480         AUTHMECH_USERPASS
481         AUTHMECH_INVALID
482         AUTHREPLY_SUCCESS
483         AUTHREPLY_FAILURE
484         ISS_UNKNOWN_ADDRESS # address type sent by client/server not supported by I::S::S
485         ISS_BAD_VERSION     # socks version sent by client/server != specified version
486         ISS_CANT_RESOLVE    # I::S::S failed to resolve some host
487         REPLY_SUCCESS
488         REPLY_GENERAL_FAILURE
489         REPLY_CONN_NOT_ALLOWED
490         REPLY_NETWORK_UNREACHABLE
491         REPLY_HOST_UNREACHABLE
492         REPLY_CONN_REFUSED
493         REPLY_TTL_EXPIRED
494         REPLY_CMD_NOT_SUPPORTED
495         REPLY_ADDR_NOT_SUPPORTED
496         REQUEST_GRANTED
497         REQUEST_FAILED
498         REQUEST_REJECTED_IDENTD
499         REQUEST_REJECTED_USERID
500         SOCKS_WANT_READ
501         SOCKS_WANT_WRITE
502         ESOCKSPROTO
503
504       SOCKS_WANT_READ, SOCKS_WANT_WRITE and ESOCKSPROTO are imported by
505       default.
506

IPv6

508       Since version 0.66 "IO::Socket::Socks" supports IPv6 with help of
509       IO::Socket::IP 0.36+. And will use "IO::Socket::IP" as base class if
510       available. However you can force set "$SOCKET_CLASS =
511       "IO::Socket::INET"" to use IPv4 only. See also "$SOCKET_CLASS"
512

FAQ

514       How to determine is connection to socks server (client accept) failed
515       or some protocol error occurred?
516           You can check $! variable. If $! == ESOCKSPROTO constant, then it
517           was error in the protocol. Error description could be found in
518           $SOCKS_ERROR.
519
520       How to determine which error in the protocol occurred?
521           You should compare $SOCKS_ERROR with constants below:
522
523             AUTHMECH_INVALID
524             AUTHREPLY_FAILURE
525             ISS_UNKNOWN_ADDRESS
526             ISS_BAD_VERSION
527             REPLY_GENERAL_FAILURE
528             REPLY_CONN_NOT_ALLOWED
529             REPLY_NETWORK_UNREACHABLE
530             REPLY_HOST_UNREACHABLE
531             REPLY_CONN_REFUSED
532             REPLY_TTL_EXPIRED
533             REPLY_CMD_NOT_SUPPORTED
534             REPLY_ADDR_NOT_SUPPORTED
535             REQUEST_FAILED
536             REQUEST_REJECTED_IDENTD
537             REQUEST_REJECTED_USERID
538

BUGS

540       The following options are not implemented:
541
542       GSSAPI authentication
543       UDP server side support
544
545       Patches are welcome.
546

SEE ALSO

548       IO::Socket::Socks::Wrapper
549

AUTHOR

551       Original author is Ryan Eatmon
552
553       Now maintained by Oleg G <oleg@cpan.org>
554
556       This module is free software, you can redistribute it and/or modify it
557       under the terms of LGPL.
558
559
560
561perl v5.34.0                      2021-07-22              IO::Socket::Socks(3)
Impressum