diff --git a/docs/entitydb/format-rules.md b/docs/entitydb/format-rules.md new file mode 100644 index 0000000..246ee8c --- /dev/null +++ b/docs/entitydb/format-rules.md @@ -0,0 +1,34 @@ + +# Format and Rules + +## Language +In edb JSON is used to describe the entities. Each entity has a JSON file in the format: `.json`, where `` is the name of the entity. This file may contain the following characters: + - `a-z` + - `0-9` + - `_` + - `-` + +The entity must not be `schema`. + +## Indentation +An indentation of two spaces is used. Each entity must be formatted correctly. You can use a tool like jq or [jsonlint.com](https://jsonlint.com/) for this. + +## Format verification +In the `schema.json` a schema with the format for the JSON files is defined. A check can be done for example with the Python tool `check-jsonschema`: +``` +check-jsonschema --schemafile schema.json entity.json +``` + +## Availability +The edb is hosted by [Codeberg](https://codeberg.org/). The edb uses git for version control. + +## Propose changes / registration +To propose a change or to register in the edb, you have to fork the repository, make your changes and then request a PR. + +## Scripts +The edb repository currently contains two different scripts: +| `test.sh` | Tests the JSON files for validity | +| `build_maxlen_filter.sh` | Builds a bird-compatible filter list | + +## License +The edb is available under the AGPL v3 license. More information is available in the `LICENSE.md` in the repository of the edb. diff --git a/docs/entitydb/index.md b/docs/entitydb/index.md new file mode 100644 index 0000000..6d1a715 --- /dev/null +++ b/docs/entitydb/index.md @@ -0,0 +1,12 @@ + +# entitydb + +Note: This documentation is in WIP. + +In entitydb, the persons or organizations are registered in CRXN with their IP addresses. Here, each entity has a JSON file in which the data is recorded. The entitydb is also abbreviated as edb. + +- [Format and Rules](format-rules) + +Attributes: + - route + - [max-len](maxlen) diff --git a/docs/entitydb/maxlen.md b/docs/entitydb/maxlen.md new file mode 100644 index 0000000..a087fbe --- /dev/null +++ b/docs/entitydb/maxlen.md @@ -0,0 +1,22 @@ +# max-len filter + +## What is a max-len filter? +By default, a prefix can be divided into any number of /64 blocks. By a `max-len` one can define the maximum size of a prefix of a subnet. For example, if you want to divide your subnet into /56 blocks, you can set the `max-len` to 56. This will filter all larger prefixes (e.g. `/60` or `/64`) from that subnet. + +## Why is this important? +The principle of [longest prefix match](https://en.wikipedia.org/wiki/Longest_prefix_match) applies. This means that the largest and thus most accurate prefix is always selected. If an attacker now wants to hijack an IP address, one can propagate a larger prefix that contains the IP address. This means that the packets are now forwarded to them instead of the actual operator of the prefix. To fend off such attacks, it is necessary to filter more accurate prefixes. However, since each operator wants to propagate a different prefix size, the `max-len` can be set in the entitydb. If no `max-len` is specified, 64 is assumed. + +## Where do I have to enter this in the edb? + +``` +"route": { + "/48": { + "description": "", + "max-len": "", + "device": { + "": { } + } + } +} +``` +Under `route`/`IP-Address` you create an attribute `max-len` of type string with the maximum length like `56` or `48`. diff --git a/docs/routing/bird_alternative.md b/docs/routing/bird/bird-alternative.md similarity index 100% rename from docs/routing/bird_alternative.md rename to docs/routing/bird/bird-alternative.md diff --git a/docs/routing/bird.md b/docs/routing/bird/bird.md similarity index 99% rename from docs/routing/bird.md rename to docs/routing/bird/bird.md index 8653993..d187674 100644 --- a/docs/routing/bird.md +++ b/docs/routing/bird/bird.md @@ -17,7 +17,7 @@ now have support for it. ## Alternative bird configuration -A guide to an alternative configuration with similar functionality can be found at [here](bird_alternative). +A guide to an alternative configuration with similar functionality can be found at [here](bird-alternative). ## Installation diff --git a/docs/routing/bird/index.md b/docs/routing/bird/index.md new file mode 100644 index 0000000..1cc986a --- /dev/null +++ b/docs/routing/bird/index.md @@ -0,0 +1,6 @@ + +# bird routing daemon + +- [Configuring Bird2](bird) +- [Alternative bird configuration](bird-alternative) +- [`max-len` filter](maxlen-filter) diff --git a/docs/routing/bird/maxlen-filter.md b/docs/routing/bird/maxlen-filter.md new file mode 100644 index 0000000..0a0d379 --- /dev/null +++ b/docs/routing/bird/maxlen-filter.md @@ -0,0 +1,23 @@ + +# Implement max-len filter + +To implement a max-length filter, we need a rule/policy/filter file that contains the corresponding prefixes with their maximum length. The entitydb contains a bash script `build_maxlen_filter.sh` for this purpose. If you run this script, you will get a bird-compatible list. + +``` +define CRXN_IPs = [ + include ""; +]; + +function is_crxn_net() { + return net ~ CRXN_IPs; +} +``` +This bird configuration can be used to load the file. You have to replace `` with the path of the filter file. The function `is_crxn_net` then checks whether a route complies with the rules or not. + +``` +if (! is_crxn_net() ) then { + print "[CRXN] Invalid crxn route: ", net; + reject; +} +``` +This configuration can then be added to your import filter before 'accept'. The line with `print` is optional. If you leave this line, every hjack attempt will be logged in the bird log output. diff --git a/mkdocs.yml b/mkdocs.yml index 06d41a0..6ae1e66 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -13,7 +13,7 @@ nav: - Routing: - Fowarding: routing/forwarding - - Setting up Bird: routing/bird + - Setting up Bird: routing/bird/bird - Tunneling: - Fastd: tunneling/fastd