Ugh.. Without the annoying tabs:

Filename: xxx-postmessage-ipc.txt Title: Message-based Inter-Controller IPC Channel Author: Mike Perry Created: 16-03-2012 Status: Proposed Target: 0.2.4.x

Overview

This proposal seeks to create a means for inter-controller communication using the Tor Control Port.

Motivation

With the advent of pluggable transports, bridge discovery mechanisms, and tighter browser-Vidalia integration, we're going to have an increasing number of collaborating Tor controller programs communicating with each other. Rather than define new pairwise IPC mechanisms for each case, we will instead create a generalized message-passing mechanism through the Tor Control Port.

Control Protocol Specification Changes

CONTROLLERNAME command

Sent from the client to the server. The syntax is:

"CONTROLLERNAME" SP ControllerID ControllerID = 1*(ALNUM / "_")

Server returns "250 OK" and records the ControllerID to use for this control port connection for messaging information if successful, or "553 Controller name already in use" if the name is in use by another controller, or if an attempt is made to register the special names "all" or "unset".

[CONTROLLERNAME need not be issued to send POSTMESSAGE commands, and CONTROLLERNAME may be unsupported by initial POSTMESSAGE implementations in Tor.]

POSTMESSAGE command

Sent from the client to the server. The syntax is:

"POSTMESSAGE" SP "@" DestControllerID SP LineItem CRLF DestControllerID = "all" / 1*(ALNUM / "_")

If DestControllerID is "all", the message will be posted to all controllers that have "SETEVENTS POSTMESSAGE" set. Otherwise, the message should be posted to the controller with the appropriate ControllerID.

Server returns "250 OK" if successful, or "552 Invalid destination controller name" if the name is not registered.

[Initial implementations may require DestControllerID always be "all"]

POSTMESSAGE event

"650" SP "POSTMESSAGE" SP MessageID SP SourceControllerID SP "@" DestControllerID SP LineItem CRLF MessageID = 1*DIGIT SourceControllerID = "unset" / 1*(ALNUM / "_") DestControllerID = "all" / 1*(ALNUM / "_")

MessageID is an incrementing integer identifier that uniquely identifies this message to all controllers.

The SourceControllerID is the value from the sending controller's CONTROLLERNAME command, or "unset" if the CONTROLLERNAME command was not used or unimplemented.

GETINFO commands "recent-messages" -- Retrieves messages sent to ControllerIDs that match the current controller in POSTMESSAGE event format. This list should be generated on the fly, to handle disconnecting controllers.

"new-messages" -- Retrieves the last 10 "unread" messages sent to this controller, in POSTMESSAGE event format. If SETEVENTS POSTMESSAGE was set, this command should always return nothing.

"list-controllers" -- Retrieves a list of all connected controllers with either their registered ControllerID or "unset".

Implementation plan

The POSTMESSAGE protocol is designed to be incrementally deployable. Initial implementations are only expected to implement broadcast capabilities and SETEVENTS based delivery. CONTROLLERNAME need not be supported, nor do non-"@all" POSTMESSAGE destinations.

To support command-based controllers (which do not use SETEVENTS) such as Torbutton, at minimum the "GETINFO recent-messages" command is needed. However, Torbutton does not have immediate need for this protocol.