Configuration of SocksProxy


Because SocksProxy is open source, it is possible to write your own custom SocksConf.dll that delivers the required setup to the proxy, or you can use the accompanying SocksConf.dll, either manually editing the registry settings required, or, which is recommended, use the SocksSetup program, which will give the best overview of everything. Here are presented first some basic concepts and examples of setting up typical scenarios using the SocksProxy, followed by a detailed description of the setup parameters.

Connection Types:

The basic scenario is a machine, A, that wants to connect to another machine, B:

A => B

Note that here and in the following, A and B and the other players can be referred to as "machines", but any combination of them, even possibly all of them, can easily be located on the same machine, and should really be considered "applications" instead. However, thinking of them as machines will sometimes make it easier to hold an overview of what is actually going on. Typically though, the network on the immediate right side of the (first) proxy is the internet, while other networks involved are typically local, at least for the tunnel examples – but it is not necessarily so.

If A for some reason cannot contact B directly, it can use the help of a proxy that can:

A => P => B

A proxy can be transparent, in which case A isn’t even aware that a proxy is in use, except perhaps through the use of a different ip address and port, but the protocol in the communication at least isn’t aware. A proxy can also be a socks proxy using either socks 4 or socks 5, in which case A must first negotiate with P to establish a connection to B. This is the basic difference between transparent and socks proxies; the proxy needs to know how to contact B, and for a transparent proxy, it must be configured in advance, for a socks proxy, A is required to deliver this information, including any user name and password necessary to access the socks proxy. This requires a more complicated application A, but then the same proxy can be used for different B’s, whereas a transparent proxy can only contact the preconfigured B.

Proxies can be chained, meaning there is a chain of any number of proxies between A and B:

A => P => P => B

For transparent proxies, this is the precise description, but for socks proxies, the situation is more complicated. If the second proxy in the figure above is a socks proxy, then the first proxy will need to know how to communicate with a socks proxy, including socks version and any user name and password - just as A needs to be able to do this in case the first proxy is a socks proxy. The SocksProxy application is doing this through the concept of a "carrier":

A => PC => P => B

The second proxy is considered a "carrier" of the communication from the first proxy to B, so the first proxy must have a carrier interface that can take on the task to communicate with the second proxy, the carrier, on behalf of the first proxy. For a transparent second proxy, no carrier interface is of course required, for any other type of proxy, a properly configured carrier definition must be used. In the following, the word "carrier" is used to refer to the carrier definition belonging to the first proxy, while the physical carrier is refered to simply as the "second proxy".

SocksProxy also offers the use of tunnels, having the benefits of taking some of the danger out of exposing the second proxy to the internet. A tunnel is using a proprietary protocol, it can be encrypted, it is possible to change SocksProxy to only accept certain ip addresses, and it is even possible to write your very own protocol.

A special kind of tunnel offered is the "reverse tunnel":
A => PC <= P => B
Note that the communication line between the two proxies is created in the opposite direction. This can be useful in cases where firewalls or NAT routers are involved, or if a static ip is not available on the second proxy where it is needed, but is available only on the first proxy.

SocksSetup:

SocksSetup can administer the setup of both (user) local and service settings, local settings are used when running the proxy with the -l option. In the SocksSetup application, you will find 3 tabs called "Proxies", "Carriers" and "Names". The "Names" tab can be used to define aliases for ip addresses that can be used just as dns names. This will sometimes make it easier to create and maintain the proxy and carrier definitions, but it is also possible to use the ip adresses or dns names directly, the use of defined names is optional. In the examples below, no names but only ip addresses are used for simplicity.

Examples:

