forked from torproject/torspec
-
Notifications
You must be signed in to change notification settings - Fork 0
/
197-postmessage-ipc.txt
99 lines (71 loc) · 3.57 KB
/
197-postmessage-ipc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
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.