Peering API

1.1. Business Justification

By using the Peering API, entities requesting and accepting peering can significantly improve the process to turn up interconnections by:¶

• Reducing in person-hours spent configuring peering¶

• Reducing configuration mistakes by reducing human interaction¶

• And by peering, reducing network latency through expansion of interconnection relationships¶

4.1. Example Peering Request Negotiation

Diagram of the Peering Request Process¶

+-------------------+                    +-------------------+
|     Step 1        |                    |     Step 2        |
|    Network 1      |------------------->|    Network 1      |
|  Identifies need  |                    |   Checks details  |
+-------------------+                    +-------------------+
                                                 |
                                                 v
+-------------------+                    +-------------------+
|      Step 4       |                    |      Step 3       |
|    Network 1      |<-------------------|    Network 1      |
|  gets approval    |                    |     Public or     |
|      token        |                    | Private Peering   |
+-------------------+                    +-------------------+
        |
        v
+-------------------+                    +-------------------+
|      Step 5       |                    |      Step 6       |
|  Network 1 finds  |------------------->|    Network 1      |
| common locations  |                    |  request peering  |
+-------------------+                    +-------------------+
                                                  |
                                                  v
+-------------------+                   +--------------------+
|      Step 8       |                   |       Step 7       |
|     Network 2     |<------------------|     Network 2      |
| accepts or reject |                   |      verifies      |
|    sessions       |                   |     credentials    |
+-------------------+                   +--------------------+
       /     \
      /       \
     /         \
(yes)           (no)
      \          |
       \         +-------------------------------|
        \                                        |
         \                                       |
          v                                      |
+---------------+          +----------------+    |
|    Step 9     |          |    Step 10     |    |
| Sessions are  |          | Network 1 or 2 |    |
|  provisioned  |--------->| checks session |    |
|     status    |          | until it is up |    |
+---------------+          +----------------+    |
                                   |             |
                      +------------+             |
                      |                          |
                      v                          |
            +-------------+                      |
            |   Step 11   |                      |
            |   Request   |<---------------------+
            |  Terminate  |
            +-------------+







Step 1 [Human]: Network 1 identifies that it would be useful to peer with Network 2 to interchange traffic more optimally


Step 2 [Human]: Network 1 checks technical and other peering details about Network 2 to check if peering is possible


Step 3 [Human]: Network 1 decides in type (Public or PNI) of peering and facility


Step 4 [API]: Network 1 gets approval/token that is authorized to ‘speak’ on behalf of Network 1’s ASN.


Step 5 [API]: Network 1 checks PeeringDB for common places between Network 1 and Network 2.
API: GET /locations


Step 6 [API]: Network 1 request peering with Network 2
API:      POST /add_sessions


Step 7 [API]: Network 2 verifies Network 1 credentials, check requirements for peering


Step 8 [API]: Network 2 accepts or rejects session(s)
API Server gives yes/no for request


Step 9 [API]: If yes, sessions are provisioned, Networks 1 or Network 2 can check status
API: /sessions Get session status


Step 10 [API]: API keeps polling until sessions are up


Step 11 [API]: Process Terminate

4.2. Example API Flow

The diagram below outlines the proposed API flow.¶

OIDC Authentication

+-----------+                 +-------+                    +-----------+
| Initiator |                 | Peer  |                    | PeeringDB |
+-----------+                 +-------+                    +-----------+
      |                           |                              |
      | OIDC Authentication       |                              |
      |--------------------------------------------------------->|
      |                           |                              |
      |                                        Provide auth code |
      |<---------------------------------------------------------|
      |                           |                              |
      | Send auth code to Peer    |                              |
      |--------------------------------------------------------->|
      |                           |                              |
      |                           | Exchange auth code for token |
      |                           |----------------------------->|
      |                           |                              |
      |                           |                 Return token |
      |                           |<-----------------------------|
      |                           |
      | Peer determines permissions based on token
      |                           |
      | Send OK back to Initiator |
      |<--------------------------|

Operations, loop until peering is complete.

List Locations

+-----------+                                                  +-------+
| Initiator |                                                  | Peer  |
+-----------+                                                  +-------+
      |                                                            |
      | QUERY peering locations (peer type, ASN, auth code)        |
      |----------------------------------------------------------->|
      |                                                            |
      |                               Reply with peering locations |
      |                            or errors (401, 406, 451, etc.) |
      |<-----------------------------------------------------------|


