mirror of
https://github.com/torproject/torspec.git
synced 2024-12-13 05:05:41 +00:00
100 lines
3.6 KiB
Plaintext
100 lines
3.6 KiB
Plaintext
Filename: 197-postmessage-ipc.txt
|
|
Title: Message-based Inter-Controller IPC Channel
|
|
Author: Mike Perry
|
|
Created: 16-03-2012
|
|
Status: REJECTED
|
|
|
|
|
|
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.
|
|
|