mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-08-03 12:06:54 -04:00
Split qrexec docs into multiple pages
- Moves the "Qubes RPC internals" section to qrexec-internals.md. - Fixes redirects for new pages. - Retitles docs to reflect deprecation of qrexec2. - Revises the texts and links referring to deprecated qrexec2 docs.
This commit is contained in:
parent
6476996227
commit
32621ef94f
4 changed files with 169 additions and 160 deletions
314
developer/services/qrexec.md
Normal file
314
developer/services/qrexec.md
Normal file
|
@ -0,0 +1,314 @@
|
|||
---
|
||||
layout: doc
|
||||
title: Qrexec
|
||||
permalink: /doc/qrexec/
|
||||
redirect_from:
|
||||
- /en/doc/qrexec3/
|
||||
- /doc/Qrexec3/
|
||||
- /doc/qrexec3/
|
||||
- /wiki/Qrexec3/
|
||||
- /doc/qrexec/
|
||||
- /en/doc/qrexec/
|
||||
- /doc/Qrexec/
|
||||
- /wiki/Qrexec/
|
||||
---
|
||||
|
||||
# Qrexec: secure communication across domains
|
||||
|
||||
(*This page is about qrexec v3. For qrexec v2, see [here](/doc/qrexec2/).*)
|
||||
|
||||
The **qrexec** framework is used by core Qubes components to implement communication between domains.
|
||||
Qubes domains are strictly isolated by design.
|
||||
However, the OS needs a mechanism to allow the administrative domain (dom0) to force command execution in another domain (VM).
|
||||
For instance, when a user selects an application from the KDE menu, it should start in the selected VM.
|
||||
Also, it is often useful to be able to pass stdin/stdout/stderr from an application running in a VM to dom0 (and the other way around).
|
||||
(For example, so that a VM can notify dom0 that there are updates available for it).
|
||||
By default, Qubes allows VMs initiate such communications in specific circumstances.
|
||||
The qrexec framework generalizes this process.
|
||||
It allows users and developers to use and design secure inter-VM tools.
|
||||
|
||||
## Qrexec basics: architecture and examples
|
||||
|
||||
Qrexec is built on top of *vchan*, a Xen library providing data links between VMs.
|
||||
During domain creation, a process named `qrexec-daemon` is started in dom0, and a process named `qrexec-agent` is started in the VM.
|
||||
They are connected over a **vchan** channel.
|
||||
`qrexec-daemon` listens for connections from a dom0 utility named `qrexec-client`.
|
||||
Let's say we want to start a process (call it `VMprocess`) in a VM (`someVM`).
|
||||
Typically, the first thing that a `qrexec-client` instance does is to send a request to the `qrexec-daemon`, which in turn relays it to `qrexec-agent` running in `someVM`.
|
||||
`qrexec-daemon` assigns unique vchan connection details and sends them to both `qrexec-client` (in dom0) and `qrexec-agent` (in `someVM`).
|
||||
`qrexec-client` starts a vchan server, which `qrexec-agent` then connects to.
|
||||
Once this channel is established, stdin/stdout/stderr from the VMprocess is passed between `qrexec-agent` and the `qrexec-client` process.
|
||||
|
||||
The `qrexec-client` command is used to make connections to VMs from dom0.
|
||||
For example, the following command
|
||||
|
||||
qrexec-client -e -d someVM user:'touch hello-world.txt'
|
||||
|
||||
creates an empty file called `hello-world.txt` in the home folder of `someVM`.
|
||||
|
||||
The string before the colon specifies what user to run the command as.
|
||||
The `-e` flag tells `qrexec-client` to exit immediately after sending the execution request and receiving a status code from `qrexec-agent` (whether the process creation succeeded).
|
||||
With this option, no further data is passed between the domains.
|
||||
By contrast, the following command demonstrates an open channel between dom0 and someVM (in this case, a remote shell):
|
||||
|
||||
qrexec-client -d someVM user:bash
|
||||
|
||||
The `qvm-run` command is heavily based on `qrexec-client`.
|
||||
It also takes care of additional activities, e.g. starting the domain if it is not up yet and starting the GUI daemon.
|
||||
Thus, it is usually more convenient to use `qvm-run`.
|
||||
|
||||
There can be almost arbitrary number of `qrexec-client` processes for a domain (so, connected to the same `qrexec-daemon`, same domain) -- their data is multiplexed independently.
|
||||
Number of available vchan channels is the limiting factor here, it depends on the underlying hypervisor.
|
||||
|
||||
## Qubes RPC services
|
||||
|
||||
Some common tasks (like copying files between VMs) have an RPC-like structure: a process in one VM (say, the file sender) needs to invoke and send/receive data to some process in other VM (say, the file receiver).
|
||||
The Qubes RPC framework was created to securely facilite a range of such actions.
|
||||
|
||||
Obviously, inter-VM communication must be tightly controlled to prevent one VM from taking control of another, possibly more privileged, VM.
|
||||
Therefore the design decision was made to pass all control communication via dom0, that can enforce proper authorization.
|
||||
Then, it is natural to reuse the already-existing qrexec framework.
|
||||
|
||||
Also, note that bare qrexec provides `VM <-> dom0` connectivity, but the command execution is always initiated by dom0.
|
||||
There are cases when VM needs to invoke and send data to a command in dom0 (e.g. to pass information on newly installed `.desktop` files).
|
||||
Thus, the framework allows dom0 to be the RPC target as well.
|
||||
|
||||
Thanks to the framework, RPC programs are very simple -- both RPC client and server just use their stdin/stdout to pass data.
|
||||
The framework does all the inner work to connect these processes to each other via `qrexec-daemon` and `qrexec-agent`.
|
||||
Additionally, disposable VMs are tightly integrated -- RPC to a DisposableVM is identical to RPC to a normal domain, all one needs is to pass `$dispvm` as the remote domain name.
|
||||
|
||||
## Qubes RPC administration
|
||||
|
||||
<!-- (*TODO: fix for non-linux dom0*) -->
|
||||
|
||||
The dom0 directory `/etc/qubes-rpc/policy/` contains files for each available RPC action.
|
||||
Together their contents make up the RPC access policy database.
|
||||
Currently, the defined actions are:
|
||||
|
||||
qubes.ClipboardPaste
|
||||
qubes.Filecopy
|
||||
qubes.GetImageRGBA
|
||||
qubes.GetRandomizedTime
|
||||
qubes.Gpg
|
||||
qubes.GpgImportKey
|
||||
qubes.InputKeyboard
|
||||
qubes.InputMouse
|
||||
qubes.NotifyTools
|
||||
qubes.NotifyUpdates
|
||||
qubes.OpenInVM
|
||||
qubes.OpenURL
|
||||
qubes.PdfConvert
|
||||
qubes.ReceiveUpdates
|
||||
qubes.SyncAppMenus
|
||||
qubes.USB
|
||||
qubes.VMShell
|
||||
qubes.WindowIconUpdater
|
||||
|
||||
These files contain lines with the following format:
|
||||
|
||||
srcvm destvm (allow|deny|ask)[,user=user_to_run_as][,target=VM_to_redirect_to]
|
||||
|
||||
You can specify srcvm and destvm by name or by one of three reserved keywords: `$anyvm`, `$dispvm`, and `dom0` (without the `$`).
|
||||
Only `$anyvm` keyword makes sense in srcvm field.
|
||||
(Service calls from dom0 are currently always allowed, `$dispvm` means "new VM created for this particular request," so it is never a source of request.)
|
||||
Currently there is no way to specify source VM by type.
|
||||
Whenever a RPC request for an action is received, the domain checks the first matching line of the relevant file in `/etc/qubes-rpc/policy/` to determine access:
|
||||
whether to allow the request, what VM to redirect the execution to, and what user account the program should run under.
|
||||
Note that if the request is redirected (`target=` parameter), policy action remains the same - even if there is another rule which would otherwise deny such request.
|
||||
If the policy file does not exist, the user is prompted to create one.
|
||||
If still there is no policy file after prompting, the action is denied.
|
||||
|
||||
In the target VM, the `/etc/qubes-rpc/RPC_ACTION_NAME` must exist, containing the file name of the program that will be invoked, or being that program itself - in which case it must have executable permission set (`chmod +x`).
|
||||
|
||||
In the src VM, one should invoke the client via:
|
||||
|
||||
/usr/lib/qubes/qrexec-client-vm target_vm_name RPC_ACTION_NAME rpc_client_path client arguments
|
||||
|
||||
Note that only stdin/stdout is passed between RPC server and client -- notably, no command line arguments are passed.
|
||||
Source VM name is specified by `QREXEC_REMOTE_DOMAIN` environment variable.
|
||||
By default, stderr of client and server is logged to respective `/var/log/qubes/qrexec.XID` files.
|
||||
It is also possible to call service without specific client program - in which case server stdin/out will be connected with the terminal:
|
||||
|
||||
/usr/lib/qubes/qrexec-client-vm target_vm_name RPC_ACTION_NAME
|
||||
|
||||
Be very careful when coding and adding a new RPC service.
|
||||
Unless the offered functionality equals full control over the target (it is the case with e.g. `qubes.VMShell` action), any vulnerability in an RPC server can be fatal to Qubes security.
|
||||
On the other hand, this mechanism allows to delegate processing of untrusted input to less privileged (or disposable) AppVMs, thus wise usage of it increases security.
|
||||
|
||||
For example, this command will run the `firefox` command in a DisposableVM based on `work`:
|
||||
|
||||
```
|
||||
$ qvm-run --dispvm=work firefox
|
||||
```
|
||||
|
||||
By contrast, consider this command:
|
||||
|
||||
```
|
||||
$ qvm-run --dispvm=work --service qubes.StartApp+firefox
|
||||
```
|
||||
|
||||
This will look for a `firefox.desktop` file in a standard location in a DisposableVM based on `work`, then launch the application described by that file.
|
||||
The practical difference is that the bare `qvm-run` command uses the `qubes.VMShell` service, which allows you to run an arbitrary command with arbitrary arguments, essentially providing full control over the target VM.
|
||||
By contrast, the `qubes.StartApp` service allows you to run only applications that are advertised in `/usr/share/applications` (or other standard locations) *without* control over the arguments, so giving a VM access to `qubes.StartApp` is much safer.
|
||||
While there isn't much practical difference between the two commands above when starting an application from dom0 in Qubes 4.0, there is a significant security risk when launching applications from a domU (e.g., from a separate GUI domain).
|
||||
This is why `qubes.StartApp` uses our standard `qrexec` argument grammar to strictly filter the permissible grammar of the `Exec=` lines in `.desktop` files that are passed from untrusted domUs to dom0, thereby protecting dom0 from command injection by maliciously-crafted `.desktop` files.
|
||||
|
||||
### Extra keywords available in Qubes 4.0 and later
|
||||
|
||||
**This section is about a not-yet-released version, some details may change**
|
||||
|
||||
In Qubes 4.0, target VM can be specified also as `$dispvm:DISP_VM`, which is very similar to `$dispvm` but forces using a particular VM (`DISP_VM`) as a base VM to be started as DisposableVM.
|
||||
For example:
|
||||
|
||||
anon-whonix $dispvm:anon-whonix-dvm allow
|
||||
|
||||
Adding such policy itself will not force usage of this particular `DISP_VM` - it will only allow it when specified by the caller.
|
||||
But `$dispvm:DISP_VM` can also be used as target in request redirection, so _it is possible_ to force particular `DISP_VM` usage, when caller didn't specify it:
|
||||
|
||||
anon-whonix $dispvm allow,target=$dispvm:anon-whonix-dvm
|
||||
|
||||
Note that without redirection, this rule would allow using default Disposable VM (`default_dispvm` VM property, which itself defaults to global `default_dispvm` property).
|
||||
Also note that the request will be allowed (`allow` action) even if there is no second rule allowing calls to `$dispvm:anon-whonix-dvm`, or even if there is a rule explicitly denying it.
|
||||
This is because the redirection happens _after_ considering the action.
|
||||
|
||||
In Qubes 4.0 there are also additional methods to specify source/target VM:
|
||||
|
||||
* `$tag:some-tag` - meaning a VM with tag `some-tag`
|
||||
* `$type:type` - meaning a VM of `type` (like `AppVM`, `TemplateVM` etc)
|
||||
|
||||
Target VM can be also specified as `$default`, which matches the case when calling VM didn't specified any particular target (either by using `$default` target, or empty target).
|
||||
|
||||
In Qubes 4.0 policy confirmation dialog (`ask` action) allow the user to specify target VM.
|
||||
User can choose from VMs that, according to policy, would lead to `ask` or `allow` actions.
|
||||
It is not possible to select VM that policy would deny.
|
||||
By default no VM is selected, even if the caller provided some, but policy can specify default value using `default_target=` parameter.
|
||||
For example:
|
||||
|
||||
work-mail work-archive allow
|
||||
work-mail $tag:work ask,default_target=work-files
|
||||
work-mail $default ask,default_target=work-files
|
||||
|
||||
The first rule allow call from `work-mail` to `work-archive`, without any confirmation.
|
||||
The second rule will ask the user about calls from `work-mail` VM to any VM with tag `work`.
|
||||
And the confirmation dialog will have `work-files` VM chosen by default, regardless of the VM specified by the caller (`work-mail` VM).
|
||||
The third rule allow the caller to not specify target VM at all and let the user choose, still - from VMs with tag `work` (and `work-archive`, regardless of tag), and with `work-files` as default.
|
||||
|
||||
### Service argument in policy
|
||||
|
||||
Sometimes just service name isn't enough to make reasonable qrexec policy.
|
||||
One example of such a situation is [qrexec-based USB passthrough](https://github.com/qubesos/qubes-issues/issues/531) - using just service name isn't possible to express the policy "allow access to device X and deny to others".
|
||||
It also isn't feasible to create a separate service for every device...
|
||||
|
||||
For this reason, starting with Qubes 3.2, it is possible to specify a service argument, which will be subject to policy.
|
||||
Besides the above example of USB passthrough, a service argument can make many service policies more fine-grained and easier to write precise policy with "allow" and "deny" actions, instead of "ask" (offloading additional decisions to the user).
|
||||
And generally the less choices the user must make, the lower the chance to make a mistake.
|
||||
|
||||
The syntax is simple: when calling a service, add an argument to the service name separated with `+` sign, for example:
|
||||
|
||||
/usr/lib/qubes/qrexec-client-vm target_vm_name RPC_ACTION_NAME+ARGUMENT
|
||||
|
||||
Then create a policy as usual, including the argument (`/etc/qubes-rpc/policy/RPC_ACTION_NAME+ARGUMENT`).
|
||||
If the policy for the specific argument is not set (file does not exist), then the default policy for this service is loaded (`/etc/qubes-rpc/policy/RPC_ACTION_NAME`).
|
||||
|
||||
In target VM (when the call is allowed) the service file will searched as:
|
||||
|
||||
- `/etc/qubes-rpc/RPC_ACTION_NAME+ARGUMENT`
|
||||
- `/etc/qubes-rpc/RPC_ACTION_NAME`
|
||||
|
||||
In any case, the script will receive `ARGUMENT` as its argument and additionally as `QREXEC_SERVICE_ARGUMENT` environment variable.
|
||||
This means it is also possible to install a different script for a particular service argument.
|
||||
|
||||
See below for an example service using an argument.
|
||||
|
||||
### Revoking "Yes to All" authorization
|
||||
|
||||
Qubes RPC policy supports "ask" action.
|
||||
This will prompt the user whether given RPC call should be allowed.
|
||||
That prompt window also has a "Yes to All" option, which will allow the action and add a new entry to the policy file, which will unconditionally allow further calls for the given service-srcVM-dstVM tuple.
|
||||
|
||||
In order to remove such authorization, issue this command from a dom0 terminal (for `qubes.Filecopy` service):
|
||||
|
||||
sudo nano /etc/qubes-rpc/policy/qubes.Filecopy
|
||||
|
||||
and then remove the first line(s) (before the first `##` comment) which are the "Yes to All" results.
|
||||
|
||||
### Qubes RPC example
|
||||
|
||||
As a demonstration, we can create an RPC service that adds two integers in a target domain (the server, call it "anotherVM") and returns back the result to the invoker (the client, "someVM").
|
||||
In someVM, create a file with the following contents and save it with the path `/usr/bin/our_test_add_client`:
|
||||
|
||||
#!/bin/sh
|
||||
echo $1 $2 # pass data to RPC server
|
||||
exec cat >&$SAVED_FD_1 # print result to the original stdout, not to the other RPC endpoint
|
||||
|
||||
Our server will be anotherVM at `/usr/bin/our_test_add_server`.
|
||||
The code for this file is:
|
||||
|
||||
#!/bin/sh
|
||||
read arg1 arg2 # read from stdin, which is received from the RPC client
|
||||
echo $(($arg1+$arg2)) # print to stdout, which is passed to the RPC client
|
||||
|
||||
We'll need to create a service called `test.Add` with its own definition and policy file in dom0.
|
||||
In dom0 add the following test to `/etc/qubes-rpc/policy/test.Add`:
|
||||
|
||||
$anyvm $anyvm ask
|
||||
|
||||
Now we need to define what the service does.
|
||||
In this case, it should call our additing script.
|
||||
We define the service with another one-line file, `/etc/qubes-rpc/test.Add`:
|
||||
|
||||
/usr/bin/our_test_add_server
|
||||
|
||||
Before we make the call, ensure that the client and server scripts have executable permissions.
|
||||
Now, invoke the RPC service!
|
||||
|
||||
qrexec-client-vm anotherVM test.Add /usr/bin/our_test_add_client 1 2
|
||||
|
||||
We should get "3" as answer.
|
||||
(dom0 will ask for confirmation first.)
|
||||
|
||||
**Note:** For a real world example of writing a qrexec service, see this [blog post](https://blog.invisiblethings.org/2013/02/21/converting-untrusted-pdfs-into-trusted.html).
|
||||
|
||||
### Qubes RPC example - with argument usage
|
||||
|
||||
We will show the necessary files to create an RPC call that reads a specific file from a predefined directory on the target.
|
||||
Besides really naive storage, it may be a very simple password manager.
|
||||
Additionally, in this example a simplified workflow will be used - server code placed directly in the service definition file (in `/etc/qubes-rpc` directory).
|
||||
And no separate client script will be used.
|
||||
|
||||
* RPC server code (*/etc/qubes-rpc/test.File*)
|
||||
|
||||
#!/bin/sh
|
||||
argument="$1" # service argument, also available as $QREXEC_SERVICE_ARGUMENT
|
||||
if [ -z "$argument" ]; then
|
||||
echo "ERROR: No argument given!"
|
||||
exit 1
|
||||
fi
|
||||
# service argument is already sanitized by qrexec framework and it is
|
||||
# guaranteed to not contain any space or /, so no need for additional path
|
||||
# sanitization
|
||||
cat "/home/user/rpc-file-storage/$argument"
|
||||
|
||||
* specific policy file in dom0 (*/etc/qubes-rpc/policy/test.File+testfile1* )
|
||||
|
||||
source_vm1 target_vm allow
|
||||
|
||||
* another specific policy file in dom0 (*/etc/qubes-rpc/policy/test.File+testfile2* )
|
||||
|
||||
source_vm2 target_vm allow
|
||||
|
||||
* default policy file in dom0 (*/etc/qubes-rpc/policy/test.File* )
|
||||
|
||||
$anyvm $anyvm deny
|
||||
|
||||
* invoke RPC from `source_vm1` via
|
||||
|
||||
/usr/lib/qubes/qrexec-client-vm target_vm test.File+testfile1
|
||||
|
||||
and we should get content of `/home/user/rpc-file-storage/testfile1` as answer.
|
||||
|
||||
* also possible to invoke RPC from `source_vm2` via
|
||||
|
||||
/usr/lib/qubes/qrexec-client-vm target_vm test.File+testfile2
|
||||
|
||||
But when invoked with other argument or from different VM, it should be denied.
|
Loading…
Add table
Add a link
Reference in a new issue