Request session status

+-----------+                                                  +-------+
| Initiator |                                                  | Peer  |
+-----------+                                                  +-------+
      |                                                            |
      | QUERY request status using request ID & auth code          |
      |----------------------------------------------------------->|
      |                                                            |
      |                                  Reply with session status |
      |                                      (200, 404, 202, etc.) |
      |<-----------------------------------------------------------|

4.3. AUTH

First, the initiating OAuth2 Client is also the Resource Owner (RO) so it can follow the OAuth2 client credentials grant Section 4.4 of [RFC6749]. In this example, the client will use PeeringDB OIDC credentials to acquire a JWT access token that is scoped for use with the receiving API. On successful authentication, PeeringDB provides the Resource Server (RS) with the client's email (for potential manual discussion), along with the client's usage entitlements (known as OAuth2 scopes), to confirm the client is permitted to make API requests on behalf of the initiating AS.¶

4.4. REQUEST

1. ADD SESSION (CLIENT BATCHED REQUEST)¶

• 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¶

    2. Local IP¶

    3. Peer ASN¶

    4. Peer IP¶

    5. Local BGP Role according to [RFC9234]¶

    6. Peer BGP Role according to [RFC9234]¶

    7. Local insert ASN (optional to support route servers)¶

    8. Peer insert ASN (optional to support route servers)¶

    9. Local monitoring session (optional to support monitoring systems)¶

    10. Peer monitoring session (optional to support monitoring systems)¶

    11. Peer Type (public or private)¶

    12. Session Secret (optional with encoding agreed outside of this specification)¶

    13. 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.¶

  • Optional: checks traffic levels, prefix limit counters, other desired internal checks.¶

1. ADD SESSIONS (SERVER BATCHED RESPONSE)¶

• APPROVAL CASE¶

  • Server returns a list with the structure for each of the acceptable peering sessions. Note: this structure may also contain additional attributes such as the server generated session ID.¶

• PARTIAL APPROVAL CASE¶

  • Server returns a list with the structure for each of the acceptable peering sessions as in the approval case. The server also returns a list of sessions that have not deemed as validated or acceptable to be created. The set of sessions accepted and rejected is disjoint and the join of both sets matches the cardinality of the requested sessions.¶

• REJECTION CASE¶

  • Server returns an error message which indicates that all of the sessions requested have been rejected and the reason for it.¶

4.5. CLIENT CONFIGURATION

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.¶

4.6. SERVER CONFIGURATION

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.¶

4.7. 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 (where local refers to the server and peer refers to the client):¶

  • Session ID¶

  • Local ASN¶

  • Local IP¶

  • 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¶

  • Session secret (optional, as defined above)¶

  • Location¶

  • Status¶

The server then responds with the same structure, with the information that it understands (status, etc).¶

4.8. 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.¶

5.1. DATA TYPES

Please see specification ([autopeer]) for OpenAPI format.¶

Peering Location¶

Contains string field listing the desired peering location in format pdb:ix:$IX_ID, and an enum specifying peering type (public or private).¶

Session Status¶

Status of BGP Session, both as connection status and approval status (Established, Pending, Approved, Rejected, Down, Unestablished, etc)¶

Session Array¶

Array of potential BGP sessions, with request UUID. Request UUID is optional for client, and required for server. Return URL is optional, and indicates the client's Peering API endpoint. The client's return URL is used by the server to request additional sessions. Client may provide initial UUID for client-side tracking, but the server UUID will be the final definitive ID. RequestID will not change across the request.¶

BGP Session¶

A structure that describes a BGP session and contains the following elements:¶

• local_asn (ASN of requestor)¶

• 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)¶

• 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.¶

The above is sourced largely from the linked OpenAPI specification.¶

5.2. Endpoints

(As defined in [autopeer]). On each call, there should be rate limits, allowed senders, and other optional restrictions.¶

9.1. Threats

Each of the following threats assume a scenario where an arbitrary actor is capable of reaching the peering API instance of a given operator, the client and the operator follow their own endpoint security and maintenance practices, and the trust anchors in use are already established following guidelines outside of the scope of this document.¶

• T1: A malicious actor with physical access to the IX fabric and peering API of the receiver can use ASN or IP address information to impersonate a different IX member to discover, create, update or delete peering information which leads to loss of authenticity, confidentiality, and authorization of the spoofed IX member.¶

