Yawning / liballium Public

liballium: A C Tor Pluggable Transports Utility Library
Yawning Angel <yawning at schwanenlied dot me>

liballium attempts to reduce the amount of boilerplate code required to
implement pluggable transports for Tor in C or C++.

Features:
 * Handles the runtime configuration of PT clients and servers
 * (TODO) Routines for talking to the transport control port
 * (TODO) Routines for talking to the extended OR port (including a traffic shaper)

liballium embeds the following third party codebases:
 * Better String Library (safer string manipulation routines)
 * sput (unit test framework, included in tests only)

Specs implemented:
 * https://gitweb.torproject.org/torspec.git/blob/HEAD:/pt-spec.txt
 * (TODO) https://gitweb.torproject.org/torspec.git/blob/HEAD:/proposals/196-transport-control-ports.txt

Notes:
 * Basic familiarity with the relevant Tor specs is assumed.
 * The code should work on Windows, however it is untested on that platform
   and most likely requires changes.  Patches accepted.
 * The Tor Pluggable Transport spec does not currently specify the format for
   IPv6 addresses.  liballium assumes that the standard [addr]:port form is to
   be used.

Known gotchas:
 * allium_ptcfg_state_dir()/allium_ptcfg_auth_cookie_file() will probably
   misbehave if the paths are non-ASCII.  This behavior is not considered a bug
   as environment variable values are NULL terminated by definition (See IEEE
   Std. 1003.1 8.1).
 * liballium is slightly more strict than pt-spec.txt for the contents of
   PTCFG_SERVER_TRANSPORT_OPTIONS.  In particular, the "k" string is not
   unescaped when doing processing, so things like "foo:arg\=bleah=123" will
   cause a ENV-ERROR to be returned to Tor (As of the date of writing this
   library, that functionality is still rather experimental in Tor anyway).
 * tests/ptcfg_test.c depends on inet_pton so it won't run on ancient systems.
   A notable one would be WinXP.  This probably won't be fixed.

See the COPYING file for licence related information.