Commit 8ed28132 authored by Jakob Olsson's avatar Jakob Olsson

add README.md

parent 3c7d9976
Pipeline #980 passed with stages
in 1 minute and 21 seconds
# Remote Procedure Call Daemon
The remote procedure call daemon, RPCD, is a multipurpose daemon exposing
session management and UCI configuration to ubus. RPCD implements methods to
restrict users access to uci and ubus, by assigning each login to an access
list, based on the user, and a session ID.
Additionally, RPCD supports additional features and may the binaries iwinfo,
rpc-sys and file may be selected and compiled.
## Overview
With the main responsibilities of RPCD being session management and exposing
UCI over ubus, one API is exposed for each.
### Session
The sessions are dependent on several configuration files, reading standard UCI
files to map available logins to passwords and access lists.
#### Access Lists
The access lists are provided in a JSON format and found under the
path `/usr/share/rpcd/acl.d/`. Each access list should have a root key which
is an identifier for the list, under the root key identifier, read and write
access may be provided in `read` and/or `write` keys. Note that write access
does not imply read access, i.e. allowing write access to a uci configuration
does not give access to read the uci configuration. The `write` and `read` keys
expect four potential sub-keys:
1. `ubus` - An object containing keys representing ubus objects, listing the
accessible methods in an array.
2. `uci` - An array with names of UCI configuration files to which access is
granted.
3. `owsd` - An array of event types which may be subscribed to through RPC.
4. `uci_granular` - An object containing keys representing configuration files,
each sub-key being arrays of objects, holding match criteria in a `match` key,
and option permissions in an `option` key.
##### UCI Granular Access Lists
The uci granular access control offers increased control over what users are
able to see, add or change through RPCD's `uci` object, published on ubus.
The UCI granular control is implemented ontop of the existing RPCD access
control list functionality (`/usr/share/rpcd/acl.d/`), by defining a
`uci_granular` object. In the `uci_granular` object, configuration file names
are used as keys to arrays, holding permission objects for the corresponding
configuration file. A permission object should contain a `match` object,
specifying what options, section types or section names (or any combination
thereof) on which the restriction should be applied to. Secondly, a permission
object can contain an `option` array, specifying which options that should be
made accessible. If an option array is not specified, or `*` is listed,
unrestricted access is granted to matching sections, meaning the user may `get`,
`set`, `add`, `delete` etc. freely (assuming the access control list is provided
as a `write` list). If options are listed, the user will only be able to get or
set those options, and have no other section access.
It is possible for a user to belong to several access groups with unique access
restrictions, in which case the access for that user will be a union of the
restrictions.
###### Example
The following example restricts access to the wireless configuration,
having two different restriction criterias:
* Allow access to the two options `ssid` and `key` in sections of type
`wifi-iface`, which ALSO contain the key `network`, set to `lan`.
* Allow access to the option `channel`, for all sections ioofhe type
`wifi-device`.
Seeing as these granular access lists are done on a whitelist basis, no other
access is granted to the configuration.
```
"uci_granular":{
"wireless" : [
{
"match" : {
".type" : "wifi-iface",
"network" : "lan"
},
"option" : [
"ssid",
"key"
]
},
{
"match" : {
".type" : "wifi-device"
},
"option" : [
"channel"
]
}
]
}
```
#### Ubus API
A verbose print of the session object API exposed on ubus by RPCD:
```
'session' @46921633
"create":{"timeout":"Integer"}
"list":{"ubus_rpc_session":"String"}
"grant":{"ubus_rpc_session":"String","scope":"String","objects":"Array"}
"revoke":{"ubus_rpc_session":"String","scope":"String","objects":"Array"}
"access":{"ubus_rpc_session":"String","scope":"String","object":"String","function":"String"}
"set":{"ubus_rpc_session":"String","values":"Table"}
"get":{"ubus_rpc_session":"String","keys":"Array"}
"unset":{"ubus_rpc_session":"String","keys":"Array"}
"destroy":{"ubus_rpc_session":"String"}
"login":{"username":"String","password":"String","timeout":"Integer"}
```
### UCI
The second ubus object published by rpcd, `uci`, implements the C library,
`libuci` on ubus. The ubus object, mimics the functionality of the `uci`
binaries, with some additions, such as session support, and it is all done in
JSON format.
#### Ubus API
A verbose print of the uci object API exposed on ubus by RPCD:
```
'uci' @26773c4a
"configs":{}
"get":{"config":"String","section":"String","option":"String","type":"String","match":"Table","ubus_rpc_session":"String"}
"state":{"config":"String","section":"String","option":"String","type":"String","match":"Table","ubus_rpc_session":"String"}
"add":{"config":"String","type":"String","name":"String","values":"Table","ubus_rpc_session":"String"}
"set":{"config":"String","section":"String","type":"String","match":"Table","values":"Table","ubus_rpc_session":"String"}
"delete":{"config":"String","section":"String","type":"String","match":"Table","option":"String","options":"Array","ubus_rpc_session":"String"}
"rename":{"config":"String","section":"String","option":"String","name":"String","ubus_rpc_session":"String"}
"order":{"config":"String","sections":"Array","ubus_rpc_session":"String"}
"changes":{"config":"String","ubus_rpc_session":"String"}
"revert":{"config":"String","ubus_rpc_session":"String"}
"commit":{"config":"String","ubus_rpc_session":"String"}
"apply":{"rollback":"Boolean","timeout":"Integer","ubus_rpc_session":"String"}
"confirm":{"ubus_rpc_session":"String"}
"rollback":{"ubus_rpc_session":"String"}
"reload_config":{}
```
### UCI Configuration
The RPCD configuration file, found at `/etc/config/rpcd`. The following is an
example that creates one login for the user `user` for RPCD, mirroring the
password of the user from `/etc/shadow`, applying the access lists user
and unauthenticated to the user.
```
config login
option username 'user'
option password '$p$user'
list write 'user'
list write 'unauthenticated'
```
## Tests
This section will give a brief overview of the tests for the granular access
control.
Currently, only the granular access control is tested through the gitlab-ci
pipeline, as this is the major addition created by IOPSYS, ontop of the base
OpenWrt RPCD.
The tests exercise every uci functioon thoroughly, verifying that old UCI
behavior is maintained (i.e. no session should have full access, no granular
access list specified should have full access), and new functionality adheres to
the specification. Tests are performed on multiple `uci` methods callbacks,
which are published on ubus, and some more generic setup functions. All done as
unit tests by compiling a shared library of the project source files.
The methods tested are primarily the UCI object methods:
1. `get`
2. `set`
3. `add`
4. `delete`
5. `rename`
For all of the methods above the tests exercise several variations of input,
i.e. by setting `type`, `name`, `option`, and any valid combination, depending
on the method requirements on input.
Additional all tests have false positives test cases.
## Dependencies
To successfully build RPCD, the following libraries are needed:
| Dependency | Link | License |
| ----------------- | ---------------------------------------------------------------- | -------------- |
| libuci | https://git.openwrt.org/project/uci.git | LGPL 2.1 |
| libubox | https://git.openwrt.org/project/libubox.git | BSD |
| libubus | https://git.openwrt.org/project/ubus.git | LGPL 2.1 |
| libjson-c | https://s3.amazonaws.com/json-c_releases | MIT |
| libcrypt | https://dev.gnupg.org/source/libgcrypt/ | LGPL |
| libblobmsg_json | | |
Additionally, in order to build with the tests, the following libraries are needed:
| Dependency | Link | License |
| ------------------------- | --------------------------------------------------------- | ------------- |
| libjson-editor | https://dev.iopsys.eu/iopsys/json-editor | |
\ No newline at end of file
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment