mirror of
https://github.com/QubesOS/qubes-doc.git
synced 2025-03-13 10:16:29 -04:00
merge main
This commit is contained in:
qm
commit
9b2e206e53
@ -56,17 +56,17 @@ We strongly recommend [updating Qubes OS](/doc/how-to-update/) immediately after
|
||||
|
||||
- Qubes 4.2.2 includes a fix for [#8332: File-copy qrexec service is overly restrictive](https://github.com/QubesOS/qubes-issues/issues/8332). As explained in the issue comments, we introduced a change in Qubes 4.2.0 that caused inter-qube file-copy/move actions to reject filenames containing, e.g., non-Latin characters and certain symbols. The rationale for this change was to mitigate the security risks associated with unusual unicode characters and invalid encoding in filenames, which some software might handle in an unsafe manner and which might cause confusion for users. Such a change represents a trade-off between security and usability.
|
||||
|
||||
After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place.
|
||||
- After the change went live, we received several user reports indicating more severe usability problems than we had anticipated. Moreover, these problems were prompting users to resort to dangerous workarounds (such as packing files into an archive format prior to copying) that carry far more risk than the original risk posed by the unrestricted filenames. In addition, we realized that this was a backward-incompatible change that should not have been introduced in a minor release in the first place.
|
||||
|
||||
Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service.
|
||||
- Therefore, we have decided, for the time being, to restore the original (pre-4.2) behavior by introducing a new `allow-all-names` argument for the `qubes.Filecopy` service. By default, `qvm-copy` and similar tools will use this less restrictive service (`qubes.Filecopy +allow-all-names`) whenever they detect any files that would be have been blocked by the more restrictive service (`qubes.Filecopy +`). If no such files are detected, they will use the more restrictive service.
|
||||
|
||||
Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules:
|
||||
- Users who wish to opt for the more restrictive 4.2.0 and 4.2.1 behavior can do so by modifying their RPC policy rules. To switch a single rule to the more restrictive behavior, change `*` in the argument column to `+` (i.e., change "any argument" to "only empty"). To use the more restrictive behavior globally, add the following "deny" rule before all other relevant rules:
|
||||
|
||||
```
|
||||
qubes.Filecopy +allow-all-names @anyvm @anyvm deny
|
||||
```
|
||||
|
||||
For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc).
|
||||
- For more information, see [RPC policies](/doc/rpc-policy/) and [Qube configuration interface](/doc/vm-interface/#qubes-rpc).
|
||||
|
||||
## Download
|
||||
|
||||
|
||||
@ -13,8 +13,7 @@ ref: 36
|
||||
title: Admin API
|
||||
---
|
||||
|
||||
_You may also be interested in the article
|
||||
[Introducing the Qubes Admin API](/news/2017/06/27/qubes-admin-api/)._
|
||||
_You may also be interested in the article [Introducing the Qubes Admin API](/news/2017/06/27/qubes-admin-api/)._
|
||||
|
||||
## Goals
|
||||
|
||||
|
||||
@ -122,25 +122,25 @@ Details of all possible use cases and the messages involved are described below.
|
||||
|
||||
qrexec-client -d domX [-l local_program] user:cmd
|
||||
|
||||
(If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.)
|
||||
- (If `local_program` is set, `qrexec-client` executes it and uses that child's stdin/stdout in place of its own when exchanging data with `qrexec-agent` later.)
|
||||
|
||||
`qrexec-client` translates that request into a `MSG_EXEC_CMDLINE` message sent to `qrexec-daemon`, with `connect_domain` set to 0 (connect to **dom0**) and `connect_port also set to 0 (allocate a port).
|
||||
- `qrexec-client` translates that request into a `MSG_EXEC_CMDLINE` message sent to `qrexec-daemon`, with `connect_domain` set to 0 (connect to **dom0**) and `connect_port also set to 0 (allocate a port).
|
||||
|
||||
- **dom0**: `qrexec-daemon` allocates a free port (in this case 513), and sends a `MSG_EXEC_CMDLINE` back to the client with connection parameters (**domX** and 513) and with command field empty.
|
||||
|
||||
`qrexec-client` disconnects from the daemon, starts a vchan server on port 513 and awaits connection.
|
||||
- `qrexec-client` disconnects from the daemon, starts a vchan server on port 513 and awaits connection.
|
||||
|
||||
Then, `qrexec-daemon` passes on the request as `MSG_EXEC_CMDLINE` message to the `qrexec-agent` running in **domX**. In this case, the connection parameters are **dom0** and 513.
|
||||
- Then, `qrexec-daemon` passes on the request as `MSG_EXEC_CMDLINE` message to the `qrexec-agent` running in **domX**. In this case, the connection parameters are **dom0** and 513.
|
||||
|
||||
- **domX**: `qrexec-agent` receives `MSG_EXEC_CMDLINE`, and starts the command (`user:cmd`, or `cmd` as user `user`). If possible, this is actually delegated to a separate server (`qrexec-fork-server`) also running on domX.
|
||||
|
||||
After starting the command, `qrexec-fork-server` connects to `qrexec-client` in **dom0** over the provided vchan port 513.
|
||||
- After starting the command, `qrexec-fork-server` connects to `qrexec-client` in **dom0** over the provided vchan port 513.
|
||||
|
||||
- Data is forwarded between the `qrexec-client` in **dom0** and the command executed in **domX** using `MSG_DATA_STDIN`, `MSG_DATA_STDOUT` and `MSG_DATA_STDERR`.
|
||||
|
||||
Empty messages (with data `len` field set to 0 in `msg_header`) are an EOF marker. Peer receiving such message should close the associated input/output pipe.
|
||||
- Empty messages (with data `len` field set to 0 in `msg_header`) are an EOF marker. Peer receiving such message should close the associated input/output pipe.
|
||||
|
||||
When `cmd` terminates, **domX**'s `qrexec-fork-server` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**).
|
||||
- When `cmd` terminates, **domX**'s `qrexec-fork-server` sends `MSG_DATA_EXIT_CODE` header to `qrexec-client` followed by the exit code (**int**).
|
||||
|
||||
### domX: request execution of service `admin.Service` in dom0
|
||||
|
||||
@ -150,41 +150,41 @@ Details of all possible use cases and the messages involved are described below.
|
||||
|
||||
qrexec-client-vm dom0 admin.Service [local_program] [params]
|
||||
|
||||
(If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
|
||||
- (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
|
||||
|
||||
`qrexec-client-vm` connects to `qrexec-agent` and requests service execution (`admin.Service`) in **dom0**.
|
||||
- `qrexec-client-vm` connects to `qrexec-agent` and requests service execution (`admin.Service`) in **dom0**.
|
||||
|
||||
`qrexec-agent` assigns an internal identifier to the request. It's based on a file descriptor of the connected `qrexec-client-vm`: in this case, `SOCKET11`.
|
||||
- `qrexec-agent` assigns an internal identifier to the request. It's based on a file descriptor of the connected `qrexec-client-vm`: in this case, `SOCKET11`.
|
||||
|
||||
`qrexec-agent` forwards the request (`MSG_TRIGGER_SERVICE3`) to its corresponding `qrexec-daemon` running in dom0.
|
||||
- `qrexec-agent` forwards the request (`MSG_TRIGGER_SERVICE3`) to its corresponding `qrexec-daemon` running in dom0.
|
||||
|
||||
- **dom0**: `qrexec-daemon` receives the request and triggers `qrexec-policy` program, passing all necessary parameters: source domain **domX**, target domain **dom0**, service `admin.Service` and identifier `SOCKET11`.
|
||||
|
||||
`qrexec-policy` evaluates if the RPC should be allowed or denied, possibly also launching a GUI confirmation prompt.
|
||||
- `qrexec-policy` evaluates if the RPC should be allowed or denied, possibly also launching a GUI confirmation prompt.
|
||||
|
||||
(If the RPC is denied, it returns with exit code 1, in which case `qrexec-daemon` sends a `MSG_SERVICE_REFUSED` back).
|
||||
- (If the RPC is denied, it returns with exit code 1, in which case `qrexec-daemon` sends a `MSG_SERVICE_REFUSED` back).
|
||||
|
||||
- **dom0**: If the RPC is allowed, `qrexec-policy` will launch a `qrexec-client` with the right command:
|
||||
|
||||
qrexec-client -d dom0 -c domX,X,SOCKET11 "QUBESRPC admin.Service domX name dom0"
|
||||
|
||||
The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
|
||||
- The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
|
||||
|
||||
The command parameter describes the RPC call: it contains service name (`admin.Service`), source domain (`domX`) and target description (`name dom0`, could also be e.g. `keyword @dispvm`). The target description is important in case the original target wasn't dom0, but the service is executing in dom0.
|
||||
- The command parameter describes the RPC call: it contains service name (`admin.Service`), source domain (`domX`) and target description (`name dom0`, could also be e.g. `keyword @dispvm`). The target description is important in case the original target wasn't dom0, but the service is executing in dom0.
|
||||
|
||||
`qrexec-client` connects to a `qrexec-daemon` for **domX** and sends a `MSG_SERVICE_CONNECT` with connection parameters (**dom0**, and port 0, indicating a port should be allocated) and request identifier (`SOCKET11`).
|
||||
- `qrexec-client` connects to a `qrexec-daemon` for **domX** and sends a `MSG_SERVICE_CONNECT` with connection parameters (**dom0**, and port 0, indicating a port should be allocated) and request identifier (`SOCKET11`).
|
||||
|
||||
`qrexec-daemon` allocates a free port (513) and sends back connection parameters to `qrexec-client` (**domX** port 513).
|
||||
- `qrexec-daemon` allocates a free port (513) and sends back connection parameters to `qrexec-client` (**domX** port 513).
|
||||
|
||||
`qrexec-client` starts the command, and tries to connect to **domX** over the provided port 513.
|
||||
- `qrexec-client` starts the command, and tries to connect to **domX** over the provided port 513.
|
||||
|
||||
Then, `qrexec-daemon` forwards the connection request (`MSG_SERVICE_CONNECT`) to `qrexec-agent` running in **domX**, with the right parameters (**dom0** port 513, request `SOCKET11`).
|
||||
- Then, `qrexec-daemon` forwards the connection request (`MSG_SERVICE_CONNECT`) to `qrexec-agent` running in **domX**, with the right parameters (**dom0** port 513, request `SOCKET11`).
|
||||
|
||||
- **dom0**: Because the command has the form `QUBESRPC: ...`, it is started through the `qubes-rpc-multiplexer` program with the provided parameters (`admin.Service domX name dom0`). That program finds and executes the necessary script in `/etc/qubes-rpc/`.
|
||||
|
||||
- **domX**: `qrexec-agent` receives the `MSG_SERVICE_CONNECT` and passes the connection parameters back to the connected `qrexec-client-vm`. It identifies the `qrexec-client-vm` by the request identifier (`SOCKET11` means file descriptor 11).
|
||||
|
||||
`qrexec-client-vm` starts a vchan server on 513 and receives a connection from `qrexec-client`.
|
||||
- `qrexec-client-vm` starts a vchan server on 513 and receives a connection from `qrexec-client`.
|
||||
|
||||
- Data is forwarded between **dom0** and **domX** as in the previous example (dom0-VM).
|
||||
|
||||
@ -196,37 +196,37 @@ Details of all possible use cases and the messages involved are described below.
|
||||
|
||||
qrexec-client-vm domY qubes.Service [local_program] [params]
|
||||
|
||||
(If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
|
||||
- (If `local_program` is set, it will be executed in **domX** and connected to the remote command's stdin/stdout).
|
||||
|
||||
- The request is forwarded as `MSG_TRIGGER_SERVICE3` to `qrexec-daemon` running in **dom0**, then to `qrexec-policy`, then (if allowed) to `qrexec-client`.
|
||||
|
||||
This is the same as in the previous example (VM-dom0).
|
||||
- This is the same as in the previous example (VM-dom0).
|
||||
|
||||
- **dom0**: If the RPC is allowed, `qrexec-policy` will launch a `qrexec-client` with the right command:
|
||||
|
||||
qrexec-client -d domY -c domX,X,SOCKET11 user:cmd "DEFAULT:QUBESRPC qubes.Service domX"
|
||||
|
||||
The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
|
||||
- The `-c domX,X,SOCKET11` are parameters indicating how connect back to **domX** and pass its input/output.
|
||||
|
||||
The command parameter describes the service call: it contains the username (or `DEFAULT`), service name (`qubes.Service`) and source domain (`domX`).
|
||||
- The command parameter describes the service call: it contains the username (or `DEFAULT`), service name (`qubes.Service`) and source domain (`domX`).
|
||||
|
||||
`qrexec-client` will then send a `MSG_EXEC_CMDLINE` message to `qrexec-daemon` for **domY**. The message will be with port number 0, requesting port allocation.
|
||||
- `qrexec-client` will then send a `MSG_EXEC_CMDLINE` message to `qrexec-daemon` for **domY**. The message will be with port number 0, requesting port allocation.
|
||||
|
||||
`qrexec-daemon` for **domY** will allocate a port (513) and send it back. It will also send a `MSG_EXEC_CMDLINE` to its corresponding agent. (It will also translate `DEFAULT` to the configured default username).
|
||||
- `qrexec-daemon` for **domY** will allocate a port (513) and send it back. It will also send a `MSG_EXEC_CMDLINE` to its corresponding agent. (It will also translate `DEFAULT` to the configured default username).
|
||||
|
||||
Then, `qrexec-client` will also send `MSG_SERVICE_CONNECT` message to **domX**'s agent, indicating that it should connect to **domY** over port 513.
|
||||
- Then, `qrexec-client` will also send `MSG_SERVICE_CONNECT` message to **domX**'s agent, indicating that it should connect to **domY** over port 513.
|
||||
|
||||
Having notified both domains about a connection, `qrexec-client` now exits.
|
||||
- Having notified both domains about a connection, `qrexec-client` now exits.
|
||||
|
||||
- **domX**: `qrexec-agent` receives a `MSG_SERVICE_CONNECT` with connection parameters (**domY** port 513) and request identifier (`SOCKET11`). It sends the connection parameters back to the right `qrexec-client-vm`.
|
||||
|
||||
`qrexec-client-vm` starts a vchan server on port 513. note that this is different than in the other examples: `MSG_SERVICE_CONNECT` means you should start a server, `MSG_EXEC_CMDLINE` means you should start a client.
|
||||
- `qrexec-client-vm` starts a vchan server on port 513. note that this is different than in the other examples: `MSG_SERVICE_CONNECT` means you should start a server, `MSG_EXEC_CMDLINE` means you should start a client.
|
||||
|
||||
- **domY**: `qrexec-agent` receives a `MSG_EXEC_CMDLINE` with the command to execute (`user:QUBESRPC...`) and connection parameters (**domX** port 513).
|
||||
|
||||
It forwards the request to `qrexec-fork-server`, which handles the command and connects to **domX** over the provided port.
|
||||
- It forwards the request to `qrexec-fork-server`, which handles the command and connects to **domX** over the provided port.
|
||||
|
||||
Because the command is of the form `QUBESRPC ...`, `qrexec-fork-server` starts it using `qubes-rpc-multiplexer` program, which finds and executes the necessary script in `/etc/qubes-rpc/`.
|
||||
- Because the command is of the form `QUBESRPC ...`, `qrexec-fork-server` starts it using `qubes-rpc-multiplexer` program, which finds and executes the necessary script in `/etc/qubes-rpc/`.
|
||||
|
||||
- After that, the data is passed between **domX** and **domY** as in the previous examples (dom0-VM, VM-dom0).
|
||||
|
||||
|
||||
@ -16,8 +16,8 @@ title: GUI virtualization
|
||||
|
||||
All AppVM X applications connect to local (running in AppVM) Xorg servers that use the following "hardware" drivers:
|
||||
|
||||
- *`dummyqsb_drv`* - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
|
||||
- *`qubes_drv`* - it provides a virtual keyboard and mouse (in fact, more, see below)
|
||||
- `dummyqsb_drv` - video driver, that paints onto a framebuffer located in RAM, not connected to real hardware
|
||||
- `qubes_drv` - it provides a virtual keyboard and mouse (in fact, more, see below)
|
||||
|
||||
For each AppVM, there is a pair of `qubes-gui` (running in AppVM) and `qubes-guid` (running in the AppVM’s GuiVM, dom0 by default) processes connected over vchan.
|
||||
The main responsibilities of `qubes-gui` are:
|
||||
|
||||
@ -154,6 +154,7 @@ The newly installed package is set as the default VM kernel.
|
||||
It is possible to package a kernel installed in dom0 as a VM kernel.
|
||||
This makes it possible to use a VM kernel which is not packaged by Qubes team.
|
||||
This includes:
|
||||
|
||||
* using a Fedora kernel package
|
||||
* using a manually compiled kernel
|
||||
|
||||
|
||||
@ -52,13 +52,11 @@ any GNU/Linux system with the following procedure.
|
||||
[user@restore ~]$ cat backup-header.hmac
|
||||
(stdin)= 5b266783e116fe3b2601a54c249ca5f5f96d421dfe6828eeaeb2dcd014e9e945c27b3d7b0f952f5d55c927318906d9c360f387b0e1f069bb8195e96543e2969c
|
||||
|
||||
**Note:** The hash values should match. If they do not match, then the
|
||||
- **Note:** The hash values should match. If they do not match, then the
|
||||
backup file may have been tampered with, or there may have been a storage
|
||||
error.
|
||||
|
||||
|
||||
|
||||
**Note:** If your backup was hashed with a message digest algorithm other
|
||||
- **Note:** If your backup was hashed with a message digest algorithm other
|
||||
than `sha512`, you must substitute the correct message digest command. This
|
||||
information is contained in the `backup-header` file (see step 4), however
|
||||
it is not recommended to open this file until its integrity and
|
||||
@ -88,13 +86,11 @@ any GNU/Linux system with the following procedure.
|
||||
[user@restore vm1]$ cat private.img.000.hmac
|
||||
(stdin)= cf83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e
|
||||
|
||||
**Note:** The hash values should match. If they do not match, then the
|
||||
- **Note:** The hash values should match. If they do not match, then the
|
||||
backup file may have been tampered with, or there may have been a storage
|
||||
error.
|
||||
|
||||
|
||||
|
||||
**Note:** If your backup was hashed with a message digest algorithm other
|
||||
- **Note:** If your backup was hashed with a message digest algorithm other
|
||||
than `sha512`, you must substitute the correct message digest command. This
|
||||
information is contained in the `backup-header` file (see step 4). A
|
||||
complete list of supported message digest algorithms can be found with
|
||||
@ -139,9 +135,7 @@ any GNU/Linux system with the following procedure.
|
||||
10. Success! If you wish to recover data from more than one VM in your backup,
|
||||
simply repeat steps 5--9 for each additional VM.
|
||||
|
||||
|
||||
|
||||
**Note:** You may wish to store a copy of these instructions with your
|
||||
- **Note:** You may wish to store a copy of these instructions with your
|
||||
Qubes backups in the event that you fail to recall the above procedure
|
||||
while this web page is inaccessible. All Qubes documentation, including
|
||||
this page, is available in plain text format in the following Git
|
||||
|
||||
@ -152,10 +152,10 @@ Emergency Recovery Instructions
|
||||
done | gzip -d | tar -xv
|
||||
vm1/private.img
|
||||
|
||||
If this pipeline fails, it is likely that the backup is corrupted or has
|
||||
- If this pipeline fails, it is likely that the backup is corrupted or has
|
||||
been tampered with.
|
||||
|
||||
**Note:** If your backup was compressed with a program other than `gzip`,
|
||||
- **Note:** If your backup was compressed with a program other than `gzip`,
|
||||
you must substitute the correct compression program in the command above.
|
||||
This information is contained in `backup-header` (see step 4). For example,
|
||||
if your backup is compressed with `bzip2`, use `bzip2 -d` instead in the
|
||||
@ -171,7 +171,7 @@ Emergency Recovery Instructions
|
||||
8. Success! If you wish to recover data from more than one VM in your backup,
|
||||
simply repeat steps 6 and 7 for each additional VM.
|
||||
|
||||
**Note:** You may wish to store a copy of these instructions with your
|
||||
- **Note:** You may wish to store a copy of these instructions with your
|
||||
Qubes backups in the event that you fail to recall the above procedure
|
||||
while this web page is inaccessible. All Qubes documentation, including
|
||||
this page, is available in plain text format in the following Git
|
||||
|
||||
@ -48,7 +48,6 @@ Such attacks have been described in the academic literature, but it is doubtful
|
||||
3. **Unintentional leaks.** Non-malicious software which is either buggy or doesn't maintain the privacy of user data, whether by design or accident.
|
||||
For example, software which automatically sends error reports to a remote server, where these reports contain details about the system which the user did not want to share.
|
||||
|
||||
|
||||
Both Qubes firewall and an empty NetVM (i.e., setting the NetVM of an app qube to "none") can fully protect against leaks of type 3.
|
||||
However, neither Qubes firewall nor an empty NetVM are guaranteed to protect against leaks of types 1 and 2.
|
||||
There are few effective, practical policy measures available to end-users today to stop the leaks of type 1.
|
||||
|
||||
@ -155,11 +155,10 @@ Consider the following example. `mytcp-service` qube has a TCP service running o
|
||||
|
||||
- In untrusted, use the Qubes tool `qvm-connect-tcp`:
|
||||
|
||||
~~~
|
||||
```
|
||||
[user@untrusted #]$ qvm-connect-tcp 444:@default:444
|
||||
~~~
|
||||
|
||||
> Note: The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
|
||||
```
|
||||
- **Note:** The syntax is the same as SSH tunnel handler. The first `444` correspond to the localport destination of `untrusted`, `@default` the remote machine and the second `444` to the remote machine port.
|
||||
|
||||
The service of `mytcp-service` running on port `444` is now accessible in `untrusted` as `localhost:444`.
|
||||
|
||||
@ -257,15 +256,16 @@ In order to allow a service present in a qube to be exposed to the outside world
|
||||
|
||||
As an example we can take the use case of a web server listening on port 443 that we want to expose on our physical interface eth0, but only to our local network 192.168.x.0/24.
|
||||
|
||||
> Note: To have all interfaces available and configured, make sure the 3 qubes are up and running
|
||||
- **Note:** To have all interfaces available and configured, make sure the 3 qubes are up and running
|
||||
|
||||
> Note: [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
|
||||
- **Note:** [Issue #4028](https://github.com/QubesOS/qubes-issues/issues/4028) discusses adding a command to automate exposing the port.
|
||||
|
||||
**1. Identify the IP addresses you will need to use for sys-net, sys-firewall and the destination qube.**
|
||||
|
||||
You can get this information from the Settings Window for the qube, or by running this command in each qube:
|
||||
`ifconfig | grep -i cast `
|
||||
Note the IP addresses you will need.
|
||||
|
||||
> Note: The vifx.0 interface is the one used by qubes connected to this netvm so it is _not_ an outside world interface.
|
||||
|
||||
**2. Route packets from the outside world to the FirewallVM**
|
||||
@ -280,23 +280,23 @@ iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 443 -d 192.168.x.y -j DNAT
|
||||
|
||||
Code the appropriate new filtering firewall rule to allow new connections for the service
|
||||
|
||||
```
|
||||
iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
|
||||
```
|
||||
```
|
||||
iptables -I FORWARD 2 -i eth0 -d 10.137.1.z -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
|
||||
```
|
||||
|
||||
> If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface.
|
||||
> In Qubes R4, at the moment ([QubesOS/qubes-issues#3644](https://github.com/QubesOS/qubes-issues/issues/3644)), nftables is also used which imply that additional rules need to be set in a `qubes-firewall` nft table with a forward chain.
|
||||
- If you want to expose the service on multiple interfaces, repeat the steps described in part 1 for each interface.
|
||||
- In Qubes R4, at the moment ([QubesOS/qubes-issues#3644](https://github.com/QubesOS/qubes-issues/issues/3644)), nftables is also used which imply that additional rules need to be set in a `qubes-firewall` nft table with a forward chain.
|
||||
|
||||
`nft add rule ip qubes-firewall forward meta iifname eth0 ip daddr 10.137.1.z tcp dport 443 ct state new counter accept`
|
||||
|
||||
Verify you are cutting through the sys-net VM firewall by looking at its counters (column 2)
|
||||
|
||||
```
|
||||
iptables -t nat -L -v -n
|
||||
iptables -L -v -n
|
||||
```
|
||||
```
|
||||
iptables -t nat -L -v -n
|
||||
iptables -L -v -n
|
||||
```
|
||||
- **Note:** On Qubes R4, you can also check the nft counters
|
||||
|
||||
> Note: On Qubes R4, you can also check the nft counters
|
||||
|
||||
```
|
||||
nft list table ip qubes-firewall
|
||||
@ -358,7 +358,9 @@ if ! iptables -w -n -L FORWARD | grep --quiet MY-HTTPS; then
|
||||
fi
|
||||
~~~
|
||||
|
||||
> Note: Again in R4 the following needs to be added:
|
||||
|
||||
- **Note:** Again in R4 the following needs to be added:
|
||||
|
||||
|
||||
~~~
|
||||
#############
|
||||
@ -389,9 +391,9 @@ Code the appropriate new filtering firewall rule to allow new connections for th
|
||||
iptables -I FORWARD 2 -i eth0 -s 192.168.x.0/24 -d 10.137.0.xx -p tcp --dport 443 -m conntrack --ctstate NEW -j ACCEPT
|
||||
```
|
||||
|
||||
> Note: If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 `
|
||||
- **Note:** If you do not wish to limit the IP addresses connecting to the service, remove the ` -s 192.168.0.1/24 `
|
||||
|
||||
> Note: On Qubes R4
|
||||
- **Note:** On Qubes R4
|
||||
|
||||
```
|
||||
nft add rule ip qubes-firewall forward meta iifname eth0 ip saddr 192.168.x.0/24 ip daddr 10.137.0.xx tcp dport 443 ct state new counter accept
|
||||
|
||||
@ -60,7 +60,7 @@ and then use it as an additional factor to login to your Qubes system.
|
||||
|
||||
> **Warning**: in the next session if incorrectly performed, there is the risk of locking yourself out. Before procedding ensure that you have an up-to-date backup.
|
||||
>
|
||||
> For advanced users, to make sure you can quickly recover, you can also open another loging session in a tty. To do this, you do <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F2</kbd> and login normally. Should anything go wrong, as long as you don't shut the computer down, you can still access this tty by entering the same key combination and reverting the changes. After you've opened this "backup" login, you can get to your graphical desktop with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F1</kbd>.
|
||||
> For advanced users, to make sure you can quickly recover, you can also open another loging session in a tty. To do this, you do `ctrl` + `alt` + `F2` and login normally. Should anything go wrong, as long as you don't shut the computer down, you can still access this tty by entering the same key combination and reverting the changes. After you've opened this "backup" login, you can get to your graphical desktop with `ctrl` + `alt` + `F1`.
|
||||
|
||||
Now we are going to add the authenticator as a login requirement:
|
||||
|
||||
@ -89,7 +89,7 @@ Now we are going to add the authenticator as a login requirement:
|
||||
sudo authselect select custom/mfa
|
||||
```
|
||||
|
||||
Now you can test by locking the screen with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>l</kbd>. If it was successful and you are pleased with the results, restart your computer.
|
||||
Now you can test by locking the screen with `ctrl` + `alt` + `l` . If it was successful and you are pleased with the results, restart your computer.
|
||||
|
||||
**Note**: When logging in. the first thing you put is the TOTP secret and then the password. This is true in the screen locker and as well as the session manager (the login window that shows right after you put the disk encryption passphrase).
|
||||
|
||||
@ -99,12 +99,12 @@ After this is done, its recommended to do a backup. This is because as long as y
|
||||
|
||||
The following assumes you haven't restarted your computer since setting up TOTP secret.
|
||||
|
||||
1. Switch to TTY2 with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F2</kbd>.
|
||||
1. Switch to TTY2 with `ctrl` + `alt` + `F2` .
|
||||
2. Revert to the original policy with:
|
||||
```
|
||||
sudo authselect select sssd
|
||||
```
|
||||
3. Switch back to the graphical desktop with <kbd>ctrl</kbd>+<kbd>alt</kbd>+<kbd>F1</kbd>. You should be able to login normally (without multi-factor authentication).
|
||||
3. Switch back to the graphical desktop with `ctrl` + `alt` + `F1` . You should be able to login normally (without multi-factor authentication).
|
||||
4. Change the mfa custom policy and apply it again.
|
||||
|
||||
#### Lost TOTP / authentication device?
|
||||
@ -157,30 +157,28 @@ Note that setting up both a YubiKey and a NitroKey3 is not supported.
|
||||
1. Install YubiKey / NitroKey3 software in the template on which your USB VM is based.
|
||||
Without this software the challenge-response / HOTP mechanism won't work.
|
||||
|
||||
- **YubiKey**
|
||||
|
||||
**YubiKey**
|
||||
|
||||
|
||||
For Fedora.
|
||||
- For Fedora.
|
||||
|
||||
```
|
||||
sudo dnf install ykpers
|
||||
```
|
||||
|
||||
For Debian.
|
||||
- For Debian.
|
||||
|
||||
```
|
||||
sudo apt-get install yubikey-personalization
|
||||
```
|
||||
|
||||
**NitroKey3**
|
||||
- **NitroKey3**
|
||||
|
||||
|
||||
Follow the installation instructions on the official [NitroKey
|
||||
- Follow the installation instructions on the official [NitroKey
|
||||
website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation).
|
||||
|
||||
|
||||
**WARNING**: *as of April 2024 the official instructions involve using pipx to
|
||||
- **WARNING**: *as of April 2024 the official instructions involve using pipx to
|
||||
install the pynitrokey package and its dependencies without any GPG
|
||||
verification! This is not a recommended practice, but will soon be
|
||||
fixed by NitroKey when they start providing release artifacts with
|
||||
@ -190,10 +188,10 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation).
|
||||
**Installing packages using pip or pipx is not recommended!**
|
||||
|
||||
|
||||
**both**
|
||||
- **both**
|
||||
|
||||
|
||||
Shut down your template. Then, either reboot your USB VM (so changes inside
|
||||
- Shut down your template. Then, either reboot your USB VM (so changes inside
|
||||
the template take effect in your USB app qube) or install the packages inside
|
||||
your USB VM as well if you would like to avoid rebooting it.
|
||||
|
||||
@ -207,16 +205,13 @@ website](https://docs.nitrokey.com/software/nitropy/all-platforms/installation).
|
||||
3. Configure your YubiKey / NitroKey3:
|
||||
|
||||
|
||||
**YubiKey**
|
||||
- **YubiKey**
|
||||
|
||||
|
||||
Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be
|
||||
- Configure your YubiKey for challenge-response `HMAC-SHA1` mode. This can be
|
||||
done on any qube, e.g. a disposable (you need to [attach the
|
||||
YubiKey](https://www.qubes-os.org/doc/how-to-use-usb-devices/) to this app qube
|
||||
though) or directly on the sys-usb vm.
|
||||
|
||||
|
||||
You need to (temporarily) install the package "yubikey-personalization-gui" and
|
||||
though) or directly on the sys-usb vm. You need to (temporarily) install the package "yubikey-personalization-gui" and
|
||||
run it by typing `yubikey-personalization-gui` in the command line.
|
||||
|
||||
- In the program go to `Challenge-Response`,
|
||||
@ -228,50 +223,52 @@ though) or directly on the sys-usb vm.
|
||||
to the vm,
|
||||
- press `Write Configuration` once you are ready.
|
||||
|
||||
**NitroKey3**
|
||||
- **NitroKey3**
|
||||
|
||||
|
||||
Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your
|
||||
- Set up a new NK3 Secrets App HOTP secret by attaching the NitroKey to your
|
||||
USB qube and running the following commands in it:
|
||||
|
||||
```
|
||||
AESKEY=$(echo -n "your-20-digit-secret" | base32)
|
||||
nitropy nk3 secrets register --kind hotp --hash sha256 --digits-str 8 --counter-start 1 --touch-button loginxs $AESKEY
|
||||
```
|
||||
Note that the 20 digit sequence can contain any printable ASCII character,
|
||||
|
||||
- Note that the 20 digit sequence can contain any printable ASCII character,
|
||||
e.g. letters, numbers, punctuation marks. The actual `Secret Key (base 32)`
|
||||
is the base32 encoded form of that sequence.
|
||||
|
||||
|
||||
**both**
|
||||
- **both**
|
||||
|
||||
|
||||
We will call the `Secret Key (20 bytes hex)` (YubiKey) or `Secret Key (base 32)` `AESKEY`.
|
||||
- We will call the `Secret Key (20 bytes hex)` (YubiKey) or `Secret Key (base 32)` `AESKEY`.
|
||||
|
||||
- It is recommended to keep a backup of your `AESKEY` in an offline VM used as a vault.
|
||||
- Consider keeping a backup of your `AESKEY` on paper and storing it in a safe place.
|
||||
- If you have multiple YubiKeys for backup purposes (in case one gets
|
||||
lost, stolen or breaks) you can write the same settings into other
|
||||
YubiKeys. For YubiKeys you can choose "Program multiple YubiKeys" in the program;
|
||||
YubiKeys. For YubiKeys you can choose "Program multiple YubiKeys" in the program;
|
||||
make sure to select `Same secret for all keys` in this case. For NitroKeys you can set up
|
||||
the secret for multiple of them, but you must always use the same NitroKey, because the
|
||||
HOTP counter will be incremented in dom0 as well as the used NitroKey whenever you make use
|
||||
of this method. If you want to switch to a different NitroKey later, delete the file
|
||||
`/etc/qubes/yk-keys/nk-hotp-counter` in dom0 first to make it work with a fresh NitroKey 3.
|
||||
Do the same if for some reason your counters get desynchronized (it stops working), e.g. due
|
||||
to connectivity issues (NitroKey3A Minis are known to wear out quickly).
|
||||
the secret for multiple of them, but you must always use the same NitroKey, because the
|
||||
HOTP counter will be incremented in dom0 as well as the used NitroKey whenever you make use
|
||||
of this method. If you want to switch to a different NitroKey later, delete the file
|
||||
`/etc/qubes/yk-keys/nk-hotp-counter` in dom0 first to make it work with a fresh NitroKey 3.
|
||||
Do the same if for some reason your counters get desynchronized (it stops working), e.g. due
|
||||
to connectivity issues (NitroKey3A Minis are known to wear out quickly).
|
||||
|
||||
4. **YubiKey**
|
||||
|
||||
|
||||
Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
|
||||
- Paste your `AESKEY` into `/etc/qubes/yk-keys/yk-secret-key.hex` in dom0.
|
||||
Note that if you had previously used a NitroKey3 with this package, you *must* delete
|
||||
the file `/etc/qubes/yk-keys/nk-hotp-secret` or its content!
|
||||
|
||||
|
||||
**NitroKey3**
|
||||
- **NitroKey3**
|
||||
|
||||
|
||||
Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY`
|
||||
- Create the file `/etc/qubes/yk-keys/nk-hotp-secret` in dom0 and paste your `AESKEY`
|
||||
(in base 32 format) into it.
|
||||
|
||||
5. As mentioned before, you need to define a new password that is only used in
|
||||
@ -280,11 +277,11 @@ to connectivity issues (NitroKey3A Minis are known to wear out quickly).
|
||||
ultimately trusted anyway.
|
||||
|
||||
|
||||
However, if you prefer you can paste a hashed password instead into
|
||||
- However, if you prefer you can paste a hashed password instead into
|
||||
`/etc/qubes/yk-keys/login-pass-hashed.hex` in dom0.
|
||||
|
||||
|
||||
You can calculate your hashed password using the following two commands.
|
||||
- You can calculate your hashed password using the following two commands.
|
||||
First run the following command to store your password in a temporary variable `password`.
|
||||
(This way your password will not leak to the terminal command history file.)
|
||||
|
||||
@ -292,7 +289,7 @@ ultimately trusted anyway.
|
||||
read -r password
|
||||
```
|
||||
|
||||
Now run the following command to calculate your hashed password.
|
||||
- Now run the following command to calculate your hashed password.
|
||||
|
||||
```
|
||||
echo -n "$password" | openssl dgst -sha1 | cut -f2 -d ' '
|
||||
|
||||
@ -295,8 +295,7 @@ In this example, the following keys are stored in the following locations (see b
|
||||
| `ssb` | `work-gpg` |
|
||||
| `pub` | `work-email` |
|
||||
|
||||
* `sec` (master secret key)
|
||||
|
||||
- `sec` (master secret key)
|
||||
|
||||
* Depending on your needs, you may wish to create this as a **certify-only (C)** key, i.e., a key which is capable only of signing (a.k.a., "certifying") other keys.
|
||||
This key may be created *without* an expiration date.
|
||||
@ -313,8 +312,7 @@ In this example, the following keys are stored in the following locations (see b
|
||||
Therefore, using a passphrase at all should be considered optional.
|
||||
It is, however, recommended that a **revocation certificate** be created and safely stored in multiple locations so that the master keypair can be revoked in the (exceedingly unlikely) event that it is ever compromised.
|
||||
|
||||
* `ssb` (secret subkey)
|
||||
|
||||
- `ssb` (secret subkey)
|
||||
|
||||
* Depending on your needs, you may wish to create two different subkeys: one for **signing (S)** and one for **encryption (E)**.
|
||||
You may also wish to give these subkeys reasonable expiration dates (e.g., one year).
|
||||
@ -328,30 +326,26 @@ In this example, the following keys are stored in the following locations (see b
|
||||
This can be problematic, since there is no consensus on how expired signatures should be handled.
|
||||
Generally, digital signatures are intended to last forever, so this is a strong reason against regularly retiring one's signing subkeys.
|
||||
|
||||
* `pub` (public key)
|
||||
|
||||
- `pub` (public key)
|
||||
|
||||
* This is the complement of the master secret key.
|
||||
It can be uploaded to keyservers (or otherwise publicly distributed) and may be signed by others.
|
||||
|
||||
* `vault`
|
||||
|
||||
- `vault`
|
||||
|
||||
* This is a network-isolated VM.
|
||||
The initial master keypair and subkeys are generated in this VM.
|
||||
The master secret key *never* leaves this VM under *any* circumstances.
|
||||
No files or text is *ever* [copied](/doc/how-to-copy-and-move-files/#security) or [pasted](/doc/how-to-copy-and-paste-text/#security) into this VM under *any* circumstances.
|
||||
|
||||
* `work-gpg`
|
||||
|
||||
- `work-gpg`
|
||||
|
||||
* This is a network-isolated VM.
|
||||
This VM is used *only* as the GPG backend for `work-email`.
|
||||
The secret subkeys (but *not* the master secret key) are [copied](/doc/how-to-copy-and-move-files/#security) from the `vault` VM to this VM.
|
||||
Files from less trusted VMs are *never* [copied](/doc/how-to-copy-and-move-files/#security) into this VM under *any* circumstances.
|
||||
|
||||
* `work-email`
|
||||
|
||||
- `work-email`
|
||||
|
||||
* This VM has access to the mail server.
|
||||
It accesses the `work-gpg` VM via the Split GPG protocol.
|
||||
|
||||
@ -79,9 +79,9 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
|
||||
|
||||
certutil -hashfile C:\qubes-tools-4.0.1.3.exe SHA256
|
||||
|
||||
And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support.
|
||||
- And compare it the value to `148A2A993F0C746B48FA6C5C9A5D1B504E09A7CFBA3FB931A4DCF86FDA4EC9B1` (**it has to exactly match for security reasons**). If it matches, feel free to continue the installation. If not, repeat the download to make sure it was not corrupted due to a network problem. If keeps on not matching it might be an attacker attempting to do something nasty to your system -- Ask for support.
|
||||
|
||||
**Note**: This is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken.
|
||||
- **Note**: This is a workaround for installing the qubes windows tools on windows 10 since the standard way is broken.
|
||||
|
||||
7. Install Qubes Windows Tools 4.0.1.3 by starting `qubes-tools-4.0.1.3.exe`, not selecting the `Xen PV disk drivers` and the `Move user profiles` (which would probably lead to problems in Windows, anyhow). If during installation, the Xen driver requests a reboot, select "No" and let the installation continue - the system will be rebooted later.
|
||||
|
||||
@ -98,7 +98,9 @@ This will allow you to install the Qubes Windows Tools on Windows 10 both as a S
|
||||
|
||||
12. Lastly to enable file copy operations to a Windows 10 VM the `default_user` property should be set the `<username>` that you use to login to the Windows VM. This can be done via the following command on a `dom0` terminal: *(where `<VMname>` is the name of your Windows 10 VM)*
|
||||
|
||||
`qvm-prefs <VMname> default_user <username> `
|
||||
```
|
||||
qvm-prefs <VMname> default_user <username>
|
||||
```
|
||||
|
||||
**Note:** If this property is not set or set to a wrong value, files copied to this VM are stored in the folder
|
||||
|
||||
@ -333,7 +335,7 @@ If the VM is inaccessible (doesn't respond to qrexec commands, gui is not functi
|
||||
Safe Mode should at least give you access to logs (see above).
|
||||
|
||||
**Please include appropriate logs when reporting bugs/problems.** Starting from version 2.4.2 logs contain QWT version, but if you're using an earlier version be sure to mention which one. If the OS crashes (BSOD) please include the BSOD code and parameters in your bug report. The BSOD screen should be visible if you run the VM in debug mode (`qvm-start --debug vmname`). If it's not visible or the VM reboots automatically, try to start Windows in safe mode (see above) and 1) disable automatic restart on BSOD (Control Panel - System - Advanced system settings - Advanced - Startup and recovery), 2) check the system event log for BSOD events. If you can, send the `memory.dmp` dump file from `c:\Windows`.
|
||||
Xen logs (/var/log/xen/console/guest-*) are also useful as they contain pvdrivers diagnostic output.
|
||||
Xen logs (`/var/log/xen/console/guest-*`) are also useful as they contain pvdrivers diagnostic output.
|
||||
|
||||
If a specific component is malfunctioning, you can increase its log verbosity as explained above to get more troubleshooting information. Below is a list of components:
|
||||
|
||||
|
||||
@ -62,10 +62,7 @@ Unofficial “debloated” ISOs from projects like reviOS 18 or ameliorated 10 c
|
||||
|
||||
Create a VM named WindowsNew in [HVM](/doc/hvm/) mode (Xen's current PVH limitations precludes from using PVH). This can be done in either of two ways:
|
||||
|
||||
- Using Qube Manager
|
||||
|
||||
|
||||
In order to create the new qube, select the command Qube -> New Qube in the Qube Manager:
|
||||
- Using Qube Manager: In order to create the new qube, select the command Qube -> New Qube in the Qube Manager:
|
||||
|
||||
- Name: `WindowsNew`, Color: `orange` (for a standalone qubes, `black` for a template)
|
||||
- Type: `StandaloneVM (fully persistent)` or `TemplateVM (template home, persistent root)`
|
||||
@ -73,7 +70,6 @@ Create a VM named WindowsNew in [HVM](/doc/hvm/) mode (Xen's current PVH limitat
|
||||
- Networking: `sys-firewall (default)`
|
||||
- Launch settings after creation: check
|
||||
- Click "OK".
|
||||
|
||||
- Settings:
|
||||
- Basic:
|
||||
- System storage: 60.0+ GB
|
||||
@ -171,7 +167,7 @@ These parameters are set for the following reasons:
|
||||
</div>
|
||||
|
||||
|
||||
The installation of Windows 11 may require an internet connection to grab a Microsoft ID. This is currently true only for the home addition, but will probably extend to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that currently works for version 21H2 but may be blocked some time in the future by Microsoft:
|
||||
- The installation of Windows 11 may require an internet connection to grab a Microsoft ID. This is currently true only for the home addition, but will probably extend to the Pro edition, too. A workaround to bypass the internet connection requirements of the Windows 11 setup has been published that currently works for version 21H2 but may be blocked some time in the future by Microsoft:
|
||||
|
||||
- When you reach the “Let’s Connect You To A Network” page, type Shift-F10 to open a console window.
|
||||
- Here you type `taskmgr` to start the Task Manager window so you can see all running processes.
|
||||
@ -179,7 +175,7 @@ These parameters are set for the following reasons:
|
||||
- Select this process and then hit the “End Task” button.
|
||||
- Now you can close these newly opened windows and return to the Windows 11 setup, where you will enter local account information.
|
||||
|
||||
For Windows 11 version 22H2, the following sequence of actions to use a local account instead of a Microsoft account has been published:
|
||||
- For Windows 11 version 22H2, the following sequence of actions to use a local account instead of a Microsoft account has been published:
|
||||
|
||||
- Enter `no@thankyou.com` (or some other senseless address) as the email address and click `Next` when Windows 11 setup prompts you to log into your Microsoft account.
|
||||
- Enter any text you want in the password field and click `Sign in`. If this method works, you'll get a message saying "Oops, something went wrong."
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user