socks — Socks 5 proxy client API
#include <socks.h>
int rc=Rconnect( | fd, | |
addr, | ||
addrlen) ; |
int rc=Rbind( | fd, | |
addr, | ||
addrlen) ; |
cc
{-o binary
} [argument...] {-lsocks}
This is the Courier Socks 5 client proxy library. It is used by the Courier mail server, starting with version 0.46, to send outgoing E-mail through a Socks 5 proxy server. This is a generic proxy API. This library may be used with other applications to establish network connections using a Socks 5 proxy.
There are several ways to use this API library. The preferred way is to
include the header file socks.h
which declares the
Socks-aware equivalents of the socket API functions:
Rconnect
is the Socks-aware version of
connect(2),
Rbind
is the Socks-aware version of
bind(2), and so on.
Use the Socks-aware
functions just like their regular counterparts.
They will transparently
use a Socks 5 proxy to establish and use the network connections,
as specified by the
socksrc(5)
configuration file.
See “CAPABILITIES”, below, for differences in behavior between the regular network functions and their Socks-aware counterparts.
Finally, link the application against the socks
library,
by adding -lsocks
to the link command.
Some platforms do not provide the socket functions in the standard C library.
Applications that use socket functions normally have to explicitly link with a
separate library, such as -lsocket
or
-lnsl_s
.
Try to avoid linking with a separate socket library when using
-lsocks
.
In most cases, linking with those separate libraries is not required any more.
Continue to link with them only if it is still necessary to do
so (try not to link with them, and see what happens).
socks.h
declares the following functions:
Raccept |
Rbind |
Rclose |
Rconnect |
Rdup |
Rdup2 |
Rfclose |
Rgetpeername |
Rgetsockname |
Rgetsockopt |
Rlisten |
Rpoll |
Rread |
Rreadv |
Rrecv |
Rrecvfrom |
Rrecvmsg |
Rselect |
Rsend |
Rsendmsg |
Rsendto |
Rwrite |
Rwritev |
Only some of the above functions are really defined. The rest are mapped, using “#define”-s, to their “R”-less counterparts, but applications should use the “R” functions in order to remain upward-compatible with future versions of this library.
This Socks 5 proxy library supports the following functionality:
Establishing blocking or non-blocking SOCK_STREAM
client connections.
Accepting a single incoming SOCK_STREAM
connection using
Rbind
,
Rlisten
, and
Raccept
.
This Socks 5 proxy library does not support using
Rbind
to bind a socket to a specific port,
then using Rconnect
to establish an outgoing connection
originating from the specific port.
The
Rbind
function can only be used for a
listening socket, and is expected to be followed by
Rlisten
.
This is a limitation of the Socks 5 protocol.
Only one connection may be received by a bound, listening socket.
After the first connection is established, that's it.
The Socks 5 protocol no longer
listens for more connections on the listening socket.
This implementation of
Rbind
,
Rlisten
, and
Raccept
mimics the usual semantics of the non-proxying
versions of these functions.
As far as the application is concerned, only one incoming connection will
ever be received on the listening socket
Continuing to listen on the
socket will never produce any more incoming connections.
This is a limitation of the Socks 5 protocol.
#define SOCKS_REMAP #include <socks.h>
cc
{-o binary
} [argument...] {-lsocks}
The alternative way to use this Socks 5 API is to define
SOCKS_REMAP
before including
socks.h
, and then using the usual socket functions, like
connect
, bind
, and the rest.
It's rather obvious that SOCKS_REMAP
runs
a bunch of C preprocessor definitions, such as:
#define connect Rconnect #define bind Rbind /* More of the same */
This is going to work because this Socks 5 API library automatically
ignores file descriptors
that are not TCP sockets.
A PF_UNIX
file descriptor passed to
Rbind
is automatically shunted off to the real
bind
function, and the application will not know any
better.
Other Socks 5 API functions work in the same way.
The preferred, explicit usage of the “R” functions permits
fine-grained control over proxying.
The application has complete control of which network connections will use
a Socks 5 proxy server
(by using the “R” functions with that file descriptor),
and which network connections won't (by using normal network socket
functions).
Implicit usage, via
SOCKS_REMAP
, loses the control over this process.
All TCP network connections will use Socks 5 proxies, if so indicated by
the
socksrc(5)
configuration file.
cc
{-o binary
} [argument...] {-lsockswrap}
The third alternative mechanism of using this Socks 5 API involves no changes
to the source code.
The only change is to the link command.
The final application executable is linked to the
sockswrap
library instead of the socks
library.
This mechanism may not be available on all platforms, or may not work reliably
with all applications.
The sockswrap
library provides fake definitions of the
normal socket functions, just as connect
,
bind
, and all the others.
These function calls are intercepted, and redirected to their “R”
equivalents.
Some platforms require explicit linkage with the
socks
library
in addition to the sockwrap
library:
cc
{-o binary
} [argument...] {-lsockswrap} {-lsocks}
In any case, if possible,
do not link against any extra libraries, even if your
platform otherwise requires linking against extra libraries,
such as -lsocket
or -lnsl_s
.
This mechanism is equivalent to running the socksify(1) wrapper with an already-linked executable. This approach may succeed in adding Socks 5 proxying abilities to an existing object code library, or module, if its source code is not available.