Git-Mirrors/qubes-doc
1
0
Fork 0
mirror of https://github.com/QubesOS/qubes-doc.git synced 2024-10-01 01:25:40 -04:00
Code Issues Packages Projects Releases Wiki Activity

Add documentation for policy admin API

Browse Source
This commit is contained in:
Paweł Marczewski 2020-08-25 13:30:14 +02:00
parent b894253c40
commit e7a882a497
No known key found for this signature in database
GPG Key ID: DE42EE9B14F96465
1 changed files with 31 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
developer/services/admin-api.md
View File

@ -306,9 +306,39 @@ destination_path: ncftpput -u my-ftp-username -p my-ftp-pass -c my-ftp-server /d
- closing qrexec connection normally does _not_ interrupt running operation; this is important to avoid leaving the system in inconsistent state
- actual operation starts only after caller send all the parameters (including a payload), signaled by sending EOF mark; there is no support for interactive protocols, to keep the protocol reasonable simple
## Policy admin API
There is also an API to view and update [Qubes RPC policy files](/doc/qrexec) in dom0. All of the following calls have dom0 as destination:
| call | argument | inside | return |
| ---------------------------------------------- | ---- | -------------------- | ----------------------- |
| `policy.List` <br> `policy.include.List` | - | - | `<name1>\n<name2>\n...` |
| `policy.Get` <br> `policy.include.Get` | name | - | `<token>\n<content>` |
| `policy.Replace` <br> `policy.include.Replace` | name | `<token>\n<content>` | - |
| `policy.Remove` <br> `policy.include.Remove` | name | `<token>` | - |
The `policy.*` calls refer to main policy files (`/etc/qubes/policy.d/`), and
the `policy.include.*` calls refer to the include directory
(`/etc/qubes/policy.d/include/`). The `.policy` extension for files in the main
directory is always omitted.
The responses do not follow admin API protocol, but signal error using an exit
code and a message on stdout.
The changes are validated before saving, so that the policy cannot end up in an
invalid state (e.g. syntax error, missing include file).
In addition, there is a mechanism to prevent concurrent modifications of the policy files:
- A `*.Get` call returns a file along with a *token* (currently implemented as
a hash of the file).
- When calling `Replace` or `Remove`, you need to include the current token as
first line. If the token does not match, the modification will fail.
- When adding a new file using `Replace`, pass `new` as token. This will ensure
that the file does not exist before adding.
- To skip the check, pass `any` as token.
## TODO
- something to configure/update policy
- notifications
- how to constrain the events?
- how to pass the parameters? maybe XML, since this is trusted anyway and