Merge pull request #9 from bgp/jramseyer-patch-example-request

Sample request flow

draft-ramseyer-grow-peering-api.md

@@ -8,12 +8,12 @@ number:
 date:
 consensus: true
 v: 3
-# area: AREA
+# area: RTG
 # workgroup: GROW
 keyword:
- - next generation
- - unicorn
- - sparkling distributed ledger
+ - BGP
+ - peering
+ - configuration
 venue:
 #  group: WG
 #  type: Working Group
@@ -88,10 +88,75 @@ For RPKI-based authentication, this document refers to RFC9323.
 
 
 # Protocol
-(Jenny--this is not up-to-date, but I pasted in what we had in the google doc and will revise)
-TODO: Update this spec, include API endpoints
-
-## full list of endpoints:
+The Peering API follows the RESTful API mode.
+After authentication, a client can request to add or remove peering connections, list potential interconnection locations, and query for upcoming maintenance events.
+
+## Example Request Flow
+### AUTH
+First, the client makes an authenticated request to the server.
+In this example, the client will use PeeringDB OAuth.
+Authentication provides the server with client's email (for potential manual discussion), along with client's entitlements, to confirm client is permitted to request on behalf of the proposed ASN.
+### REQUEST
+1. ADD SESSION (CLIENT REQUEST)
+  * Client provides:
+    * Dictionary (multiple):
+        1. Local ASN (server)
+        2. Local IP
+        3. Peer ASN (client)
+        4. Peer IP
+        5. Peer Type
+        6. MD5 (optional)
+        7. IXP ID
+        8. Status
+        9: UUID
+        10. Sent prefixes (0 if not Established) (optional)
+        11. Received prefixes (0 if not Established) (optional)
+        12. Accepted Prefixes (optional)
+  * Server actions:
+    * Server confirms requested clientASN in list of authorized ASN.
+    * Optional: checks traffic levels, prefix limit counters, other desired internal checks.
+2.  ADD SESSION (SERVER RESPONSE)
+  * APPROVAL CASE
+    * Server returns dictionary of acceptable peering sessions.  Note: this dictionary may also contain additional sessions on which to peer.  See "Public Peering Session Negotiation" for details.
+  * REJECTION CASE
+    * Server returns dictionary of acceptable and rejected sessions.
+  * Optional information:
+    * The server may also include the following details:
+      1. Prefix limit counters (optional value)
+      2. TimeWindow: Time window indicating when sessions will be configured after being notified (may be 0 if sessions are already configured on receiver side)
+      3. isInboundFiltered: optional bool that indicates whether prefixes will be filtered inbound.  If this is set to true, the time window should be set for how long the prefixes will be filtered.
+      4. isOutboundFiltered: optional bool that indicates whether prefixes will be filtered outbound.  If this is set to true, the time window should be set for how long the prefixes will be filtered.  If the outbound limit is longer than the inbound limit time, the time window should be set to the max of inbound versus outbound.
+### CLIENT CONFIGURATION
+The client then configures the chosen peering sessions.
+If the server added additional approved peering sessions, the client may choose whether or not to configure those sessions.
+For every session that the server rejected, the client removes that session from the list to be configured.
+### SERVER CONFIGURATION
+The server configures all sessions that are in its list of approved peering sessions from its reply to the client.
+### 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 original request (by UUID) or of a session (by session UUID).
+The client will send a dictionary along with the request, as follows:
+* Dictionary:
+        1. Local ASN (server)
+        2. Local IP
+        3. Peer ASN (client)
+        4. Peer IP
+        5. Peer Type
+        6. MD5 (optional)
+        7. IXP ID
+        8. Status
+        9: UUID
+        10. Sent prefixes (0 if not Established) (optional)
+        11. Received prefixes (0 if not Established) (optional)
+        12. Accepted Prefixes (optional)
+The server then responds with the same dictionary, with the information that it understands (status, etc).
+### COMPLETION
+If both sides report that the session is established, then peering is complete.
+If one side does not configure sessions within the server's acceptable configuration window (TimeWindow), then the server is entitled to remove the configured sessions and report "Unestablished" to the client.
+
+
+
+## Endpoints:
 * ADD IX PEER
 * Augment IX PEER
 * TOPUP IX
