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 5 January 2026.¶
The Peering API is a mechanism that allows networks to automate interdomain interconnection between two Autonomous Systems (AS) through the Border Gateway Protocol 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.¶
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¶
All terms used in this document will be defined here:¶
- Initiator
-
Network that wants to peer¶
- Receiver
-
Network that is receiving communications about peering¶
- Configured
-
peering session that is set up on one side¶
- Established
-
session is already defined as per BGP-4 specification Section 8.2.2 of [RFC4271]¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be interpreted as
described in BCP 14 [RFC2119] [RFC8174] when, and only when, they
appear in all capitals, as shown here.
These words may also appear in this document in
lower case as plain English words, absent their normative meanings.¶
The Peering API aims to simplify peering interconnection configuration.
To that end, the API can be called by either a human or some automation.
A network engineer can submit API requests through a client-side tool, and configure sessions by hand or through existing tooling.
Alternately, an automated service can request BGP sessions through some trigger or regularly scheduled request (for example, upon joining a new peering location, or through regular polling of potential peers).
That automated client can then configure the client sessions through its own tooling.
For ease of exchanging peering requests, the authors suggest peers to maintain both a client and a server for the API.
Toward the goal of streamlining peering configuration, the authors encourage peers to automate their network configuration wherever possible, but do not require full automation to use this API.¶
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 ([autopeer]).¶
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.¶
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.¶
This document does not specify how to discover an ASN's Peering API endpoint.
Some possible options are:¶
The preferred method is via the RPKI.¶
(As defined in [autopeer]).
On each call, there should be rate limits, allowed senders, and other optional restrictions.¶
Endpoints which provide useful information for potential interconnections.¶
-
ADD/AUGMENT PNI¶
-
Parameters:¶
-
Response:¶
-
REMOVE PNI¶
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 either reject all the session that do not meet the criteria caused by such absence in the client's request or approve the client's request and issue a separate request to the client's server requesting those 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 document describes a mechanism to standardize the discovery, creation and maintenance of peering relationships across autonomous systems (AS) using an out-of-band application programming interface (API). With it, AS operators take a step to operationalize their peering policy with new and existing peers in ways that improve or completely replace manual business validations, ultimately leading to the automation of the interconnection. However, this improvement can only be fully materialized when operators are certain that such API follows the operational trust and threat models they are comfortable with, some of which are documented in BGP operations and security best practices ([RFC7454]). To that extent, this document assumes the peering API will be deployed following a strategy of defense in-depth and proposes the following common baseline threat model below.¶
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.¶
The following list of mitigations address different parts of the threats identified above:¶
-
M1: Authorization controls - A initiator using a client application is authorized using the claims presented in the request prior to any interaction with the peering API (addresses T1, T2).¶
-
M2: Proof of holdership - The initiator of a request through a client can prove their holdership of an Internet Number Resource (addresses T1, T3).¶
-
M3: Request integrity and proof of possession - The peering API can verify HTTP requests signed with a key that is cryptographically bound to the authorized initiator (addresses T1, T2).¶
The Peering API does not enforce any kind of peering policy on the incoming requests. It is left to the peering API instance implementation to enforce the AS-specific peering policy. This document encourages each peer to consider the needs of their peering policy and implement request validation as desired.¶
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.¶
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 Attested OAuth
([draft-blahaj-grow-rpki-oauth]).¶
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.¶