PicoSOCKS5: a lightweight and simple SOCKS5 proxy server

PicoSOCKS5 is a very simple and very lightweight SOCKS5 proxy server. It is written in pure C and by default uses no extra libraries besides GLibc or any other POSIX-compatible runtime (such as musl).

License

PicoSOCKS5 is licensed under GNU General Public License Version 3 (GPLv3). For full text of the license see file LICENSE.txt in the root of the project.

In addition, linking to and/or using OpenSSL is allowed. This additional permission is required since recent OpenSSL license is considered by some to be incompatible with GPL.

Supported features

• PicoSOCKS5 implements SOCKS5 (RFC 1928). Currently only CONNECT and BIND are supported, but UDP ASSOCIATE may be implemented later. Draft SOCKS5a is partially taken into account, but not completely implemented. Earlier versions of SOCKS (SOCKS4, SOCKS4a) are not implemented. Draft SOCKS6 and other enhancements are not implemented.
• PicoSOCKS5 implements username/password authentication for SOCKS5 (RFC 1929).
• PicoSOCKS5 implements CHAP authentication for SOCKS5 (draft), including mutual authentication. PicoSOCKS5 can use external crypto libraries (GnuTLS or OpenSSL), if available, or fall back to its own home-grown crypto implementation.
• PicoSOCKS5 supports incoming and outgoing connections both in IPv4 and IPv6. In particular, it can accept requests to connect to IPv6 servers from IPv4 clients, and vice versa, serving as a gateway for mechanism described in RFC 3089.

Known disadvantages

• User list for authentication (in the default password format) is kept in memory, so PicoSOCKS5 doesn't work well for really large number of users.
• There's currently no support for GSS-API authentication method (RFC 1961), required for full SOCKS5 compliance.
• SOCKS5 BIND request support relies on "external" interface addresses specified in daemon configuration. Automatic interface selection is difficult to implement portably.

Building PicoSOCKS5

For building PicoSOCKS5 you'll need:

• GCC compiler. Any version supporting C99 will do (v4.8.4 or newer is guaranteed to work). PicoSOCKS5 conforms to C99 standard, so it can be ported to any compiler supporting it; however, if C11 or later is supported, some of newer features may be used.

• GLibc or compatible library (such as musl). PicoSOCKS5 uses POSIX.1-2017 (with XSI extensions) and following GNU extensions:

  • vsyslog(3).
  • getopt_long(3).
  • crypt_r(3) and algorithm extensions for crypt(3) family.
  • Format specifier "%m" in printf(3) family.
  • Optionally, getifaddrs(3). The program will compile without it, but when it's available, additional functionality is enabled.
  • If the program is compiled without external crypto libraries, it will use home-grown crypto implementation, which uses following extensions:
    • Header <endian.h> (if available) and macros htole32(x) and le32toh(x) defined in it. If there is no <endian.h> for your platform, or if it doesn't define these macros, and you want to avoid using external crypto, you'll have to define these macros yourself and pass them in CFLAGS.
    • Optionally, getentropy(3). If this function is not available, the program will use direct reading from /dev/urandom. If either method fails at runtime, low-quality standard rand(3) will be used instead.

  So if you have another POSIX-compliant C runtime library that includes these features, PicoSOCKS5 can be ported to it. In particular, PicoSOCKS5 is known to successfully build and run with musl (version 1.2.2).

• For crypto implementation, PicoSOCKS5 can use GnuTLS or OpenSSL library. Following features are used:

  • Random bytes generation.
  • MD5 hash and HMAC functions.

  Without at least one of these libraries, PicoSOCKS5 will use getentropy(3) (if available) or standard rand(3) (which is very low quality), and a home-grown HMAC-MD5 implementation, which is not provably secure. Also, internal HMAC-MD5 implementation needs macros htole32(x) and le32toh(x) for converting 32-bit unsigned integers between native (host) byte order and little-endian byte order. In many systems these macros are defined in header file <endian.h>, but if your system is not one of them, you'll have to define these macros yourself and pass your definitions in CFLAGS.

  If you have another library implementing random bytes generation and HMAC-MD5, you can write a wrapper for it as described in docs/crypto-libs.md.

• GNU Autoconf/Automake, and their dependencies. The project was built initially using automake version 1.15, but version 1.14 is also known to work.

• If you want to build man pages, you'll also need pandoc.

First, get the latest sources and configure the project:

git clone https://gitlab.com/oldnomad/picosocks5
cd picosocks5
autoreconf -f -i -Wall
./configure

Configure script supports option with-crypto=<MODULE>, which allows you to specify which crypto library you want to use for CHAP authentication. Possible values are yes (default, use whatever is available), gnutls, openssl, and no (use internal implementation). It is possible to write your own wrapper if you want to use some other library (see documentation).

Next, build and install the daemon:

make && sudo make install

Using PicoSOCKS5

picosocks5 -u nobody -g nogroup -a authfile.txt "*:1080"

For more information on running PicoSOCKS5 see file src/picosocks5.md or man page for picosocks5(8). Short summary of options is also available from command line:

picosocks5 --help