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.
--
Mike Perry
signature.asc
Description: Digital signature
___
tor-dev mailing list
tor-dev@lists.torproject.org
https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev
