doc/rpki.texi

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