In the following are shown examples on how to set up the scenarios mentioned above:

  1. To create a transparent connection, A => P => B, a transparent proxy must be set up:

    Note that port 80 is chosen arbitrarily. It could as well have been any other port, even different ports depending on the services involved. A "GRE Proxy" is used for a Microsoft VPN. Note that no carrier is chosen, since the proxy has direct access to B – or it has access through another transparent proxy, in which case it doesn’t need to know.
  2. To create a connection through a socks 5 proxy server, A => P => B, a socks 5 proxy must be set up:

    Note that no specification of the destination, B, is present, A will supply this during the initial negotiation. Note also that the public ip address, which is required for socks binding, is not explicitly known here, but will be determined through querying an external service. No authentication is specified in this example.
  3. To create a connection through first a transparent proxy, and then a socks proxy, A => PC => P => B, the two different proxies should be configured like this:

    Note how this proxy is defined in the same way as the proxy in example 1 except for the use of the carrier, which must be defined as follows:

    The "Carrier IP Address" is the ip address of the actual carrier, the second proxy. The second proxy can then be defined on the machine running the second proxy as follows:

    Note that the carrier definition’s "Carrier IP Address" and port must match the second proxy’s "Listening IP Address" and port – although "All Adapters" or a dns name would of course also be acceptable for the second proxy. Note also that the final destination, B, is configured in the first proxy.

  4. A tunnel is a special kind of proxy. Once the connection is made, it can carry many connections from different A’s to as many B’s. A tunnel is by definition chained, since it requires a first proxy using a carrier definition and a second proxy. This is an example of the first proxy:

    Note that the first proxy is transparent, so A will never know anything. It is however using a carrier to reach the destination:

    Of course, the second proxy that this carrier definition is to match, looks like this:
  5. If for some reason it is not possible to configure a carrier to reach the second proxy, either because a firewall or a NAT router prevents it, or if the second proxy doesn’t have a static ip address that can be configured, a reverse tunnel can be used instead:

    This proxy looks exactly like the first proxy in previous example, except for the choice of a different carrier, which is defined like this:

    Note that this carrier also includes a "Listen IP Address". This is due to the nature of the reverse tunnel. It is not the carrier that connects to the second proxy, it is the second proxy that connects to the carrier. The second proxy looks like this:

    Note that this proxy does not have a listening address, but rather a "Destination IP Address" and port, which match exactly the carrier definition. This way, the second proxy can connect to the carrier definition with the first proxy, and then any connections going through the first proxy can be routed through the tunnel to the second proxy and on from there. A reverse tunnel proxy is of course not capable of knowing exactly when the first proxy will need its services, so for reverse tunnels, the connection is set up permanently – and reconnected as soon as possible, if it breaks. To know if the connection is still valid, when not in use, a heartbeat is sent every 4-5 minuttes, so unless a connection becomes impossible for other reasons it should never take more than 4-5 minutes to detect it and reestablish it. If the connection is closed gracefully for some reason, the second proxy will immediately try to reconnect, and continue to do so with gradually longer intervals.

Configuration Parameters In Detail

The module SocksSetup is recommended for configuring SocksProxy, but here is a description of the setup in the registry for the knowledgable. The configuration parameters are located in the registry under "HKLM\SOFTWARE\Wow6432Node\SocksProxy" for 64 bit Windows, and "HKLM\SOFTWARE\SocksProxy" for 32 bit Windows. Note that if the server is run from a command prompt, it will ask for elevation, if the prompt is not already elevated, for the server to have access to the registry key. Alternatively, use the -l option together with -c. This will read the configuration from HKCU\SOFTWARE\SocksProxy instead, eliminating the nead for elevation, but also removing the possibility of sharing the configuration between running from a command prompt and as a service. This is mostly intended for testing.

The structure of the registry keys under the SocksProxy key is as follows:

Proxies\<name>\

    Active (DWORD)
0, not active, 1 active, default 1.
    Authentication (SZ)
"None" or "UsernamePassword" ("unpw"), default "None".
    Carrier (SZ)
Name of the carrier to use (optional).
    ChaChaKey (BINARY)
ChaCha encryption key used for tunnels (32 bytes).
    Compression (SZ)
Compression method for tunnels: "None", "Runlength", "Huffman".
    DestinationIP (SZ)
IP address or name of destination, used by Transparent.
    DestinationPort (DWORD)
