From 86aa6ef638c58ea62d857b0997f0a88b9dd8a425 Mon Sep 17 00:00:00 2001 From: Joanna Rutkowska Date: Sat, 4 Oct 2014 19:26:01 +0000 Subject: [PATCH] Qrexec2Implementation changed Some more content --- Qrexec2Implementation.md | 64 ++++++++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 12 deletions(-) diff --git a/Qrexec2Implementation.md b/Qrexec2Implementation.md index 682de82f..08f4c2da 100644 --- a/Qrexec2Implementation.md +++ b/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