Merge pull request #31 from mwichtlh/main

Adding route server support

draft-ramseyer-grow-peering-api.md

@@ -299,15 +299,21 @@ REQUEST     {#request}
 1. ADD SESSION (CLIENT BATCHED REQUEST)
 
 
-  * The initiator's client provides a set of:
+  * The initiator's client provides a set of the following information, where local always refers to the receiver and peer always refers to the initiator:
     * Structure:
-        1. Local ASN (receiver)
+        1. Local ASN
         2. Local IP
-        3. Peer ASN (initiator)
+        3. Peer ASN
         4. Peer IP
-        5. Peer Type (public or private)
-        6. MD5 (optional with encoding agreed outside of this specification)
-        7. Location (Commonly agreed identifier of the BGP speaker, e.g. PeeringDB IX lan ID)
+        5. Local BGP Role according to {{?RFC9234}}
+        6. Peer BGP Role according to {{?RFC9234}}
+        8. Local insert ASN (optional to support route servers)
+        9. Peer insert ASN (optional to support route servers)
+       11. Local monitoring session (optional to support monitoring systems)
+       12. Peer monitoring session (optional to support monitoring systems)
+       10. Peer Type (public or private)
+       11. Session Secret (optional with encoding agreed outside of this specification)
+       12. Location (Commonly agreed identifier of the BGP speaker, e.g. PeeringDB IX lan ID)
 
   * The receiver's expected actions:
     * The server confirms requested clientASN in list of authorized ASNs.
@@ -325,26 +331,34 @@ REQUEST     {#request}
 CLIENT CONFIGURATION    {#clientconfig}
 --------------------
 The client then configures the chosen peering sessions asynchronously using their internal mechanisms.
+The client SHOULD pull and use additional information on the new peering from public sources as required to ensure routing security, e.g., AS-SETs to configure appropriate filters.
 For every session that the server rejected, the client removes that session from the list to be configured.
 
 SERVER CONFIGURATION    {#serverconfig}
 --------------------
 The server configures all sessions that are in its list of approved peering sessions from its reply to the client.
+The server SHOULD pull and use additional information on the new peering from public sources to ensure routing security, e.g., AS-SETs to configure appropriate filters.
 
 MONITORING   {#monitoring}
 ----------
 Both client and server wait for sessions to establish.
 At any point, client may send a "GET STATUS" request to the server, to request the status of the session (by session ID).
 The client will send a structure along with the request, as follows:
 
-* structure:
+* structure (where local refers to the server and peer refers to the client):
   * Session ID
-  * Local ASN (server)
+  * Local ASN
   * Local IP
-  * Peer ASN (client)
+  * Peer ASN
   * Peer IP
+  * Local BGP Role ({{?RFC9234}})
+  * Peer BGP Role ({{?RFC9234}})
+  * Local insert ASN (optional, as defined above)
+  * Peer insert ASN (optional, as defined above)
+  * Local monitoring session (optional, as defined above)
+  * Peer monitoring session (optional, as defined above)
   * Peer Type
-  * MD5 (optional, as defined above)
+  * Session secret (optional, as defined above)
   * Location
   * Status
 
@@ -402,12 +416,24 @@ BGP Session
   * local_ip (IP of requestor, v4 or v6)
   * peer_asn (server ASN)
   * peer_ip (server-side IP)
+  * local_bgp_role (BGP role according to {{?RFC9234}})
+  * peer_bgp_role (BGP role according to {{?RFC9234}})
+  * local_insert_asn (optional, to support route servers, defaults to true)
+  * peer_insert_asn (optional, to support route servers, defaults to true)
+  * local_monitoring_session (optional, to support monitoring systems, defaults to false)
+  * peer_monitoring_session (optional, to support monitoring systems, defaults to false)
   * peer_type (public or private)
-  * md5 (optional, as defined above)
+  * session_secret (optional, as defined above)
   * location (Peering Location, as defined above)
   * status (Session Status, as defined above)
   * session_id (of individual session and generated by the server)
 
+As not all elements are reflected in the {{autopeer}} OpenAPI definition to date, we define the missing fields here to be reflected in {{autopeer}} in the future.
+
+  * local_bgp_role and peer_bgp_role: these field describe the BGP roles of the local and peer side of the session according to {{?RFC9234}} represented by an integer. The roles for both sides MUST be set in a way that does not violate role correctness as defined in Section 4.2 of {{?RFC9234}}.
+  * local_insert_asn and peer_insert_asn: these fields define whether the local or peer side will insert their ASN into the AS path attribute of forwarded BGP routes. They are mostly relevant to route servers. The fields are boolean and optional. If not provided, they default to true.
+  * local_monitoring_session and peer_monitoring_session: these fields define whether the local or peer side of the session will forward routes to other ASes or not. As the role of monitoring systems is not defined in {{?RFC9234}}, we add this role via a boolean, optional flag. If not provided, they default to false. local_monitoring_session and peer_monitoring_sessions MUST NOT be true at the same time for the same session to avoid a role mismatch.
+
 Error
 
   API Errors, for field validation errors in requests, and request-level errors.
@@ -636,19 +662,13 @@ The API described in this document follows REST ({{rest}}) principles over an HT
 
 Instead, this document proposes to address the message integrity property by cryptographically signing the parameters of the request with a key pair that creates a HTTP message signature to be included in the request ({{!RFC9421}}). The client application controls the lifecycle of this key pair. The authenticity property of the messages signed with such key pair is addressed by binding the public key of the pair to the JWT access token in one of its claims of the access token using a mechanism that demonstrates proof of possession of the private key {{!RFC9449}}. With these two mechanisms, the resource server should authenticate, authorize, and validate the integrity of the request using a JWT access token that can rightfully claim to represent a given ASN.
 
-Possible Extensions     {#extensions}
-===================
-
-The authors acknowledge that route-server configuration may also be of interest for this proposed API, and look forward to future discussions in this area.
-
 IANA Considerations     {#iana}
 ===================
 
 This document has no IANA actions.
 
 --- back
 
-
 Acknowledgments     {#acknowledgments}
 ===============
 
@@ -663,6 +683,7 @@ The authors would like to thank their collaborators, who implemented API version
 * David Tuber (Cloudflare)
 * Aaron Rose (Amazon)
 * Prithvi Nath Manikonda (Amazon)
+* Matthias Wichtlhuber (DE-CIX)