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