doc/user/rpki.rst

   1 .. _prefix-origin-validation-using-rpki:
   2
   3 Prefix Origin Validation Using RPKI
   4 ===================================
   5
   6 Prefix Origin Validation allows BGP routers to verify if the origin AS of an IP
   7 prefix is legitimate to announce this IP prefix. The required attestation
   8 objects are stored in the Resource Public Key Infrastructure (:abbr:`RPKI`).
   9 However, RPKI-enabled routers do not store cryptographic data itself but only
  10 validation information. The validation of the cryptographic data (so called
  11 Route Origin Authorization, or short :abbr:`ROA`, objects) will be performed by
  12 trusted cache servers. The RPKI/RTR protocol defines a standard mechanism to
  13 maintain the exchange of the prefix/origin AS mapping between the cache server
  14 and routers. In combination with a  BGP Prefix Origin Validation scheme a
  15 router is able to verify received BGP updates without suffering from
  16 cryptographic complexity.
  17
  18 The RPKI/RTR protocol is defined in :rfc:`6810` and the validation scheme in
  19 :rfc:`6811`. The current version of Prefix Origin Validation in FRR implements
  20 both RFCs.
  21
  22 For a more detailed but still easy-to-read background, we suggest:
  23
  24 - [Securing-BGP]_
  25 - [Resource-Certification]_
  26
  27 .. _features-of-the-current-implementation:
  28
  29 Features of the Current Implementation
  30 --------------------------------------
  31
  32 In a nutshell, the current implementation provides the following features
  33
  34 - The BGP router can connect to one or more RPKI cache servers to receive
  35   validated prefix to origin AS mappings. Advanced failover can be implemented
  36   by server sockets with different preference values.
  37 - If no connection to an RPKI cache server can be established after a
  38   pre-defined timeout, the router will process routes without prefix origin
  39   validation. It still will try to establish a connection to an RPKI cache
  40   server in the background.
  41 - By default, enabling RPKI does not change best path selection. In particular,
  42   invalid prefixes will still be considered during best path selection.
  43   However, the router can be configured to ignore all invalid prefixes.
  44 - Route maps can be configured to match a specific RPKI validation state. This
  45   allows the creation of local policies, which handle BGP routes based on the
  46   outcome of the Prefix Origin Validation.
  47
  48
  49 .. _enabling-rpki:
  50
  51 Enabling RPKI
  52 -------------
  53
  54 .. index:: rpki
  55 .. clicmd:: rpki
  56
  57    This command enables the RPKI configuration mode. Most commands that start
  58    with *rpki* can only be used in this mode.
  59
  60    When it is used in a telnet session, leaving of this mode cause rpki to be initialized.
  61
  62    Executing this command alone does not activate prefix validation. You need
  63    to configure at least one reachable cache server. See section
  64    :ref:`configuring-rpki-rtr-cache-servers` for configuring a cache server.
  65
  66 .. _configuring-rpki-rtr-cache-servers:
  67
  68 Configuring RPKI/RTR Cache Servers
  69 ----------------------------------
  70
  71 The following commands are independent of a specific cache server.
  72
  73 .. index:: rpki polling_period (1-3600)
  74 .. clicmd:: rpki polling_period (1-3600)
  75
  76 .. index:: no rpki polling_period
  77 .. clicmd:: no rpki polling_period
  78
  79    Set the number of seconds the router waits until the router asks the cache
  80    again for updated data.
  81
  82    The default value is 300 seconds.
  83
  84 .. index:: rpki timeout <1-4,294,967,296>
  85 .. clicmd:: rpki timeout <1-4,294,967,296>
  86
  87 .. index:: no rpki timeout
  88 .. clicmd:: no rpki timeout
  89
  90    Set the number of seconds the router waits for the cache reply. If the cache
  91    server is not replying within this time period, the router deletes all
  92    received prefix records from the prefix table.
  93
  94    The default value is 600 seconds.
  95
  96 .. index:: rpki initial-synchronisation-timeout <1-4,294,967,296>
  97 .. clicmd:: rpki initial-synchronisation-timeout <1-4,294,967,296>
  98
  99 .. index:: no rpki initial-synchronisation-timeout
 100 .. clicmd:: no rpki initial-synchronisation-timeout
 101
 102    Set the number of seconds until the first synchronization with the cache
 103    server needs to be completed. If the timeout expires, BGP routing is started
 104    without RPKI. The router will try to establish the cache server connection in
 105    the background.
 106
 107    The default value is 30 seconds.
 108
 109    The following commands configure one or multiple cache servers.
 110
 111 .. index:: rpki cache (A.B.C.D|WORD) PORT [SSH_USERNAME] [SSH_PRIVKEY_PATH] [SSH_PUBKEY_PATH] [KNOWN_HOSTS_PATH] PREFERENCE
 112 .. clicmd:: rpki cache (A.B.C.D|WORD) PORT [SSH_USERNAME] [SSH_PRIVKEY_PATH] [SSH_PUBKEY_PATH] [KNOWN_HOSTS_PATH] PREFERENCE
 113
 114 .. index:: no rpki cache (A.B.C.D|WORD) [PORT] PREFERENCE
 115 .. clicmd:: no rpki cache (A.B.C.D|WORD) [PORT] PREFERENCE
 116
 117    Add a cache server to the socket. By default, the connection between router
 118    and cache server is based on plain TCP. Protecting the connection between
 119    router and cache server by SSH is optional. Deleting a socket removes the
 120    associated cache server and terminates the existing connection.
 121
 122    A.B.C.D|WORD
 123       Address of the cache server.
 124
 125    PORT
 126       Port number to connect to the cache server
 127
 128    SSH_USERNAME
 129       SSH username to establish an SSH connection to the cache server.
 130
 131
 132    SSH_PRIVKEY_PATH
 133       Local path that includes the private key file of the router.
 134
 135
 136    SSH_PUBKEY_PATH
 137       Local path that includes the public key file of the router.
 138
 139
 140    KNOWN_HOSTS_PATH
 141       Local path that includes the known hosts file. The default value depends
 142       on the configuration of the operating system environment, usually
 143       :file:`~/.ssh/known_hosts`.
 144
 145
 146 .. _validating-bgp-updates:
 147
 148 Validating BGP Updates
 149 ----------------------
 150
 151 .. index:: match rpki notfound|invalid|valid
 152 .. clicmd:: match rpki notfound|invalid|valid
 153
 154 .. index:: no match rpki notfound|invalid|valid
 155 .. clicmd:: no match rpki notfound|invalid|valid
 156
 157     Create a clause for a route map to match prefixes with the specified RPKI
 158     state.
 159
 160     **Note** that the matching of invalid prefixes requires that invalid
 161     prefixes are considered for best path selection, i.e.,
 162     ``bgp bestpath prefix-validate disallow-invalid`` is not enabled.
 163
 164     In the following example, the router prefers valid routes over invalid
 165     prefixes because invalid routes have a lower local preference.
 166
 167     ::
 168
 169        ! Allow for invalid routes in route selection process
 170        route bgp 60001
 171        !
 172        ! Set local preference of invalid prefixes to 10
 173        route-map rpki permit 10
 174         match rpki invalid
 175         set local-preference 10
 176        !
 177        ! Set local preference of valid prefixes to 500
 178        route-map rpki permit 500
 179         match rpki valid
 180         set local-preference 500
 181
 182
 183 .. _debugging:
 184
 185 Debugging
 186 ---------
 187
 188 .. index:: debug rpki
 189 .. clicmd:: debug rpki
 190
 191 .. index:: no debug rpki
 192 .. clicmd:: no debug rpki
 193
 194    Enable or disable debugging output for RPKI.
 195
 196 .. _displaying-rpki:
 197
 198 Displaying RPKI
 199 ---------------
 200
 201 .. index:: show rpki prefix-table
 202 .. clicmd:: show rpki prefix-table
 203
 204    Display all validated prefix to origin AS mappings/records which have been
 205    received from the cache servers and stored in the router. Based on this data,
 206    the router validates BGP Updates.
 207
 208 .. index:: show rpki cache-connection
 209 .. clicmd:: show rpki cache-connection
 210
 211    Display all configured cache servers, whether active or not.
 212
 213 RPKI Configuration Example
 214 --------------------------
 215
 216 ::
 217
 218    hostname bgpd1
 219    password zebra
 220    ! log stdout
 221    debug bgp updates
 222    debug bgp keepalives
 223    debug rpki
 224    !
 225    rpki
 226     rpki polling_period 1000
 227     rpki timeout 10
 228      ! SSH Example:
 229      rpki cache example.com 22 rtr-ssh ./ssh_key/id_rsa ./ssh_key/id_rsa.pub preference 1
 230      ! TCP Example:
 231      rpki cache rpki-validator.realmv6.org 8282 preference 2
 232      exit
 233    !
 234    router bgp 60001
 235     bgp router-id 141.22.28.223
 236     network 192.168.0.0/16
 237     neighbor 123.123.123.0 remote-as 60002
 238     neighbor 123.123.123.0 route-map rpki in
 239    !
 240     address-family ipv6
 241      neighbor 123.123.123.0 activate
 242       neighbor 123.123.123.0 route-map rpki in
 243     exit-address-family
 244    !
 245    route-map rpki permit 10
 246     match rpki invalid
 247     set local-preference 10
 248    !
 249    route-map rpki permit 20
 250     match rpki notfound
 251     set local-preference 20
 252    !
 253    route-map rpki permit 30
 254     match rpki valid
 255     set local-preference 30
 256    !
 257    route-map rpki permit 40
 258    !
 259
 260 .. [Securing-BGP] Geoff Huston, Randy Bush: Securing BGP, In: The Internet Protocol Journal, Volume 14, No. 2, 2011. <http://www.cisco.com/web/about/ac123/ac147/archived_issues/ipj_14-2/142_bgp.html>
 261 .. [Resource-Certification] Geoff Huston: Resource Certification, In: The Internet Protocol Journal, Volume 12, No.1, 2009. <http://www.cisco.com/web/about/ac123/ac147/archived_issues/ipj_12-1/121_resource.html>