1IO::Socket::Socks(3) User Contributed Perl Documentation IO::Socket::Socks(3)
2
6 IO::Socket::Socks - Provides a way to create socks client or server
7 both 4 and 5 version.
8
10 Client
11 use IO::Socket::Socks;
12 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 print $socks_client "foo\n";
21 $socks_client->close();
22 Server
24 use IO::Socket::Socks ':constants';
25 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 while(1) {
35 my $client = $socks_server->accept();
36 unless ($client) {
38 print "ERROR: $SOCKS_ERROR\n";
39 next;
40 }
41 my $command = $client->command();
43 if ($command->[0] == CMD_CONNECT) {
44 # Handle the CONNECT
45 $client->command_reply(REPLY_SUCCESS, addr, port);
46 }
47 ...
49 #read from the client and send to the CONNECT address
50 ...
51 $client->close();
53 }
54 sub auth {
56 my ($user, $pass) = @_;
57 return 1 if $user eq "foo" && $pass eq "bar";
59 return 0;
60 }
61
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
71 For complete examples of socks 4/5 client and server see `examples'
72 subdirectory in the distribution.
73
75 Socks Client
76 new( %cfg )
77 new_from_socket($socket, %cfg)
79 new_from_fd($socket, %cfg)
81 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 Both takes the following config hash:
88 SocksVersion => 4 or 5. Default is 5
90 Timeout => connect/accept timeout
92 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 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 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 ProxyAddr => Hostname of the proxy
108 ProxyPort => Port of the proxy
110 ConnectAddr => Hostname of the remote machine
112 ConnectPort => Port of the remote machine
114 BindAddr => Hostname of the remote machine which will
116 connect to the proxy server after bind request
117 BindPort => Port of the remote machine which will
119 connect to the proxy server after bind request
120 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 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 AuthType => What kind of authentication to support:
130 none - no authentication (default)
131 userpass - Username/Password. For socks5
132 proxy only.
133 RequireAuth => Do not send ANON as a valid auth mechanism.
135 For socks5 proxy only
136 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 Password => If AuthType is set to userpass, then you must
142 provide a password. For socks5 proxy only.
143 The following options should be specified:
145 (ProxyAddr and ProxyPort)
147 (ConnectAddr and ConnectPort) or (BindAddr and BindPort) or (UdpAddr and UdpPort)
148 Other options are facultative.
150 start_SOCKS($socket, %cfg)
152 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 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 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 use IO::Socket;
179 use IO::Socket::Socks;
180 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 version( )
185 Returns socks version for this socket
187 ready( )
189 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 Example:
198 use IO::Socket::Socks;
200 use IO::Select;
201 my $sock = IO::Socket::Socks->new(
203 ProxyAddr => 'localhost', ProxyPort => 1080, ConnectAddr => 'mail.com', ConnectPort => 80, Blocking => 0
204 ) or die $SOCKS_ERROR;
205 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 # 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 # you may want to return socket to blocking state by $sock->blocking(1)
226 $sock->syswrite("I am ready");
227 accept( )
229 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 command( %cfg )
238 Allows one to execute socks command on already opened socket. Thus you
240 can create socks chain. For example see "EXAMPLES" section.
241 %cfg is like hash in the constructor. Only options listed below makes
243 sence:
244 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 Values of the other options (Timeout for example) inherited from the
261 constructor. Options like ProxyAddr and ProxyPort are not included.
262 dst( )
264 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 Socks Server
270 new( %cfg )
271 new_from_socket($socket, %cfg)
273 new_from_fd($socket, %cfg)
275 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 SocksVersion => 4 for socks4, 5 for socks5 or [4,5] if you want accept both 4 and 5. Default is 5
282 Timeout => Timeout value for various operations
284 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 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 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 ProxyAddr => Local host bind address
303 ProxyPort => Local host bind port
305 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 RequireAuth => Not allow anonymous access for socks5 proxy.
312 Listen => Same as IO::Socket::INET listen option. Should be
314 specified as number > 0.
315 The following options should be specified:
317 Listen
319 ProxyAddr
320 ProxyPort
321 Other options are facultative.
323 accept( )
325 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 version( )
332 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 ready( )
338 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 Example:
351 use IO::Socket::Socks;
353 use IO::Select;
354 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 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 while (1) {
367 if ($client->ready) {
368 my $command = $client->command;
369 ... # do client command
371 $client->command_reply(IO::Socket::Socks::REPLY_SUCCESS, $command->[1], $command->[2]);
373 ... # transfer traffic
375 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 command( )
390 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 [ COMMAND, ADDRESS, PORT, ADDRESS TYPE ]
396 command_reply( REPLY CODE, ADDRESS, PORT )
398 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 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 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 HOST and PORT are the resulting host and port (where server socket
420 responsible for this command bound).
421 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
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 $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 $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 $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 $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
468 The following constants could be imported manually or using
469 `:constants' tag:
470 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 SOCKS_WANT_READ, SOCKS_WANT_WRITE and ESOCKSPROTO are imported by
505 default.
506
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
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 How to determine which error in the protocol occurred?
521 You should compare $SOCKS_ERROR with constants below:
522 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
540 The following options are not implemented:
541 GSSAPI authentication
543 UDP server side support
544 Patches are welcome.
546
548 IO::Socket::Socks::Wrapper
549
551 Original author is Ryan Eatmon
552 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.
558perl v5.36.0 2023-01-20 IO::Socket::Socks(3)