[tor-bugs] #27801 [Core Tor/Tor]: tor_api: CreateConnection() interface

[Tor Bug Tracker & Wiki]

#27801: tor_api: CreateConnection() interface
---------------------------------+----------------------------------
 Reporter:  sysrqb               |          Owner:  (none)
     Type:  enhancement          |         Status:  new
 Priority:  Medium               |      Milestone:  Tor: unspecified
Component:  Core Tor/Tor         |        Version:
 Severity:  Normal               |     Resolution:
 Keywords:  040-deferred-201915  |  Actual Points:
Parent ID:  #25510               |         Points:
 Reviewer:                       |        Sponsor:
---------------------------------+----------------------------------

Comment (by DCNick3):

 I would propose these changes in embedding API:
 {{{

 /* The actual type depends on backend */
 typedef void tor_main_token_t;

 typedef void (*tor_ready_callback_t)(tor_main_token_t*, void*);
 typedef void (*tor_stop_callback_t)(tor_main_token_t*, void*);

 /** Requests resource allocation for tor_api_create_connection() to work
 */
 int tor_main_configuration_enable_create_connection(
         tor_main_configuration_t *cfg, int enable);

 int tor_main_configuration_register_callbacks(
         tor_main_configuration_t *cfg, tor_ready_callback_t ready,
         tor_stop_callback_t stop, void* userdata);

 tor_embedded_socket_t tor_api_create_connection(tor_main_token_t *tok,
                                                 const char *hostname,
                                                 uint16_t port);

 tor_embedded_socket_t tor_main_configuration_setup_control_socket(
                                           tor_main_configuration_t *cfg);
 }}}

 (`tor_control_socket_t` renamed to `tor_embedded_socket_t`. This breaks
 API, but we can allow usage of `tor_control_socket_t` as deprecated
 behavior or introduce another type of socket for the connection).

 It is safe to run functions taking token only between calling of
 `tor_ready_callback_t` and `tor_stop_callback_t` for this token (Not
 inside stop callback, but possibly inside ready callback). Token would
 implements locking inside, so it would be safe to call token-related
 functions from multiple threads. Stop callback won't be called during
 API's method execution, so there should not be races.

 Internally, `tor_runner` would request socks unix socket allocation and
 use it for connections. When embedding tor directly, call to
 `tor_api_create_connection()` would allocate a new socket pair, add one of
 them to the connection list inside tor in the way similar to transparent
 proxy handling and return another one.

--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/27801#comment:8>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online