commit fb9999239378993838166fab4d29dbc537b50c27 Author: Nick Mathewson <nickm@torproject.org> Date: Fri Mar 16 22:29:44 2012 -0400 Add Mike 's proposal 197: Message-based Inter-Controller IPC Channel --- proposals/000-index.txt | 2 + proposals/197-postmessage-ipc.txt | 132 +++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 0 deletions(-) diff --git a/proposals/000-index.txt b/proposals/000-index.txt index 4507a18..c5f7707 100644 --- a/proposals/000-index.txt +++ b/proposals/000-index.txt @@ -117,6 +117,7 @@ Proposals by number: 194 Mnemonic .onion URLs [OPEN] 195 TLS certificate normalization for Tor 0.2.4.x [DRAFT] 196 Extended ORPort and TransportControlPort [OPEN] +197 Message-based Inter-Controller IPC Channel [OPEN] Proposals by status: @@ -154,6 +155,7 @@ Proposals by status: 193 Safe cookie authentication for Tor controllers 194 Mnemonic .onion URLs 196 Extended ORPort and TransportControlPort [for 0.2.4.x] + 197 Message-based Inter-Controller IPC Channel [for 0.2.4.x] ACCEPTED: 117 IPv6 exits [for 0.2.3.x] 140 Provide diffs between consensuses diff --git a/proposals/197-postmessage-ipc.txt b/proposals/197-postmessage-ipc.txt new file mode 100644 index 0000000..45348c8 --- /dev/null +++ b/proposals/197-postmessage-ipc.txt @@ -0,0 +1,132 @@ +Filename: 197-postmessage-ipc.txt +Title: Message-based Inter-Controller IPC Channel +Author: Mike Perry +Created: 16-03-2012 +Status: Open +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 =3D 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 =3D "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 =3D 1*DIGIT + SourceControllerID =3D "unset" / 1*(ALNUM / "_") + DestControllerID =3D "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=20 + sent to ControllerIDs that match the current controller=20 + 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. + + =20 + + + +--=20 +Mike Perry + +--GID0FwUMdk1T2AWN +Content-Type: application/pgp-signature; name="signature.asc" +Content-Description: Digital signature + +-----BEGIN PGP SIGNATURE----- +Version: GnuPG v1.4.11 (GNU/Linux) + +iEYEARECAAYFAk9j144ACgkQGwyjDN3GwK07dgCdEqImEOU/QeGwdAs9Nxe8vlYO +H+UAn0/NlNoEwFfRDbnH3fv+3C/MOOF8 +=gs9Z +-----END PGP SIGNATURE----- + +--GID0FwUMdk1T2AWN-- + +--===============7807826766355441436== +Content-Type: text/plain; charset="us-ascii" +MIME-Version: 1.0 +Content-Transfer-Encoding: 7bit +Content-Disposition: inline + +_______________________________________________ +tor-dev mailing list +tor-dev@lists.torproject.org +https://lists.torproject.org/cgi-bin/mailman/listinfo/tor-dev + +--===============7807826766355441436==--