Add Mike 's proposal 197: Message-based Inter-Controller IPC Channel

1 files changed, 132 insertions, 0 deletions

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==--