--- 1/draft-ietf-asap-sip-auto-peer-02.txt 2021-10-24 23:13:11.077056428 -0700 +++ 2/draft-ietf-asap-sip-auto-peer-03.txt 2021-10-24 23:13:11.153058340 -0700 @@ -1,20 +1,20 @@ ASAP K. Inamdar Internet-Draft Unaffiliated Intended status: Standards Track S. Narayanan -Expires: 9 December 2021 C. Jennings +Expires: 27 April 2022 C. Jennings Cisco Systems - 7 June 2021 + 24 October 2021 Automatic Peering for SIP Trunks - draft-ietf-asap-sip-auto-peer-02 + draft-ietf-asap-sip-auto-peer-03 Abstract This draft specifies a configuration workflow to enable enterprise Session Initiation Protocol (SIP) networks to solicit the capability set of a SIP service provider network. The capability set can subsequently be used to configure features and services on the enterprise edge element, such as a Session Border Controller (SBC), to ensure smooth peering between enterprise and service provider networks. @@ -27,99 +27,96 @@ 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 9 December 2021. + This Internet-Draft will expire on 27 April 2022. Copyright Notice Copyright (c) 2021 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 - 2. Overview of Operations . . . . . . . . . . . . . . . . . . . 4 - 2.1. Reference Architecture . . . . . . . . . . . . . . . . . 4 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 + 2. Overview of Operations . . . . . . . . . . . . . . . . . . . 3 + 2.1. Reference Architecture . . . . . . . . . . . . . . . . . 3 2.2. Configuration Workflow . . . . . . . . . . . . . . . . . 5 - 2.3. Transport . . . . . . . . . . . . . . . . . . . . . . . . 7 + 2.3. Transport . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Conventions and Terminology . . . . . . . . . . . . . . . . . 8 4. HTTP Transport . . . . . . . . . . . . . . . . . . . . . . . 8 4.1. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 8 4.2. Integrity and Confidentiality . . . . . . . . . . . . . . 8 - 4.3. Authenticated Client Identity . . . . . . . . . . . . . . 9 - 4.4. Encoding the Request . . . . . . . . . . . . . . . . . . 9 - 4.5. Identifying the Request Target . . . . . . . . . . . . . 9 - 4.6. Generating the response . . . . . . . . . . . . . . . . . 10 - 5. State Deltas . . . . . . . . . . . . . . . . . . . . . . . . 11 - 6. Encoding the Service Provider Capability Set . . . . . . . . 11 - 7. Data Model for Capability Set . . . . . . . . . . . . . . . . 12 - 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12 - 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 14 - 7.3. Node Definitions . . . . . . . . . . . . . . . . . . . . 20 - 7.4. Extending the Capability Set . . . . . . . . . . . . . . 29 - 8. Processing the Capability Set Response . . . . . . . . . . . 30 - 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 31 - 9.1. XML Capability Set Document . . . . . . . . . . . . . . . 31 - 9.2. Example Exchange . . . . . . . . . . . . . . . . . . . . 33 - 10. Security Considerations . . . . . . . . . . . . . . . . . . . 33 - 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 33 - 12. Normative References . . . . . . . . . . . . . . . . . . . . 33 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 + 4.3. Authenticated Client Identity . . . . . . . . . . . . . . 8 + 4.4. Encoding the Request . . . . . . . . . . . . . . . . . . 11 + 4.5. Identifying the Request Target . . . . . . . . . . . . . 11 + 4.6. Generating the response . . . . . . . . . . . . . . . . . 12 + 5. State Deltas . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6. Encoding the Service Provider Capability Set . . . . . . . . 13 + 7. Data Model for Capability Set . . . . . . . . . . . . . . . . 13 + 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 + 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 15 + 7.3. Node Definitions . . . . . . . . . . . . . . . . . . . . 22 + 7.4. Extending the Capability Set . . . . . . . . . . . . . . 32 + 8. Processing the Capability Set Response . . . . . . . . . . . 33 + 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 34 + 9.1. JSON Capability Set Document . . . . . . . . . . . . . . 34 + 9.2. Example Exchange . . . . . . . . . . . . . . . . . . . . 36 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 36 + 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36 + 12. Normative References . . . . . . . . . . . . . . . . . . . . 37 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 1. Introduction - The deployment of a Session Initiation Protocol [RFC 3261 - (https://tools.ietf.org/html/rfc3261)] (SIP)-based infrastructure in - enterprise and service provider communication networks is increasing - at a rapid pace. Consequently, direct IP peering between enterprise - and service provider networks is quickly replacing traditional - methods of interconnection between enterprise and service provider - networks. Currently published standards provide a strong foundation - over which direct IP peering can be realized. However, given the - sheer number of these standards, it is often not clear which - behavioral subsets, extensions to baseline protocols and operating - principles ought to be implemented by service provider and enterprise - networks to ensure successful peering. + The deployment of a Session Initiation Protocol [RFC3261] (SIP)-based + infrastructure in enterprise and service provider communication + networks is increasing at a rapid pace. Consequently, direct IP + peering between enterprise and service provider networks is quickly + replacing traditional methods of interconnection between enterprise + and service provider networks. Currently published standards provide + a strong foundation over which direct IP peering can be realized. + However, given the sheer number of these standards, it is often not + clear which behavioral subsets, extensions to baseline protocols and + operating principles ought to be implemented by service provider and + enterprise networks to ensure successful peering. - The SIP Connect technical recommendations - (https://www.sipforum.org/download/sipconnect-technical- - recommendation-version-2-0/?wpdmdl=2818) aim to solve this problem by - providing a master reference that promotes seamless peering between - enterprise and service provider SIP networks. However, despite the - extensive set of implementation rules and operating guidelines, - interoperability issues between service provider and enterprise - networks persist. This is in large part because service providers - and equipment manufacturers aren't required to enforce the guidelines - of the technical specifications and have a fair degree of freedom to - deviate from them. Consequently, enterprise administrators usually - undertake a fairly rigorous regimen of testing, analysis and - troubleshooting to arrive at a configuration block that ensures - seamless service provider peering. However, this workflow - complements the SIP Connect technical recommendations, in that both - endeavours aim to promote/achieve interop between the enterprise and - service provider. + The SIP Connect technical recommendations [SIP-Connect-TR] aim to + solve this problem by providing a master reference that promotes + seamless peering between enterprise and service provider SIP + networks. However, despite the extensive set of implementation rules + and operating guidelines, interoperability issues between service + provider and enterprise networks persist. This is in large part + because service providers and equipment manufacturers aren't required + to enforce the guidelines of the technical specifications and have a + fair degree of freedom to deviate from them. Consequently, + enterprise administrators usually undertake a fairly rigorous regimen + of testing, analysis and troubleshooting to arrive at a configuration + block that ensures seamless service provider peering. However, this + workflow complements the SIP Connect technical recommendations, in + that both endeavours aim to promote/achieve interop between the + enterprise and service provider. Another set of interoperability problems arise when enterprise administrators are required to translate a set of technical recommendations from service providers to configuration blocks across one or more devices in the enterprise, which is usually an error prone exercise. Additionally, such technical recommendations might not be nuanced enough to intuitively allow the generation of specific configuration blocks. This draft introduces a mechanism using which an enterprise network @@ -132,25 +129,24 @@ 2. Overview of Operations This section details the configuration workflow proposed by this draft. 2.1. Reference Architecture Figure 1 illustrates a reference architecture that may be deployed to support the mechanism described in this document. The enterprise network consists of a SIP-PBX, media endpoints and a Session Border - Controller [RFC 7092 (https://tools.ietf.org/html/rfc7092)]. It may - also include additional components such as application servers for - voicemail, recording, fax etc. At a high level, the service provider - consists of a SIP signaling entity (SP-SSE), a media entity and a - HTTPS [RFC 7231 (https://tools.ietf.org/html/rfc7231)] server. + Controller [RFC7092]. It may also include additional components such + as application servers for voicemail, recording, fax etc. At a high + level, the service provider consists of a SIP signaling entity (SP- + SSE), a media entity and a HTTPS [RFC7231] server. +-----------------------------------------------------+ | +---------------+ +-----------------------+ | | | | | | | | | +----------+ | | +-------+ | | | | | Cap | | HTTPS | | | | | | | | Server |<-|---------|-->| | | | | | | | | | | | +-----+ | | | | +----------+ | | | | | SIP | | | | | | | | |<->| PBX | | | @@ -174,22 +170,22 @@ * Enterprise Network: A communications network infrastructure deployed by an enterprise which interconnects with the service provider network over SIP. The enterprise network could include devices such as application servers, endpoints, call agents and edge devices, among others. * Edge Device: A device that is the last hop in the enterprise network and that is the transit point for traffic entering and leaving the enterprise. An edge device is typically a back-to- - back user agent (B2BUA) [RFC 7092 (https://tools.ietf.org/html/ - rfc7092)] such as a Session Border Controller (SBC). + back user agent (B2BUA) [RFC7092] such as a Session Border + Controller (SBC). * Service Provider Network: A communications network infrastructure deployed by service providers. In the context of this draft, the service provider network is accessible over SIP for the establishment, modification and termination of calls and accessible over HTTPS for the transfer of the capability set document. The service provider network is also referred to as a SIP Service Provider (SSP) or Internet Telephony Service Provider (ITSP) network. @@ -241,52 +237,51 @@ enterprise network can solicit and ultimately obtain the service provider capability set. The enterprise network creates a well formed HTTPS GET request to solicit the service provider capability set. Subsequently, the HTTPS response from the SIP service provider includes the capability set. The capability set is encoded in either XML or JSON, thus ensuring that the response can be easily parsed by automaton. There are alternative mechanisms using which the SIP service provider can offload its capability set. For example, the Session Initiation - Protocol (SIP) can be extended to define a new event package [RFC - 6665 (https://tools.ietf.org/html/rfc6665)], such that the enterprise - network can establish a SIP subscription with the service provider - for its capability set; the SIP service provider can subsequently use - the SIP NOTIFY request to communicate its capability set or any state - deltas to its baseline capability set. + Protocol (SIP) can be extended to define a new event package + [RFC6665], such that the enterprise network can establish a SIP + subscription with the service provider for its capability set; the + SIP service provider can subsequently use the SIP NOTIFY request to + communicate its capability set or any state deltas to its baseline + capability set. This mechanism is likely to result in a barrier to adoption for SIP service providers and enterprise networks as equipment manufacturers would have to first add support for such a SIP extension. A HTTPS- based approach would be relatively easier to adopt as most edge devices deployed in enterprise networks today already support HTTPS; from the perspective of service provider networks, all that is required is for them to deploy HTTPS servers that function as capability servers. Additionally, most SIP service providers require enterprise networks to register with them (using a SIP REGISTER message) before any other SIP methods that initiate subscriptions (SIP SUBSCRIBE) or calls (SIP INVITE) are processed. As a result, a SIP-based framework to obtain a capability set would require operational changes on the part of service provider networks. Yet another example of an alternative mechanism would be for service providers and enterprise equipment manufacturers to agree on YANG - models [RFC 6020 (https://tools.ietf.org/html/rfc6020)] that enable - configuration to be pushed over NETCONF [RFC 6241 - (https://tools.ietf.org/html/rfc6241)] to enterprise networks from a - centralised source hosted in service provider networks. The presence - of proprietary software logic for call and media handling in - enterprise devices would preclude the generation of a "one-size-fits- - all" YANG model. Additionally, service provider networks pushing - configuration to enterprises devices might lead to the loss of - implementation autonomy on the part of the enterprise network. + models [RFC6020] that enable configuration to be pushed over NETCONF + [RFC6241] to enterprise networks from a centralised source hosted in + service provider networks. The presence of proprietary software + logic for call and media handling in enterprise devices would + preclude the generation of a "one-size-fits-all" YANG model. + Additionally, service provider networks pushing configuration to + enterprises devices might lead to the loss of implementation autonomy + on the part of the enterprise network. 2.3. Transport To solicit the capability set of a SIP service provider, the edge element in an enterprise network generates a well-formed HTTPS GET request. There are two reasons why it makes sense for the enterprise edge element to generate the HTTPS request: 1. Edge elements are devices that normalise any mismatches between the enterprise and service provider networks in the media and @@ -351,34 +346,129 @@ The workflow defined in this document leverages the HTTPS GET method and its corresponding response(s) to request for and subsequently obtain the service provider capability set document. 4.2. Integrity and Confidentiality Peering requests and responses are defined over HTTPS. However, due to the sensitive nature of information transmitted between client and server, it is required to secure HTTP using Transport Layer Security - [RFC 5246 (https://tools.ietf.org/html/rfc5246)]. The enterprise - edge element and capability server MUST be compliant with RFC 7235 - (https://tools.ietf.org/html/rfc7235). The enterprise edge element - and capability server MUST support the use of the HTTPS uri scheme as - defined in RFC 7230 (https://tools.ietf.org/html/rfc7230). + [RFC5246]. The enterprise edge element and capability server MUST be + compliant with [RFC7235]. The enterprise edge element and capability + server MUST support the use of the HTTPS uri scheme as defined in RFC + 7230 (https://tools.ietf.org/html/rfc7230). 4.3. Authenticated Client Identity - It is only required for the SIP service provider to authenticate the - client (enterprise edge element). How the SIP service provider - authenticates the client is out of the scope of this document, - however, methods such as HTTP Digest Authentication or validation of - the hostname presented in the certificate during the TLS exchange may - be used. + HTTP usually adopts asymmetric methods of authentication. For + example, clients typically use certificate based authentication to + verify the server they are talking to, whereas, servers typically use + methods such as HTTP digest authentication or OAuth2.0 to + authenticate clients. Though OAuth2.0 is not an authentication + protocol, it nonetheless allows for client authentication to be + carried out with the use of OAuth tokens. + + Figure 2 elucidates the use of this grant type. + + In the context of the SIP Auto Peer framework, OAuth2.0 MUST be used + to carry out client authentication. Enterprise edge elements that + obtain the capability set document from SIP service providers could + have differing capabilities in terms of adhering to a specific + OAuth2.0 authorisation grant flow. For example, an SBC that is + configured and managed through a CLI and that does not have the + ability to launch a web-browser wouldn't be able to obtain an + authorisation code and subsequently an access token. Alternatively, + an SBC that is configured and managed via a GUI could redirect an + administrator to an appropriate OAuth2.0 authorisation server to + obtain an authorisation grant and subsequently an access token. In + order to ensure that OAuth2.0-based client authentication can be + carried out irrespective of enterprise edge element capabilities, + this draft requires that the Resource Owner Password Credentials + grant type be supported. + + Using the resource owner password credentials grant type requires the + existence of a trust relationship between the resource owner(in this + context, the administrator/enterprise network) and the client(in this + context, an edge element such as an SBC). In SIP trunking + deployments between enterprise and service provider networks, such a + trust relationship between the administrator/resource owner/ + enterprise network and the client(edge element) already exists, as + SIP trunk registration (and refreshing registrations) require + credentials - typically a username and password, that are configured + on the edge element by the administrator. + + The use of the resource owner credential grant type in the context of + the SIP Auto Peer framework, provides two advantages: + + 1. It enables OAuth2.0-based client authentication even in + deployments in wherein the edge element is not capable of + launching a web-browser to set in motion the authorisation code + grant flow of OAuth2.0 + + 2. For situations in which a refresh token is not provided by the + authorisation endpoint, human/administrator involvement is not + required to obtain fresh tokens once an existing token expires. + Figure 2 provides a high-level diagrammatic illustration of how + OAuth2.0-based client authentication is achieved using resource + owner credentials in the context of SIP Auto Peer. + + +--------------+ + | Resource | + | Owner | + | (Enterprise) | + +--------------+ + v + | Resource Owner + (1) Password Credentials + | + v + +---------+ +---------------+ + | |>--(2)---- Resource Owner ------->| Service | + | Client | Password Credentials | Provider | + | | | Authorization | + | (SBC) |<--(3)---- Access Token ---------<| Server | + | | (w/ Optional Refresh Token) | | + +---------+ +---------------+ + ^ v + | | + | | +--------------+ + | -------(4)---- Access Token --------->| Capability | + -----------(5)---- Capability set -------<| Server | + +--------------+ + + Figure 2: Client Authentication Mechanism + + The flow illustrated in Figure 2 includes the following steps: + + 1. The enterprise SBC stores the enterprise credentials required to + authenticate with the authorization server located in the service + provider network. These credentials may be passed to the + enterprise from the service provider in an out-of-band fashion + such as an email or a self-management service provided by the + service provider to the enterprise. + + 2. The enterprise SBC contacts the service provider authorization + server to obtain an access token using the credentials acquired + in Step 1. + + 3. The service provider authorization server ratifies the + credentials and grants the access token to the enterprise SBC. + The server could also provide a refresh token to the SBC to + regenerate the access token in the future. + + 4. The enterprise SBC then contacts the capability server located in + the service provider network with an HTTPS GET request along with + the access token to retrieve the capability set document. + + 5. The capability server checks for a valid access token and returns + the capability set document to the enterprise SBC. 4.4. Encoding the Request The edge element in the enterprise network generates a HTTPS GET request such that the request-target is obtained using the procedure outlined in section 6.6 The MIME types for the capability set document defined in this draft are "application/peering-info+json" and "application/peering-info+xml". Accordingly, the Accept header field value MUST be restricted only to these MIME types. It is possible that the edge element supports responses formatted in both @@ -422,34 +512,33 @@ HTTP/1.1 200 OK Access-Control-Allow-Origin: * Content-Type: application/jrd+json { "subject" : "http://ssp1.example.com", "links" : [ { "rel" : "capabilitySet", - "href" :"https://capserver.ssp1.com/capserver/capdoc.xml" + "href" : + "https://capserver.ssp1.com/capserver/capdoc.json" }, ] } Once the target URI is obtained by an enterprise telephony network, the URI may be dereferenced to obtain a unique capability set document that is specific to that given enterprise telephony network. The ITSP may use credentials to determine the identity of the enterprise telephony network and provide the appropriate capability set document. - TODO: Should we have a new link-relation type registered for ASAP? - 4.6. Generating the response Capability servers include the capability set documents in the body of a successful response. Capability set documents MUST be formatted in XML or JSON. For requests that are incorrectly formatted, the capability server must generate a "400 Bad Request" response. If the client (enterprise edge element) includes any other MIME types in Accept header field other than "application/peering-info+json" or "application/peering-info+xml", the capability set must reject the request with a "406 Not Acceptable" response. @@ -500,24 +588,23 @@ 7. Data Model for Capability Set This section defines a YANG module for encoding the service provider capability set. Section 9.1 provides the tree diagram, which is followed by a description of the various nodes within the module defined in this draft. 7.1. Tree Diagram - This section provides a tree diagram [RFC 8340 - (https://tools.ietf.org/html/rfc8340)] for the "ietf-capability-set" - module. The interpretation of the symbols appearing in the tree - diagram is as follows: + This section provides a tree diagram [RFC8340] for the "ietf- + capability-set" module. The interpretation of the symbols appearing + in the tree diagram is as follows: * Brackets "[" and "]" enclose list keys. * Abbreviations before data node names: "rw" means configuration (read-write), and "ro" means state data (read-only). * Symbols after data node names: "?" means an optional node, "!" means a presence container, and "*" denotes a list and leaf-list. * Parentheses enclose choice and case nodes, and case nodes are also @@ -525,31 +612,37 @@ * Ellipsis ("...") stands for contents of subtrees that are not shown. The data model for the peering capability document has the following structure: module: ietf-sip-auto-peering +--rw peering-info +--rw variant string + +--rw revision + | +--rw notBefore? string + | +--rw location? string +--rw transport-info | +--rw transport? enumeration | +--rw registrar* host-port | +--rw registrarRealm? string | +--rw callControl* host-port | +--rw dns* inet:ip-address | +--rw outboundProxy? host-port +--rw call-specs | +--rw earlyMedia? boolean | +--rw signalingForking? boolean | +--rw supportedMethods? string + | +--rw callerId + | | +--rw e164Format? boolean + | | +--rw preferredMethod? string | +--rw numRange | +--rw numRangeType? string | +--rw count? int32 | +--rw value* string +--rw media | +--rw mediaTypeAudio | | +--rw mediaFormat* string | +--rw fax | | +--rw protocol* enumeration | +--rw rtp @@ -571,44 +664,45 @@ | +--rw secureTelephonyIdentity | +--rw STIRCompliance? boolean | +--rw certDelegation? boolean | +--rw ACMEDirectory? string +--rw extensions? string 7.2. YANG Model This section defines the YANG module for the peering capability set document. It imports modules (ietf-yang-types and ietf-inet-types) - from [RFC 6991 (https://tools.ietf.org/html/rfc6991)]. + from [RFC6991]. module ietf-sip-auto-peering { namespace "urn:ietf:params:xml:ns:ietf-sip-auto-peering"; prefix "peering"; description "Data model for transmitting peering parameters from SP to Enterprise"; revision 2019-05-06 { description "Initial revision of peering-response doc."; } import ietf-inet-types { prefix "inet"; } typedef ipv4-address-port { type string { - pattern "(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\" - + ".){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" + pattern "(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" + + "\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" + "{2}|655[1-2][0-9]|6553[1-5])$"; + } description "The ipv4-address-port type represents an IPv4 address in dotted-quad notation followed by a port number."; } typedef ipv6-address-port { type string { pattern "((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}" + "((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|" + "(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}" @@ -662,20 +756,35 @@ "The host type represents either an IP address or a DNS domain name followed by a port number."; } container peering-info { leaf variant { type string; mandatory true; description "Variant of peering-response document"; } + + container revision { + leaf notBefore { + type string; + description "Time and date of activation of new + capability set"; + } + + leaf location { + type string; + description "Location of the new version of + capability set document"; + } + } + container transport-info { leaf transport { type enumeration { enum "TCP"; enum "TLS"; enum "UDP"; enum "TCP;TLS"; enum "TCP;TLS;UDP"; enum "TCP;UDP"; } @@ -691,21 +799,22 @@ leaf registrarRealm { type string; description "Realm for REGISTER requests carrying credentials"; } leaf-list callControl { type host-port; max-elements 3; - description "List of service provider call control servers"; + description "List of service provider call control + servers"; } leaf-list dns { type inet:ip-address; max-elements 2; description "IP address of the DNS Server(s) hosted by the service provider"; } leaf outboundProxy { @@ -726,39 +835,54 @@ description "Flag indicating whether the service provider is capable of forking incoming calls "; } leaf supportedMethods { type string; description "Leaf/Leaf List indicating the different SIP methods support by the service provider."; } + container callerId { + leaf e164Format { + type boolean; + description "Flag indicating whether enterprise must + format caller information into E.164"; + } + + leaf preferredMethod { + type string; + description "Field that instructs enterprise regarding + which SIP header it must populate to communicate caller + information."; + } + } + container numRange { leaf numRangeType { type string; description "String indicating whether the DID number - range is passed by value or by reference" + range is passed by value or by reference"; } leaf count { when "../numRangeType = 'range' or ../numRangeType = 'block'"; type int32; description "Number of DID numbers present in the number - range." + range."; } leaf-list value { type string; description "Value of the DID number range or URL being - passed as reference." + passed as reference."; } } } container media { container mediaTypeAudio { leaf-list mediaFormat { type string; description "Leaf List indicating the audio media formats @@ -794,21 +920,22 @@ container rtcp { leaf symmetricRTCP { type boolean; description " Flag indicating whether the service provider expects symmetric RTP defined in [@RFC4961]."; } leaf RTCPfeedback { type boolean; description "Flag Indicating support for RTP profile - extension for RTCP-based feedback, as defined in [@RFC4585]"; + extension for RTCP-based feedback, as defined in + [@RFC4585]"; } } } container dtmf { leaf payloadNumber { type int8 { range "96..127"; } description "Leaf that indicates the payload number(s) @@ -892,29 +1020,39 @@ } } 7.3. Node Definitions This sub-sections provides the definition and encoding rules of the various nodes of the YANG module defined in section 9.2 *capability-set*: This node serves as a container for all the other nodes in the YANG module; the capability-set node is akin to the root - element of an XML schema. + element of an json document. *variant*: This node identifies the version number of the capability set document. This draft defines the parameters for variant 1.0; future specifications might define a richer parameter set, in which case the variant must be changed to 2.0, 3.0 and so on. Future extensions to the capability set document MUST also ensure that the corresponding YANG module is defined. + *revision*: The revision node is a container that encapsulates + information regarding the availability of a new version of the + capability set document for the enterprise. + + *notBefore*: The notBefore node indicates the date and time at which + the new capabilities go live in the service provider network. + + *location*: This leaf node value provides the URL of the new revision + of the capability set document + *transport-info*: The transport-info node is a container that encapsulates transport characteristics of SIP sessions between enterprise and service provider networks. *transport*: A leaf node that enumerates the different Transport Layer protocols supported by the SIP service provider. Valid transport layer protocols include: UDP, TCP, TLS or a combination of them (with the exception of TLS and UDP). *registrar*: A leaf-list that specifies the transport address of one @@ -993,20 +1132,42 @@ from the enterprise. A value of 0/false indicates that the service provider will not fork outbound call requests. *supportedMethods*: A leaf node that specifies the various SIP methods supported by the SIP service provider. The list of supported methods help to appropriately configuration various devices within the enterprise network. For example, if the service provider enumerates support for the OPTIONS method, the enterprise network could periodically send OPTIONS requests as a keep-alive mechanism. + *callerId*: This is a container that encodes the preferences of SIP + Service Providers in terms calling number presentation by the + enterprise network. Certain ITSPs require that the calling number be + formatted in E.164, whereas others place no such restrictions. + Additionally, some ITSPs require that the calling number be included + in a specific SIP header field, for example, the P-Asserted-ID header + field or the P-Asserted-ID field, whereas others place no + restrictions on the specific SIP header field used to convey the + calling number. + + *e164Format*: A leaf node that indicates whether the service provider + requires enterprise to normalize the caller number into the E.164 + format while communicating caller details. This node is of the + boolean type. A value of 'true' or '1' mandates the enterprise + format caller numbers into the E.164 format, while a 'false' or '0' + leaves the formatting of the caller number up to the enterprise. + + *preferredMethod*: A leaf node that instructs the enterprise + regarding which SIP header to populate the caller information into + when communicating caller ID information. This node will contain the + name of the SIP Header. + *numRange*: Is a container that specifies the Direct Inward Dial (DID) number range allocated to the enterprise network by the SIP service provider. The DID number range allocated by the service provider to the enterprise network might be a contiguous or a non- contiguous block. The number range allocated to an enterprise can be communicated as a value or as a reference. For large enterprise networks, the size of the DID range might run into several hundred numbers. For situations in which the enterprise is allocated a large DID number range or a non-contiguous number range it is RECOMMENDED that the SIP service provider communicate this information by @@ -1047,34 +1208,34 @@ supported by the SIP service provider. *mediaFormat*: A leaf-list encoding the various audio media formats supported by the SIP service provider. The relative ordering of different media format leaf nodes from left to right indicates preference from the perspective of the service provider. Each mediaFormat node begins with the encoding name of the media format, which is the same encoding name as used in the "RTP/AVP" and "RTP/ SAVP" profiles. The encoding name is followed by required and optional parameters for the given media format as specified when the - media format is registered [RFC 4855 (https://tools.ietf.org/html/ - rfc4855)]. Given that the parameters of media formats can vary from - one communication session to another, for example, across two - separate communication sessions, the packetization time (ptime) used - for the PCMU media format might vary from 10 to 30 ms, the parameters - included in the format element must be the ones that are expected to - be invariant from the perspective of the service provider. Providing - information about supported media formats and their respective - parameters, allows enterprise networks to configure the media plane - characteristics of various devices such as endpoints and middleboxes. - The encoding name, one or more required parameters, one or more - optional parameters are all separated by a semicolon. The formatting - of a given media format parameter, must follow the formatting rules - as specified for that media format. + media format is registered [RFC4855]. Given that the parameters of + media formats can vary from one communication session to another, for + example, across two separate communication sessions, the + packetization time (ptime) used for the PCMU media format might vary + from 10 to 30 ms, the parameters included in the format element must + be the ones that are expected to be invariant from the perspective of + the service provider. Providing information about supported media + formats and their respective parameters, allows enterprise networks + to configure the media plane characteristics of various devices such + as endpoints and middleboxes. The encoding name, one or more + required parameters, one or more optional parameters are all + separated by a semicolon. The formatting of a given media format + parameter, must follow the formatting rules as specified for that + media format. *fax*: A container that encapsulates the fax protocol(s) supported by the SIP service provider. The fax container encloses a leaf-list (named protocol) that enumerates whether the service provider supports t38 relay, protocol-based fax passthrough or both. The relative ordering of leaf nodes within the leaf lists indicates preference. *rtp*: A container that encapsulates generic characteristics of RTP sessions between the enterprise and service provider network. This @@ -1098,25 +1259,25 @@ While the practise of preserving the enterprise network in a hairpinned call flow is fairly common, it is recommended that SIP service providers avoid this practise. In the context of a hairpinned call, the enterprise device retained in the call flow can easily eavesdrop on the conversation between the offnet parties. *symmetricRTP*: A leaf node indicating whether the SIP service provider expects the enterprise network to use symmetric RTP as defined in RFC 4961 (https://tools.ietf.org/html/rfc4961). Uncovering this expectation is useful in scenarios where "latching" - [RFC 7362 (https://tools.ietf.org/html/rfc7362)] is implemented in - the service provider network. This node is a Boolean type, a value - of 1/true indicates that the service provider expects the enterprise - network to use symmetric RTP, whereas a value of 0/false indicates - that the enterprise network can use asymmetric RTP. + [RFC7362] is implemented in the service provider network. This node + is a Boolean type, a value of 1/true indicates that the service + provider expects the enterprise network to use symmetric RTP, whereas + a value of 0/false indicates that the enterprise network can use + asymmetric RTP. *rtcp*: A container that encapsulates generic characteristics of RTCP sessions between the enterprise and service provider network. This node is a container for the "RTCPFeedback" and "SymmetricRTCP" leaf nodes. *RTCPFeedback*: A leaf node that indicates whether the SIP service provider supports the RTP profile extension for RTCP-based feedback RFC 4585 (https://tools.ietf.org/html/rfc4585). Media sessions spanning enterprise and service provider networks, are rarely made to @@ -1303,47 +1464,49 @@ follows: module vendorA-config { namespace "urn:ietf:params:xml:ns:yang:vendorA-config"; prefix "vendorA"; description "Data model for configuring VendorA Enterprise SBC"; revision 2020-05-06 { - description "Initial revision of VendorA Enterprise SBC configuration data model"; + description "Initial revision of VendorA Enterprise SBC + configuration data model"; } import ietf-peering { prefix "peering"; } augment "/peering:peering-info" { container vendorAConfig { leaf vendorAConfigParam1 { type int32; - description "vendorA configuration parameter 1 (SBC Device ID)"; + description "vendorA configuration parameter 1 + (SBC Device ID)"; } leaf vendorAConfigParam2 { type string; - description "vendorA configuration parameter 2 (SBC Device name)"; + description "vendorA configuration parameter 2 + (SBC Device name)"; } description "Container for vendorA SBC configuration"; } } } In the example above, a custom module named "vendorA-config" uses the - "augment" statement as defined in Section 4.2.8 of [RFC 7950 - (https://tools.ietf.org/html/rfc7950)] to extend the module defined - in this draft. + "augment" statement as defined in Section 4.2.8 of [RFC7950] to + extend the module defined in this draft. 8. Processing the Capability Set Response This section provides a non-normative description of the procedures that could be carried out by the enterprise network after obtaining the SIP service provider capability set. On obtaining the capability set, the enterprise edge element can parse the various fields within the capability set and generate configuration blocks. For example, the configuration required to successfully register a SIP trunk with the SIP registrar hosted in the service provider network, the @@ -1364,123 +1527,133 @@ document might be used to communicate the specific fields of capacity set and their corresponding value. Alternatively, a human administrator could go through the capability set document and configure the edge element (and if required, other devices in the enterprise network appropriately. 9. Examples This section provides examples of how capability set documents that leverage the YANG module defined in this document can be encoded over - JSON or XML as well as the exchange of messages between the - enterprise edge element and the service provider to acquire the - capability set document. + JSON as well as the exchange of messages between the enterprise edge + element and the service provider to acquire the capability set + document. -9.1. XML Capability Set Document +9.1. JSON Capability Set Document - - 1.0 - - TCP;TLS;UDP - registrar1.voip.example.com:5060 - registrar2.voip.example.com:5060 - voip.example.com - callServer1.voip.example.com:5060 - 192.168.12.25:5065 - 8.8.8.8 - 208.67.222.222 - 0.0.0.0 - - - true - false - INVITE;OPTIONS;BYE;CANCEL;ACK;PRACK;SUBSCRIBE;NOTIFY;REGISTER - - range - 20 - 19725455000 - - - block - 2 - 1972546000 - 1972546001 - - - - - PCMU;rate=8000;ptime=20 - G729;rate=8000;annexb=yes - G722;rate=8000;bitrate=56k,64k - - - pass-through - t38 - - - true - true - - - true - true - - - - 101 - 0 - - - - TLS - 1.0;1.2 - - - SDES;DTLS-SRTP,version=1.2 - - https://sipserviceprovider.com/certificateList.pem - - true - true - https://sipserviceprovider.com/acme.html - - - timer;rel100;gin;path - + { + "peering-info": { + "variant": "1.0", + "revision": { + "notBefore": "2021-10-16T00:00:00.00000Z", + "location": + "https://capserver.ssp1.com/capserver/capdoc.json", + }, + "transport-info": { + "transport": "TCP;TLS;UDP", + "registrar": ["registrar1.voip.example.com:5060", + "registrar2.voip.example.com:5060"], + "registerRealm": "voip.example.com", + "callControl": ["callServer1.voip.example.com:5060", + "192.168.12.25:5065"], + "dns": ["8.8.8.8", "208.67.222.222"], + "outboundProxy": "0.0.0.0" + }, + "call-specs": { + "earlyMedia": "true", + "signalingForking": "false", + "supportedMethods": "INVITE;OPTIONS;BYE;CANCEL;ACK; + PRACK;SUBSCRIBE;NOTIFY;REGISTER", + "callerId": { + "e164Format": "true", + "preferredMethod": "P-Asserted-Identity" + }, + "numRange": { + "type": "range", + "count": "20", + "value": "19725455000" + }, + "numRange": { + "type": "block", + "count": "2", + "value": ["19725455000", "19725455001"] + } + }, + "media": { + "mediaTypeAudio": { + "mediaFormat": ["PCMU;rate=8000;ptime=20", + "G729;rate=8000;annexb=yes", + "G722;rate=8000;bitrate=56k,64k"] + }, + "fax": { + "protocol": ["t38", "pass-through"] + }, + "rtp": { + "RTPTrigger": "true", + "symmetricRTP": "true" + }, + "rtcp": { + "symmetricRTCP": "true", + "RTCPFeedback": "true" + } + }, + "dtmf": { + "payloadNumber": "101", + "iteration": "0" + }, + "security": { + "signaling": { + "type": "TLS", + "version": "1.0;1.2" + }, + "mediaSecurity": { + "keyManagement": "SDES;DTLS-SRTP,version=1.2" + + }, + "certLocation": + "https://sipserviceprovider.com/certificateList.pem", + "secureTelephonyIdentity": { + "STIRCompliance": "true", + "certDelegation": "true", + "ACMEDirectory": + "https://sipserviceprovider.com/acme.html" + } + }, + "extensions": "timer;rel100;gin;path" + } + } 9.2. Example Exchange - This section depicts an example of the configuration flow that - ultimately results in the enterprise edge element obtaining the - capability set document from the SIP service provider. Assuming the - enterprise edge element has been pre-configured with the request + This section is an informational example depicting the configuration + flow that ultimately results in the enterprise edge element obtaining + the capability set document from the SIP service provider. Assuming + the enterprise edge element has been pre-configured with the request target for the capability set document or has dynamically found the request target, the edge element generates a HTTPS GET request. This request can be challenged by the service provider to authenticate the enterprise. GET /capdoc?trunkid=trunkent1456 HTTP/1.1 Host: capserver.ssp1.com - Accept:application/peering-info+xml + Accept:application/peering-info+json The capability set document is obtained in the body of the response - and is encoded in XML. + and is encoded in JSON. HTTP/1.1 200 OK - Content-Type: application/peering-info+xml + Content-Type: application/peering-info+json Content-Length: nnn - - … - + { + "peering-info": ... + } 10. Security Considerations [TBD] 11. Acknowledgments [TBD] 12. Normative References @@ -1544,38 +1717,57 @@ . [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", RFC 6991, DOI 10.17487/RFC6991, July 2013, . [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr, "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September 2013, . + [RFC7092] Kaplan, H. and V. Pascual, "A Taxonomy of Session + Initiation Protocol (SIP) Back-to-Back User Agents", + RFC 7092, DOI 10.17487/RFC7092, December 2013, + . + [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, June 2014, . + [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer + Protocol (HTTP/1.1): Authentication", RFC 7235, + DOI 10.17487/RFC7235, June 2014, + . + [RFC7362] Ivov, E., Kaplan, H., and D. Wing, "Latching: Hosted NAT Traversal (HNT) for Media in Real-Time Communication", RFC 7362, DOI 10.17487/RFC7362, September 2014, . + [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", + RFC 7950, DOI 10.17487/RFC7950, August 2016, + . + [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, . [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, . + [SIP-Connect-TR] + "SIP Connect Technical Recommendation", + . + Authors' Addresses Kaustubh Inamdar Unaffiliated Email: kaustubh.ietf@gmail.com Sreekanth Narayanan Cisco Systems