mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2024-12-25 15:29:29 -05:00
begin standardizing markdown lineation of qrexec3 docs
This commit is contained in:
pierwill
parent
cc0d62e2d4
commit
bdffd0fa59
@ -18,92 +18,68 @@ redirect_from:
|
||||
|
||||
# Command execution in VMs #
|
||||
|
||||
(*This page is about qrexec v3. For qrexec v2, see
|
||||
[here](/doc/qrexec2/).*)
|
||||
(*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 isolated by design, but
|
||||
there is a need for a mechanism to allow the administrative domain (dom0) to
|
||||
force command execution in another domain (VM). For instance, when user
|
||||
selects an application from the KDE menu, it should be started 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). In specific
|
||||
circumstances, Qubes allows VMs to be initiators of such communications (so,
|
||||
for example, a VM can notify dom0 that there are updates available for it).
|
||||
The **qrexec** framework is used by core Qubes components to implement communication between domains.
|
||||
Qubes domains are isolated by design, but there is a need for a mechanism to allow the administrative domain (dom0) to force command execution in another domain (VM).
|
||||
For instance, when user selects an application from the KDE menu, it should be started 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).
|
||||
In specific circumstances, Qubes allows VMs to be initiators of such communications (so, for example, a VM can notify dom0 that there are updates available for it).
|
||||
|
||||
|
||||
## Qrexec basics ##
|
||||
|
||||
Qrexec is built on top of vchan (a 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 **vchan** channel. `qrexec-daemon` listens for connections
|
||||
from dom0 utility named `qrexec-client`. Typically, the first thing that a
|
||||
`qrexec-client` instance does is to send a request to `qrexec-daemon` to
|
||||
start a process (let's name it `VMprocess`) with a given command line in
|
||||
a specified VM (`someVM`). `qrexec-daemon` assigns unique vchan connection
|
||||
details and sends them both to `qrexec-client` (in dom0) and `qrexec-agent`
|
||||
(in `someVM`). `qrexec-client` starts a vchan server which `qrexec-agent`
|
||||
connects to. Since then, stdin/stdout/stderr from the VMprocess is passed
|
||||
via vchan between `qrexec-agent` and the `qrexec-client` process.
|
||||
Qrexec is built on top of vchan (a 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 **vchan** channel.
|
||||
`qrexec-daemon` listens for connections from dom0 utility named `qrexec-client`.
|
||||
Typically, the first thing that a `qrexec-client` instance does is to send a request to `qrexec-daemon` to start a process (let's name it `VMprocess`) with a given command line in a specified VM (`someVM`).
|
||||
`qrexec-daemon` assigns unique vchan connection details and sends them both to `qrexec-client` (in dom0) and `qrexec-agent` (in `someVM`).
|
||||
`qrexec-client` starts a vchan server which `qrexec-agent` connects to.
|
||||
Since then, stdin/stdout/stderr from the VMprocess is passed via vchan between `qrexec-agent` and the `qrexec-client` process.
|
||||
|
||||
So, for example, executing in dom0:
|
||||
|
||||
qrexec-client -d someVM user:bash
|
||||
|
||||
allows to work with the remote shell. The string before the first
|
||||
semicolon specifies what user to run the command as. Adding `-e` on the
|
||||
`qrexec-client` command line results in mere command execution (no data
|
||||
passing), and `qrexec-client` exits immediately after sending the execution
|
||||
request and receiving status code from `qrexec-agent` (whether the process
|
||||
creation succeeded). There is also the `-l local_program` flag -- with it,
|
||||
`qrexec-client` passes stdin/stdout of the remote process to the (spawned
|
||||
for this purpose) `local_program`, not to its own stdin/stdout.
|
||||
allows to work with the remote shell.
|
||||
The string before the first semicolon specifies what user to run the command as.
|
||||
Adding `-e` on the `qrexec-client` command line results in mere command execution (no data passing), and `qrexec-client` exits immediately after sending the execution request and receiving status code from `qrexec-agent` (whether the process creation succeeded).
|
||||
There is also the `-l local_program` flag -- with it, `qrexec-client` passes stdin/stdout of the remote process to the (spawned for this purpose) `local_program`, not to its own stdin/stdout.
|
||||
|
||||
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`.
|
||||
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.
|
||||
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 tasks (like inter-vm file copy) share the same rpc-like structure:
|
||||
a process in one VM (say, file sender) needs to invoke and send/receive
|
||||
data to some process in other VM (say, file receiver). Thus, the Qubes RPC
|
||||
framework was created, facilitating such actions.
|
||||
Some tasks (like inter-vm file copy) share the same rpc-like structure: a process in one VM (say, file sender) needs to invoke and send/receive data to some process in other VM (say, file receiver).
|
||||
Thus, the Qubes RPC framework was created, facilitating such actions.
|
||||
|
||||
Obviously, inter-VM communication must be tightly controlled to prevent one
|
||||
VM from taking control over other, 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.
|
||||
Obviously, inter-VM communication must be tightly controlled to prevent one VM from taking control over other, 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.
|
||||
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.
|
||||
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*)
|
||||
|
||||
In dom0, there is a bunch of files in `/etc/qubes-rpc/policy` directory,
|
||||
whose names describe the available rpc actions. Their content is the rpc
|
||||
access policy database. Currently defined actions are:
|
||||
In dom0, there is a bunch of files in `/etc/qubes-rpc/policy` directory, whose names describe the available rpc actions.
|
||||
Their content is the rpc access policy database.
|
||||
Currently defined actions are:
|
||||
|
||||
qubes.ClipboardPaste
|
||||
qubes.Filecopy
|
||||
@ -128,47 +104,31 @@ 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 `$anyvm`, `$dispvm`,
|
||||
`dom0` reserved keywords (note string `dom0` does not match the `$anyvm`
|
||||
pattern; all other names do). 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 action X is received, the first line in
|
||||
`/etc/qubes-rpc/policy/X` that match srcvm/destvm is consulted to determine
|
||||
whether to allow rpc, what user account the program should run in target VM
|
||||
under, and what VM to redirect the execution to. 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, user is prompted to create one; if still there is no
|
||||
policy file after prompting, the action is denied.
|
||||
You can specify srcvm and destvm by name, or by one of `$anyvm`, `$dispvm`, `dom0` reserved keywords (note string `dom0` does not match the `$anyvm` pattern; all other names do).
|
||||
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 action X is received, the first line in `/etc/qubes-rpc/policy/X` that match srcvm/destvm is consulted to determine whether to allow rpc, what user account the program should run in target VM under, and what VM to redirect the execution to.
|
||||
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, 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 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:
|
||||
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.
|
||||
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`:
|
||||
For example, this command will run the `firefox` command in a DisposableVM based on `work`:
|
||||
|
||||
```
|
||||
$ qvm-run --dispvm=work firefox
|
||||
@ -180,133 +140,95 @@ 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.
|
||||
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:
|
||||
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:
|
||||
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.
|
||||
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).
|
||||
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:
|
||||
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.
|
||||
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...
|
||||
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.
|
||||
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:
|
||||
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`).
|
||||
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.
|
||||
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.
|
||||
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):
|
||||
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.
|
||||
and then remove the first line(s) (before the first `##` comment) which are the "Yes to All" results.
|
||||
|
||||
|
||||
### Qubes RPC example ###
|
||||
|
||||
We will show the necessary files to create an rpc call that adds two integers
|
||||
on the target and returns back the result to the invoker.
|
||||
We will show the necessary files to create an rpc call that adds two integers on the target and returns back the result to the invoker.
|
||||
|
||||
* rpc client code (`/usr/bin/our_test_add_client`):
|
||||
|
||||
@ -334,17 +256,14 @@ on the target and returns back the result to the invoker.
|
||||
|
||||
and we should get "3" as answer, after dom0 allows it.
|
||||
|
||||
**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).
|
||||
**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.
|
||||
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*)
|
||||
|
||||
@ -385,13 +304,11 @@ no separate client script will be used.
|
||||
|
||||
# Qubes RPC internals #
|
||||
|
||||
(*This is about the implementation of qrexec v3. For the implementation of
|
||||
qrexec v2, see [here](/doc/qrexec2/#qubes-rpc-internals).*)
|
||||
(*This is about the implementation of qrexec v3.
|
||||
For the implementation of qrexec v2, see [here](/doc/qrexec2/#qubes-rpc-internals).*)
|
||||
|
||||
Qrexec framework consists of a number of processes communicating with each
|
||||
other using common IPC protocol (described in detail below). Components
|
||||
residing in the same domain (`qrexec-client-vm` to `qrexec-agent`, `qrexec-client` to `qrexec-daemon`) use pipes as the underlying transport medium,
|
||||
while components in separate domains (`qrexec-daemon` to `qrexec-agent`, data channel between `qrexec-agent`s) use vchan link.
|
||||
Qrexec framework consists of a number of processes communicating with each other using common IPC protocol (described in detail below).
|
||||
Components residing in the same domain (`qrexec-client-vm` to `qrexec-agent`, `qrexec-client` to `qrexec-daemon`) use pipes as the underlying transport medium, while components in separate domains (`qrexec-daemon` to `qrexec-agent`, data channel between `qrexec-agent`s) use vchan link.
|
||||
Because of [vchan limitation](https://github.com/qubesos/qubes-issues/issues/951), it is not possible to establish qrexec connection back to the source domain.
|
||||
|
||||
|
||||
@ -457,16 +374,15 @@ by an optional data packet.
|
||||
uint32_t len; /* data length */
|
||||
};
|
||||
|
||||
When two peers establish connection, the server sends `MSG_HELLO` followed by
|
||||
`peer_info` struct:
|
||||
When two peers establish connection, the server sends `MSG_HELLO` followed by `peer_info` struct:
|
||||
|
||||
struct peer_info {
|
||||
uint32_t version; /* qrexec protocol version */
|
||||
};
|
||||
|
||||
The client then should reply with its own `MSG_HELLO` and `peer_info`. The
|
||||
lower of two versions define protocol used for this connection. If either side
|
||||
does not support this version, the connection is closed.
|
||||
The client then should reply with its own `MSG_HELLO` and `peer_info`.
|
||||
The lower of two versions define protocol used for this connection.
|
||||
If either side does not support this version, the connection is closed.
|
||||
|
||||
Details of all possible use cases and the messages involved are described below.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user