• T2: A malicious actor with physical access to the IX fabric can expose a peering API for an IX member different of its own to accept requests on behalf of such third party and supplant it, leading to a loss of authenticity, integrity, non-repudiability, and confidentiality between IX members.¶

• T3: A malicious actor without physical access to the IX fabric but with access the the peering API can use any ASN to impersonate any autonomous system and overload the receiver's peering API internal validations leading to a denial of service.¶

9.2. Authorization controls

The peering API instance receives HTTP requests from a client application from a peering initiator. Those requests can be authorized using the authorization model based on OAuth 2.0 ([RFC6749]) with the OpenID Connect [oidc] core attribute set. The choice of OpenID Connect is to use a standardized and widely adopted authorization exchange format based on JSON Web Tokens ([RFC7519]) which allows interoperation with existing web-based application flows. JWT tokens also supply sufficient claims to implement receiver-side authorization decisions by third parties when used as bearer access tokens ([RFC9068]). The peering API instance (a resource server in OAuth2 terms) should follow the bearer token usage ([RFC6750]) which describes the format and validation of an access token obtained from the Oauth 2.0 Authorization Server. The resource server should follow the best practices for JWT access validation ([RFC8725]) and in particular verify that the access token is constrained to the resource server via the audience claim. Upon successful access token validation, the resource server should decide whether to proceed with the request based on the presence of expected and matching claims in the access token or reject it altogether. The core identity and authorization claims present in the access token may be augmented with specific claims vended by the Authorization Service. This document proposes to use PeeringDB's access token claims as a baseline to use for authorization, however the specific matching of those claims to an authorization business decision is specific to each operator and outside of this specification. Resource servers may also use the claims in the access token to present the callers' identity to the application and for auditing purposes.¶

9.3. Proof of holdership

The peering API defined in this document uses ASNs as primary identifiers to identify each party on a peering session besides other resources such as IP addresses. ASNs are explicitly expected in some API payloads but are also implicitly expected when making authorization business decisions such as listing resources that belong to an operator. Given that ASNs are Internet Number Resources assigned by RIRs and that the OAuth2 Authorization Server in use may not be operated by any of those RIRs, as it is the case of PeeringDB or any other commercial OAuth2 service, JWT claims that contain an ASN need be proved to be legitimately used by the initiator. This document proposes to attest ASN resource holdership using a mechanism based on RPKI ([RFC6480]) and in particular with the use of RPKI Signed Checklists (RSCs) ([RFC9323]).¶

JWT access tokens can be of two kinds, identifier-based tokens or self-contained tokens (Section 1.4 of [RFC6749]). Resource servers must validate them for every request. AS operators can hint other operators to validate whether a caller holds ownership of the ASN their request represent by issuing a signed checklist that is specific to the different validation methods as described below.¶

For Identifier-based access tokens, if the Authorization Server supports metadata, ASN holders must create a signed checklist that contains the well-known Authorization Server Metadata URI and a digest of the JSON document contained (Section 3 of [RFC8414]). If the authorization server does not support metadata, the signed checklist contains the token introspection URI and its digest.¶

Self-contained access tokens are cryptographically signed by the token issuer using a JSON Web Signature (JWS) ([RFC7515]). The cryptographic keys used for signature validation is exposed as a JSON Web Key (JWK) ([RFC7517]). ASN holders must create a signed checklist for the "jwks_uri" field of the Authorization Server Metadata URI and a digest of the JSON document contained (Section 3.2 of [RFC8414]).¶

Resource servers must validate the JWT access token in the following manner:¶

• If the access token is identifier-based, the resource server must resolve what introspection endpoint to use for the given access token, that is, either resolved through the Authorization Server Metadata URI (Section 3 of [RFC8414]) or pre-configured upon registration in the absence of metadata support.¶

  • The resource server must verify the metadata URI and its content with a signed checklist issued by the ASN contained in the access token claims.¶

  • If the Authorization Server does not support metadata, the resource server must validate the introspection endpoint URI matches exactly the URI contained in a signed checklist issued by the ASN contained in the access token claims.¶

  • Upon successful signed checklist validation, resource servers must use the introspection endpoint for regular access token validation process ([RFC7662]).¶

• If the access token is self-contained, the resource server must follow the regular validation process for signed access tokens (Section 5.2 of [RFC7515]).¶

  • After discovering the valid public keys used to sign the token, the resource server must validate that the JWKS URI where the public keys have been discovered, and the content of such JSON document referred by it, match the signed checklist issued by the ASN contained in the access token claims.¶

