Opened 2 years ago

Last modified 17 months ago

#27801 new enhancement

tor_api: CreateConnection() interface

Reported by: sysrqb Owned by:
Priority: Medium Milestone: Tor: unspecified
Component: Core Tor/Tor Version:
Severity: Normal Keywords: 040-deferred-201915
Cc: Actual Points:
Parent ID: #25510 Points:
Reviewer: Sponsor:


In ticket:26653#comment:8 I mentioned it may be nice if there was an easier way of requesting a new connection other than via a SOCKS connection. Adding an interface for creating a connection when roughly the same parameters Tor receives from the SOCKS handshake. In fact, I wonder if providing this as a wrapper around a default SOCKS client implementation may be an easy way of doing this.

Something like:

 * Tells Tor to open a socket for a client connection to the requested
 * destination.  Return the socket.
SOCKS_SOCKET tor_main_create_connection(tor_main_configuration_t *cfg,
                                        const char * hostname,
                                        uint16_t port,
                                        const char * stream_isolation);

Note, we don't need this for Tor Browser for Android. This is simply a more general idea.

Child Tickets

Change History (9)

comment:1 Changed 2 years ago by nickm

Milestone: Tor: unspecifiedTor: 0.3.6.x-final

adding for consideration to 0.3.6

comment:2 Changed 2 years ago by nickm

Sponsor: Sponsor8-can

comment:3 Changed 2 years ago by nickm

Milestone: Tor: 0.3.6.x-finalTor: 0.4.0.x-final

Tor 0.3.6.x has been renamed to 0.4.0.x.

comment:4 Changed 22 months ago by gaba

Sponsor: Sponsor8-can

comment:5 Changed 22 months ago by nickm

Keywords: 040-deferred-201915 added
Milestone: Tor: 0.4.0.x-finalTor: unspecified

Deferring some tickets from 0.4.0 without proposing them for later. Please tag with 041-proposed if you want to do them.

comment:6 Changed 17 months ago by DCNick3

Internally this can be done even without SOCKS client (the same way as tor handles transparent connections, setting address and port in socks_request_t), but it would not work with libtorrunner. Socks client may work there, but if we consider wrapping around socks client, it would require to know the port to connect to, which may be troublesome.

comment:7 Changed 17 months ago by nickm

The API proposed above should get tweaked some: we don't want to have it take a tor_main_configuration_t object, since that is only used for setting up the main() function. Instead it should take some kind of token or handle to a running Tor instance.

We'd need to extent the current API to return such a token or handle in a way that another thread could use.

Remember that new APIs need to be implemented both by embedded Tor and libtorrunner.

comment:8 Changed 17 months ago 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.

comment:9 Changed 17 months ago by nickm

(sorry for delay, I'll try to review this API this week)

Note: See TracTickets for help on using tickets.