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 - Updates from the RPKI cache servers are directly applied and path selection
  48   is updated accordingly. (Soft reconfiguration **must** be enabled for this
  49   to work).
  50
  51
  52 .. _enabling-rpki:
  53
  54 Enabling RPKI
  55 -------------
  56
  57 .. index:: rpki
  58 .. clicmd:: rpki
  59
  60    This command enables the RPKI configuration mode. Most commands that start
  61    with *rpki* can only be used in this mode.
  62
  63    When it is used in a telnet session, leaving of this mode cause rpki to be
  64    initialized.
  65
  66    Executing this command alone does not activate prefix validation. You need
  67    to configure at least one reachable cache server. See section
  68    :ref:`configuring-rpki-rtr-cache-servers` for configuring a cache server.
  69
  70 .. index:: daemons.conf
  71
  72    When first installing FRR with RPKI support from the pre-packaged binaries.
  73    Remember to append :option:`-M rpki` in the :file:`/etc/frr/daemons.conf`
  74    file to ``bgpd_options``, like so::
  75
  76       bgpd_options="   --daemon -A 127.0.0.1 -M rpki"
  77
  78    instead of the default setting::
  79
  80       bgpd_options="   --daemon -A 127.0.0.1"
  81
  82    Otherwise you will encounter an error when trying to enter RPKI
  83    configuration mode due to the ``rpki`` module not being loaded when the BGP
  84    daemon is initialized.
  85
  86    Examples of the error::
  87
  88       router(config)# debug rpki
  89       % [BGP] Unknown command: debug rpki
  90
  91       router(config)# rpki
  92       % [BGP] Unknown command: rpki
  93
  94    Note that the RPKI commands will be available in vtysh when running ``find
  95    rpki`` regardless of whether the module is loaded.
  96
  97 .. _configuring-rpki-rtr-cache-servers:
  98
  99 Configuring RPKI/RTR Cache Servers
 100 ----------------------------------
 101
 102 The following commands are independent of a specific cache server.
 103
 104 .. index:: rpki polling_period (1-3600)
 105 .. clicmd:: rpki polling_period (1-3600)
 106
 107 .. index:: no rpki polling_period
 108 .. clicmd:: no rpki polling_period
 109
 110    Set the number of seconds the router waits until the router asks the cache
 111    again for updated data.
 112
 113    The default value is 300 seconds.
 114
 115 .. index:: rpki timeout <1-4,294,967,296>
 116 .. clicmd:: rpki timeout <1-4,294,967,296>
 117
 118 .. index:: no rpki timeout
 119 .. clicmd:: no rpki timeout
 120
 121    Set the number of seconds the router waits for the cache reply. If the cache
 122    server is not replying within this time period, the router deletes all
 123    received prefix records from the prefix table.
 124
 125    The default value is 600 seconds.
 126
 127 .. index:: rpki initial-synchronisation-timeout <1-4,294,967,296>
 128 .. clicmd:: rpki initial-synchronisation-timeout <1-4,294,967,296>
 129
 130 .. index:: no rpki initial-synchronisation-timeout
 131 .. clicmd:: no rpki initial-synchronisation-timeout
 132
 133    Set the number of seconds until the first synchronization with the cache
 134    server needs to be completed. If the timeout expires, BGP routing is started
 135    without RPKI. The router will try to establish the cache server connection in
 136    the background.
 137
 138    The default value is 30 seconds.
 139
 140    The following commands configure one or multiple cache servers.
 141
 142 .. index:: rpki cache (A.B.C.D|WORD) PORT [SSH_USERNAME] [SSH_PRIVKEY_PATH] [SSH_PUBKEY_PATH] [KNOWN_HOSTS_PATH] PREFERENCE
 143 .. clicmd:: rpki cache (A.B.C.D|WORD) PORT [SSH_USERNAME] [SSH_PRIVKEY_PATH] [SSH_PUBKEY_PATH] [KNOWN_HOSTS_PATH] PREFERENCE
 144
 145 .. index:: no rpki cache (A.B.C.D|WORD) [PORT] PREFERENCE
 146 .. clicmd:: no rpki cache (A.B.C.D|WORD) [PORT] PREFERENCE
 147
 148    Add a cache server to the socket. By default, the connection between router
 149    and cache server is based on plain TCP. Protecting the connection between
 150    router and cache server by SSH is optional. Deleting a socket removes the
 151    associated cache server and terminates the existing connection.
 152
 153    A.B.C.D|WORD
 154       Address of the cache server.
 155
 156    PORT
 157       Port number to connect to the cache server
 158
 159    SSH_USERNAME
 160       SSH username to establish an SSH connection to the cache server.
 161
 162
 163    SSH_PRIVKEY_PATH
 164       Local path that includes the private key file of the router.
 165
 166
 167    SSH_PUBKEY_PATH
 168       Local path that includes the public key file of the router.
 169
 170
 171    KNOWN_HOSTS_PATH
 172       Local path that includes the known hosts file. The default value depends
 173       on the configuration of the operating system environment, usually
 174       :file:`~/.ssh/known_hosts`.
 175
 176
 177 .. _validating-bgp-updates:
 178
 179 Validating BGP Updates
 180 ----------------------
 181
 182 .. index:: match rpki notfound|invalid|valid
 183 .. clicmd:: match rpki notfound|invalid|valid
 184
 185 .. index:: no match rpki notfound|invalid|valid
 186 .. clicmd:: no match rpki notfound|invalid|valid
 187
 188     Create a clause for a route map to match prefixes with the specified RPKI
 189     state.
 190
 191     **Note** that the matching of invalid prefixes requires that invalid
 192     prefixes are considered for best path selection, i.e.,
 193     ``bgp bestpath prefix-validate disallow-invalid`` is not enabled.
 194
 195     In the following example, the router prefers valid routes over invalid
 196     prefixes because invalid routes have a lower local preference.
 197
 198     .. code-block:: frr
 199
 200        ! Allow for invalid routes in route selection process
 201        route bgp 60001
 202        !
 203        ! Set local preference of invalid prefixes to 10
 204        route-map rpki permit 10
 205         match rpki invalid
 206         set local-preference 10
 207        !
 208        ! Set local preference of valid prefixes to 500
 209        route-map rpki permit 500
 210         match rpki valid
 211         set local-preference 500
 212
 213
 214 .. _debugging:
 215
 216 Debugging
 217 ---------
 218
 219 .. index:: debug rpki
 220 .. clicmd:: debug rpki
 221
 222 .. index:: no debug rpki
 223 .. clicmd:: no debug rpki
 224
 225    Enable or disable debugging output for RPKI.
 226
 227 .. _displaying-rpki:
 228
 229 Displaying RPKI
 230 ---------------
 231
 232 .. index:: show rpki prefix-table
 233 .. clicmd:: show rpki prefix-table
 234
 235    Display all validated prefix to origin AS mappings/records which have been
 236    received from the cache servers and stored in the router. Based on this data,
 237    the router validates BGP Updates.
 238
 239 .. index:: show rpki cache-connection
 240 .. clicmd:: show rpki cache-connection
 241
 242    Display all configured cache servers, whether active or not.
 243
 244 RPKI Configuration Example
 245 --------------------------
 246
 247 .. code-block:: frr
 248
 249    hostname bgpd1
 250    password zebra
 251    ! log stdout
 252    debug bgp updates
 253    debug bgp keepalives
 254    debug rpki
 255    !
 256    rpki
 257     rpki polling_period 1000
 258     rpki timeout 10
 259      ! SSH Example:
 260      rpki cache example.com 22 rtr-ssh ./ssh_key/id_rsa ./ssh_key/id_rsa.pub preference 1
 261      ! TCP Example:
 262      rpki cache rpki-validator.realmv6.org 8282 preference 2
 263      exit
 264    !
 265    router bgp 60001
 266     bgp router-id 141.22.28.223
 267     network 192.168.0.0/16
 268     neighbor 123.123.123.0 remote-as 60002
 269     neighbor 123.123.123.0 route-map rpki in
 270    !
 271     address-family ipv6
 272      neighbor 123.123.123.0 activate
 273       neighbor 123.123.123.0 route-map rpki in
 274     exit-address-family
 275    !
 276    route-map rpki permit 10
 277     match rpki invalid
 278     set local-preference 10
 279    !
 280    route-map rpki permit 20
 281     match rpki notfound
 282     set local-preference 20
 283    !
 284    route-map rpki permit 30
 285     match rpki valid
 286     set local-preference 30
 287    !
 288    route-map rpki permit 40
 289    !
 290
 291 .. [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>
 292 .. [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>