• Resource servers must reject the request if any of these validations fail.¶

9.4. Request integrity and proof of possession

The API described in this document follows REST ([rest]) principles over an HTTP channel to model the transfer of requests and responses between peers. Implementations of this API should use the best common practices for the API transport ([RFC9325]) such as TLS. However, even in the presence of a TLS channel with OAuth2 bearer tokens alone, neither the client application nor the API can guarantee the end-to-end integrity of the message request or the authenticity of its content. One mechanism to add cryptographic integrity and authenticity validation can be the use a mutual authentication scheme to negotiate the parameters of the TLS channel. This requires the use of a web PKI ([RFC5280]) to carry claims for use in authorization controls, to bind such PKI to ASNs for proof of holdership, and the use of client certificates on the application.¶

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.¶

11.1. Normative References

[autopeer]

"Github repository with the API specification and diagrams", n.d., <https://github.com/bgp/autopeer/>.

[oidc]

"OpenID.Core", n.d., <https://openid.net/specs/openid-connect-core-1_0.html>.

[openapi]

"OpenAPI-v3.1.0", n.d., <https://spec.openapis.org/oas/v3.1.0>.

[rest]

Fielding, R. T., "Architectural Styles and the Design of Network-based Software Architectures", 2000, <http://roy.gbiv.com/pubs/dissertation/top.htm>.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/rfc/rfc6749>.

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/rfc/rfc6750>.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/rfc/rfc7515>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC8414]

Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/rfc/rfc8414>.

[RFC8725]

Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, February 2020, <https://www.rfc-editor.org/rfc/rfc8725>.

[RFC9068]

Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 2021, <https://www.rfc-editor.org/rfc/rfc9068>.

[RFC9323]

Snijders, J., Harrison, T., and B. Maddison, "A Profile for RPKI Signed Checklists (RSCs)", RFC 9323, DOI 10.17487/RFC9323, November 2022, <https://www.rfc-editor.org/rfc/rfc9323>.

[RFC9421]

Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP Message Signatures", RFC 9421, DOI 10.17487/RFC9421, February 2024, <https://www.rfc-editor.org/rfc/rfc9421>.

[RFC9449]

Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, <https://www.rfc-editor.org/rfc/rfc9449>.

11.2. Informative References

[RFC3912]

Daigle, L., "WHOIS Protocol Specification", RFC 3912, DOI 10.17487/RFC3912, September 2004, <https://www.rfc-editor.org/rfc/rfc3912>.

[RFC4271]

Rekhter, Y., Ed., Li, T., Ed., and S. Hares, Ed., "A Border Gateway Protocol 4 (BGP-4)", RFC 4271, DOI 10.17487/RFC4271, January 2006, <https://www.rfc-editor.org/rfc/rfc4271>.

[RFC5280]

Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, May 2008, <https://www.rfc-editor.org/rfc/rfc5280>.

[RFC6480]

Lepinski, M. and S. Kent, "An Infrastructure to Support Secure Internet Routing", RFC 6480, DOI 10.17487/RFC6480, February 2012, <https://www.rfc-editor.org/rfc/rfc6480>.

[RFC7454]

Durand, J., Pepelnjak, I., and G. Doering, "BGP Operations and Security", BCP 194, RFC 7454, DOI 10.17487/RFC7454, February 2015, <https://www.rfc-editor.org/rfc/rfc7454>.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-editor.org/rfc/rfc7517>.

[RFC7662]

Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/rfc/rfc7662>.

[RFC9092]

Bush, R., Candela, M., Kumari, W., and R. Housley, "Finding and Using Geofeed Data", RFC 9092, DOI 10.17487/RFC9092, July 2021, <https://www.rfc-editor.org/rfc/rfc9092>.

[RFC9234]

Azimov, A., Bogomazov, E., Bush, R., Patel, K., and K. Sriram, "Route Leak Prevention and Detection Using Roles in UPDATE and OPEN Messages", RFC 9234, DOI 10.17487/RFC9234, May 2022, <https://www.rfc-editor.org/rfc/rfc9234>.

[RFC9325]

Sheffer, Y., Saint-Andre, P., and T. Fossati, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 9325, DOI 10.17487/RFC9325, November 2022, <https://www.rfc-editor.org/rfc/rfc9325>.