Qrexec2Implementation changed

Some more content

Qrexec2Implementation.md

@@ -4,22 +4,62 @@ title: Qrexec2Implementation
 permalink: /wiki/Qrexec2Implementation/
 ---
 
-Implemention of qrexec in Qubes R2
-==================================
+Implementation of qrexec in Qubes R2
+====================================
 
 This page describes implementation of the [qrexec framework](/wiki/Qrexec) in Qubes OS R2. Note that the implementation has changed significantly in Qubes R3 (see [Qrexec3Implementation](/wiki/Qrexec3Implementation)), although the user API reminded backwards compatible (i.e. qrexec apps written for Qubes R2 should run without modifications on Qubes R3).
 
-General architecture
---------------------
+Dom0 tools implementation
+-------------------------
 
-Dom0-specific details
----------------------
+Players:
 
-VM-specific details (Linux AppVMs)
-----------------------------------
+-   `/usr/lib/qubes/qrexec-daemon` \<- started by mgmt stack (qubes.py) when a VM is started.
+-   `/usr/lib/qubes/qrexec-policy` \<- internal program used to evaluate the policy file and making the 2nd half of the connection.
+-   `/usr/lib/qubes/qrexec-client` \<- raw command line tool that talks to the daemon via unix socket (`/var/run/qubes/qrexec.XID`)
 
-VM-specific details (Windows AppVMs)
-------------------------------------
+Note: neither of the above tools are designed to be used by users.
 
-Protocol description
---------------------
+Linux VMs implementation
+------------------------
+
+Players:
+
+-   `/usr/lib/qubes/qrexec-agent` \<- started by VM bootup scripts, a daemon.
+-   `/usr/lib/qubes/qubes-rpc-multiplexer` \<- executes the actual service program, as specified in VM's `/etc/qubes-rpc/qubes.XYZ`
+-   `/usr/lib/qubes/qrexec-client-vm` \<- raw command line tool that talks to the agent
+
+Note: neither of the above tools are designed to be used by users. `qrexec-client-vm` is designed to be wrapped up by Qubes apps.
+
+Windows VMs implemention
+------------------------
+
+TODO
+
+All the pieces together at work
+-------------------------------
+
+Note: this section is not needed to use qrexec for writing Qubes apps. Also note the qrexec framework implemention in Qubes R3 significantly differs from what is described in this section.
+
+The VM-VM channels in Qubes R2 are made via "gluing" two VM-Dom0 and Dom0-VM vchan connections:
+
+[![No image "qrexec2-implemention.png" attached to Qrexec2Implementation](/chrome/common/attachment.png "No image "qrexec2-implemention.png" attached to Qrexec2Implementation")](/attachment/wiki/Qrexec2Implementation/qrexec2-implemention.png)
+
+Note: Dom0 never examines the actual data flowing in neither of the two vchan connections.
+
+When a user in a source VM executes `qrexec-client-vm` utility, the following steps are taken:
+
+-   `qrexec-client-vm` connects to `qrexec-agent`'s `/var/run/qubes/qrexec-agent-fdpass` unix socket 3 times. Reads 4 bytes from each of them, which is the fd number of the accepted socket in agent. These 3 integers, in text, concatenated, form "connection identifier" (CID)
+-   `qrexec-client-vm` writes to `/var/run/qubes/qrexec-agent` fifo a blob, consisting of target vmname, rpc action, and CID
+-   `qrexec-client-vm` executes the rpc client, passing the above mentioned unix sockets as process stdin/stdout, and optionally stderr (if the PASS\_LOCAL\_STDERR env variable is set)
+-   `qrexec-agent` passes the blob to `qrexec-daemon`, via MSG\_AGENT\_TO\_SERVER\_TRIGGER\_CONNECT\_EXISTING message over vchan
+-   `qrexec-daemon` executes `qrexec-policy`, passing source vmname, target vmname, rpc action, and CID as cmdline arguments
+-   `qrexec-policy` evaluates the policy file. If successful, creates a pair of `qrexec-client` processes, whose stdin/stdout are cross-connencted.
+    -   The first `qrexec-client` connects to the src VM, using the `-c ClientID` parameter, which results in not creating a new process, but connecting to the existing process file descriptors (these are the fds of unix socket created in step 1).
+    -   The second `qrexec-client` connects to the target VM, and executes `qubes-rpc-multiplexer` command there with the rpc action as the cmdline argument. Finally, `qubes-rpc-multiplexer` executes the correct rpc server on the target.
+-   In the above step, if the target VM is `$dispvm`, the dispvm is created via the `qfile-daemon-dvm` program. The latter waits for the `qrexec-client` process to exit, and then destroys the dispvm.
+
+Protocol description ("wire-level" spec)
+----------------------------------------
+
+TODO