idnits 2.17.1 draft-ietf-asap-sip-auto-peer-04.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 copyright year in the IETF Trust and authors Copyright Line does not match the current year == 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 (24 October 2021) is 916 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 975, but not defined == Missing Reference: '1-9' is mentioned on line 974, but not defined == Missing Reference: '0-4' is mentioned on line 708, but not defined == Missing Reference: '0-5' is mentioned on line 708, but not defined == Missing Reference: '1-5' is mentioned on line 740, but not defined == Missing Reference: '1-4' is mentioned on line 739, but not defined == Missing Reference: '1-2' is mentioned on line 740, but not defined -- Looks like a reference, but probably isn't: '01' on line 708 == Missing Reference: 'TBD' is mentioned on line 1644, but not defined == Unused Reference: 'RFC2119' is defined on line 1655, but no explicit reference was found in the text == Unused Reference: 'RFC5764' is defined on line 1700, but no explicit reference was found in the text == Unused Reference: 'RFC6749' is defined on line 1720, but no explicit reference was found in the text == Unused Reference: 'RFC8446' is defined on line 1765, 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 ** Obsolete normative reference: RFC 7230 (Obsoleted by RFC 9110, RFC 9112) ** Obsolete normative reference: RFC 7231 (Obsoleted by RFC 9110) ** Obsolete normative reference: RFC 7235 (Obsoleted by RFC 9110) ** Downref: Normative reference to an Informational RFC: RFC 7362 -- Possible downref: Non-RFC (?) normative reference: ref. 'SIP-Connect-TR' Summary: 8 errors (**), 0 flaws (~~), 15 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: 27 April 2022 C. Jennings 6 Cisco Systems 7 24 October 2021 9 Automatic Peering for SIP Trunks 10 draft-ietf-asap-sip-auto-peer-04 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 27 April 2022. 39 Copyright Notice 41 Copyright (c) 2021 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 Simplified BSD License text 50 as described in Section 4.e of the Trust Legal Provisions and are 51 provided without warranty as described in the Simplified 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] may be leveraged. 502 If an enterprise edge element attempts to discover the URL of the 503 endpoints hosted in the ssp1.example.com domain, it issues the 504 following request (line wraps are for display purposes only). 506 GET /.well-known/webfinger? 507 resource=http%3A%2F%2Fssp1.example.com 508 rel=capabilitySet 509 HTTP/1.1 510 Host: ssp1.example.com 512 HTTP/1.1 200 OK 513 Access-Control-Allow-Origin: * 514 Content-Type: application/jrd+json 515 { 516 "subject" : "http://ssp1.example.com", 517 "links" : 518 [ 519 { 520 "rel" : "capabilitySet", 521 "href" : 522 "https://capserver.ssp1.com/capserver/capdoc.json" 523 }, 524 ] 525 } 527 Once the target URI is obtained by an enterprise telephony network, 528 the URI may be dereferenced to obtain a unique capability set 529 document that is specific to that given enterprise telephony network. 530 The ITSP may use credentials to determine the identity of the 531 enterprise telephony network and provide the appropriate capability 532 set document. 534 4.6. Generating the response 536 Capability servers include the capability set documents in the body 537 of a successful response. Capability set documents MUST be formatted 538 in XML or JSON. For requests that are incorrectly formatted, the 539 capability server must generate a "400 Bad Request" response. If the 540 client (enterprise edge element) includes any other MIME types in 541 Accept header field other than "application/peering-info+json" or 542 "application/peering-info+xml", the capability set must reject the 543 request with a "406 Not Acceptable" response. 545 The capability server can respond to client requests with redirect 546 responses, specifically, the server can respond with the following 547 redirect responses: 549 1. 301 Moved Temporarily 551 2. 302 Found 552 3. 307 Temporary Redirect 554 The server SHOULD include the Location header field in such 555 responses. 557 5. State Deltas 559 Given that the service provider capability set is largely expected to 560 remain static, the work needed to implement an asynchronous push 561 mechanism to encode minor changes in the capability set document 562 (state deltas) is not commensurate with the benefits. Rather, 563 enterprise edge elements can poll capability servers at pre-defined 564 intervals to obtain the full capability set document. It is 565 recommended that capability servers are polled every 24 hours. 567 6. Encoding the Service Provider Capability Set 569 In the context of this draft, the capability set of a service 570 provider refers collectively to a set of characteristics which when 571 communicated to an enterprise network, provides it with sufficient 572 information to directly peer with the service provider network. The 573 capability set document is not designed to encode extremely granular 574 details of all features, services, and protocol extensions that are 575 supported by the service provider network. For example, it is 576 sufficient to encode that the service provider uses T.38 relay for 577 faxing, it is not required to know the value of the 578 "T38FaxFillBitRemoval" parameter. 580 The parameters within the capability set document represent a wide 581 array of characteristics, such that these characteristics 582 collectively disseminate sufficient information to enable direct IP 583 peering between enterprise and service provider networks. The 584 various parameters represented in the capability set are chosen based 585 on existing practises and common problem sets typically seen between 586 enterprise and service provider SIP networks. 588 7. Data Model for Capability Set 590 This section defines a YANG module for encoding the service provider 591 capability set. Section 9.1 provides the tree diagram, which is 592 followed by a description of the various nodes within the module 593 defined in this draft. 595 7.1. Tree Diagram 597 This section provides a tree diagram [RFC8340] for the "ietf- 598 capability-set" module. The interpretation of the symbols appearing 599 in the tree diagram is as follows: 601 * Brackets "[" and "]" enclose list keys. 603 * Abbreviations before data node names: "rw" means configuration 604 (read-write), and "ro" means state data (read-only). 606 * Symbols after data node names: "?" means an optional node, "!" 607 means a presence container, and "*" denotes a list and leaf-list. 609 * Parentheses enclose choice and case nodes, and case nodes are also 610 marked with a colon (":"). 612 * Ellipsis ("...") stands for contents of subtrees that are not 613 shown. 615 The data model for the peering capability document has the following 616 structure: 618 module: ietf-sip-auto-peering 619 +--rw peering-info 620 +--rw variant string 621 +--rw revision 622 | +--rw notBefore? string 623 | +--rw location? string 624 +--rw transport-info 625 | +--rw transport? enumeration 626 | +--rw registrar* host-port 627 | +--rw registrarRealm? string 628 | +--rw callControl* host-port 629 | +--rw dns* inet:ip-address 630 | +--rw outboundProxy? host-port 631 +--rw call-specs 632 | +--rw earlyMedia? boolean 633 | +--rw signalingForking? boolean 634 | +--rw supportedMethods? string 635 | +--rw callerId 636 | | +--rw e164Format? boolean 637 | | +--rw preferredMethod? string 638 | +--rw numRange 639 | +--rw numRangeType? string 640 | +--rw count? int32 641 | +--rw value* string 642 +--rw media 643 | +--rw mediaTypeAudio 644 | | +--rw mediaFormat* string 645 | +--rw fax 646 | | +--rw protocol* enumeration 647 | +--rw rtp 648 | | +--rw RTPTrigger? boolean 649 | | +--rw symmetricRTP? boolean 650 | +--rw rtcp 651 | +--rw symmetricRTCP? boolean 652 | +--rw RTCPfeedback? boolean 653 +--rw dtmf 654 | +--rw payloadNumber? int8 655 | +--rw iteration? boolean 656 +--rw security 657 | +--rw signaling 658 | | +--rw type? string 659 | | +--rw version? string 660 | +--rw mediaSecurity 661 | | +--rw keyManagement? string 662 | +--rw certLocation? string 663 | +--rw secureTelephonyIdentity 664 | +--rw STIRCompliance? boolean 665 | +--rw certDelegation? boolean 666 | +--rw ACMEDirectory? string 667 +--rw extensions? string 669 7.2. YANG Model 671 This section defines the YANG module for the peering capability set 672 document. It imports modules (ietf-yang-types and ietf-inet-types) 673 from [RFC6991]. 675 module ietf-sip-auto-peering { 676 namespace "urn:ietf:params:xml:ns:ietf-sip-auto-peering"; 677 prefix "peering"; 679 description 680 "Data model for transmitting peering parameters from SP to 681 Enterprise"; 683 revision 2019-05-06 { 684 description "Initial revision of peering-response doc."; 685 } 687 import ietf-inet-types { 688 prefix "inet"; 689 } 691 typedef ipv4-address-port { 692 type string { 693 pattern "(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" 694 + "\.){3}([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])" 695 + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" 696 + "{2}|655[1-2][0-9]|6553[1-5])$"; 698 } 699 description "The ipv4-address-port type represents an IPv4 700 address in dotted-quad notation followed by a port number."; 701 } 703 typedef ipv6-address-port { 704 type string { 705 pattern "((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}" 706 + "((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|" 707 + "(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}" 708 + "(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))" 709 + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" 710 + "{2}|655[1-2][0-9]|6553[1-5])$"; 711 pattern 712 "(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|" 713 + "((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)" 714 + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" 715 + "{2}|655[1-2][0-9]|6553[1-5])$"; 716 } 717 description 718 "The ipv6-address type represents an IPv6 address in full, 719 mixed, shortened, and shortened-mixed notation followed by 720 a port number."; 721 } 723 typedef ip-address-port { 724 type union { 725 type ipv4-address-port; 726 type ipv6-address-port; 727 } 728 description 729 "The ip-address-port type represents an IP address:port number 730 and is IP version neutral."; 731 } 733 typedef domain-name-port { 734 type string { 735 pattern 736 "((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.)*" 737 + "([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.?)" 738 + "|\." 739 + ":^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]" 740 + "{2}655[1-2][0-9]|6553[1-5])$"; 741 length "1..258"; 742 } 743 description 744 "The domain-name-port type represents a DNS domain name 745 followed by a port number. The name SHOULD be fully qualified 746 whenever possible."; 747 } 749 typedef host-port { 750 type union { 751 type ip-address-port; 752 type domain-name-port; 753 } 754 description 755 "The host type represents either an IP address or a DNS 756 domain name followed by a port number."; 757 } 759 container peering-info { 760 leaf variant { 761 type string; 762 mandatory true; 763 description "Variant of peering-response document"; 764 } 766 container revision { 767 leaf notBefore { 768 type string; 769 description "Time and date of activation of new 770 capability set"; 771 } 773 leaf location { 774 type string; 775 description "Location of the new version of 776 capability set document"; 777 } 778 } 780 container transport-info { 781 leaf transport { 782 type enumeration { 783 enum "TCP"; 784 enum "TLS"; 785 enum "UDP"; 786 enum "TCP;TLS"; 787 enum "TCP;TLS;UDP"; 788 enum "TCP;UDP"; 789 } 790 description "Transport Protocol(s) used in SIP 791 communication"; 792 } 793 leaf-list registrar { 794 type host-port; 795 max-elements 3; 796 description "List of service provider registrar servers"; 797 } 799 leaf registrarRealm { 800 type string; 801 description "Realm for REGISTER requests carrying 802 credentials"; 803 } 805 leaf-list callControl { 806 type host-port; 807 max-elements 3; 808 description "List of service provider call control 809 servers"; 810 } 812 leaf-list dns { 813 type inet:ip-address; 814 max-elements 2; 815 description "IP address of the DNS Server(s) hosted by the 816 service provider"; 817 } 819 leaf outboundProxy { 820 type host-port; 821 description "SIP Outbound Proxy"; 822 } 823 } 825 container call-specs { 826 leaf earlyMedia { 827 type boolean; 828 description "Flag indicating whether the service provider 829 is expected to deliver early media."; 830 } 832 leaf signalingForking { 833 type boolean; 834 description "Flag indicating whether the service provider 835 is capable of forking incoming calls "; 836 } 838 leaf supportedMethods { 839 type string; 840 description "Leaf/Leaf List indicating the different SIP 841 methods support by the service provider."; 842 } 844 container callerId { 845 leaf e164Format { 846 type boolean; 847 description "Flag indicating whether enterprise must 848 format caller information into E.164"; 849 } 851 leaf preferredMethod { 852 type string; 853 description "Field that instructs enterprise regarding 854 which SIP header it must populate to communicate caller 855 information."; 856 } 857 } 859 container numRange { 860 leaf numRangeType { 861 type string; 862 description "String indicating whether the DID number 863 range is passed by value or by reference"; 864 } 866 leaf count { 867 when "../numRangeType = 'range' or 868 ../numRangeType = 'block'"; 869 type int32; 870 description "Number of DID numbers present in the number 871 range."; 872 } 874 leaf-list value { 875 type string; 876 description "Value of the DID number range or URL being 877 passed as reference."; 878 } 880 } 881 } 883 container media { 884 container mediaTypeAudio { 885 leaf-list mediaFormat { 886 type string; 887 description "Leaf List indicating the audio media formats 888 supported."; 890 } 891 } 893 container fax { 894 leaf-list protocol { 895 type enumeration { 896 enum "pass-through"; 897 enum "t38"; 898 } 899 max-elements 2; 900 description "Leaf List indicating the different fax 901 protocols supported by the service provider."; 902 } 903 } 905 container rtp { 906 leaf RTPTrigger { 907 type boolean; 908 description "Flag indicating whether the service provider 909 expects to receive the first media packet."; 910 } 912 leaf symmetricRTP { 913 type boolean; 914 description "Flag indicating whether the service provider 915 expects symmetric RTP defined in [@RFC4961]"; 916 } 917 } 919 container rtcp { 920 leaf symmetricRTCP { 921 type boolean; 922 description "Flag indicating whether the service 923 provider expects symmetric RTP defined in [@RFC4961]."; 924 } 926 leaf RTCPfeedback { 927 type boolean; 928 description "Flag Indicating support for RTP profile 929 extension for RTCP-based feedback, as defined in 930 [@RFC4585]"; 931 } 932 } 933 } 935 container dtmf { 936 leaf payloadNumber { 937 type int8 { 938 range "96..127"; 939 } 940 description "Leaf that indicates the payload number(s) 941 supported by the service provider for DTMF relay via 942 Named-Telephony-Events"; 943 } 945 leaf iteration { 946 type boolean; 947 description "Flag identifying whether the service provider 948 supports NTE DTMF relay using the procedures of [@RFC2833] 949 or [@RFC4733] ."; 950 } 951 } 953 container security { 954 container signaling { 955 leaf type { 956 type string { 957 pattern "TLS"; 958 } 959 description "Type of signaling security supported."; 960 } 962 leaf version { 963 type string { 964 pattern "([1-9]\.[0-9])(;[1-9]\.[0-9])?|(NULL)"; 965 } 966 description "Indicates TLS version for SIP signaling"; 967 } 968 } 970 container mediaSecurity { 971 leaf keyManagement { 972 type string { 973 pattern "(SDES(;DTLS-SRTP,version=[1-9]\.[0-9](,[1-9]" 974 + "\.[0-9])?)?)|(DTLS-SRTP,version=[1-9]\.[0-9](,[1-9]" 975 + "\.[0-9])?)|(NULL)"; 976 } 977 description "Leaf that identifies the key management 978 methods supported by the service provider for SRTP."; 979 } 980 } 982 leaf certLocation { 983 type string; 984 description "Location of the service provider certificate 985 chain for SIP over TLS."; 987 } 989 container secureTelephonyIdentity { 990 leaf STIRCompliance { 991 type boolean; 992 description "Indicates whether the SIP service provider 993 is STIR compliant."; 994 } 996 leaf certDelegation { 997 type boolean; 998 description "Indicates whether a SIP service provider is 999 willing to delegate authority to the enterprise network 1000 over its allocated number range(s)"; 1001 } 1003 leaf ACMEDirectory { 1004 when "../certDelegation = 1 1005 or ../certDelegation = 'true'"; 1006 type string; 1007 description "Directory object URL, when de-referenced, 1008 provides a collection of field name-value pairs to 1009 kickstart ACME."; 1010 } 1011 } 1012 } 1014 leaf extensions { 1015 type string; 1016 description "Lists the various SIP extensions supported by 1017 the service provider."; 1018 } 1019 } 1020 } 1022 7.3. Node Definitions 1024 This sub-sections provides the definition and encoding rules of the 1025 various nodes of the YANG module defined in section 9.2 1027 *capability-set*: This node serves as a container for all the other 1028 nodes in the YANG module; the capability-set node is akin to the root 1029 element of an json document. 1031 *variant*: This node identifies the version number of the capability 1032 set document. This draft defines the parameters for variant 1.0; 1033 future specifications might define a richer parameter set, in which 1034 case the variant must be changed to 2.0, 3.0 and so on. Future 1035 extensions to the capability set document MUST also ensure that the 1036 corresponding YANG module is defined. 1038 *revision*: The revision node is a container that encapsulates 1039 information regarding the availability of a new version of the 1040 capability set document for the enterprise. 1042 *notBefore*: The notBefore node indicates the date and time at which 1043 the new capabilities go live in the service provider network. 1045 *location*: This leaf node value provides the URL of the new revision 1046 of the capability set document 1048 *transport-info*: The transport-info node is a container that 1049 encapsulates transport characteristics of SIP sessions between 1050 enterprise and service provider networks. 1052 *transport*: A leaf node that enumerates the different Transport 1053 Layer protocols supported by the SIP service provider. Valid 1054 transport layer protocols include: UDP, TCP, TLS or a combination of 1055 them (with the exception of TLS and UDP). 1057 *registrar*: A leaf-list that specifies the transport address of one 1058 or more registrar servers in the service provider network. The 1059 transport address of the registrar can be provided using a 1060 combination of a valid IP address and port number, or a subdomain of 1061 the SIP service provider network, or the fully qualified domain name 1062 (FQDN) of the SIP service provider network. If the transport address 1063 of a registrar is specified using either a subdomain or a fully 1064 qualified domain name, the DNS element must be populated with one or 1065 more valid DNS server IP addresses. 1067 *callControl*: A leaf-list that specifies the transport address of 1068 the call server(s) in the service provider network. The enterprise 1069 network must use an applicable transport protocol in conjunction with 1070 the call control server(s) transport address when transmitting call 1071 setup requests. The transport address of a call server(s) within the 1072 service provider network can be specified using a combination of a 1073 valid IP address and port number, or a subdomain of the SIP service 1074 provider network, or a fully qualified domain name of the SIP service 1075 provider network. If the transport address of a call control 1076 server(s) is specified using either a subdomain or a fully qualified 1077 domain name, the DNS element must be populated with one or more valid 1078 DNS server IP addresses. The transport address specified in this 1079 element can also serve as the target for non-call requests such as 1080 SIP OPTIONS. 1082 *dns*: A leaf list that encodes the IP address of one or more DNS 1083 servers hosted by the SIP service provider. If the enterprise 1084 network is unaware of the IP address, port number, and transport 1085 protocol of servers within the service provider network (for example, 1086 the registrar and call control server), it must use DNS NAPTR and 1087 SRV. Alternatively, if the enterprise network has the fully 1088 qualified domain name of the SIP service provider network, it must 1089 use DNS to resolve the said FQDN to an IP address. The dns element 1090 encodes the IP address of one or more DNS servers hosted in the 1091 service provider network. If however, either the registrar or 1092 callControl elements or both are populated with a valid IP address 1093 and port pair, the dns element must be set to the quadruple octet of 1094 0.0.0.0 1096 *outboundProxy*: A leaf list that specifies the transport address of 1097 one or more outbound proxies. The transport address can be specified 1098 by using a combination of an IP address and a port number, a 1099 subdomain of the SIP service provider network, or a fully qualified 1100 domain name and port number of the SIP service provider network. If 1101 the outbound-proxy sub-element is populated with a valid transport 1102 address, it represents the default destination for all outbound SIP 1103 requests and therefore, the registrar and callControl elements must 1104 be populated with the quadruple octet of 0.0.0.0 1106 *call-specs*: A container that encapsulates information about call 1107 specifications, restrictions and additional handling criteria for SIP 1108 calls between the enterprise and service provider network. 1110 *earlyMedia*: A leaf that specifies whether the service provider 1111 network is expected to deliver in-band announcements/tones before 1112 call connect. The P-Early-Media header field can be used to indicate 1113 pre-connect delivery of tones and announcements on a per-call basis. 1114 However, given that signalling and media could traverse a large 1115 number of intermediaries with varying capabilities (in terms of 1116 handling of the P-Early-Media header field) within the enterprise, 1117 such devices can be appropriately configured for media cut through if 1118 it is known before-hand that early media is expected for some or all 1119 of the outbound calls. This element is a Boolean type, where a value 1120 of 1/true signifies that the service provider is capable of early 1121 media. A value of 0/false signifies that the service provider is not 1122 expected to generate early media. 1124 *signalingForking*: A leaf that specifies whether outbound call 1125 requests from the enterprise might be forked on the service provider 1126 network that MAY lead to multiple early dialogs. This information 1127 would be useful to the enterprise network in appropriately handling 1128 multiple early dialogs reliably and in enforcing local policy. This 1129 element is a Boolean type, where a value of 1/true signifies that the 1130 service provider network can potentially fork outbound call requests 1131 from the enterprise. A value of 0/false indicates that the service 1132 provider will not fork outbound call requests. 1134 *supportedMethods*: A leaf node that specifies the various SIP 1135 methods supported by the SIP service provider. The list of supported 1136 methods help to appropriately configuration various devices within 1137 the enterprise network. For example, if the service provider 1138 enumerates support for the OPTIONS method, the enterprise network 1139 could periodically send OPTIONS requests as a keep-alive mechanism. 1141 *callerId*: This is a container that encodes the preferences of SIP 1142 Service Providers in terms calling number presentation by the 1143 enterprise network. Certain ITSPs require that the calling number be 1144 formatted in E.164, whereas others place no such restrictions. 1145 Additionally, some ITSPs require that the calling number be included 1146 in a specific SIP header field, for example, the P-Asserted-ID header 1147 field or the P-Asserted-ID field, whereas others place no 1148 restrictions on the specific SIP header field used to convey the 1149 calling number. 1151 *e164Format*: A leaf node that indicates whether the service provider 1152 requires enterprise to normalize the caller number into the E.164 1153 format while communicating caller details. This node is of the 1154 boolean type. A value of 'true' or '1' mandates the enterprise 1155 format caller numbers into the E.164 format, while a 'false' or '0' 1156 leaves the formatting of the caller number up to the enterprise. 1158 *preferredMethod*: A leaf node that instructs the enterprise 1159 regarding which SIP header to populate the caller information into 1160 when communicating caller ID information. This node will contain the 1161 name of the SIP Header. 1163 *numRange*: Is a container that specifies the Direct Inward Dial 1164 (DID) number range allocated to the enterprise network by the SIP 1165 service provider. The DID number range allocated by the service 1166 provider to the enterprise network might be a contiguous or a non- 1167 contiguous block. The number range allocated to an enterprise can be 1168 communicated as a value or as a reference. For large enterprise 1169 networks, the size of the DID range might run into several hundred 1170 numbers. For situations in which the enterprise is allocated a large 1171 DID number range or a non-contiguous number range it is RECOMMENDED 1172 that the SIP service provider communicate this information by 1173 reference, that is, through a URL. The enterprise network is 1174 required to de-reference this URL in order to obtain the DID number 1175 range allocated by the SIP service provider. The numRange container 1176 can be used more than once. Refer to the example provided in 1177 Section 10.1. 1179 *numRangeType*: A leaf node that indicates whether the DID range is 1180 communicated by value or by reference. It can have a value of 1181 'range', 'block' or 'reference'. 1183 *count*: A leaf node that indicates the size of the DID number range. 1184 The number range may be contiguous or non-contiguous. This leaf node 1185 MUST NOT be included when using the 'reference' numRangeType value. 1187 *value*: A leaf-list that encapsulates the DID number range allocated 1188 to the enterprise. If the numRangeType value is set to 'range' or 1189 'block', this is the list of numbers allocated to the enterprise. If 1190 the numRangeType value is set to 'reference', this is the URL of the 1191 resource containing the DID number range. To ensure ease of parsing, 1192 it is RECOMMENDED that the resource contain a number range formatted 1193 as if it were being passed as a block or range. 1195 *media*: A container that is used to collectively encapsulate the 1196 characteristics of UDP-based audio streams. A future extension to 1197 this draft may extend the media container to describe other media 1198 types. The media container is also used to encapsulate basic 1199 information about Real-Time Transport Protocol (RTP) and Real-Time 1200 Transport Control Protocol (RTCP) from the perspective of the service 1201 provider network. As of the date of writing this draft, video media 1202 streams aren't exchanged between enterprise and service provider SIP 1203 networks. 1205 *mediaTypeAudio*: A container for the mediaFormat leaf-list. This 1206 container collectively encapsulates the various audio media formats 1207 supported by the SIP service provider. 1209 *mediaFormat*: A leaf-list encoding the various audio media formats 1210 supported by the SIP service provider. The relative ordering of 1211 different media format leaf nodes from left to right indicates 1212 preference from the perspective of the service provider. Each 1213 mediaFormat node begins with the encoding name of the media format, 1214 which is the same encoding name as used in the "RTP/AVP" and "RTP/ 1215 SAVP" profiles. The encoding name is followed by required and 1216 optional parameters for the given media format as specified when the 1217 media format is registered [RFC4855]. Given that the parameters of 1218 media formats can vary from one communication session to another, for 1219 example, across two separate communication sessions, the 1220 packetization time (ptime) used for the PCMU media format might vary 1221 from 10 to 30 ms, the parameters included in the format element must 1222 be the ones that are expected to be invariant from the perspective of 1223 the service provider. Providing information about supported media 1224 formats and their respective parameters, allows enterprise networks 1225 to configure the media plane characteristics of various devices such 1226 as endpoints and middleboxes. The encoding name, one or more 1227 required parameters, one or more optional parameters are all 1228 separated by a semicolon. The formatting of a given media format 1229 parameter, must follow the formatting rules as specified for that 1230 media format. 1232 *fax*: A container that encapsulates the fax protocol(s) supported by 1233 the SIP service provider. The fax container encloses a leaf-list 1234 (named protocol) that enumerates whether the service provider 1235 supports t38 relay, protocol-based fax passthrough or both. The 1236 relative ordering of leaf nodes within the leaf lists indicates 1237 preference. 1239 *rtp*: A container that encapsulates generic characteristics of RTP 1240 sessions between the enterprise and service provider network. This 1241 node is a container for the "RTPTrigger" and "SymmetricRTP" leaf 1242 nodes. 1244 *RTPTrigger*: A leaf node indicating whether the SIP service provider 1245 network always expects the enterprise network to send the first RTP 1246 packet for an established communication session. This information is 1247 useful in scenarios such as "hairpinned" calls, in which the caller 1248 and callee are on the service provider network and because of sub- 1249 optimal media routing, an enterprise device such as an SBC is 1250 retained in the media path. Based on the encoding of this node, it 1251 is possible to configure enterprise devices such as SBCs to start 1252 streaming media (possibly filled with silence payloads) toward the 1253 address:port tuples provided by caller and callee. This node is a 1254 Boolean type. A value of 1/true indicates that the service provider 1255 expects the enterprise network to send the first RTP packet, whereas 1256 a value of 0/false indicates that the service provider network does 1257 not require the enterprise network to send the first media packet. 1258 While the practise of preserving the enterprise network in a 1259 hairpinned call flow is fairly common, it is recommended that SIP 1260 service providers avoid this practise. In the context of a 1261 hairpinned call, the enterprise device retained in the call flow can 1262 easily eavesdrop on the conversation between the offnet parties. 1264 *symmetricRTP*: A leaf node indicating whether the SIP service 1265 provider expects the enterprise network to use symmetric RTP as 1266 defined in [RFC4961]. Uncovering this expectation is useful in 1267 scenarios where "latching" [RFC7362] is implemented in the service 1268 provider network. This node is a Boolean type, a value of 1/true 1269 indicates that the service provider expects the enterprise network to 1270 use symmetric RTP, whereas a value of 0/false indicates that the 1271 enterprise network can use asymmetric RTP. 1273 *rtcp*: A container that encapsulates generic characteristics of RTCP 1274 sessions between the enterprise and service provider network. This 1275 node is a container for the "RTCPFeedback" and "SymmetricRTCP" leaf 1276 nodes. 1278 *RTCPFeedback*: A leaf node that indicates whether the SIP service 1279 provider supports the RTP profile extension for RTCP-based feedback 1280 [RFC4585]. Media sessions spanning enterprise and service provider 1281 networks, are rarely made to flow directly between the caller and 1282 callee, rather, it is often the case that media traffic flows through 1283 network intermediaries such as SBCs. As a result, RTCP traffic from 1284 the service provider network is intercepted by these intermediaries, 1285 which in turn can either pass across RTCP traffic unmodified or 1286 modify RTCP traffic before it is forwarded to the endpoint in the 1287 enterprise network. Modification of RTCP traffic would be required, 1288 for example, if the intermediary has performed media payload 1289 transformation operations such as transcoding or transrating. In a 1290 similar vein, for the RTCP-based feedback mechanism as defined in 1291 [RFC4585] to be truly effective, intermediaries must ensure that 1292 feedback messages are passed reliably and with the correct formatting 1293 to enterprise endpoints. This might require additional configuration 1294 and considerations that need to be dealt with at the time of 1295 provisioning the intermediary device. This node is a Boolean type, a 1296 value of 1/true indicates that the service provider supports the RTP 1297 profile extension for RTP-based feedback and a value of 0/false 1298 indicates that the service provider does not support the RTP profile 1299 extension for RTP-based feedback. 1301 *symmetricRTCP*: A leaf node indicating whether the SIP service 1302 provider expects the enterprise network to use symmetric RTCP as 1303 defined in [RFC4961]. This node is a Boolean type, a value of 1 1304 indicates that the service provider expects symmetric RTCP reports, 1305 whereas a value of 0 indicates that the enterprise can use asymmetric 1306 RTCP. 1308 *dtmf*: A container that describes the various aspects of DTMF relay 1309 via RTP Named Telephony Events. The dtmf container allows SIP 1310 service providers to specify two facets of DTMF relay via Named 1311 Telephony Events: 1313 1. The payload type number using the payloadNumber leaf node. 1315 2. Support for [RFC2833] or [RFC4733] using the iteration leaf node. 1317 In the context of named telephony events, senders and receivers may 1318 negotiate asymmetric payload type numbers. For example, the sender 1319 might advertise payload type number 97 and the receiver might 1320 advertise payload type number 101. In such instances, it is either 1321 required for middleboxes to interwork payload type numbers or allow 1322 the endpoints to send and receive asymmetric payload numbers. The 1323 behaviour of middleboxes in this context is largely dependent on 1324 endpoint capabilities or on service provider constraints. Therefore, 1325 the payloadNumber leaf node can be used to determine middlebox 1326 configuration before-hand. 1328 [RFC4733] iterates over [RFC2833] by introducing certain changes in 1329 the way NTE events are transmitted. SIP service providers can 1330 indicate support for [RFC4733] by setting the iteration flag to 1 or 1331 indicating support for [RFC2833] by setting the iteration flag to 0. 1333 *security*: A container that encapsulates characteristics about 1334 encrypting signalling streams between the enterprise and SIP service 1335 provider networks. 1337 *signaling*: A container that encapsulates the type of security 1338 protocol for the SIP communication between the enterprise SBC and the 1339 service provider. 1341 *type*: A leaf node that specifies the protocol used for protecting 1342 SIP signalling messages between the enterprise and service provider 1343 network. The value of the type leaf node is only defined for 1344 Transport Layer Security (TLS). Accordingly, if TLS is allowed for 1345 SIP sessions between the enterprise and service provider network, the 1346 type leaf node is set to the string "tls". 1348 *version*: A leaf node that specifies the version(s) of TLS supported 1349 in decimal format. If multiple versions of TLS are supported, they 1350 should be separated by semi-colons. If the service provider does not 1351 support TLS for protecting SIP sessions, the signalling element is 1352 set to the string "NULL". 1354 *mediaSecurity*: A container that describes the various 1355 characteristics of securing media streams between enterprise and 1356 service provider networks. 1358 *keyManagement*: A leaf node that specifies the key management method 1359 used by the service provider. Possible values of this node include: 1360 "SDES" and "DTLS-SRTP". A value of "SDES" signifies that the SIP 1361 service provider uses the methods defined in [RFC4568] for the 1362 purpose of key management. A value of "DTLS-SRTP" signifies that the 1363 SIP service provider uses the methods defined in [RFC5764]for the 1364 purpose of key management. If the value of this leaf node is set to 1365 "DTLS-SRTP", the various versions of DTLS supported by the SIP 1366 service provider MUST be encoded as per the formatting rules of 1367 Section 9.2. If the service provider does not support media 1368 security, the keyManagement node MUST be set to "NULL". 1370 *certLocation:*: If the enterprise network is required to exchange 1371 SIP traffic over TLS with the SIP service provider, and if the SIP 1372 service provider is capable of accepting TLS connections from the 1373 enterprise network, it may be required for the SIP service provider 1374 certificates to be pre-installed on the enterprise edge element. In 1375 such situations, the certLocation leaf node is populated with a URL, 1376 which when dereferenced, provides a single PEM encoded file that 1377 contains all certificates in the chain of trust. This is an optional 1378 leaf node. 1380 *secureTelephonyIdentity*: A container that is used to collectively 1381 encapsulate Secure Telephony Identity Revisited (STIR) 1382 characteristics. 1384 *STIRCompliance*: A leaf node that indicates whether the SIP service 1385 provider is STIR compliant. This node is a Boolean type, a value 1/ 1386 true indicates that the SIP service provider is STIR compliant. A 1387 value of 0/false indicates that the SIP service provider is not STIR 1388 compliant. A SIP service provider being STIR compliant has 1389 implications for inbound and outbound calls, from the perspective of 1390 the enterprise network. 1392 For inbound calls received from a STIR compliant SIP service 1393 provider, the enterprise edge element can be configured to 1394 appropriately handle calls based on their "attestation value". For 1395 example, calls with an attestation value of "A" (Full Attestation) 1396 are allowed to go through, while calls with an attestation value of 1397 "C" (Gateway Attestation) may be flagged for administrative analysis. 1399 For outgoing calls placed to a STIR compliant SIP service provider, 1400 the enterprise edge element must ensure that the calling number 1401 populated in SIP From header field (or in trusted environments, the 1402 P-Asserted-Identity header field), is as per what the service 1403 provider expects. This is so that the Authentication Service running 1404 in the SIP service provider network can determine if it is 1405 authoritative for the calling number presented by the enterprise 1406 network. 1408 *certDelegation*: A leaf node value that indicates whether a SIP 1409 service provider that allocates one or more number ranges to an 1410 enterprise network, is willing to delegate authority to the 1411 enterprise network over that number range(s). This node is a Boolean 1412 type, a value of 1/true indicates that the SIP service provider is 1413 willing to delegate authority to the enterprise network over one or 1414 more number ranges. A value of 0/false indicates that the SIP 1415 service provider is not willing to delegate authority to the 1416 enterprise network over one or more number ranges. This leaf node 1417 MUST only be included in the capability set if the value of the 1418 STIRCompliance leaf node is set to 1/true. In order to obtain 1419 delegate certificates, the enterprise network must be made aware of 1420 the scope of delegation - the number or number range(s) over which 1421 the SIP service provider is willing to delegate authority. This 1422 information is included in the numRange container. 1424 *ACMEDirectory*: For delegate certificates that are obtained by the 1425 enterprise network using Automatic Certificate Management Environment 1426 (ACME), this leaf node value provides the URL of the directory object 1427 [ACME]. The directory object URL, when de-referenced, provides a 1428 collection of field name-value pairs. Certain field name-value pairs 1429 provided in the response are used to bootstrap the process the 1430 obtaining delegate certificates. This leaf node MUST only be 1431 included in the capability set if the value of the certDelegation 1432 leaf node is set to 1/true. 1434 *extensions*: A leaf node that is a semicolon separated list of all 1435 possible SIP option tags supported by the service provider network. 1436 These extensions must be referenced using name registered under IANA. 1437 If the service provider network does not support any extensions to 1438 baseline SIP, the extensions node must be set to "NULL". 1440 7.4. Extending the Capability Set 1442 There are situations in which equipment manufactures or service 1443 providers would benefit from extending the YANG module defined in 1444 this draft. For example, service providers could extend the YANG 1445 module to include information that further simplifies direct IP 1446 peering. Such information could include: trunk group identifiers, 1447 direct-inward-dial (DID) number ranges allocated to the enterprise, 1448 customer/enterprise account numbers, service provider support 1449 numbers, among others. Extension of the module can be achieved by 1450 importing the module defined in this draft. An example is provided 1451 below: Consider a new YANG module "vendorA" specified for VendorA's 1452 enterprise SBC. The "vendorA-config" YANG module is configured as 1453 follows: 1455 module vendorA-config { 1456 namespace "urn:ietf:params:xml:ns:yang:vendorA-config"; 1457 prefix "vendorA"; 1459 description 1460 "Data model for configuring VendorA Enterprise SBC"; 1462 revision 2020-05-06 { 1463 description "Initial revision of VendorA Enterprise SBC 1464 configuration data model"; 1465 } 1467 import ietf-peering { 1468 prefix "peering"; 1469 } 1471 augment "/peering:peering-info" { 1472 container vendorAConfig { 1473 leaf vendorAConfigParam1 { 1474 type int32; 1475 description "vendorA configuration parameter 1 1476 (SBC Device ID)"; 1477 } 1479 leaf vendorAConfigParam2 { 1480 type string; 1481 description "vendorA configuration parameter 2 1482 (SBC Device name)"; 1483 } 1484 description "Container for vendorA SBC configuration"; 1485 } 1486 } 1487 } 1489 In the example above, a custom module named "vendorA-config" uses the 1490 "augment" statement as defined in Section 4.2.8 of [RFC7950] to 1491 extend the module defined in this draft. 1493 8. Processing the Capability Set Response 1495 This section provides a non-normative description of the procedures 1496 that could be carried out by the enterprise network after obtaining 1497 the SIP service provider capability set. On obtaining the capability 1498 set, the enterprise edge element can parse the various fields within 1499 the capability set and generate configuration blocks. For example, 1500 the configuration required to successfully register a SIP trunk with 1501 the SIP registrar hosted in the service provider network, the 1502 configuration required to ensure that fax calls are handled 1503 appropriately, the configuration required to advertise only audio 1504 codecs supported by the SIP service provider, among many other 1505 configuration blocks. A configuration block generated for an almost 1506 identical SIP service provider capability set document is likely 1507 going to differ drastically from one vendor to the next. 1509 Enterprise edge elements are usually capable of normalising 1510 mismatches in the signalling and media planes between the enterprise 1511 and service provider SIP networks. As a result, most, if not all of 1512 the configuration blocks required to enable successful SIP service 1513 provider peering might need to be added on the edge element. In 1514 situations wherein configuration blocks need to be distributed across 1515 multiple devices, some mechanism, that is out of scope of this 1516 document might be used to communicate the specific fields of capacity 1517 set and their corresponding value. Alternatively, a human 1518 administrator could go through the capability set document and 1519 configure the edge element (and if required, other devices in the 1520 enterprise network appropriately. 1522 9. Examples 1524 This section provides examples of how capability set documents that 1525 leverage the YANG module defined in this document can be encoded over 1526 JSON as well as the exchange of messages between the enterprise edge 1527 element and the service provider to acquire the capability set 1528 document. 1530 9.1. JSON Capability Set Document 1531 { 1532 "peering-info": { 1533 "variant": "1.0", 1534 "revision": { 1535 "notBefore": "2021-10-16T00:00:00.00000Z", 1536 "location": 1537 "https://capserver.ssp1.com/capserver/capdoc.json", 1538 }, 1539 "transport-info": { 1540 "transport": "TCP;TLS;UDP", 1541 "registrar": ["registrar1.voip.example.com:5060", 1542 "registrar2.voip.example.com:5060"], 1543 "registerRealm": "voip.example.com", 1544 "callControl": ["callServer1.voip.example.com:5060", 1545 "192.168.12.25:5065"], 1546 "dns": ["8.8.8.8", "208.67.222.222"], 1547 "outboundProxy": "0.0.0.0" 1548 }, 1549 "call-specs": { 1550 "earlyMedia": "true", 1551 "signalingForking": "false", 1552 "supportedMethods": "INVITE;OPTIONS;BYE;CANCEL;ACK; 1553 PRACK;SUBSCRIBE;NOTIFY;REGISTER", 1554 "callerId": { 1555 "e164Format": "true", 1556 "preferredMethod": "P-Asserted-Identity" 1557 }, 1558 "numRange": { 1559 "type": "range", 1560 "count": "20", 1561 "value": "19725455000" 1562 }, 1563 "numRange": { 1564 "type": "block", 1565 "count": "2", 1566 "value": ["19725455000", "19725455001"] 1567 } 1568 }, 1569 "media": { 1570 "mediaTypeAudio": { 1571 "mediaFormat": ["PCMU;rate=8000;ptime=20", 1572 "G729;rate=8000;annexb=yes", 1573 "G722;rate=8000;bitrate=56k,64k"] 1574 }, 1575 "fax": { 1576 "protocol": ["t38", "pass-through"] 1577 }, 1578 "rtp": { 1579 "RTPTrigger": "true", 1580 "symmetricRTP": "true" 1581 }, 1582 "rtcp": { 1583 "symmetricRTCP": "true", 1584 "RTCPFeedback": "true" 1585 } 1586 }, 1587 "dtmf": { 1588 "payloadNumber": "101", 1589 "iteration": "0" 1590 }, 1591 "security": { 1592 "signaling": { 1593 "type": "TLS", 1594 "version": "1.0;1.2" 1595 }, 1596 "mediaSecurity": { 1597 "keyManagement": "SDES;DTLS-SRTP,version=1.2" 1598 }, 1599 "certLocation": 1600 "https://sipserviceprovider.com/certificateList.pem", 1601 "secureTelephonyIdentity": { 1602 "STIRCompliance": "true", 1603 "certDelegation": "true", 1604 "ACMEDirectory": 1605 "https://sipserviceprovider.com/acme.html" 1606 } 1607 }, 1608 "extensions": "timer;rel100;gin;path" 1609 } 1610 } 1612 9.2. Example Exchange 1614 This section is an informational example depicting the configuration 1615 flow that ultimately results in the enterprise edge element obtaining 1616 the capability set document from the SIP service provider. Assuming 1617 the enterprise edge element has been pre-configured with the request 1618 target for the capability set document or has dynamically found the 1619 request target, the edge element generates a HTTPS GET request. This 1620 request can be challenged by the service provider to authenticate the 1621 enterprise. 1623 GET /capdoc?trunkid=trunkent1456 HTTP/1.1 1624 Host: capserver.ssp1.com 1625 Accept:application/peering-info+json 1627 The capability set document is obtained in the body of the response 1628 and is encoded in JSON. 1630 HTTP/1.1 200 OK 1631 Content-Type: application/peering-info+json 1632 Content-Length: nnn 1634 { 1635 "peering-info": ... 1636 } 1638 10. Security Considerations 1640 [TBD] 1642 11. Acknowledgments 1644 [TBD] 1646 12. Normative References 1648 [ACME] "Automatic Certificate Management Environment", 1649 . 1652 [BCP-14] "Key words for use in RFCs to Indicate Requirement 1653 Levels", . 1655 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1656 Requirement Levels", BCP 14, RFC 2119, 1657 DOI 10.17487/RFC2119, March 1997, 1658 . 1660 [RFC2833] Schulzrinne, H. and S. Petrack, "RTP Payload for DTMF 1661 Digits, Telephony Tones and Telephony Signals", RFC 2833, 1662 DOI 10.17487/RFC2833, May 2000, 1663 . 1665 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 1666 A., Peterson, J., Sparks, R., Handley, M., and E. 1667 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 1668 DOI 10.17487/RFC3261, June 2002, 1669 . 1671 [RFC4568] Andreasen, F., Baugher, M., and D. Wing, "Session 1672 Description Protocol (SDP) Security Descriptions for Media 1673 Streams", RFC 4568, DOI 10.17487/RFC4568, July 2006, 1674 . 1676 [RFC4585] Ott, J., Wenger, S., Sato, N., Burmeister, C., and J. Rey, 1677 "Extended RTP Profile for Real-time Transport Control 1678 Protocol (RTCP)-Based Feedback (RTP/AVPF)", RFC 4585, 1679 DOI 10.17487/RFC4585, July 2006, 1680 . 1682 [RFC4733] Schulzrinne, H. and T. Taylor, "RTP Payload for DTMF 1683 Digits, Telephony Tones, and Telephony Signals", RFC 4733, 1684 DOI 10.17487/RFC4733, December 2006, 1685 . 1687 [RFC4855] Casner, S., "Media Type Registration of RTP Payload 1688 Formats", RFC 4855, DOI 10.17487/RFC4855, February 2007, 1689 . 1691 [RFC4961] Wing, D., "Symmetric RTP / RTP Control Protocol (RTCP)", 1692 BCP 131, RFC 4961, DOI 10.17487/RFC4961, July 2007, 1693 . 1695 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 1696 (TLS) Protocol Version 1.2", RFC 5246, 1697 DOI 10.17487/RFC5246, August 2008, 1698 . 1700 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 1701 Security (DTLS) Extension to Establish Keys for the Secure 1702 Real-time Transport Protocol (SRTP)", RFC 5764, 1703 DOI 10.17487/RFC5764, May 2010, 1704 . 1706 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1707 the Network Configuration Protocol (NETCONF)", RFC 6020, 1708 DOI 10.17487/RFC6020, October 2010, 1709 . 1711 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1712 and A. Bierman, Ed., "Network Configuration Protocol 1713 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1714 . 1716 [RFC6665] Roach, A.B., "SIP-Specific Event Notification", RFC 6665, 1717 DOI 10.17487/RFC6665, July 2012, 1718 . 1720 [RFC6749] Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", 1721 RFC 6749, DOI 10.17487/RFC6749, October 2012, 1722 . 1724 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1725 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1726 . 1728 [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr, 1729 "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September 1730 2013, . 1732 [RFC7092] Kaplan, H. and V. Pascual, "A Taxonomy of Session 1733 Initiation Protocol (SIP) Back-to-Back User Agents", 1734 RFC 7092, DOI 10.17487/RFC7092, December 2013, 1735 . 1737 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1738 Protocol (HTTP/1.1): Message Syntax and Routing", 1739 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1740 . 1742 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1743 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1744 DOI 10.17487/RFC7231, June 2014, 1745 . 1747 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1748 Protocol (HTTP/1.1): Authentication", RFC 7235, 1749 DOI 10.17487/RFC7235, June 2014, 1750 . 1752 [RFC7362] Ivov, E., Kaplan, H., and D. Wing, "Latching: Hosted NAT 1753 Traversal (HNT) for Media in Real-Time Communication", 1754 RFC 7362, DOI 10.17487/RFC7362, September 2014, 1755 . 1757 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1758 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1759 . 1761 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1762 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1763 . 1765 [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol 1766 Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, 1767 . 1769 [SIP-Connect-TR] 1770 "SIP Connect Technical Recommendation", 1771 . 1774 Authors' Addresses 1776 Kaustubh Inamdar 1777 Unaffiliated 1779 Email: kaustubh.ietf@gmail.com 1781 Sreekanth Narayanan 1782 Cisco Systems 1784 Email: sreenara@cisco.com 1786 Cullen Jennings 1787 Cisco Systems 1789 Email: fluffy@iii.ca