Port of destination, used by Transparent.
    Encryption (SZ)
Encryption method for tunnels: "None", "ChaCha".
    ExternalIP (SZ)
IP or name used to connect from, 0.0.0.0 means any.
    Gre (DWORD)
0, no gre routing, 1 gre routing, used by Transparent.
    ListenIP (SZ)
IP or name of listener, 0.0.0.0 to listen on all.
    ListenPort (DWORD)
Port used by listener.
    PublicIP (SZ)
IP address used for Socks bind.
    Protocol (SZ)
Protocol for proxy: "Socks", "Socks4", "Socks5", "Transparent".
    ResolveRemotely (DWORD)
0 if DestinationIP is a name to be resolved locally, 1 if resolving is to be done by the carrier.

Carriers\<name>\

    Authentication (SZ)
"None" or "UsernamePassword" ("unpw"), default "None".
    ChaChaKey (BINARY)
ChaCha encryption key used for tunnels (32 bytes).
    Compression (SZ)
Compression method for tunnels: "None", "Runlength", "Huffman".
    Encryption (SZ)
Encryption method for tunnels: "None", "ChaCha".
    IP (SZ)
IP or name of the "next" proxy.
    ListenIP (SZ)
IP or name of listener, 0.0.0.0 to listen on all. Used by reverse tunnel.
    ListenPort (DWORD)
Port used by listener. Used by reverse tunnel.
    Password (SZ)
Password if authentication is "UsernamePassword" ("unpw").
    Port (DWORD)
Port of the "next" proxy.
    Protocol (SZ)
Protocol to use when talking to the next proxy.
    Username (SZ)
Username if authentication is "UsernamePassword" ("unpw").

Names\

    <name> (SZ)
IP address or DNS name.

Even More Detailed explanation of the configuration.

Proxies

Proxies are all configured seperately under their individually named keys under the "Proxies" key.

When configuring a proxy, first consider what type of proxy you need:

Protocol (SZ)
    "Transparent"
Simple forwarding to a fixed destination. Configure your client program to connect to this proxy instead of the real destination, and configure the proxy to connect to the actual destination (see later).
    "Socks"
Socks proxy, either 4, 4a or 5. The client will need to know one of these protocols, and will itself instruct the proxy where to connect.
    "Socks4"
As above, but only Socks 4 or 4a.
    "Socks5"
As above, but only Socks 5.
    "Tunnel"
For a carrier, this is the client of a tunnel meant to send connection request to another proxy. For a proxy, this is the server end of a tunnel that is to receive request.
    "ReverseTunnel"
For a carrier, this is the client of a tunnel meant to send connection request to another proxy, but the underlying connection is to be made by the proxy, not the carrier. For a proxy, this is the server end of a tunnel that is to receive request. The server end is to create the connection to use.

Next, specify the ip and port to listen on. These are the values that you will need to put into your client application. Note that for a reverse tunnel proxy, no ListenIP and -Port are required, rather DestinationIP and -Port as the proxy is to make a connection, not receive one.

ListenIP (SZ)
IP address or name (see later).
ListenPort (DWORD)
Tcp port.

If your proxy is on a multihomed PC (it usually is), you may configure the ip address to connect from, to ensure that the connection is established on the right network adapter.

ExternalIP (SZ)
IP address or name (see later).

When using one of the Socks protocols, the required type of authentication must be specified:

Authentication (SZ)

    "None"
No authentication is required.
    "UsernamePassword"
(Or simply "unpw".) The socks client must specify a username and password.

Certain elements of the Socks protocol requires the socks proxy to know on which ip address servers will connect to when doing callback. When chaining to another proxy, this is not relevant, but when not chaining, (the most frequent case), that ip can be specified as:

PublicIP (SZ)
IP address or name (see later).

If you are configuring a transparent proxy, there are a few more choices to make. For transparent proxies, the client application should be configured with the proxy IP address and port, and the proxy should be configured with the actual destination IP and port. The DestinationIP and -Port are also required by a reverse tunnel proxy and should specify the ip and port of the client's carrier.

