idnits 2.17.00 (12 Aug 2021) /tmp/idnits16015/draft-ietf-asap-sip-auto-peer-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (21 April 2022) is 23 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: '0-9' is mentioned on line 976, but not defined == Missing Reference: '1-9' is mentioned on line 975, but not defined == Missing Reference: '0-4' is mentioned on line 709, but not defined == Missing Reference: '0-5' is mentioned on line 709, but not defined == Missing Reference: '1-5' is mentioned on line 741, but not defined == Missing Reference: '1-4' is mentioned on line 740, but not defined == Missing Reference: '1-2' is mentioned on line 741, but not defined -- Looks like a reference, but probably isn't: '01' on line 709 == Missing Reference: 'TBD' is mentioned on line 1645, but not defined == Unused Reference: 'RFC2119' is defined on line 1656, but no explicit reference was found in the text == Unused Reference: 'RFC5764' is defined on line 1701, but no explicit reference was found in the text == Unused Reference: 'RFC6749' is defined on line 1721, but no explicit reference was found in the text == Unused Reference: 'RFC8446' is defined on line 1766, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'ACME' -- Possible downref: Non-RFC (?) normative reference: ref. 'BCP-14' ** Obsolete normative reference: RFC 2833 (Obsoleted by RFC 4733, RFC 4734) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) ** Downref: Normative reference to an Informational RFC: RFC 7092 ** Downref: Normative reference to an Informational RFC: RFC 7362 -- Possible downref: Non-RFC (?) normative reference: ref. 'SIP-Connect-TR' Summary: 5 errors (**), 0 flaws (~~), 14 warnings (==), 5 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 ASAP K. Inamdar 3 Internet-Draft Unaffiliated 4 Intended status: Standards Track S. Narayanan 5 Expires: 23 October 2022 C. Jennings 6 Cisco Systems 7 21 April 2022 9 Automatic Peering for SIP Trunks 10 draft-ietf-asap-sip-auto-peer-05 12 Abstract 14 This draft specifies a configuration workflow to enable enterprise 15 Session Initiation Protocol (SIP) networks to solicit the capability 16 set of a SIP service provider network. The capability set can 17 subsequently be used to configure features and services on the 18 enterprise edge element, such as a Session Border Controller (SBC), 19 to ensure smooth peering between enterprise and service provider 20 networks. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at https://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on 23 October 2022. 39 Copyright Notice 41 Copyright (c) 2022 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 46 license-info) in effect on the date of publication of this document. 47 Please review these documents carefully, as they describe your rights 48 and restrictions with respect to this document. Code Components 49 extracted from this document must include Revised BSD License text as 50 described in Section 4.e of the Trust Legal Provisions and are 51 provided without warranty as described in the Revised BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Overview of Operations . . . . . . . . . . . . . . . . . . . 3 57 2.1. Reference Architecture . . . . . . . . . . . . . . . . . 3 58 2.2. Configuration Workflow . . . . . . . . . . . . . . . . . 5 59 2.3. Transport . . . . . . . . . . . . . . . . . . . . . . . . 6 60 3. Conventions and Terminology . . . . . . . . . . . . . . . . . 8 61 4. HTTP Transport . . . . . . . . . . . . . . . . . . . . . . . 8 62 4.1. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 8 63 4.2. Integrity and Confidentiality . . . . . . . . . . . . . . 8 64 4.3. Authenticated Client Identity . . . . . . . . . . . . . . 8 65 4.4. Encoding the Request . . . . . . . . . . . . . . . . . . 11 66 4.5. Identifying the Request Target . . . . . . . . . . . . . 11 67 4.6. Generating the response . . . . . . . . . . . . . . . . . 12 68 5. State Deltas . . . . . . . . . . . . . . . . . . . . . . . . 13 69 6. Encoding the Service Provider Capability Set . . . . . . . . 13 70 7. Data Model for Capability Set . . . . . . . . . . . . . . . . 13 71 7.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 13 72 7.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 15 73 7.3. Node Definitions . . . . . . . . . . . . . . . . . . . . 22 74 7.4. Extending the Capability Set . . . . . . . . . . . . . . 32 75 8. Processing the Capability Set Response . . . . . . . . . . . 33 76 9. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 33 77 9.1. JSON Capability Set Document . . . . . . . . . . . . . . 33 78 9.2. Example Exchange . . . . . . . . . . . . . . . . . . . . 35 79 10. Security Considerations . . . . . . . . . . . . . . . . . . . 36 80 11. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 36 81 12. Normative References . . . . . . . . . . . . . . . . . . . . 36 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 39 84 1. Introduction 86 The deployment of a Session Initiation Protocol [RFC3261] (SIP)-based 87 infrastructure in enterprise and service provider communication 88 networks is increasing at a rapid pace. Consequently, direct IP 89 peering between enterprise and service provider networks is quickly 90 replacing traditional methods of interconnection between enterprise 91 and service provider networks. Currently published standards provide 92 a strong foundation over which direct IP peering can be realized. 93 However, given the sheer number of these standards, it is often not 94 clear which behavioral subsets, extensions to baseline protocols and 95 operating principles ought to be implemented by service provider and 96 enterprise networks to ensure successful peering. 98 The SIP Connect technical recommendations [SIP-Connect-TR] aim to 99 solve this problem by providing a master reference that promotes 100 seamless peering between enterprise and service provider SIP 101 networks. However, despite the extensive set of implementation rules 102 and operating guidelines, interoperability issues between service 103 provider and enterprise networks persist. This is in large part 104 because service providers and equipment manufacturers aren't required 105 to enforce the guidelines of the technical specifications and have a 106 fair degree of freedom to deviate from them. Consequently, 107 enterprise administrators usually undertake a fairly rigorous regimen 108 of testing, analysis and troubleshooting to arrive at a configuration 109 block that ensures seamless service provider peering. However, this 110 workflow complements the SIP Connect technical recommendations, in 111 that both endeavours aim to promote/achieve interop between the 112 enterprise and service provider. 114 Another set of interoperability problems arise when enterprise 115 administrators are required to translate a set of technical 116 recommendations from service providers to configuration blocks across 117 one or more devices in the enterprise, which is usually an error 118 prone exercise. Additionally, such technical recommendations might 119 not be nuanced enough to intuitively allow the generation of specific 120 configuration blocks. 122 This draft introduces a mechanism using which an enterprise network 123 can solicit a detailed capability set from a SIP service provider; 124 the detailed capability set can subsequently be used by automaton or 125 an administrator to generate configuration blocks across one or more 126 devices within the enterprise to ensure successful service provider 127 peering. 129 2. Overview of Operations 131 This section details the configuration workflow proposed by this 132 draft. 134 2.1. Reference Architecture 136 Figure 1 illustrates a reference architecture that may be deployed to 137 support the mechanism described in this document. The enterprise 138 network consists of a SIP-PBX, media endpoints and a Session Border 139 Controller [RFC7092]. It may also include additional components such 140 as application servers for voicemail, recording, fax etc. At a high 141 level, the service provider consists of a SIP signaling entity (SP- 142 SSE), a media entity and a HTTPS [RFC7231] server. 144 +-----------------------------------------------------+ 145 | +---------------+ +-----------------------+ | 146 | | | | | | 147 | | +----------+ | | +-------+ | | 148 | | | Cap | | HTTPS | | | | | 149 | | | Server |<-|---------|-->| | | | 150 | | | | | | | | +-----+ | | 151 | | +----------+ | | | | | SIP | | | 152 | | | | | |<->| PBX | | | 153 | | | | | | +-----+ | | 154 | | +----------+ | | | SBC | | | 155 | | | | | SIP | | | | | 156 | | | SP - SSE |<-|---------|-->| | +-----+ | | 157 | | | | | | | |<->| M.E.| | | 158 | | +----------+ | | | | | | | | 159 | | | | | | +-----+ | | 160 | | +----------+ | (S)RTP | | | | | 161 | | | Media |<-|---------|-->+-------+ | | 162 | | +----------+ | | | | 163 | +---------------+ +-----------------------+ | 164 | | 165 +-----------------------------------------------------+ 167 Figure 1: Reference Architecture 169 This draft makes use of the following terminology: 171 * Enterprise Network: A communications network infrastructure 172 deployed by an enterprise which interconnects with the service 173 provider network over SIP. The enterprise network could include 174 devices such as application servers, endpoints, call agents and 175 edge devices, among others. 177 * Edge Device: A device that is the last hop in the enterprise 178 network and that is the transit point for traffic entering and 179 leaving the enterprise. An edge device is typically a back-to- 180 back user agent (B2BUA) [RFC7092] such as a Session Border 181 Controller (SBC). 183 * Service Provider Network: A communications network infrastructure 184 deployed by service providers. In the context of this draft, the 185 service provider network is accessible over SIP for the 186 establishment, modification and termination of calls and 187 accessible over HTTPS for the transfer of the capability set 188 document. The service provider network is also referred to as a 189 SIP Service Provider (SSP) or Internet Telephony Service Provider 190 (ITSP) network. 192 * Call Control: Call Control within a telephony networks refers to 193 software that is responsible for delivering its core 194 functionality. Call control not only provides the basic 195 functionality of setting up, sustaining and terminating calls, but 196 also provides the necessary control and logic required for 197 additional services within the telephony network. 199 * Capability Server: A server hosted in the service provider 200 network, such that this server is the target for capability set 201 document requests from the enterprise network. 203 * Capability Set: The term capability set (or capability set 204 document) refers collectively to a set of characteristics within 205 the service provider network, which when communicated to the 206 enterprise network, provides the enterprise network the 207 information required to interconnect with the service provider 208 network. The various parameters that constitute the capability 209 set relate to characteristics that are specific to signalling, 210 media, transport and security. Certain aspects of interconnecting 211 with service providers are out of scope of the capability set. 212 For example, the access technology used to interconnect with 213 service provider networks. 215 2.2. Configuration Workflow 217 A workflow that facilitates an enterprise network to solicit the 218 capability set of a SIP service provider ought to take into account 219 the following considerations: 221 * The configuration workflow must be based on a protocol or a set of 222 protocols commonly used between enterprise and service provider 223 telephony networks. 225 * The configuration workflow must be flexible enough to allow the 226 service provider network to dynamically offload different 227 capability sets to different enterprise networks based on the 228 identity of the enterprise network. 230 * Capability set documents obtained as a result of the configuration 231 workflow must be conducive to easy parsing by automaton. 232 Subsequently, automaton may be used for generation of appropriate 233 configuration blocks. 235 Taking the above considerations into account, this document proposes 236 a Hypertext Transfer Protocol (HTTP)-based workflow using which the 237 enterprise network can solicit and ultimately obtain the service 238 provider capability set. The enterprise network creates a well 239 formed HTTPS GET request to solicit the service provider capability 240 set. Subsequently, the HTTPS response from the SIP service provider 241 includes the capability set. The capability set is encoded in either 242 XML or JSON, thus ensuring that the response can be easily parsed by 243 automaton. 245 There are alternative mechanisms using which the SIP service provider 246 can offload its capability set. For example, the Session Initiation 247 Protocol (SIP) can be extended to define a new event package 248 [RFC6665], such that the enterprise network can establish a SIP 249 subscription with the service provider for its capability set; the 250 SIP service provider can subsequently use the SIP NOTIFY request to 251 communicate its capability set or any state deltas to its baseline 252 capability set. 254 This mechanism is likely to result in a barrier to adoption for SIP 255 service providers and enterprise networks as equipment manufacturers 256 would have to first add support for such a SIP extension. A HTTPS- 257 based approach would be relatively easier to adopt as most edge 258 devices deployed in enterprise networks today already support HTTPS; 259 from the perspective of service provider networks, all that is 260 required is for them to deploy HTTPS servers that function as 261 capability servers. Additionally, most SIP service providers require 262 enterprise networks to register with them (using a SIP REGISTER 263 message) before any other SIP methods that initiate subscriptions 264 (SIP SUBSCRIBE) or calls (SIP INVITE) are processed. As a result, a 265 SIP-based framework to obtain a capability set would require 266 operational changes on the part of service provider networks. 268 Yet another example of an alternative mechanism would be for service 269 providers and enterprise equipment manufacturers to agree on YANG 270 models [RFC6020] that enable configuration to be pushed over NETCONF 271 [RFC6241] to enterprise networks from a centralised source hosted in 272 service provider networks. The presence of proprietary software 273 logic for call and media handling in enterprise devices would 274 preclude the generation of a "one-size-fits-all" YANG model. 275 Additionally, service provider networks pushing configuration to 276 enterprises devices might lead to the loss of implementation autonomy 277 on the part of the enterprise network. 279 2.3. Transport 281 To solicit the capability set of a SIP service provider, the edge 282 element in an enterprise network generates a well-formed HTTPS GET 283 request. There are two reasons why it makes sense for the enterprise 284 edge element to generate the HTTPS request: 286 1. Edge elements are devices that normalise any mismatches between 287 the enterprise and service provider networks in the media and 288 signaling planes. As a result, when the capability set is 289 received from the SIP service provider network, the edge element 290 can generate appropriate configuration blocks (possibly across 291 multiple devices) to enable interconnection. 293 2. Given that edge elements are configured to "talk" to networks 294 external to the enterprise, the complexity in terms of NAT 295 traversal and firewall configuration would be minimal. 297 The HTTPS GET request is targeted at a capability server that is 298 managed by the SIP service provider such that this server processes, 299 and on successfully processing the request, includes the capability 300 set document in the response. The capability set document is 301 constructed according the guidelines of the YANG model described in 302 this draft. The capability set document included in a successful 303 response is formatted in either XML or JSON. The formatting depends 304 on the value of the "Accept" header field of the HTTP GET request. 305 More details about the formatting of the HTTP request and response 306 are provided in Section 4. 308 There could be situations wherein an enterprise telephony network 309 interconnects with its SIP service provider such that traffic between 310 the two networks traverses an intermediary SIP service provider 311 network. This could be a result of interconnect agreements between 312 the terminating and transit SIP service provider networks. In such 313 situations, the capability set provided to the enterprise network by 314 its SIP service provider must account for the characteristics of the 315 transit SIP service provider network from a signalling and media 316 perspective. For example, if the terminating SIP service provider 317 network supports the G.729 codec and the transit SIP service provider 318 network does not, G.729 must not be advertised in the capability set. 319 As another example, if the transit SIP service provider network 320 doesn't support a SIP extension, for instance, the SIP extension for 321 Reliable Provisional Responses as defined in RFC 3262, the 322 terminating SIP service provider network must not advertise support 323 for this extension in the capability set provided to the enterprise 324 network. How a terminating SIP service provider obtains the 325 characteristics of the intermediary SIP service provider network is 326 out of the scope of this document; however, one method could be for 327 the terminating SIP service provider to obtain the characteristics of 328 the intermediary SIP service provider by leveraging the YANG model 329 introduced in this document. 331 3. Conventions and Terminology 333 The The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 334 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 335 this document are to be interpreted as described in [BCP-14] 337 4. HTTP Transport 339 This section describes the use of HTTPS as a transport protocol for 340 the peering workflow. This workflow is based on HTTP version 1.1, 341 and as such is compatible with any future version of HTTP that is 342 backward compatible with HTTP 1.1. 344 4.1. HTTP Methods 346 The workflow defined in this document leverages the HTTPS GET method 347 and its corresponding response(s) to request for and subsequently 348 obtain the service provider capability set document. 350 4.2. Integrity and Confidentiality 352 Peering requests and responses are defined over HTTPS. However, due 353 to the sensitive nature of information transmitted between client and 354 server, it is required to secure HTTP using Transport Layer Security 355 [RFC5246]. The enterprise edge element and capability server MUST be 356 compliant with [RFC7235]. The enterprise edge element and capability 357 server MUST support the use of the HTTPS uri scheme as defined in 358 [RFC7230]. 360 4.3. Authenticated Client Identity 362 HTTP usually adopts asymmetric methods of authentication. For 363 example, clients typically use certificate based authentication to 364 verify the server they are talking to, whereas, servers typically use 365 methods such as HTTP digest authentication or OAuth2.0 to 366 authenticate clients. Though OAuth2.0 is not an authentication 367 protocol, it nonetheless allows for client authentication to be 368 carried out with the use of OAuth tokens. 370 Figure 2 elucidates the use of this grant type. 372 In the context of the SIP Auto Peer framework, OAuth2.0 MUST be used 373 to carry out client authentication. Enterprise edge elements that 374 obtain the capability set document from SIP service providers could 375 have differing capabilities in terms of adhering to a specific 376 OAuth2.0 authorisation grant flow. For example, an SBC that is 377 configured and managed through a CLI and that does not have the 378 ability to launch a web-browser wouldn't be able to obtain an 379 authorisation code and subsequently an access token. Alternatively, 380 an SBC that is configured and managed via a GUI could redirect an 381 administrator to an appropriate OAuth2.0 authorisation server to 382 obtain an authorisation grant and subsequently an access token. In 383 order to ensure that OAuth2.0-based client authentication can be 384 carried out irrespective of enterprise edge element capabilities, 385 this draft requires that the Resource Owner Password Credentials 386 grant type be supported. 388 Using the resource owner password credentials grant type requires the 389 existence of a trust relationship between the resource owner(in this 390 context, the administrator/enterprise network) and the client(in this 391 context, an edge element such as an SBC). In SIP trunking 392 deployments between enterprise and service provider networks, such a 393 trust relationship between the administrator/resource owner/ 394 enterprise network and the client(edge element) already exists, as 395 SIP trunk registration (and refreshing registrations) require 396 credentials - typically a username and password, that are configured 397 on the edge element by the administrator. 399 The use of the resource owner credential grant type in the context of 400 the SIP Auto Peer framework, provides two advantages: 402 1. It enables OAuth2.0-based client authentication even in 403 deployments in wherein the edge element is not capable of 404 launching a web-browser to set in motion the authorisation code 405 grant flow of OAuth2.0 407 2. For situations in which a refresh token is not provided by the 408 authorisation endpoint, human/administrator involvement is not 409 required to obtain fresh tokens once an existing token expires. 410 Figure 2 provides a high-level diagrammatic illustration of how 411 OAuth2.0-based client authentication is achieved using resource 412 owner credentials in the context of SIP Auto Peer. 414 +--------------+ 415 | Resource | 416 | Owner | 417 | (Enterprise) | 418 +--------------+ 419 v 420 | Resource Owner 421 (1) Password Credentials 422 | 423 v 424 +---------+ +---------------+ 425 | |>--(2)---- Resource Owner ------->| Service | 426 | Client | Password Credentials | Provider | 427 | | | Authorization | 428 | (SBC) |<--(3)---- Access Token ---------<| Server | 429 | | (w/ Optional Refresh Token) | | 430 +---------+ +---------------+ 431 ^ v 432 | | 433 | | +--------------+ 434 | -------(4)---- Access Token --------->| Capability | 435 -----------(5)---- Capability set -------<| Server | 436 +--------------+ 438 Figure 2: Client Authentication Mechanism 440 The flow illustrated in Figure 2 includes the following steps: 442 1. The enterprise SBC stores the enterprise credentials required to 443 authenticate with the authorization server located in the service 444 provider network. These credentials may be passed to the 445 enterprise from the service provider in an out-of-band fashion 446 such as an email or a self-management service provided by the 447 service provider to the enterprise. 449 2. The enterprise SBC contacts the service provider authorization 450 server to obtain an access token using the credentials acquired 451 in Step 1. 453 3. The service provider authorization server ratifies the 454 credentials and grants the access token to the enterprise SBC. 455 The server could also provide a refresh token to the SBC to 456 regenerate the access token in the future. 458 4. The enterprise SBC then contacts the capability server located in 459 the service provider network with an HTTPS GET request along with 460 the access token to retrieve the capability set document. 462 5. The capability server checks for a valid access token and returns 463 the capability set document to the enterprise SBC. 465 4.4. Encoding the Request 467 The edge element in the enterprise network generates a HTTPS GET 468 request such that the request-target is obtained using the procedure 469 outlined in section 6.6 The MIME types for the capability set 470 document defined in this draft are "application/peering-info+json" 471 and "application/peering-info+xml". Accordingly, the Accept header 472 field value MUST be restricted only to these MIME types. It is 473 possible that the edge element supports responses formatted in both 474 JSON and XML. In such situations, the edge element might generate a 475 HTTPS GET request such that the Accept header field includes both 476 MIME types along with the corresponding "qvalue" for each MIME type. 478 The generated HTTPS GET request MUST NOT use the "Expect" and "Range" 479 header fields. The requests MUST also not use any conditional 480 request. 482 4.5. Identifying the Request Target 484 HTTPS GET requests from enterprise edge elements MUST carry a valid 485 request-target. The enterprise edge element might obtain the URL of 486 the resource hosted on the capability server in one of two ways: 488 1. Manual Configuration 490 2. Discovery using the Webfinger Protocol 492 The complete HTTPS URLs to be used when authenticating the enterprise 493 edge element (optional) and obtaining the SIP service provider 494 capability set can be obtained from the SIP service provider 495 beforehand and entered into the edge element manually via some 496 interface - for example, a CLI or GUI. 498 However, if the resource URL is unknown to the administrator (and by 499 extension of that to the edge element), the WebFinger protocol 500 [RFC7033] and the 'sipTrunkingCapability' [sipTrunkCapability] link 501 relation type may be leveraged. 503 If an enterprise edge element attempts to discover the URL of the 504 endpoints hosted in the ssp1.example.com domain, it issues the 505 following request (line wraps are for display purposes only). 507 GET /.well-known/webfinger? 508 resource=http%3A%2F%2Fssp1.example.com 509 rel=sipTrunkingCapability 510 HTTP/1.1 511 Host: ssp1.example.com 513 HTTP/1.1 200 OK 514 Access-Control-Allow-Origin: * 515 Content-Type: application/jrd+json 516 { 517 "subject" : "http://ssp1.example.com", 518 "links" : 519 [ 520 { 521 "rel" : "sipTrunkingCapability", 522 "href" : 523 "https://capserver.ssp1.com/capserver/capdoc.json" 524 }, 525 ] 526 } 528 Once the target URI is obtained by an enterprise telephony network, 529 the URI may be dereferenced to obtain a unique capability set 530 document that is specific to that given enterprise telephony network. 531 The ITSP may use credentials to determine the identity of the 532 enterprise telephony network and provide the appropriate capability 533 set document. 535 4.6. Generating the response 537 Capability servers include the capability set documents in the body 538 of a successful response. Capability set documents MUST be formatted 539 in XML or JSON. For requests that are incorrectly formatted, the 540 capability server must generate a "400 Bad Request" response. If the 541 client (enterprise edge element) includes any other MIME types in 542 Accept header field other than "application/peering-info+json" or 543 "application/peering-info+xml", the capability set must reject the 544 request with a "406 Not Acceptable" response. 546 The capability server can respond to client requests with redirect 547 responses, specifically, the server can respond with the following 548 redirect responses: 550 1. 301 Moved Temporarily 552 2. 302 Found 553 3. 307 Temporary Redirect 555 The server SHOULD include the Location header field in such 556 responses. 558 5. State Deltas 560 Given that the service provider capability set is largely expected to 561 remain static, the work needed to implement an asynchronous push 562 mechanism to encode minor changes in the capability set document 563 (state deltas) is not commensurate with the benefits. Rather, 564 enterprise edge elements can poll capability servers at pre-defined 565 intervals to obtain the full capability set document. It is 566 recommended that capability servers are polled every 24 hours. 568 6. Encoding the Service Provider Capability Set 570 In the context of this draft, the capability set of a service 571 provider refers collectively to a set of characteristics which when 572 communicated to an enterprise network, provides it with sufficient 573 information to directly peer with the service provider network. The 574 capability set document is not designed to encode extremely granular 575 details of all features, services, and protocol extensions that are 576 supported by the service provider network. For example, it is 577 sufficient to encode that the service provider uses T.38 relay for 578 faxing, it is not required to know the value of the 579 "T38FaxFillBitRemoval" parameter. 581 The parameters within the capability set document represent a wide 582 array of characteristics, such that these characteristics 583 collectively disseminate sufficient information to enable direct IP 584 peering between enterprise and service provider networks. The 585 various parameters represented in the capability set are chosen based 586 on existing practises and common problem sets typically seen between 587 enterprise and service provider SIP networks. 589 7. Data Model for Capability Set 591 This section defines a YANG module for encoding the service provider 592 capability set. Section 9.1 provides the tree diagram, which is 593 followed by a description of the various nodes within the module 594 defined in this draft. 596 7.1. Tree Diagram 598 This section provides a tree diagram [RFC8340] for the "ietf- 599 capability-set" module. The interpretation of the symbols appearing 600 in the tree diagram is as follows: 602 * Brackets "[" and "]" enclose list keys. 604 * Abbreviations before data node names: "rw" means configuration 605 (read-write), and "ro" means state data (read-only). 607 * Symbols after data node names: "?" means an optional node, "!" 608 means a presence container, and "*" denotes a list and leaf-list. 610 * Parentheses enclose choice and case nodes, and case nodes are also 611 marked with a colon (":"). 613 * Ellipsis ("...") stands for contents of subtrees that are not 614 shown. 616 The data model for the peering capability document has the following 617 structure: 619 module: ietf-sip-auto-peering 620 +--rw peering-info 621 +--rw variant string 622 +--rw revision 623 | +--rw notBefore? string 624 | +--rw location? string 625 +--rw transport-info 626 | +--rw transport? enumeration 627 | +--rw registrar* host-port 628 | +--rw registrarRealm? string 629 | +--rw callControl* host-port 630 | +--rw dns* inet:ip-address 631 | +--rw outboundProxy? host-port 632 +--rw call-specs 633 | +--rw earlyMedia? boolean 634 | +--rw signalingForking? boolean 635 | +--rw supportedMethods? string 636 | +--rw callerId 637 | | +--rw e164Format? boolean 638 | | +--rw preferredMethod? string 639 | +--rw numRange 640 | +--rw numRangeType? string 641 | +--rw count? int32 642 | +--rw value* string 643 +--rw media 644 | +--rw mediaTypeAudio 645 | | +--rw mediaFormat* string 646 | +--rw fax 647 | | +--rw protocol* enumeration 648 | +--rw rtp 649 | | +--rw RTPTrigger? boolean 650 | | +--rw symmetricRTP? boolean 651 | +--rw rtcp 652 | +--rw symmetricRTCP? boolean 653 | +--rw RTCPfeedback? boolean 654 +--rw dtmf 655 | +--rw payloadNumber? int8 656 | +--rw iteration? boolean 657 +--rw security 658 | +--rw signaling 659 | | +--rw type? string 660 | | +--rw version? string 661 | +--rw mediaSecurity 662 | | +--rw keyManagement? string 663 | +--rw certLocation? string 664 | +--rw secureTelephonyIdentity 665 | +--rw STIRCompliance? boolean 666 | +--rw certDelegation? boolean 667 | +--rw ACMEDirectory? string 668 +--rw extensions? string 670 7.2. YANG Model 672 This section defines the YANG module for the peering capability set 673 document. It imports modules (ietf-yang-types and ietf-inet-types) 674 from [RFC6991]. 676 module ietf-sip-auto-peering { 677 namespace "urn:ietf:params:xml:ns:ietf-sip-auto-peering"; 678 prefix "peering"; 680 description 681 "Data model for transmitting peering parameters from SP to 682 Enterprise"; 684 revision 2019-05-06 { 685 description "Initial revision of peering-response doc."; 686 } 688 import ietf-inet-types { 689 prefix "inet"; 690 } 692 typedef ipv4-address-port { 693 type string { 694 pattern "(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" 695 + "\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" 696 + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" 697 + "{2}|655[1-2][0-9]|6553[1-5])$"; 699 } 700 description "The ipv4-address-port type represents an IPv4 701 address in dotted-quad notation followed by a port number."; 702 } 704 typedef ipv6-address-port { 705 type string { 706 pattern "((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}" 707 + "((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|" 708 + "(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}" 709 + "(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))" 710 + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" 711 + "{2}|655[1-2][0-9]|6553[1-5])$"; 712 pattern 713 "(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|" 714 + "((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)" 715 + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" 716 + "{2}|655[1-2][0-9]|6553[1-5])$"; 717 } 718 description 719 "The ipv6-address type represents an IPv6 address in full, 720 mixed, shortened, and shortened-mixed notation followed by 721 a port number."; 722 } 724 typedef ip-address-port { 725 type union { 726 type ipv4-address-port; 727 type ipv6-address-port; 728 } 729 description 730 "The ip-address-port type represents an IP address:port number 731 and is IP version neutral."; 732 } 734 typedef domain-name-port { 735 type string { 736 pattern 737 "((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.)*" 738 + "([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.?)" 739 + "|\." 740 + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" 741 + "{2}655[1-2][0-9]|6553[1-5])$"; 742 length "1..258"; 743 } 744 description 745 "The domain-name-port type represents a DNS domain name 746 followed by a port number. The name SHOULD be fully qualified 747 whenever possible."; 748 } 750 typedef host-port { 751 type union { 752 type ip-address-port; 753 type domain-name-port; 754 } 755 description 756 "The host type represents either an IP address or a DNS 757 domain name followed by a port number."; 758 } 760 container peering-info { 761 leaf variant { 762 type string; 763 mandatory true; 764 description "Variant of peering-response document"; 765 } 767 container revision { 768 leaf notBefore { 769 type string; 770 description "Time and date of activation of new 771 capability set"; 772 } 774 leaf location { 775 type string; 776 description "Location of the new version of 777 capability set document"; 778 } 779 } 781 container transport-info { 782 leaf transport { 783 type enumeration { 784 enum "TCP"; 785 enum "TLS"; 786 enum "UDP"; 787 enum "TCP;TLS"; 788 enum "TCP;TLS;UDP"; 789 enum "TCP;UDP"; 790 } 791 description "Transport Protocol(s) used in SIP 792 communication"; 793 } 794 leaf-list registrar { 795 type host-port; 796 max-elements 3; 797 description "List of service provider registrar servers"; 798 } 800 leaf registrarRealm { 801 type string; 802 description "Realm for REGISTER requests carrying 803 credentials"; 804 } 806 leaf-list callControl { 807 type host-port; 808 max-elements 3; 809 description "List of service provider call control 810 servers"; 811 } 813 leaf-list dns { 814 type inet:ip-address; 815 max-elements 2; 816 description "IP address of the DNS Server(s) hosted by the 817 service provider"; 818 } 820 leaf outboundProxy { 821 type host-port; 822 description "SIP Outbound Proxy"; 823 } 824 } 826 container call-specs { 827 leaf earlyMedia { 828 type boolean; 829 description "Flag indicating whether the service provider 830 is expected to deliver early media."; 831 } 833 leaf signalingForking { 834 type boolean; 835 description "Flag indicating whether the service provider 836 is capable of forking incoming calls "; 837 } 839 leaf supportedMethods { 840 type string; 841 description "Leaf/Leaf List indicating the different SIP 842 methods support by the service provider."; 843 } 845 container callerId { 846 leaf e164Format { 847 type boolean; 848 description "Flag indicating whether enterprise must 849 format caller information into E.164"; 850 } 852 leaf preferredMethod { 853 type string; 854 description "Field that instructs enterprise regarding 855 which SIP header it must populate to communicate caller 856 information."; 857 } 858 } 860 container numRange { 861 leaf numRangeType { 862 type string; 863 description "String indicating whether the DID number 864 range is passed by value or by reference"; 865 } 867 leaf count { 868 when "../numRangeType = 'range' or 869 ../numRangeType = 'block'"; 870 type int32; 871 description "Number of DID numbers present in the number 872 range."; 873 } 875 leaf-list value { 876 type string; 877 description "Value of the DID number range or URL being 878 passed as reference."; 879 } 881 } 882 } 884 container media { 885 container mediaTypeAudio { 886 leaf-list mediaFormat { 887 type string; 888 description "Leaf List indicating the audio media formats 889 supported."; 891 } 892 } 894 container fax { 895 leaf-list protocol { 896 type enumeration { 897 enum "pass-through"; 898 enum "t38"; 899 } 900 max-elements 2; 901 description "Leaf List indicating the different fax 902 protocols supported by the service provider."; 903 } 904 } 906 container rtp { 907 leaf RTPTrigger { 908 type boolean; 909 description "Flag indicating whether the service provider 910 expects to receive the first media packet."; 911 } 913 leaf symmetricRTP { 914 type boolean; 915 description "Flag indicating whether the service provider 916 expects symmetric RTP defined in [@RFC4961]"; 917 } 918 } 920 container rtcp { 921 leaf symmetricRTCP { 922 type boolean; 923 description "Flag indicating whether the service 924 provider expects symmetric RTP defined in [@RFC4961]."; 925 } 927 leaf RTCPfeedback { 928 type boolean; 929 description "Flag Indicating support for RTP profile 930 extension for RTCP-based feedback, as defined in 931 [@RFC4585]"; 932 } 933 } 934 } 936 container dtmf { 937 leaf payloadNumber { 938 type int8 { 939 range "96..127"; 940 } 941 description "Leaf that indicates the payload number(s) 942 supported by the service provider for DTMF relay via 943 Named-Telephony-Events"; 944 } 946 leaf iteration { 947 type boolean; 948 description "Flag identifying whether the service provider 949 supports NTE DTMF relay using the procedures of [@RFC2833] 950 or [@RFC4733] ."; 951 } 952 } 954 container security { 955 container signaling { 956 leaf type { 957 type string { 958 pattern "TLS"; 959 } 960 description "Type of signaling security supported."; 961 } 963 leaf version { 964 type string { 965 pattern "([1-9]\.[0-9])(;[1-9]\.[0-9])?|(NULL)"; 966 } 967 description "Indicates TLS version for SIP signaling"; 968 } 969 } 971 container mediaSecurity { 972 leaf keyManagement { 973 type string { 974 pattern "(SDES(;DTLS-SRTP,version=[1-9]\.[0-9](,[1-9]" 975 + "\.[0-9])?)?)|(DTLS-SRTP,version=[1-9]\.[0-9](,[1-9]" 976 + "\.[0-9])?)|(NULL)"; 977 } 978 description "Leaf that identifies the key management 979 methods supported by the service provider for SRTP."; 980 } 981 } 983 leaf certLocation { 984 type string; 985 description "Location of the service provider certificate 986 chain for SIP over TLS."; 988 } 990 container secureTelephonyIdentity { 991 leaf STIRCompliance { 992 type boolean; 993 description "Indicates whether the SIP service provider 994 is STIR compliant."; 995 } 997 leaf certDelegation { 998 type boolean; 999 description "Indicates whether a SIP service provider is 1000 willing to delegate authority to the enterprise network 1001 over its allocated number range(s)"; 1002 } 1004 leaf ACMEDirectory { 1005 when "../certDelegation = 1 1006 or ../certDelegation = 'true'"; 1007 type string; 1008 description "Directory object URL, when de-referenced, 1009 provides a collection of field name-value pairs to 1010 kickstart ACME."; 1011 } 1012 } 1013 } 1015 leaf extensions { 1016 type string; 1017 description "Lists the various SIP extensions supported by 1018 the service provider."; 1019 } 1020 } 1021 } 1023 7.3. Node Definitions 1025 This sub-sections provides the definition and encoding rules of the 1026 various nodes of the YANG module defined in section 9.2 1028 *capability-set*: This node serves as a container for all the other 1029 nodes in the YANG module; the capability-set node is akin to the root 1030 element of an json document. 1032 *variant*: This node identifies the version number of the capability 1033 set document. This draft defines the parameters for variant 1.0; 1034 future specifications might define a richer parameter set, in which 1035 case the variant must be changed to 2.0, 3.0 and so on. Future 1036 extensions to the capability set document MUST also ensure that the 1037 corresponding YANG module is defined. 1039 *revision*: The revision node is a container that encapsulates 1040 information regarding the availability of a new version of the 1041 capability set document for the enterprise. 1043 *notBefore*: The notBefore node indicates the date and time at which 1044 the new capabilities go live in the service provider network. 1046 *location*: This leaf node value provides the URL of the new revision 1047 of the capability set document 1049 *transport-info*: The transport-info node is a container that 1050 encapsulates transport characteristics of SIP sessions between 1051 enterprise and service provider networks. 1053 *transport*: A leaf node that enumerates the different Transport 1054 Layer protocols supported by the SIP service provider. Valid 1055 transport layer protocols include: UDP, TCP, TLS or a combination of 1056 them (with the exception of TLS and UDP). 1058 *registrar*: A leaf-list that specifies the transport address of one 1059 or more registrar servers in the service provider network. The 1060 transport address of the registrar can be provided using a 1061 combination of a valid IP address and port number, or a subdomain of 1062 the SIP service provider network, or the fully qualified domain name 1063 (FQDN) of the SIP service provider network. If the transport address 1064 of a registrar is specified using either a subdomain or a fully 1065 qualified domain name, the DNS element must be populated with one or 1066 more valid DNS server IP addresses. 1068 *callControl*: A leaf-list that specifies the transport address of 1069 the call server(s) in the service provider network. The enterprise 1070 network must use an applicable transport protocol in conjunction with 1071 the call control server(s) transport address when transmitting call 1072 setup requests. The transport address of a call server(s) within the 1073 service provider network can be specified using a combination of a 1074 valid IP address and port number, or a subdomain of the SIP service 1075 provider network, or a fully qualified domain name of the SIP service 1076 provider network. If the transport address of a call control 1077 server(s) is specified using either a subdomain or a fully qualified 1078 domain name, the DNS element must be populated with one or more valid 1079 DNS server IP addresses. The transport address specified in this 1080 element can also serve as the target for non-call requests such as 1081 SIP OPTIONS. 1083 *dns*: A leaf list that encodes the IP address of one or more DNS 1084 servers hosted by the SIP service provider. If the enterprise 1085 network is unaware of the IP address, port number, and transport 1086 protocol of servers within the service provider network (for example, 1087 the registrar and call control server), it must use DNS NAPTR and 1088 SRV. Alternatively, if the enterprise network has the fully 1089 qualified domain name of the SIP service provider network, it must 1090 use DNS to resolve the said FQDN to an IP address. The dns element 1091 encodes the IP address of one or more DNS servers hosted in the 1092 service provider network. If however, either the registrar or 1093 callControl elements or both are populated with a valid IP address 1094 and port pair, the dns element must be set to the quadruple octet of 1095 0.0.0.0 1097 *outboundProxy*: A leaf list that specifies the transport address of 1098 one or more outbound proxies. The transport address can be specified 1099 by using a combination of an IP address and a port number, a 1100 subdomain of the SIP service provider network, or a fully qualified 1101 domain name and port number of the SIP service provider network. If 1102 the outbound-proxy sub-element is populated with a valid transport 1103 address, it represents the default destination for all outbound SIP 1104 requests and therefore, the registrar and callControl elements must 1105 be populated with the quadruple octet of 0.0.0.0 1107 *call-specs*: A container that encapsulates information about call 1108 specifications, restrictions and additional handling criteria for SIP 1109 calls between the enterprise and service provider network. 1111 *earlyMedia*: A leaf that specifies whether the service provider 1112 network is expected to deliver in-band announcements/tones before 1113 call connect. The P-Early-Media header field can be used to indicate 1114 pre-connect delivery of tones and announcements on a per-call basis. 1115 However, given that signalling and media could traverse a large 1116 number of intermediaries with varying capabilities (in terms of 1117 handling of the P-Early-Media header field) within the enterprise, 1118 such devices can be appropriately configured for media cut through if 1119 it is known before-hand that early media is expected for some or all 1120 of the outbound calls. This element is a Boolean type, where a value 1121 of 1/true signifies that the service provider is capable of early 1122 media. A value of 0/false signifies that the service provider is not 1123 expected to generate early media. 1125 *signalingForking*: A leaf that specifies whether outbound call 1126 requests from the enterprise might be forked on the service provider 1127 network that MAY lead to multiple early dialogs. This information 1128 would be useful to the enterprise network in appropriately handling 1129 multiple early dialogs reliably and in enforcing local policy. This 1130 element is a Boolean type, where a value of 1/true signifies that the 1131 service provider network can potentially fork outbound call requests 1132 from the enterprise. A value of 0/false indicates that the service 1133 provider will not fork outbound call requests. 1135 *supportedMethods*: A leaf node that specifies the various SIP 1136 methods supported by the SIP service provider. The list of supported 1137 methods help to appropriately configuration various devices within 1138 the enterprise network. For example, if the service provider 1139 enumerates support for the OPTIONS method, the enterprise network 1140 could periodically send OPTIONS requests as a keep-alive mechanism. 1142 *callerId*: This is a container that encodes the preferences of SIP 1143 Service Providers in terms calling number presentation by the 1144 enterprise network. Certain ITSPs require that the calling number be 1145 formatted in E.164, whereas others place no such restrictions. 1146 Additionally, some ITSPs require that the calling number be included 1147 in a specific SIP header field, for example, the P-Asserted-ID header 1148 field or the P-Asserted-ID field, whereas others place no 1149 restrictions on the specific SIP header field used to convey the 1150 calling number. 1152 *e164Format*: A leaf node that indicates whether the service provider 1153 requires enterprise to normalize the caller number into the E.164 1154 format while communicating caller details. This node is of the 1155 boolean type. A value of 'true' or '1' mandates the enterprise 1156 format caller numbers into the E.164 format, while a 'false' or '0' 1157 leaves the formatting of the caller number up to the enterprise. 1159 *preferredMethod*: A leaf node that instructs the enterprise 1160 regarding which SIP header to populate the caller information into 1161 when communicating caller ID information. This node will contain the 1162 name of the SIP Header. 1164 *numRange*: Is a container that specifies the Direct Inward Dial 1165 (DID) number range allocated to the enterprise network by the SIP 1166 service provider. The DID number range allocated by the service 1167 provider to the enterprise network might be a contiguous or a non- 1168 contiguous block. The number range allocated to an enterprise can be 1169 communicated as a value or as a reference. For large enterprise 1170 networks, the size of the DID range might run into several hundred 1171 numbers. For situations in which the enterprise is allocated a large 1172 DID number range or a non-contiguous number range it is RECOMMENDED 1173 that the SIP service provider communicate this information by 1174 reference, that is, through a URL. The enterprise network is 1175 required to de-reference this URL in order to obtain the DID number 1176 range allocated by the SIP service provider. The numRange container 1177 can be used more than once. Refer to the example provided in 1178 Section 10.1. 1180 *numRangeType*: A leaf node that indicates whether the DID range is 1181 communicated by value or by reference. It can have a value of 1182 'range', 'block' or 'reference'. 1184 *count*: A leaf node that indicates the size of the DID number range. 1185 The number range may be contiguous or non-contiguous. This leaf node 1186 MUST NOT be included when using the 'reference' numRangeType value. 1188 *value*: A leaf-list that encapsulates the DID number range allocated 1189 to the enterprise. If the numRangeType value is set to 'range' or 1190 'block', this is the list of numbers allocated to the enterprise. If 1191 the numRangeType value is set to 'reference', this is the URL of the 1192 resource containing the DID number range. To ensure ease of parsing, 1193 it is RECOMMENDED that the resource contain a number range formatted 1194 as if it were being passed as a block or range. 1196 *media*: A container that is used to collectively encapsulate the 1197 characteristics of UDP-based audio streams. A future extension to 1198 this draft may extend the media container to describe other media 1199 types. The media container is also used to encapsulate basic 1200 information about Real-Time Transport Protocol (RTP) and Real-Time 1201 Transport Control Protocol (RTCP) from the perspective of the service 1202 provider network. As of the date of writing this draft, video media 1203 streams aren't exchanged between enterprise and service provider SIP 1204 networks. 1206 *mediaTypeAudio*: A container for the mediaFormat leaf-list. This 1207 container collectively encapsulates the various audio media formats 1208 supported by the SIP service provider. 1210 *mediaFormat*: A leaf-list encoding the various audio media formats 1211 supported by the SIP service provider. The relative ordering of 1212 different media format leaf nodes from left to right indicates 1213 preference from the perspective of the service provider. Each 1214 mediaFormat node begins with the encoding name of the media format, 1215 which is the same encoding name as used in the "RTP/AVP" and "RTP/ 1216 SAVP" profiles. The encoding name is followed by required and 1217 optional parameters for the given media format as specified when the 1218 media format is registered [RFC4855]. Given that the parameters of 1219 media formats can vary from one communication session to another, for 1220 example, across two separate communication sessions, the 1221 packetization time (ptime) used for the PCMU media format might vary 1222 from 10 to 30 ms, the parameters included in the format element must 1223 be the ones that are expected to be invariant from the perspective of 1224 the service provider. Providing information about supported media 1225 formats and their respective parameters, allows enterprise networks 1226 to configure the media plane characteristics of various devices such 1227 as endpoints and middleboxes. The encoding name, one or more 1228 required parameters, one or more optional parameters are all 1229 separated by a semicolon. The formatting of a given media format 1230 parameter, must follow the formatting rules as specified for that 1231 media format. 1233 *fax*: A container that encapsulates the fax protocol(s) supported by 1234 the SIP service provider. The fax container encloses a leaf-list 1235 (named protocol) that enumerates whether the service provider 1236 supports t38 relay, protocol-based fax passthrough or both. The 1237 relative ordering of leaf nodes within the leaf lists indicates 1238 preference. 1240 *rtp*: A container that encapsulates generic characteristics of RTP 1241 sessions between the enterprise and service provider network. This 1242 node is a container for the "RTPTrigger" and "SymmetricRTP" leaf 1243 nodes. 1245 *RTPTrigger*: A leaf node indicating whether the SIP service provider 1246 network always expects the enterprise network to send the first RTP 1247 packet for an established communication session. This information is 1248 useful in scenarios such as "hairpinned" calls, in which the caller 1249 and callee are on the service provider network and because of sub- 1250 optimal media routing, an enterprise device such as an SBC is 1251 retained in the media path. Based on the encoding of this node, it 1252 is possible to configure enterprise devices such as SBCs to start 1253 streaming media (possibly filled with silence payloads) toward the 1254 address:port tuples provided by caller and callee. This node is a 1255 Boolean type. A value of 1/true indicates that the service provider 1256 expects the enterprise network to send the first RTP packet, whereas 1257 a value of 0/false indicates that the service provider network does 1258 not require the enterprise network to send the first media packet. 1259 While the practise of preserving the enterprise network in a 1260 hairpinned call flow is fairly common, it is recommended that SIP 1261 service providers avoid this practise. In the context of a 1262 hairpinned call, the enterprise device retained in the call flow can 1263 easily eavesdrop on the conversation between the offnet parties. 1265 *symmetricRTP*: A leaf node indicating whether the SIP service 1266 provider expects the enterprise network to use symmetric RTP as 1267 defined in [RFC4961]. Uncovering this expectation is useful in 1268 scenarios where "latching" [RFC7362] is implemented in the service 1269 provider network. This node is a Boolean type, a value of 1/true 1270 indicates that the service provider expects the enterprise network to 1271 use symmetric RTP, whereas a value of 0/false indicates that the 1272 enterprise network can use asymmetric RTP. 1274 *rtcp*: A container that encapsulates generic characteristics of RTCP 1275 sessions between the enterprise and service provider network. This 1276 node is a container for the "RTCPFeedback" and "SymmetricRTCP" leaf 1277 nodes. 1279 *RTCPFeedback*: A leaf node that indicates whether the SIP service 1280 provider supports the RTP profile extension for RTCP-based feedback 1281 [RFC4585]. Media sessions spanning enterprise and service provider 1282 networks, are rarely made to flow directly between the caller and 1283 callee, rather, it is often the case that media traffic flows through 1284 network intermediaries such as SBCs. As a result, RTCP traffic from 1285 the service provider network is intercepted by these intermediaries, 1286 which in turn can either pass across RTCP traffic unmodified or 1287 modify RTCP traffic before it is forwarded to the endpoint in the 1288 enterprise network. Modification of RTCP traffic would be required, 1289 for example, if the intermediary has performed media payload 1290 transformation operations such as transcoding or transrating. In a 1291 similar vein, for the RTCP-based feedback mechanism as defined in 1292 [RFC4585] to be truly effective, intermediaries must ensure that 1293 feedback messages are passed reliably and with the correct formatting 1294 to enterprise endpoints. This might require additional configuration 1295 and considerations that need to be dealt with at the time of 1296 provisioning the intermediary device. This node is a Boolean type, a 1297 value of 1/true indicates that the service provider supports the RTP 1298 profile extension for RTP-based feedback and a value of 0/false 1299 indicates that the service provider does not support the RTP profile 1300 extension for RTP-based feedback. 1302 *symmetricRTCP*: A leaf node indicating whether the SIP service 1303 provider expects the enterprise network to use symmetric RTCP as 1304 defined in [RFC4961]. This node is a Boolean type, a value of 1 1305 indicates that the service provider expects symmetric RTCP reports, 1306 whereas a value of 0 indicates that the enterprise can use asymmetric 1307 RTCP. 1309 *dtmf*: A container that describes the various aspects of DTMF relay 1310 via RTP Named Telephony Events. The dtmf container allows SIP 1311 service providers to specify two facets of DTMF relay via Named 1312 Telephony Events: 1314 1. The payload type number using the payloadNumber leaf node. 1316 2. Support for [RFC2833] or [RFC4733] using the iteration leaf node. 1318 In the context of named telephony events, senders and receivers may 1319 negotiate asymmetric payload type numbers. For example, the sender 1320 might advertise payload type number 97 and the receiver might 1321 advertise payload type number 101. In such instances, it is either 1322 required for middleboxes to interwork payload type numbers or allow 1323 the endpoints to send and receive asymmetric payload numbers. The 1324 behaviour of middleboxes in this context is largely dependent on 1325 endpoint capabilities or on service provider constraints. Therefore, 1326 the payloadNumber leaf node can be used to determine middlebox 1327 configuration before-hand. 1329 [RFC4733] iterates over [RFC2833] by introducing certain changes in 1330 the way NTE events are transmitted. SIP service providers can 1331 indicate support for [RFC4733] by setting the iteration flag to 1 or 1332 indicating support for [RFC2833] by setting the iteration flag to 0. 1334 *security*: A container that encapsulates characteristics about 1335 encrypting signalling streams between the enterprise and SIP service 1336 provider networks. 1338 *signaling*: A container that encapsulates the type of security 1339 protocol for the SIP communication between the enterprise SBC and the 1340 service provider. 1342 *type*: A leaf node that specifies the protocol used for protecting 1343 SIP signalling messages between the enterprise and service provider 1344 network. The value of the type leaf node is only defined for 1345 Transport Layer Security (TLS). Accordingly, if TLS is allowed for 1346 SIP sessions between the enterprise and service provider network, the 1347 type leaf node is set to the string "tls". 1349 *version*: A leaf node that specifies the version(s) of TLS supported 1350 in decimal format. If multiple versions of TLS are supported, they 1351 should be separated by semi-colons. If the service provider does not 1352 support TLS for protecting SIP sessions, the signalling element is 1353 set to the string "NULL". 1355 *mediaSecurity*: A container that describes the various 1356 characteristics of securing media streams between enterprise and 1357 service provider networks. 1359 *keyManagement*: A leaf node that specifies the key management method 1360 used by the service provider. Possible values of this node include: 1361 "SDES" and "DTLS-SRTP". A value of "SDES" signifies that the SIP 1362 service provider uses the methods defined in [RFC4568] for the 1363 purpose of key management. A value of "DTLS-SRTP" signifies that the 1364 SIP service provider uses the methods defined in [RFC5764]for the 1365 purpose of key management. If the value of this leaf node is set to 1366 "DTLS-SRTP", the various versions of DTLS supported by the SIP 1367 service provider MUST be encoded as per the formatting rules of 1368 Section 9.2. If the service provider does not support media 1369 security, the keyManagement node MUST be set to "NULL". 1371 *certLocation:*: If the enterprise network is required to exchange 1372 SIP traffic over TLS with the SIP service provider, and if the SIP 1373 service provider is capable of accepting TLS connections from the 1374 enterprise network, it may be required for the SIP service provider 1375 certificates to be pre-installed on the enterprise edge element. In 1376 such situations, the certLocation leaf node is populated with a URL, 1377 which when dereferenced, provides a single PEM encoded file that 1378 contains all certificates in the chain of trust. This is an optional 1379 leaf node. 1381 *secureTelephonyIdentity*: A container that is used to collectively 1382 encapsulate Secure Telephony Identity Revisited (STIR) 1383 characteristics. 1385 *STIRCompliance*: A leaf node that indicates whether the SIP service 1386 provider is STIR compliant. This node is a Boolean type, a value 1/ 1387 true indicates that the SIP service provider is STIR compliant. A 1388 value of 0/false indicates that the SIP service provider is not STIR 1389 compliant. A SIP service provider being STIR compliant has 1390 implications for inbound and outbound calls, from the perspective of 1391 the enterprise network. 1393 For inbound calls received from a STIR compliant SIP service 1394 provider, the enterprise edge element can be configured to 1395 appropriately handle calls based on their "attestation value". For 1396 example, calls with an attestation value of "A" (Full Attestation) 1397 are allowed to go through, while calls with an attestation value of 1398 "C" (Gateway Attestation) may be flagged for administrative analysis. 1400 For outgoing calls placed to a STIR compliant SIP service provider, 1401 the enterprise edge element must ensure that the calling number 1402 populated in SIP From header field (or in trusted environments, the 1403 P-Asserted-Identity header field), is as per what the service 1404 provider expects. This is so that the Authentication Service running 1405 in the SIP service provider network can determine if it is 1406 authoritative for the calling number presented by the enterprise 1407 network. 1409 *certDelegation*: A leaf node value that indicates whether a SIP 1410 service provider that allocates one or more number ranges to an 1411 enterprise network, is willing to delegate authority to the 1412 enterprise network over that number range(s). This node is a Boolean 1413 type, a value of 1/true indicates that the SIP service provider is 1414 willing to delegate authority to the enterprise network over one or 1415 more number ranges. A value of 0/false indicates that the SIP 1416 service provider is not willing to delegate authority to the 1417 enterprise network over one or more number ranges. This leaf node 1418 MUST only be included in the capability set if the value of the 1419 STIRCompliance leaf node is set to 1/true. In order to obtain 1420 delegate certificates, the enterprise network must be made aware of 1421 the scope of delegation - the number or number range(s) over which 1422 the SIP service provider is willing to delegate authority. This 1423 information is included in the numRange container. 1425 *ACMEDirectory*: For delegate certificates that are obtained by the 1426 enterprise network using Automatic Certificate Management Environment 1427 (ACME), this leaf node value provides the URL of the directory object 1428 [ACME]. The directory object URL, when de-referenced, provides a 1429 collection of field name-value pairs. Certain field name-value pairs 1430 provided in the response are used to bootstrap the process the 1431 obtaining delegate certificates. This leaf node MUST only be 1432 included in the capability set if the value of the certDelegation 1433 leaf node is set to 1/true. 1435 *extensions*: A leaf node that is a semicolon separated list of all 1436 possible SIP option tags supported by the service provider network. 1437 These extensions must be referenced using name registered under IANA. 1438 If the service provider network does not support any extensions to 1439 baseline SIP, the extensions node must be set to "NULL". 1441 7.4. Extending the Capability Set 1443 There are situations in which equipment manufactures or service 1444 providers would benefit from extending the YANG module defined in 1445 this draft. For example, service providers could extend the YANG 1446 module to include information that further simplifies direct IP 1447 peering. Such information could include: trunk group identifiers, 1448 direct-inward-dial (DID) number ranges allocated to the enterprise, 1449 customer/enterprise account numbers, service provider support 1450 numbers, among others. Extension of the module can be achieved by 1451 importing the module defined in this draft. An example is provided 1452 below: Consider a new YANG module "vendorA" specified for VendorA's 1453 enterprise SBC. The "vendorA-config" YANG module is configured as 1454 follows: 1456 module vendorA-config { 1457 namespace "urn:ietf:params:xml:ns:yang:vendorA-config"; 1458 prefix "vendorA"; 1460 description 1461 "Data model for configuring VendorA Enterprise SBC"; 1463 revision 2020-05-06 { 1464 description "Initial revision of VendorA Enterprise SBC 1465 configuration data model"; 1466 } 1468 import ietf-peering { 1469 prefix "peering"; 1470 } 1472 augment "/peering:peering-info" { 1473 container vendorAConfig { 1474 leaf vendorAConfigParam1 { 1475 type int32; 1476 description "vendorA configuration parameter 1 1477 (SBC Device ID)"; 1478 } 1480 leaf vendorAConfigParam2 { 1481 type string; 1482 description "vendorA configuration parameter 2 1483 (SBC Device name)"; 1484 } 1485 description "Container for vendorA SBC configuration"; 1486 } 1487 } 1488 } 1490 In the example above, a custom module named "vendorA-config" uses the 1491 "augment" statement as defined in Section 4.2.8 of [RFC7950] to 1492 extend the module defined in this draft. 1494 8. Processing the Capability Set Response 1496 This section provides a non-normative description of the procedures 1497 that could be carried out by the enterprise network after obtaining 1498 the SIP service provider capability set. On obtaining the capability 1499 set, the enterprise edge element can parse the various fields within 1500 the capability set and generate configuration blocks. For example, 1501 the configuration required to successfully register a SIP trunk with 1502 the SIP registrar hosted in the service provider network, the 1503 configuration required to ensure that fax calls are handled 1504 appropriately, the configuration required to advertise only audio 1505 codecs supported by the SIP service provider, among many other 1506 configuration blocks. A configuration block generated for an almost 1507 identical SIP service provider capability set document is likely 1508 going to differ drastically from one vendor to the next. 1510 Enterprise edge elements are usually capable of normalising 1511 mismatches in the signalling and media planes between the enterprise 1512 and service provider SIP networks. As a result, most, if not all of 1513 the configuration blocks required to enable successful SIP service 1514 provider peering might need to be added on the edge element. In 1515 situations wherein configuration blocks need to be distributed across 1516 multiple devices, some mechanism, that is out of scope of this 1517 document might be used to communicate the specific fields of capacity 1518 set and their corresponding value. Alternatively, a human 1519 administrator could go through the capability set document and 1520 configure the edge element (and if required, other devices in the 1521 enterprise network appropriately. 1523 9. Examples 1525 This section provides examples of how capability set documents that 1526 leverage the YANG module defined in this document can be encoded over 1527 JSON as well as the exchange of messages between the enterprise edge 1528 element and the service provider to acquire the capability set 1529 document. 1531 9.1. JSON Capability Set Document 1532 { 1533 "peering-info": { 1534 "variant": "1.0", 1535 "revision": { 1536 "notBefore": "2021-10-16T00:00:00.00000Z", 1537 "location": 1538 "https://capserver.ssp1.com/capserver/capdoc.json", 1539 }, 1540 "transport-info": { 1541 "transport": "TCP;TLS;UDP", 1542 "registrar": ["registrar1.voip.example.com:5060", 1543 "registrar2.voip.example.com:5060"], 1544 "registerRealm": "voip.example.com", 1545 "callControl": ["callServer1.voip.example.com:5060", 1546 "192.168.12.25:5065"], 1547 "dns": ["8.8.8.8", "208.67.222.222"], 1548 "outboundProxy": "0.0.0.0" 1549 }, 1550 "call-specs": { 1551 "earlyMedia": "true", 1552 "signalingForking": "false", 1553 "supportedMethods": "INVITE;OPTIONS;BYE;CANCEL;ACK; 1554 PRACK;SUBSCRIBE;NOTIFY;REGISTER", 1555 "callerId": { 1556 "e164Format": "true", 1557 "preferredMethod": "P-Asserted-Identity" 1558 }, 1559 "numRange": { 1560 "type": "range", 1561 "count": "20", 1562 "value": "19725455000" 1563 }, 1564 "numRange": { 1565 "type": "block", 1566 "count": "2", 1567 "value": ["19725455000", "19725455001"] 1568 } 1569 }, 1570 "media": { 1571 "mediaTypeAudio": { 1572 "mediaFormat": ["PCMU;rate=8000;ptime=20", 1573 "G729;rate=8000;annexb=yes", 1574 "G722;rate=8000;bitrate=56k,64k"] 1575 }, 1576 "fax": { 1577 "protocol": ["t38", "pass-through"] 1578 }, 1579 "rtp": { 1580 "RTPTrigger": "true", 1581 "symmetricRTP": "true" 1582 }, 1583 "rtcp": { 1584 "symmetricRTCP": "true", 1585 "RTCPFeedback": "true" 1586 } 1587 }, 1588 "dtmf": { 1589 "payloadNumber": "101", 1590 "iteration": "0" 1591 }, 1592 "security": { 1593 "signaling": { 1594 "type": "TLS", 1595 "version": "1.0;1.2" 1596 }, 1597 "mediaSecurity": { 1598 "keyManagement": "SDES;DTLS-SRTP,version=1.2" 1599 }, 1600 "certLocation": 1601 "https://sipserviceprovider.com/certificateList.pem", 1602 "secureTelephonyIdentity": { 1603 "STIRCompliance": "true", 1604 "certDelegation": "true", 1605 "ACMEDirectory": 1606 "https://sipserviceprovider.com/acme.html" 1607 } 1608 }, 1609 "extensions": "timer;rel100;gin;path" 1610 } 1611 } 1613 9.2. Example Exchange 1615 This section is an informational example depicting the configuration 1616 flow that ultimately results in the enterprise edge element obtaining 1617 the capability set document from the SIP service provider. Assuming 1618 the enterprise edge element has been pre-configured with the request 1619 target for the capability set document or has dynamically found the 1620 request target, the edge element generates a HTTPS GET request. This 1621 request can be challenged by the service provider to authenticate the 1622 enterprise. 1624 GET /capdoc?trunkid=trunkent1456 HTTP/1.1 1625 Host: capserver.ssp1.com 1626 Accept:application/peering-info+json 1628 The capability set document is obtained in the body of the response 1629 and is encoded in JSON. 1631 HTTP/1.1 200 OK 1632 Content-Type: application/peering-info+json 1633 Content-Length: nnn 1635 { 1636 "peering-info": ... 1637 } 1639 10. Security Considerations 1641 [TBD] 1643 11. Acknowledgments 1645 [TBD] 1647 12. Normative References 1649 [ACME] "Automatic Certificate Management Environment", 1650 . 1653 [BCP-14] "Key words for use in RFCs to Indicate Requirement 1654 Levels", . 1656 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1657 Requirement Levels", BCP 14, RFC 2119, 1658 DOI 10.17487/RFC2119, March 1997, 1659 . 1661 [RFC2833] Schulzrinne, H. and S. Petrack, "RTP Payload for DTMF 1662 Digits, Telephony Tones and Telephony Signals", RFC 2833, 1663 DOI 10.17487/RFC2833, May 2000, 1664 . 1666 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 1667 A., Peterson, J., Sparks, R., Handley, M., and E. 1668 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 1669 DOI 10.17487/RFC3261, June 2002, 1670 . 1672 [RFC4568] Andreasen, F., Baugher, M., and D. Wing, "Session 1673 Description Protocol (SDP) Security Descriptions for Media 1674 Streams", RFC 4568, DOI 10.17487/RFC4568, July 2006, 1675 . 1677 [RFC4585] Ott, J., Wenger, S., Sato, N., Burmeister, C., and J. Rey, 1678 "Extended RTP Profile for Real-time Transport Control 1679 Protocol (RTCP)-Based Feedback (RTP/AVPF)", RFC 4585, 1680 DOI 10.17487/RFC4585, July 2006, 1681 . 1683 [RFC4733] Schulzrinne, H. and T. Taylor, "RTP Payload for DTMF 1684 Digits, Telephony Tones, and Telephony Signals", RFC 4733, 1685 DOI 10.17487/RFC4733, December 2006, 1686 . 1688 [RFC4855] Casner, S., "Media Type Registration of RTP Payload 1689 Formats", RFC 4855, DOI 10.17487/RFC4855, February 2007, 1690 . 1692 [RFC4961] Wing, D., "Symmetric RTP / RTP Control Protocol (RTCP)", 1693 BCP 131, RFC 4961, DOI 10.17487/RFC4961, July 2007, 1694 . 1696 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1697 (TLS) Protocol Version 1.2", RFC 5246, 1698 DOI 10.17487/RFC5246, August 2008, 1699 . 1701 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 1702 Security (DTLS) Extension to Establish Keys for the Secure 1703 Real-time Transport Protocol (SRTP)", RFC 5764, 1704 DOI 10.17487/RFC5764, May 2010, 1705 . 1707 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1708 the Network Configuration Protocol (NETCONF)", RFC 6020, 1709 DOI 10.17487/RFC6020, October 2010, 1710 . 1712 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1713 and A. Bierman, Ed., "Network Configuration Protocol 1714 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1715 . 1717 [RFC6665] Roach, A.B., "SIP-Specific Event Notification", RFC 6665, 1718 DOI 10.17487/RFC6665, July 2012, 1719 . 1721 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1722 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1723 . 1725 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1726 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1727 . 1729 [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr, 1730 "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September 1731 2013, . 1733 [RFC7092] Kaplan, H. and V. Pascual, "A Taxonomy of Session 1734 Initiation Protocol (SIP) Back-to-Back User Agents", 1735 RFC 7092, DOI 10.17487/RFC7092, December 2013, 1736 . 1738 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1739 Protocol (HTTP/1.1): Message Syntax and Routing", 1740 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1741 . 1743 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1744 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1745 DOI 10.17487/RFC7231, June 2014, 1746 . 1748 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1749 Protocol (HTTP/1.1): Authentication", RFC 7235, 1750 DOI 10.17487/RFC7235, June 2014, 1751 . 1753 [RFC7362] Ivov, E., Kaplan, H., and D. Wing, "Latching: Hosted NAT 1754 Traversal (HNT) for Media in Real-Time Communication", 1755 RFC 7362, DOI 10.17487/RFC7362, September 2014, 1756 . 1758 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1759 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1760 . 1762 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1763 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1764 . 1766 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1767 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1768 . 1770 [SIP-Connect-TR] 1771 "SIP Connect Technical Recommendation", 1772 . 1775 [sipTrunkCapability] 1776 "The 'sipTrunkingCapability' Link Relation Type", 1777 . 1780 Authors' Addresses 1782 Kaustubh Inamdar 1783 Unaffiliated 1784 Email: kaustubh.ietf@gmail.com 1786 Sreekanth Narayanan 1787 Cisco Systems 1788 Email: sreenara@cisco.com 1790 Cullen Jennings 1791 Cisco Systems 1792 Email: fluffy@iii.ca