doc: add RPKI

Signed-off-by: FUJITA Tomonori <fujita.tomonori@lab.ntt.co.jp>

1 files changed, 187 insertions, 0 deletions

diff --git a/docs/sources/rpki.md b/docs/sources/rpki.md
new file mode 100644
index 00000000..c49f6082
--- /dev/null
+++ b/docs/sources/rpki.md
@@ -0,0 +1,187 @@
+# RPKI
+
+This page explains how to use a Resource Public Key Infrastructure
+(RPKI) server to do Origin AS Validation.
+
+## Prerequisites
+
+Assume you finished [Getting Started](https://github.com/osrg/gobgp/blob/master/docs/sources/getting-started.md).
+
+## Contents
+
+- [Configuration](#section0)
+- [Validation](#section1)
+- [Policy with validation results](#section2)
+
+## <a name="section0"> Configuration
+
+You need to add **[RpkiServers]** section to your configuration
+file. We use the following file. Note that this is for route server
+setup but RPKI can be used with non route server setup.
+
+```toml
+[Global]
+  [Global.GlobalConfig]
+    As = 64512
+    RouterId = "10.0.255.254"
+
+[Neighbors]
+  [[Neighbors.NeighborList]]
+    [Neighbors.NeighborList.NeighborConfig]
+      PeerAs = 65001
+      NeighborAddress = "10.0.255.1"
+    [Neighbors.NeighborList.RouteServer]
+      [Neighbors.NeighborList.RouteServer.RouteServerConfig]
+        RouteServerClient = true
+
+  [[Neighbors.NeighborList]]
+    [Neighbors.NeighborList.NeighborConfig]
+      PeerAs = 65002
+      NeighborAddress = "10.0.255.2"
+    [Neighbors.NeighborList.RouteServer]
+      [Neighbors.NeighborList.RouteServer.RouteServerConfig]
+        RouteServerClient = true
+
+[RpkiServers]
+  [[RpkiServers.RpkiServerList]]
+    [RpkiServers.RpkiServerList.RpkiServerConfig]
+      Address = "210.173.170.254"
+      Port = 323
+```
+
+## <a name="section1"> Validation
+
+You can verify whether gobgpd successfully connects to the RPKI server
+and get the ROA (Route Origin Authorization) information in the
+following way:
+
+```bash
+$ gobgp rpki|head -n4
+Network            Maxlen AS
+2.0.0.0/12         16     3215
+2.0.0.0/16         16     3215
+2.1.0.0/16         16     3215
+$ gobgp rpki -l|wc
+14576
+```
+
+By default, IPv4's ROA information is shown. You can see IPv6's like:
+
+```bash
+$ gobgp rpki -a ipv6|head -n4
+fujita@ubuntu:~$ gobgp rpki -a ipv6|head -n3
+Network                                    Maxlen AS
+2001:608::/32                              32     5539
+2001:610::/32                              48     1103
+2001:610:240::/42                          42     3333
+$ gobgp rpki -a ipv6|wc -l
+2150
+```
+
+We configure the peer 10.0.255.1 to send three routes:
+
+1. 2.0.0.0/12 (Origin AS: 3215)
+2. 2.1.0.0/16 (Origin AS: 65001)
+3. 192.186.1.0/24 (Origin AS: 65001)
+
+From the above ROA information, the first is valid. the second is
+invalid (the origin should be 3215 too). the third is a private IPv4
+address so it should not be in the ROA.
+
+Let's check out the adjacent rib-in of the peer:
+
+```bash
+$ gobgp neighbor 10.0.255.1 adj-in
+    Network              Next Hop             AS_PATH              Age        Attrs
+    V   2.0.0.0/12       10.0.255.1           3215                 00:08:39   [{Origin: i}]
+    I   2.1.0.0/16       10.0.255.1           65001                00:08:39   [{Origin: i}]
+    N   192.168.1.0/24   10.0.255.1           65001                00:08:39   [{Origin: i}]
+```
+
+As you can see, the first is marked as "V" (Valid), the second as "I"
+(Invalid), and the third as "N" (Not Found).
+
+
+## <a name="section2"> Policy with validation results
+
+The validation result can be used as [Policy's
+condition](https://github.com/osrg/gobgp/blob/master/docs/sources/policy.md). You
+can do any actions (e.g., drop the route, adding some extended
+community attribute, etc) according to the validation result. As an
+example, this section shows how to drop an invalid route.
+
+Currently, all the routes from peer 10.0.255.1 are included in peer 10.0.255.2's local RIB.
+
+```bash
+$ gobgp neighbor 10.0.255.2 local
+    Network              Next Hop             AS_PATH              Age        Attrs
+    V*> 2.0.0.0/12       10.0.255.1           3215                 00:23:47   [{Origin: i}]
+    I*> 2.1.0.0/16       10.0.255.1           65001                00:23:47   [{Origin: i}]
+    N*> 192.168.1.0/24   10.0.255.1           65001                00:23:47   [{Origin: i}]
+```
+
+We add a policy to the above configuration.
+
+```toml
+[Global]
+  [Global.GlobalConfig]
+    As = 64512
+    RouterId = "10.0.255.254"
+
+[Neighbors]
+  [[Neighbors.NeighborList]]
+    [Neighbors.NeighborList.NeighborConfig]
+      PeerAs = 65001
+      NeighborAddress = "10.0.255.1"
+    [Neighbors.NeighborList.RouteServer]
+      [Neighbors.NeighborList.RouteServer.RouteServerConfig]
+        RouteServerClient = true
+
+  [[Neighbors.NeighborList]]
+    [Neighbors.NeighborList.NeighborConfig]
+      PeerAs = 65002
+      NeighborAddress = "10.0.255.2"
+    [Neighbors.NeighborList.RouteServer]
+      [Neighbors.NeighborList.RouteServer.RouteServerConfig]
+        RouteServerClient = true
+    [Neighbors.NeighborList.ApplyPolicy]
+      [Neighbors.NeighborList.ApplyPolicy.ApplyPolicyConfig]
+	ImportPolicy = ["AS65002-IMPORT-RPKI"]
+
+[RpkiServers]
+  [[RpkiServers.RpkiServerList]]
+    [RpkiServers.RpkiServerList.RpkiServerConfig]
+      Address = "210.173.170.254"
+      Port = 323
+
+[PolicyDefinitions]
+  [[PolicyDefinitions.PolicyDefinitionList]]
+    Name = "AS65002-IMPORT-RPKI"
+    [PolicyDefinitions.PolicyDefinitionList.Statements]
+      [[PolicyDefinitions.PolicyDefinitionList.Statements.StatementList]]
+        Name = "statement1"
+        [PolicyDefinitions.PolicyDefinitionList.Statements.StatementList.Conditions]
+          [PolicyDefinitions.PolicyDefinitionList.Statements.StatementList.Conditions.BgpConditions]
+             RpkiValidationResult = 3
+
+        [PolicyDefinitions.PolicyDefinitionList.Statements.StatementList.Actions]
+          [PolicyDefinitions.PolicyDefinitionList.Statements.StatementList.Actions.RouteDisposition]
+	     RejectRoute = true
+```
+
+The value for **RpkiValidationResult** are defined as below.
+
+| Validation Result | Value |
+|-------------------|-------|
+| Not Found         |   1   |
+| Valid             |   2   |
+| Invalid           |   3   |
+
+With the new configuration, the IMPORT policy rejects the invalid 2.1.0.0/16.
+
+```bash
+$ gobgp neighbor 10.0.255.2 local
+    Network              Next Hop             AS_PATH              Age        Attrs
+    V*> 2.0.0.0/12       10.0.255.1           3215                 00:00:21   [{Origin: i}]
+    N*> 192.168.1.0/24   10.0.255.1           65001                00:00:21   [{Origin: i}]
+```