@@ -109,58 +174,13 @@ TODO: Update this spec, include API endpoints
   * Rate limits, allowed senders, and other restriction options
   * Request source
 
-## Request flow
-1. AUTH phase: initiator makes an authenticated request to receiver via PeeringDB OIDC.  This provides the receiver with initiator’s credentials to verify who they say they are
-2. REQUEST phase:
-    1. ADD: What is the initial information provided
-        * Your ASN
-          1. Can use internal tools to check traffic levels
-          2. Cross reference with OIDC data to verify ASN as the same one received in the OIDC token
-          3. Can get prefix limit counters
-              1. Not needed in handshake but could be allowed as an optional flag
-       * Peering Type: PNI or IX (Private or Public - however we want to brand it). This will be useful later when we want to differentiate between a public payload and a private one since they will look different
-       * PeeringDB/IXP IDs that you want to peer on (this allows you to get the peering addresses)
-    2. REMOVE: What is the initial information provided
-        1. Your ASN
-            * Cross reference with OIDC data to verify ASN as the same one received in the OIDC token
-        2. IXP ID
-3. APPROVAL: What does the other side return?
-    1. Dictionary
-        1. Key: IXP ID
-        2. Value: Bool indicating whether or not peering is acceptable at this location
-           * True: yes we can peer
-           * False: no we can’t
-             * Will return false if we’re already peered at that location
-             * Counterproposal: suggest different configuration option.  (in VLater)
-    2. Prefix limit counters (optional value)
-    3. TimeWindow: Time window indicating when sessions will be configured after being notified (may be 0 if sessions are already configured on receiver side)
-    4. isInboundFiltered: optional bool that indicates whether prefixes will be filtered inbound.  If this is set to true the time window should be set to how long the prefixes will be filtered for.
-    5. isOutboundFiltered: optional bool that indicates whether prefixes will be filtered outbound.  If this is set to true, the time window should be set to how long the prefixes will be filtered for.  If the outbound limit is longer than the inbound limit time, the time window should be set to the max of inbound versus outbound.
-4. Initiator removes sessions where receiver does not want to peer
-    1. For every IXP ID where bool = false, remove sessions from the dictionary.  This handles the case where a user may initiate requests with all possible peering sessions and receiver only wants to peer in new locations.  The initiator will then filter out duplicates before entering the CONFIG/MONITOR state.
-5. CONFIG/MONITOR: Initiator waits for maximum time window and then notifies receiver for any outstanding sessions that have not been established
-    1. Initiator sends dictionary
-        1. IXP ID
-        2. Established: bool
-        3. Sent prefixes (0 if Established is false)
-        4. Received prefixes (0 if Established is false)
-        5. Accepted Prefixes
-    2. Receiver responds with dictionary
-        1. IXP ID
-        2. Established: bool
-        3. Sent prefixes
-        4. Received prefixes
-        5. Accepted Prefixes
-    3. If established = true, sentPrefixes > 0, and acceptedPrefixes > 0
-        1. You’re done
-        2. Initiator closes connection with a GOODBYE.  Any subsequent followups must start this process over again.  If the receiver has responded with a GOODBYE, then any subsequent monitoring calls will receive a GOODBYE.  If a GOODBYE was presented erroneously, the initiator can make a new request asking the receiver to delete the session and retry.
-    4. Else, wait TimeWindow and retry
-    5. If initiator does not make a request in 3*TimeWindow or 1 week (whichever is longer), receiver automatically sends a GOODBYE and deletes the sessions on their side.
-
 # API Endpoints and Specifications
 TODO: list endpoints, both v0 and vLater
 TODO: Include diagram and openapi spec?
 
+Section: "Public Peering Session Negotiation"
+TODO put in a section about how the client and server handshake which locations to configure peering.
+
 Each peer needs an API endpoint that will listen on this and implement the above protocol
 This API should be publicly listed in peeringDB and also as a potential expansion of RFC 9092 which provides endpoint integration to whois.
 Each API endpoint should be fuzz-tested and protected against abuse.  Attackers should not be able to access internal systems using the API.