This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF). Note that other groups may also distribute working
documents as Internet-Drafts. The list of current Internet-Drafts is
at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 22 July 2024.¶
The Peering API is a mechanism that allows networks to automate interdomain interconnection between two Autonomous Systems (AS) through the Border Gateway Protocol 4 (BGP-4) (RFC4271).
Using the API, networks will be able to automatically request and accept peering interconnections between Autonomous Systems in public or private scenarios in a time faster than it would take to configure sessions manually.
By speeding up the peering turn-up process and removing the need for manual involvement in peering, the API and automation will ensure that networks can get interconnected as fast, reliably, cost-effectively, and efficiently as possible.
As a result, this improves end-user performance for all applications using networks interconnection supporting the Peering API.¶
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¶
As peering connections exchange real Internet traffic, this API requires a security component to verify that the requestor is authorized to operate the interconnection on behalf of such AS.
In this initial proposal, the API follows an authorization model based on OpenID Connect (OIDC) (OpenID.Core) and OAuth 2.0 (RFC6749) where the Authorization Server is PeeringDB. The choice of OpenID Connect is to use the standardized token 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 when used as bearer access tokens (RFC9068) and for which best common practices also exist (RFC8725).
After further discussion, the authors decided to offer alternate authentication options to accommodate the security concerns of different parties.
As peers may require varying security standards, this document proposes to support PeeringDB OIDC as the base requirement, with optional security extensions in addition (RPKI (RFC6480) or alternative OIDC Authorization Servers, for example).
This document hopes that, through the RFC process, the Working Group can come to a consensus on a base "authorization standard," to ease adoption for peering participants.¶
Of particular interest is RPKI.
PeeringDB OIDC allows the API to identify who the requesting party is, while RPKI-signing allows such requesting party to prove that they own some of the Internet-assigned resources referenced in the request.
This combination provides a low entry barrier to create an identity federation across the participating ASs' API with a stronger guarantee of resource ownership against potential for misattribution and repudiation.
The authors recognize that not all partners have the time or engineering resources to support all authorization standards, so the API reference implementations will offer an extensible security mechanism to meet varying identity and security requirements.
For RPKI-based authentication, this document refers to RPKI Signed Checklists (RSCs) (RFC9323).¶
Each peer needs a public API endpoint that will implement the API protocol.
This API should be publicly listed in peeringDB and also as a potential expansion of RFC9092 which could provide endpoint integration to WHOIS (RFC3912).
Each API endpoint should be fuzz-tested and protected against abuse. Attackers should not be able to access internal systems using the API.
Every single request should come in with a unique GUID called RequestID that maps to a peering request for later reference. This GUID format should be standardized across all requests. This GUID should be provided by the receiver once it receives the request and must be embedded in all communication. If there is no RequestID present then that should be interpreted as a new request and the process starts again.
An email address is needed for communication if the API fails or is not implemented properly (can be obtained through PeeringDB).¶
For a programmatic specification of the API, please see the public Github here: https://github.com/bgp/autopeer/blob/main/api/openapi.yaml¶
This initial draft fully specifies the Public Peering endpoints. Private Peering and Maintenance are under discussion, and the authors invite collaboration and discussion from interested parties.¶
As defined in https://github.com/bgp/autopeer/blob/main/api/openapi.yaml.
Please see specification 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.
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¶
-
local_asn (ASN of requestor)¶
-
local_ip (IP of requestor, v4 or v6)¶
-
peer_asn (server ASN)¶
-
peer_ip (server-side IP)¶
-
peer_type (public or private)¶
-
md5 (optional string)¶
-
location (Peering Location, as defined above)¶
-
status (Session Status, as defined above)¶
-
UUID (of individual session. Server must provide UUID. Client may provide initial UUID for client-side tracking, but the server UUID will be the final definitive ID)¶
Error¶
API Errors, for field validation errors in requests, and request-level errors.¶
The above is sourced largely from the linked OpenAPI specification.¶
As part of public peering configuration, this draft must consider how the client and server should handshake at which sessions to configure peering.
At first, a client will request sessions A, B, and C.
The server may choose to accept all sessions A, B, and C.
At this point, configuration proceeds as normal.
However, the server may choose to reject session B.
At that point, the server will reply back with A and C marked as "Accepted," and B as "Rejected."
The server will then configure A and C, and wait for the client to configure A and C.
If the client configured B as well, it will not come up.¶
This draft encourages peers to set up garbage collection for unconfigured or down peering sessions, to remove stale configuration and maintain good router hygiene.¶
Related to rejection, if the server would like to configure additional sessions with the client, the server may reply back with additional peering sessions D and E.
The server will configure D and E on their side, and D and E will become part of the sessions requested in the UUID.
The client may choose whether or not to accept those additional sessions.
If they do, the client should configure D and E as well.
If they do not, the client will not configure D and E, and the server should garbage-collect those pending sessions.¶
As part of the IETF discussion, the authors would like to discuss how to coordinate which side unfilters first.
Perhaps this information could be conveyed over a preferences vector.¶
This draft does not want to invent a new ticketing system.
However, there is an opportunity in this API to provide maintenance notifications to peering partners.
If there is interest, this draft would extend to propose a maintenance endpoint, where the server could broadcast upcoming and current maintenance windows.¶
A maintenance message would follow a format like:¶
-
Title: string¶
-
Start Date: date maintenance start(s/ed): UTC¶
-
End Date: date maintenance ends: UTC¶
-
Area: string or enum¶
-
Details: freeform string¶
The "Area" field could be a freeform string, or could be a parseable ENUM, like (BGP, PublicPeering, PrivatePeering, Configuration, Caching, DNS, etc).¶
Past maintenances will not be advertised.¶
This project is joint work between Meta, AWS, Cloudflare, FullCtl, and Google.
Many thanks to my collaborators: Carlos Aguado (AWS), Ben Blaustein (Meta), Matt Griswold (FullCtl), Ben Ryall (Meta), Arturo Servin (Google), and Tom Strickx (Cloudflare).¶