--- /dev/null
+---
+title: Incidence
+---
+
+[Documentation](index.html) > {{ page.title }}
+
+# {{ page.title }}
+
+## Index
+
+1. [Introduction](#introduction)
+2. [`incidences` definition](#incidences-definition)
+3. [Incidence types](#incidence-types)
+ 1. [rsaEncryption signature algorithm has parameters](#rsaencryption-signature-algorithm-has-parameters)
+ 2. [certificate public key algorithm is rsaEncryption](#certificate-public-key-algorithm-is-rsaencryption)
+
+## Introduction
+
+The RPKI RFCs define fairly strict profiles for RPKI objects, and are unequivocal in stating that incorrectly-formed objects are supposed to be rejected by Relying Party validation. In practice, however, this does not stop a significant amount of Certificate Authorities from issuing incorrect objects.
+
+By default, Fort is as pedantic as it can reasonably be. The `incidence` section of its configuration file is a means to modify its behavior upon encountering profile violations that, from experience, are often overlooked.
+
+## `incidences` definition
+
+`incidences` is a JSON array that contains (anonymous) incidence elements. Here's an example:
+
+```
+"incidences": [
+ {
+ "name": "rsaEncryption signature algorithm has parameters",
+ "action": "warn"
+ }, {
+ "name": "certificate public key algorithm is rsaEncryption",
+ "action": "ignore"
+ }
+]
+```
+
+`name` is the identifier of an incidence. It's case-sensitive and developer-defined. It states the particular error condition that will be handled by the remaining field.
+
+`action` is an enumeration that states the outcome of a violation of the corresponding incidence. It can take one of three values:
+
+1. `error`: Print error message in `error` log level, fail validation of the offending object (and all of its children).
+2. `warn`: Print error message in `warning` log level, continue validation as if nothing happened.
+3. `ignore`: Do not print error message, continue validation as if nothing happened.
+
+By Fort's pedantic nature, most incidences have an `action` of `error` by default.
+
+## Incidence types
+
+Presently, there are only two incidence types defined. This list might grow over time, depending on the state of the global RPKI and user demand.
+
+### rsaEncryption signature algorithm has parameters
+
+[RFC 6488](https://tools.ietf.org/html/rfc6488) (RPKI Signed Objects) defers signature algorithm specification to RFC 6485:
+
+```
+2.1.6.5. signatureAlgorithm
+
+ The signatureAlgorithm MUST conform to the RPKI Algorithms and Key
+ Size Profile specification [RFC6485].
+```
+
+[6485](https://tools.ietf.org/html/rfc6485) has been obsoleted by [7935](https://tools.ietf.org/html/rfc7935), which states the following:
+
+```
+ RPKI implementations MUST
+ accept either rsaEncryption or sha256WithRSAEncryption for the
+ SignerInfo signatureAlgorithm field when verifying CMS SignedData
+ objects (for compatibility with objects produced by implementations
+ conforming to [RFC6485]).
+```
+
+Regarding `rsaEncryption`, [3370](https://tools.ietf.org/html/rfc3370) states
+
+```
+ When the rsaEncryption algorithm identifier is used, the
+ AlgorithmIdentifier parameters field MUST contain NULL.
+```
+
+As of 2019-05-21, many signed objects in the global RPKI break this rule. (`parameters` is often defined as an empty object, but not NULL nonetheless.)
+
+If not `ignore`d, Fort will report this incidence with the following error message:
+
+```
+<log level>: <offending file name>: rsaEncryption signature algorithm has parameters.
+```
+
+### certificate public key algorithm is rsaEncryption
+
+> TODO missing code
--- /dev/null
+---
+title: SLURM
+---
+
+[Documentation](index.html) > {{ page.title }}
+
+# {{ page.title }}
+
+## Introduction
+
+There are reasons why you might legitimately want to modify the RPKI assertions validated and published by an RTR server:
+
+- To assert the validity of private IP addresses and/or AS numbers for local use. (Since they are outside of the scope of the global RPKI.)
+- To override temporarily incorrect or outdated global RPKI data.
+
+The "Simplified Local Internet Number Resource Management with the RPKI" (SLURM) is a [standard](https://tools.ietf.org/html/rfc8416) means to accomplish this. In a nutshell, it's just a bunch of JSON files with which you can filter out or append arbitrary ROAs to Fort's RTR payload.
+
+Note that, with the exception of the following section, most of this document is just a summary of [RFC 8416](https://tools.ietf.org/html/rfc8416). You can find more details there.
+
+## Handling of SLURM Files
+
+The SLURM files are defined by the [`--slurm`](usage.html#--slurm) flag. If the flag points to a file, the configuration is extracted from that single file. If it points to a directory, the configuration is the aggregation of its contained files' contents.
+
+> TODO: are the children filtered by extension?
+
+None of the entries of the SLURM configuration are allowed to collide with each other. If there is a collision, the overall SLURM configuration is rejected.
+
+Fort reloads the SLURM files during every validation cycle. If the new configuration is invalid, **it is treated as nonexistent**. Note that this means that an isolated mistake will temporarily drop all your SLURM overrides. This is intended to change in a future revision of Fort, in which the validator will fall back to the previous valid SLURM configuration on error.
+
+> TODO: open an issue for that. Giving the users the opportunity to argue it is probably a good idea.
+
+## SLURM File Definition
+
+### Root
+
+Each SLURM file is a JSON-formatted collection of filters and/or additions. Each of the members shown is mandatory:
+
+```
+{
+ "slurmVersion": 1,
+
+ "validationOutputFilters": {
+ "prefixFilters": [ <Removed ROAs> ],
+ "bgpsecFilters": []
+ },
+
+ "locallyAddedAssertions": {
+ "prefixAssertions": [ <Added ROAs> ],
+ "bgpsecAssertions": []
+ }
+}
+```
+
+The root object contains a `slurmVersion` field (which, for now, must be set to 1), a listing of filters called `validationOutputFilters`, and a listing of additions called `locallyAddedAssertions`. Fort does not yet support BGPsec, so `bgpsecFilters` and `bgpsecAssertions` must be empty.
+
+### `prefixFilters`
+
+`<Removed ROAs>` expands to a sequence of (zero or more) JSON objects, each of which follows this pattern:
+
+```
+{
+ "prefix": <IP prefix>,
+ "asn": <AS number>,
+ "comment": <Explanatory comment; ignored by Fort for now>
+}
+```
+
+Any ROAs that match `prefix` and `asn` will be invalidated. A ROA matches `prefix` by having an equal or more specific IP prefix, and `asn` by having the same AS number.
+
+One of `prefix` and `asn` can be absent. On absence, any prefix matches `prefix`, and any AS number matches `asn`.
+
+`comment` is always optional.
+
+### `prefixAssertions`
+
+`<Added ROAs>` expands to a sequence of (zero or more) JSON objects, each of which follows this pattern:
+
+```
+{
+ "prefix": <IP prefix>,
+ "asn": <AS number>,
+ "maxPrefixLength": <Prefix length>
+ "comment": <Explanatory comment; ignored by Fort for now>
+}
+```
+
+Will force Fort into believing that the [`prefix`, `asn`, `maxPrefixLength`] ROA validated successfully.
+
+`prefix` and `asn` are mandatory, `maxPrefixLength` and `comment` are not. `maxPrefixLength` defaults to `prefix`'s length.
+
+## SLURM File Example
+
+```
+{
+ "slurmVersion": 1,
+
+ "validationOutputFilters": {
+ "prefixFilters": [
+ {
+ "prefix": "192.0.2.0/24",
+ "comment": "All VRPs encompassed by prefix"
+ }, {
+ "asn": 64496,
+ "comment": "All VRPs matching ASN"
+ }, {
+ "prefix": "198.51.100.0/24",
+ "asn": 64497,
+ "comment": "All VRPs encompassed by prefix, matching ASN"
+ }
+ ],
+ "bgpsecFilters": []
+ },
+
+ "locallyAddedAssertions": {
+ "prefixAssertions": [
+ {
+ "asn": 64496,
+ "prefix": "198.51.100.0/24",
+ "comment": "My important route"
+ }, {
+ "asn": 64496,
+ "prefix": "2001:DB8::/32",
+ "maxPrefixLength": 48,
+ "comment": "My important de-aggregated routes"
+ }
+ ],
+ "bgpsecAssertions": []
+ }
+ }
+```
---
-title: Validator Usage
+title: Fort Usage
command: fort
---
+[Documentation](index.html) > {{ page.title }}
+
# {{ page.title }}
## Index
17. [`rsync.program`](#rsyncprogram)
18. [`rsync.arguments-recursive`](#rsyncarguments-recursive)
19. [`rsync.arguments-flat`](#rsyncarguments-flat)
+ 20. [`incidences`](#incidences)
## Syntax
### `--help`
-- Type: None
-- Availability: `argv` only
+- **Type:** None
+- **Availability:** `argv` only
-Prints medium-sized usage message.
+Prints medium-sized syntax remainder message.
{% highlight bash %}
$ {{ page.command }} --help
### `--usage`
-- Type: None
-- Availability: `argv` only
+- **Type:** None
+- **Availability:** `argv` only
-Prints small-sized help message.
+Prints small-sized syntax remainder message.
{% highlight bash %}
$ {{ page.command }} --usage
### `--version`
-- Type: None
-- Availability: `argv` only
+- **Type:** None
+- **Availability:** `argv` only
-Prints small-sized usage message.
+Prints program version.
{% highlight bash %}
$ {{ page.command }} --version
### `--tal`
-- Type: String (Path to file)
-- Availability: `argv` and JSON
+- **Type:** String (Path to file)
+- **Availability:** `argv` and JSON
Path to the _Trust Anchor Locator_ (TAL), or to a directory that contains TALs.
A TAL is a file that points to a _Trust Anchor_ (TA). A TA is a self-signed certificate that serves as root of an RPKI tree you want validated.
-The reason why you provide locators instead of anchors is to allow anchors to be officially updated without the need to awkwardly redistribute them.
+The reason why you provide locators instead of anchors is to allow the latter to be officially updated without the need to awkwardly redistribute them.
Whichever registry serves as root of the tree you want to validate is responsible for providing you with its TAL. For convenience, Fort currently ships with the TALs of four of the five RIRs. (The exception is ARIN's, since you need to read and accept an [agreement](https://www.arin.net/resources/manage/rpki/tal/) before you can use it.) If you are paranoid, however, you'd be advised to get your own.
### `--local-repository`
-- Type: String (Path to directory)
-- Availability: `argv` and JSON
-- Default: `/tmp/fort/repository`
+- **Type:** String (Path to directory)
+- **Availability:** `argv` and JSON
+- **Default:** `/tmp/fort/repository`
Path to the directory where Fort will store a local cache of the repository.
### `--sync-strategy`
-- Type: Enumeration (`off`, `strict`, `root`, `root-except-ta`)
-- Availability: `argv` and JSON
-- Default: `root`
+- **Type:** Enumeration (`off`, `strict`, `root`, `root-except-ta`)
+- **Availability:** `argv` and JSON
+- **Default:** `root`
rsync synchronization strategy. Commands the way rsync URLs are approached during downloads.
### `--shuffle-uris`
-- Availability: `argv` and JSON
+- **Type:** None
+- **Availability:** `argv` and JSON
If enabled, Fort will access TAL URLs in random order. This is meant for load balancing. If disabled, Fort will access TAL URLs in sequential order.
### `--server.address`
-- Type: String
-- Availability: `argv` and JSON
-- Default: `NULL`
+- **Type:** String
+- **Availability:** `argv` and JSON
+- **Default:** `NULL`
Hostname or numeric host address the RTR server will be bound to. Must resolve to (or be) a bindable IP address. IPv4 and IPv6 are supported.
### `--server.port`
-- Type: String
-- Availability: `argv` and JSON
-- Default: `"323"`
+- **Type:** String
+- **Availability:** `argv` and JSON
+- **Default:** `"323"`
TCP port or service the server will be bound to.
### `--server.backlog`
-- Type: Integer
-- Availability: `argv` and JSON
-- Default: [`SOMAXCONN`](http://pubs.opengroup.org/onlinepubs/9699919799.2008edition/basedefs/sys_socket.h.html)
-- Range: 1--`SOMAXCONN`
+- **Type:** Integer
+- **Availability:** `argv` and JSON
+- **Default:** [`SOMAXCONN`](http://pubs.opengroup.org/onlinepubs/9699919799.2008edition/basedefs/sys_socket.h.html)
+- **Range:** 1--`SOMAXCONN`
RTR server's listen queue length. It's the second argument of [`listen()`](http://pubs.opengroup.org/onlinepubs/9699919799.2008edition/functions/listen.html):
### `--server.validation-interval`
-- Type: Integer
-- Availability: `argv` and JSON
-- Default: 60
-- Range: 60--7200
+- **Type:** Integer
+- **Availability:** `argv` and JSON
+- **Default:** 60
+- **Range:** 60--7200
Number of seconds the server will sleep between validation cycles.
### `--slurm`
-- Type: String (path to file or directory)
-- Availability: `argv` and JSON
-- Default: `NULL`
-
-[SLURM](https://tools.ietf.org/html/rfc8416) file, or directory containing SLURM files.
+- **Type:** String (path to file or directory)
+- **Availability:** `argv` and JSON
+- **Default:** `NULL`
-> TODO this is somewhat involved, and needs a dedicated page. The format is standard, though.
+SLURM file, or directory containing SLURM files. See [SLURM](slurm.html).
### `--log.color-output`
-- Availability: `argv` and JSON
+- **Type:** None
+- **Availability:** `argv` and JSON
If enabled, the logging output will contain ANSI color codes. Meant for human consumption.
### `--log.file-name-format`
-- Type: Enumeration (`global-url`, `local-path`, `file-name`)
-- Availability: `argv` and JSON
-- Default: `global-url`
+- **Type:** Enumeration (`global-url`, `local-path`, `file-name`)
+- **Availability:** `argv` and JSON
+- **Default:** `global-url`
Decides which version of file names should be printed during most debug/error messages.
{% highlight bash %}
$ {{ page.command }} --output-file-name-format global-url --local-repository tmp/repository/ (...)
ERR: rsync://rpki.afrinic.net/repository/arin/uHxadfPZV0E6uZhkaUbUVB1RFFU.mft: Certificate validation failed: certificate has expired
+
$ {{ page.command }} --output-file-name-format local-path --local-repository tmp/repository/ (...)
ERR: tmp/repository/rpki.afrinic.net/repository/arin/uHxadfPZV0E6uZhkaUbUVB1RFFU.mft: Certificate validation failed: certificate has expired
+
$ {{ page.command }} --output-file-name-format file-name --local-repository tmp/repository/ (...)
ERR: uHxadfPZV0E6uZhkaUbUVB1RFFU.mft: Certificate validation failed: certificate has expired
{% endhighlight %}
### `--configuration-file`
-- Type: String (Path to file)
-- Availability: `argv` only
+- **Type:** String (Path to file)
+- **Availability:** `argv` only
Path to a JSON file from which additional configuration will be read.
"<a href="#--local-repository">local-repository</a>": "tmp/repository",
"<a href="#--sync-strategy">sync-strategy</a>": "root",
"<a href="#--shuffle-uris">shuffle-uris</a>": true,
+ "<a href="#--slurm">slurm</a>": "test.slurm",
"server": {
- "address": "192.0.2.1",
- "port": "8323",
- "backlog": 16,
- "validation-interval": 120
+ "<a href="#--serveraddress">address</a>": "192.0.2.1",
+ "<a href="#--serverport">port</a>": "8323",
+ "<a href="#--serverbacklog">backlog</a>": 16,
+ "<a href="#--servervalidation-interval">validation-interval</a>": 120
},
- "slurm": "test.slurm",
-
"log": {
- "<a href="#--color-output">color-output</a>": true,
- "<a href="#--output-file-name-format">file-name-format</a>": "file-name"
+ "<a href="#--logcolor-output">color-output</a>": true,
+ "<a href="#--logfile-name-format">file-name-format</a>": "file-name"
},
"rsync": {
]
},
- "incidences": [
+ "<a href="#incidences">incidences</a>": [
{
- "name": "signature algorithm has parameters",
+ "name": "rsaEncryption signature algorithm has parameters",
"action": "ignore"
}
]
### rsync.program
-- Type: String
-- Availability: JSON
-- Default: `"rsync"`
+- **Type:** String
+- **Availability:** JSON only
+- **Default:** `"rsync"`
Name of the program needed to invoke an rsync file transfer.
### rsync.arguments-recursive
-- Type: String array
-- Availability: JSON
-- Default: `[ "--recursive", "--delete", "--times", "--contimeout=20", "$REMOTE", "$LOCAL" ]`
+- **Type:** String array
+- **Availability:** JSON only
+- **Default:** `[ "--recursive", "--delete", "--times", "--contimeout=20", "$REMOTE", "$LOCAL" ]`
Arguments needed by [`rsync.program`](#rsyncprogram) to perform a recursive rsync.
### rsync.arguments-flat
-- Type: String array
-- Availability: JSON
-- Default: `[ "--times", "--contimeout=20", "$REMOTE", "$LOCAL" ]`
+- **Type:** String array
+- **Availability:** JSON only
+- **Default:** `[ "--times", "--contimeout=20", "$REMOTE", "$LOCAL" ]`
Arguments needed by [`rsync.program`](#rsyncprogram) to perform a single-file rsync.
Fort will replace `"$REMOTE"` with the remote URL it needs to download, and `"$LOCAL"` with the target local directory where the file is supposed to be dropped.
+
+### `incidences`
+
+- **Type:** JSON Object
+- **Availability:** JSON only
+
+A listing of actions to be performed by validation upon encountering certain error conditions. See [incidence](incidence.html).
projects / thirdparty / FORT-validator.git / commitdiff
