From a63cdd2ea62480d41066bf82ba312472876cba3c Mon Sep 17 00:00:00 2001 From: pierwill <19642016+pierwill@users.noreply.github.com> Date: Sun, 11 Aug 2019 13:45:36 -0500 Subject: [PATCH] Revise "Qubes RPC administration" section of qrexec docs - Remove section on "Yes to All" RPC authorization (and add TODO item for if this feature is reintroduced) - Replace `$` keywords with `@` in qrexec policy docs - Incorporate Qubes 4.0 "Extra keywords" material into RPC admin docs - Move some material to a new section on RPC security concerns --- developer/services/qrexec.md | 93 ++++++++++++++++-------------------- 1 file changed, 41 insertions(+), 52 deletions(-) diff --git a/developer/services/qrexec.md b/developer/services/qrexec.md index 9ef5f2bca0..6ff54d18ae 100644 --- a/developer/services/qrexec.md +++ b/developer/services/qrexec.md @@ -108,9 +108,9 @@ 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.) +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. @@ -131,68 +131,67 @@ It is also possible to call service without specific client program - in which c /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. +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 + 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: +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 + 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. +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: +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) + * `@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). +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. +The policy confirmation dialog (`ask` action) allows 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 + 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. +### RPC services and security + +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. + + ### Service argument in policy Sometimes just service name isn't enough to make reasonable qrexec policy. @@ -220,17 +219,7 @@ This means it is also possible to install a different script for a particular se 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