DestinationIP (SZ)
IP address or name (see later).
DestinationPort (DWORD)
Tcp port.

If you are using the transparent proxy to route a Microsoft VPN, you will need to route the GRE protocol as well:

Gre (DWORD)
    0
"Regular" transparent proxy without GRE.
    1
Route the GRE protocol as well.

When configuring tunnels and reverse tunnels, you also have the choice of using compression and encryption.

Compression (SZ)
    "None"
No compression used.
    "Runlength"
Runlength compression used. Compression relies on sequences of identical bytes in the stream.
    "Huffman"
Adaptive Huffman compression used.

Encryption (SZ)
    "None"
No encryption used.
    "ChaCha"
ChaCha20 encryption used. Encryption requires a predefined 32 byte key shared between both ends of the tunnel.

Note that already compressed and/or encrypted streams cannot benefit from further compression, where encryption always adds another layer of security. ChaCha encryption does not offer forward secrecy though, if the shared key is compromised.

Sometimes the proxy server cannot itself connect directly to the desired destination, but will need to connect to another proxy server, possibly even of another brand. This is possible, (except for the transparent protocol) if that other proxy server implements the Socks protocol in a similar manner with respect to authentication. Specify that other server as a carrier:

Carrier (SZ)
Name of carrier (see later).

IP Addresses and Names

Whenever an ip address is required, it should be specified as a string using IPV4 notation, for instance, "192.168.1.100". However, it is also possible to specify a name instead, like "MyServer". When the proxy server finds a string, that does not translate into an ip address, it will first look for a string with that name under the key "Names". If such a string is found, the value of that string is read and interpreted as an ip address or a DNS name. If no string is found with a matching name, the name itself is interpreted as a DNS name. Some speciel ip addresses are available:

"0.0.0.0"
Can be used for ListenIP and ExternalIP and means that the proxy will listen on all available addresses, and connect from any suitable address. This is also the default if not specified.
"0.0.0.1"
Can be used for PublicIP and means that an external service will be contacted in order to detect the current public ip address. This is also the default. Note that this method CAN fail, if the network or remote service is not available when the proxy server is started, in which case the specific proxy is disabled.

Carriers

Proxies can be "chained", meaning that the proxy will relay the requested service through to the "next" socks proxy in the chain. The next proxy can either be an identical proxy, or another brand of proxy, as long as it offers the required service and allows connecting to it. If either the tunnel or reverse tunnel protocol is to be used, the next proxy will of course have use the same software and also be configured identically. Carriers are specified under the key "Carriers", with a key with the chosen name of the carrier, the same name used to refer to it from a proxy, see above. Under that key, the following must be specified:

IP (SZ)
IP address or name of the next proxy to connect to.
Port (DWORD)
Tcp port of the next proxy.
Protocol (SZ)
The protocol used by the next proxy, either "Socks4", "Socks5", "Tunnel" or "ReverseTunnel".
Authentication (SZ)
"None" or "UsernamePassword" ("unpw"), default "None". Used for Socks protocols only. This setting must match how the next proxy server is configured.
Username (SZ)
Username if authentication is "UsernamePassword" ("unpw"). Used for Socks protocols only.
Password (SZ)
Password if authentication is "UsernamePassword" ("unpw"). Used for Socks protocols only.
Compression (SZ)
Compression method for tunnels: "None", "Runlength", "Huffman". See details under "Proxies".
Encryption (SZ)
Encryption method for tunnels: "None", "ChaCha". See details under "Proxies".
ChaChaKey (BINARY)
ChaCha encryption key used for tunnels (32 bytes). See details under "Proxies".
ListenIP (SZ)
For reverse tunnels, this is the IP address or name of the client. Reverse tunnels are created "backwards", and can thus only serve a single preconfigured client.
ListenPort (DWORD)
For reverse tunnels, this is the tcp port of the client.

Examine the log from the proxy server when it is started, to see if all the requested proxies have been correctly started.

Home

Last revised: 2018-12-27
·