diff --git a/draft-ramseyer-grow-peering-api.md b/draft-ramseyer-grow-peering-api.md index 6895f20..c234405 100644 --- a/draft-ramseyer-grow-peering-api.md +++ b/draft-ramseyer-grow-peering-api.md @@ -92,7 +92,7 @@ By using the Peering API, entities requesting and accepting peering can signific * And by peering, reducing network latency through expansion of interconnection relationships -Conventions and Definitions {#conventions} +Conventions and Terminology {#conventions} =========================== All terms used in this document will be defined here: @@ -103,26 +103,6 @@ All terms used in this document will be defined here: * Established: session is already defined as per BGP-4 specification {{Section 8.2.2 of ?RFC4271}} -Security Considerations {#security} -======================= - -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}} 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}}). - -The Peering API does not enforce any kind of peering policy on the incoming requests. -It is left to the server implementation to enforce the AS-specific peering policy. -The authors encourage each peer to consider the needs of their peering policy and implement request validation as desired. - - Audience {#audience} ======== The Peering API aims to simplify peering interconnection configuration. @@ -491,6 +471,60 @@ The "Area" field could be a freeform string, or could be a parseable ENUM, like Past maintenances will not be advertised. +Security Considerations {#security} +======================= + +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 fully materialize when operators can be certain that such API follows their operational trust and threat models some of which may already be based on IETF best common practices (e.g. {{?RFC7454}}). To that extent, this document assumes the peering API will be deployed following a strategy of defense in-depth and proposes a common baseline threat model with the corresponding threats and mitigations described below. + +#### Threats {#threats} + +Each of the following threats assume scenarios where an arbitrary actor is capable of reaching the peering API instance of a given operator, the operator and client follow their own endpoint practices for the security and maintenance of their respective service and client systems, and assume the trust anchors in use are established outside of this document. + +* T1: A malicious actor with physical access to the same 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 same 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 (MITM), leading to a loss of authenticity, integrity, non-repudiability, and confidentiality between IX members. +* T3: A malicious actor without physical access to the same IX fabric but with access the the peering API can use any ASN to impersonate a any autonomous system and overload the receiver's peering API internal validations leading to a denial of service. + +#### Mitigations {#mitigations} + +The following list of mitigations to the threats identified above: + +* M1: Authorization controls: a initiator using a client application is authorized from the claims presented in the request prior to any interaction with the peering API (T1, T2). +* M2: Proof of holdership: the initiator of a request through a client and prove their holdership of an Internet-assigned resource (T1, T3). +* M3: Request integrity and proof of posession: the client application can cryptographically sign HTTP requests with a key that is bound the authorized initiator (T1, T2). + +The Peering API does not enforce any kind of peering policy on the incoming requests. It is left to the server 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. + +Authorization controls {#authorization} +---------------------- + +The peering API receives HTTP requests from a client application from a peering initiator. Those requests must 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 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}}). To this extent, implementations should follow the bearer token usage ({{!RFC6750}}) that includes an access token obtained from the Oauth 2.0 Authorization Server and whose audience must be constrained to the resource server the peering API implements. Upon successful validation, the peering API should decide whether to proceed with the request based on the presence of 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 JWT access token claims as the baseline, however the specific matching of those that conform the authorization business decision are specific to each operator and outside of this specification. The use of access tokens vended through OAuth2 flows for every peering API resource also allows operators to use those to preserve the callers' identity for auditing purposes. + +Proof of holdership {#resource-holdership} +------------------- + +The peering API defined in this document uses ASNs as primary identifiers to identify each party on a peering session besides other properties like IP addresses. ASNs will be explicit expected in some API payloads but are also implicitly expected when making authorization business decisions such as listing resources that belong to an AS operator. Given that ASNs are Internet Number Resources assigned by RIRs and that the Authorization Server may not be operated by one of those RIRs, as it is the case of PeeringDB, JWT claims for an ASN cannot be proved to be legitimately bound to the initiator. For that purpose, this document proposes an additional mechanism based on RPKI ({{?RFC6480}}) to attest ASN resource holdership based on RPKI Signed Checklists (RSCs) ({{?RFC9323}}). + +JWT access tokens can be identifier-based or self-contained ({{Section 1.4 of ?RFC6749}}) and resource servers must validate them for every request. AS operators can request other operators to validate whether a caller holds ownership of the ASN they represent by issuing a RSC 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 an RSC 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 RSC 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 RSC 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, resolved through the Authorization Server Metadata URI ({{Section 3 of !RFC8414}}) or preconfigured in the absence of metadata support. + * The resource server must verify metadata URI and its content with an RSC issued by the ASN contained in the access token claims. + * If the Authorization Server does not support metadata, the resource service must validate the introspection endpoint URI matches exactly the URI contained in a RSC issued by the ASN contained in the access token claims. + * Upon successful RSC validation, resource servers must use the introspection endpoint for their validation ({{?RFC7662}}). +* If the access token is self-contained, the resource server must validate the token as per the standard validation process ({{Section 5.2 of !RFC7515}}). + * When discovering the public keys to validate the token, the resource server must validate that the JWKS URI and the content of the JSON document referred by it matches the RSC issued by the ASN contained in the access token claims. +* Resource servers must reject the request if any validation fails. + +Request integrity and proof of posession {#integrity-and-possession} +---------------------------------------- + +TODO + Possible Extensions {#extensions} ===================