idnits 2.17.1 draft-kinamdar-dispatch-sip-auto-peer-00.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 46 instances of too long lines in the document, the longest one being 67 characters in excess of 72. == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. 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). == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'SHOULD not' in this paragraph: The base URL of the capability server returned in the WebFinger response SHOULD not contain a path or query component. Once the base URL is obtained, the enterprise edge element builds on the base URL to identify the capability set document on the capability server. The general format for identifying resources on a capability server is as follows: -- The document date (September 10, 2019) is 1652 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 851, but not defined == Missing Reference: '1-9' is mentioned on line 851, but not defined == Missing Reference: '0-4' is mentioned on line 654, but not defined == Missing Reference: '0-5' is mentioned on line 654, but not defined == Missing Reference: '1-5' is mentioned on line 681, but not defined == Missing Reference: '1-4' is mentioned on line 681, but not defined == Missing Reference: '1-2' is mentioned on line 681, but not defined -- Looks like a reference, but probably isn't: '01' on line 654 -- Obsolete informational reference (is this intentional?): RFC 2833 (Obsoleted by RFC 4733, RFC 4734) -- Obsolete informational reference (is this intentional?): RFC 7230 (Obsoleted by RFC 9110, RFC 9112) -- Obsolete informational reference (is this intentional?): RFC 7231 (Obsoleted by RFC 9110) -- Obsolete informational reference (is this intentional?): RFC 7235 (Obsoleted by RFC 9110) Summary: 2 errors (**), 0 flaws (~~), 12 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group K. Inamdar 3 Internet-Draft S. Narayanan 4 Intended status: Standards Track C. Jennings 5 Expires: March 13, 2020 Cisco Systems 6 September 10, 2019 8 Automatic Peering for SIP Trunks 9 draft-kinamdar-dispatch-sip-auto-peer-00 11 Abstract 13 This draft specifies a configuration workflow to enable enterprise 14 Session Initiation Protocol (SIP) networks to solicit the capability 15 set of a SIP service provider network. The capability set can 16 subsequently be used to configure features and services on the 17 enterprise edge element, such as a Session Border Controller (SBC), 18 to ensure smooth peering between enterprise and service provider 19 networks. 21 Status of This Memo 23 This Internet-Draft is submitted in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF). Note that other groups may also distribute 28 working documents as Internet-Drafts. The list of current Internet- 29 Drafts is at https://datatracker.ietf.org/drafts/current/. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 This Internet-Draft will expire on March 13, 2020. 38 Copyright Notice 40 Copyright (c) 2019 IETF Trust and the persons identified as the 41 document authors. All rights reserved. 43 This document is subject to BCP 78 and the IETF Trust's Legal 44 Provisions Relating to IETF Documents 45 (https://trustee.ietf.org/license-info) in effect on the date of 46 publication of this document. Please review these documents 47 carefully, as they describe your rights and restrictions with respect 48 to this document. Code Components extracted from this document must 49 include Simplified BSD License text as described in Section 4.e of 50 the Trust Legal Provisions and are provided without warranty as 51 described in the Simplified BSD License. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 56 2. Conventions and Terminology . . . . . . . . . . . . . . . . . 3 57 3. Reference Architecture . . . . . . . . . . . . . . . . . . . 3 58 4. Configuration Workflow . . . . . . . . . . . . . . . . . . . 5 59 5. Overview of Operations . . . . . . . . . . . . . . . . . . . 6 60 6. HTTP Transport . . . . . . . . . . . . . . . . . . . . . . . 7 61 6.1. HTTP Methods . . . . . . . . . . . . . . . . . . . . . . 7 62 6.2. Integrity and Confidentiality . . . . . . . . . . . . . . 7 63 6.3. Authenticated Client Identity . . . . . . . . . . . . . . 7 64 6.4. Encoding the Request . . . . . . . . . . . . . . . . . . 8 65 6.5. Generating the Response . . . . . . . . . . . . . . . . . 8 66 6.6. Identifying the Request Target . . . . . . . . . . . . . 9 67 7. State Deltas . . . . . . . . . . . . . . . . . . . . . . . . 12 68 8. Encoding the Service Provider Capability Set . . . . . . . . 12 69 9. Data Model for Capability Set . . . . . . . . . . . . . . . . 12 70 9.1. Tree Diagram . . . . . . . . . . . . . . . . . . . . . . 12 71 9.2. YANG Model . . . . . . . . . . . . . . . . . . . . . . . 14 72 9.3. Node Definitions . . . . . . . . . . . . . . . . . . . . 19 73 9.4. Extending the Capability Set . . . . . . . . . . . . . . 25 74 10. Example Capability Set Document Encoding . . . . . . . . . . 26 75 10.1. JSON Capability Set Document . . . . . . . . . . . . . . 26 76 10.2. XML Capability Set Document . . . . . . . . . . . . . . 28 77 11. Example Exchange . . . . . . . . . . . . . . . . . . . . . . 29 78 12. Security Considerations . . . . . . . . . . . . . . . . . . . 32 79 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 33 80 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 33 81 14.1. Normative References . . . . . . . . . . . . . . . . . . 33 82 14.2. Informative References . . . . . . . . . . . . . . . . . 33 83 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 35 85 1. Introduction 87 The deployment of a Session Initiation Protocol (SIP)-based 88 infrastructure in enterprise and service provider communication 89 networks is increasing at a rapid pace. Consequently, direct IP 90 peering between enterprise and service provider networks is quickly 91 replacing traditional methods of interconnection between enterprise 92 and service provider networks. 94 Currently published standards provide a strong foundation over which 95 direct IP peering can be realized. However, given the sheer number 96 of these standards, it is often not clear which behavioral subsets, 97 extensions to baseline protocols and operating principles ought to be 98 implemented by service provider and enterprise networks to ensure 99 successful peering. 101 The SIP Connect technical recommendations aim to solve this problem 102 by providing a master reference that promotes seamless peering 103 between enterprise and service provider SIP networks. However, 104 despite the extensive set of implementation rules and operating 105 guidelines, interoperability issues between service provider and 106 enterprise networks persist. This is in large part because service 107 providers and equipment manufacturers aren't required to enforce the 108 guidelines of the technical specifications and have a fair degree of 109 freedom to deviate from them. Consequently, enterprise 110 administrators usually undertake a fairly rigorous regimen of 111 testing, analysis and troubleshooting to arrive at a configuration 112 block that ensures seamless service provider peering. 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. Conventions and Terminology 131 The The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL 132 NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in 133 this document are to be interpreted as described in [RFC2119] 135 3. Reference Architecture 137 Figure 1 illustrates a reference architecture that may be deployed to 138 support the mechanism described in this document. The enterprise 139 network consists of a SIP-PBX, media endpoints and a Session Border 140 Controller. It may also include additional components such as 141 application servers for voicemail, recording, fax etc. At a high 142 level, the service provider consists of a SIP signaling entity (SP- 143 SSE), a media entity and a HTTP(S) server. 145 +-----------------------------------------------------+ 146 | +---------------+ +-----------------------+ | 147 | | | | | | 148 | | +----------+ | | +-------+ | | 149 | | | Cap | | HTTPS | | | | | 150 | | | Server |<-|---------|-->| | | | 151 | | | | | | | | +-----+ | | 152 | | +----------+ | | | | | SIP | | | 153 | | | | | |<->| PBX | | | 154 | | | | | | +-----+ | | 155 | | +----------+ | | | SBC | | | 156 | | | | | SIP | | | | | 157 | | | SP - SSE |<-|---------|-->| | +-----+ | | 158 | | | | | | | |<->| M.E.| | | 159 | | +----------+ | | | | | | | | 160 | | | | | | +-----+ | | 161 | | +----------+ | SRTP | | | | | 162 | | | Media |<-|---------|-->+-------+ | | 163 | | +----------+ | | | | 164 | +---------------+ +-----------------------+ | | | 165 +-----------------------------------------------------+ 167 Figure 1: Reference Architecture 169 This draft makes use of the following terminology: 171 o 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 o 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) such as a Session Border Controller (SBC). 182 o Service Provider Network: A communications network infrastructure 183 deployed by service providers. In the context of this draft, the 184 service provider network is accessible over SIP for the 185 establishment, modification and termination of calls and 186 accessible over HTTP(S) for the transfer of the capability set 187 document. The service provider network is also referred to as a 188 SIP Service Provider (SSP) or Internet Telephony Service Provider 189 (ITSP) network. These networks typically interconnect with other 190 service provider networks over SIP or ISDN. 192 o 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 o 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 o Capability Set: This specification uses the term capability set 204 (or capability set document) to refer collectively to a set of 205 characteristics within the service provider network, which when 206 communicated to the enterprise network allows it to obtain 207 sufficient information required to peer successfully with the 208 service provider network. 210 4. Configuration Workflow 212 A workflow that facilitates an enterprise network to solicit the 213 capability set of a SIP service provider ought to take into account 214 the following considerations: 216 o The configuration workflow must be based on a protocol or a set of 217 protocols commonly used between enterprise and service provider 218 telephony networks. 220 o The configuration workflow must be flexible enough to allow the 221 service provider network to dynamically offload different 222 capability sets to different enterprise networks based on the 223 identity of the enterprise network. 225 o Capability set documents obtained as a result of the configuration 226 workflow must be conducive to easy parsing by automaton. 227 Subsequently, automaton may be used for generation of appropriate 228 configuration blocks. 230 Taking the above considerations into account, this document proposes 231 a Hypertext Transfer Protocol (HTTP)-based workflow using which the 232 enterprise network can solicit and ultimately obtain the service 233 provider capability set. The enterprise network creates a well 234 formed HTTPS GET request to solicit the service provider capability 235 set. Subsequently, the HTTPS response from the SIP service provider 236 includes the capability set. The capability set is encoded in either 237 XML or JSON, thus ensuring that the response can be easily parsed by 238 automaton. 240 There are alternative mechanisms using which the SIP service provider 241 can offload its capability set. For example, the Session Initiation 242 Protocol (SIP) can be extended to define a new event package 243 [RFC6665], such that the enterprise network can establish a SIP 244 subscription with the service provider for its capability set; the 245 SIP service provider can subsequently use the SIP NOTIFY request to 246 communicate its capability set or any state deltas to its baseline 247 capability set. This mechanism is likely to result in a significant 248 amount of operational complexity. For example, not only would this 249 workflow require enterprise and service provider equipment 250 manufacturers to upgrade their software stacks, but it would also 251 create a significant amount of ambiguity in terms of which device in 252 the service provider network handles subscriptions and generates 253 notifications. Yet another example of an alternative mechanism would 254 be for service providers and enterprise equipment manufacturers to 255 agree on YANG models [RFC6020] that enable configuration to be pushed 256 over NETCONF [RFC6241] to enterprise networks from a centralized 257 source hosted in service provider networks. The presence of 258 proprietary software logic for call and media handling in enterprise 259 devices would preclude the generation of a "one-size-fits-all" YANG 260 model. Additionally, service provider networks pushing configuration 261 to enterprises devices might lead to the loss of implementation 262 autonomy on the part of the enterprise network. 264 5. Overview of Operations 266 To solicit the capability set of the SIP service provider, the edge 267 element in the enterprise network generates a well-formed HTTPS GET 268 request. There are two reasons why it makes sense for the enterprise 269 edge element to generate the HTTPs request: 271 1. Edge elements are devices that normalize any mismatches between 272 the enterprise and service provider networks in the media and 273 signaling planes. As a result, when the capability set is 274 received from the SIP service provider network, the edge element 275 can generate appropriate configuration blocks (possibly across 276 multiple devices) to enable smooth IP peering. 277 2. Given that edge elements are configured to "talk" to networks 278 external to the enterprise, the complexity in terms of NAT 279 traversal and firewall configuration would be minimal. 281 The HTTPs GET request is targeted at a capability server that is 282 managed by the SIP service provider such that this server processes, 283 and on successfully processing the request, includes the capability 284 set document in the response. The capability set document is 285 constructed according the guidelines of the YANG model described in 286 this draft. The capability set document included in a successful 287 response is formatted in either XML or JSON. The formatting depends 288 on the value of the "Accept" header field of the HTTP GET request. 289 More details about the formatting of the HTTP request and response 290 are provided in Section 6 292 Figure 1 provides a reference architecture in which this workflow may 293 be implemented. The architecture depicted in Figure 1 consists of an 294 enterprise telephony network and a SIP service provider network, such 295 that the enterprise network attempts to provision SIP trunking 296 services for the first time. For the sake of simplicity, the 297 enterprise and service provider networks are decomposed into their 298 core constituent elements. 300 6. HTTP Transport 302 This section describes the use of HTTP as a transport protocol for 303 the peering workflow. This workflow is based on HTTP version 1.1 305 6.1. HTTP Methods 307 The workflow defined in this document leverages the HTTP GET method 308 and its corresponding response(s) to request for and subsequently 309 obtain the service provider capability set document. The HTTP POST 310 method and its corresponding response(s) is also used for client 311 authentication. 313 To ensure the smooth operation of this workflow, this draft enforces 314 certain controls (not to be confused with HTTP controls as defined in 315 [RFC7231] on the HTTP client and server. These controls as they 316 relate to formatting, operational guidelines, security concerns and 317 more, are detailed in subsequent sections of this draft. 319 6.2. Integrity and Confidentiality 321 Peering requests and responses are defined over HTTP. However, due 322 to the sensitive nature of information transmitted between client and 323 server, it is required to secure HTTP using Transport Layer Security. 324 The enterprise edge element and capability server MUST be compliant 325 to [RFC7235]. The enterprise edge element and capability server MUST 326 support the use of the https uri scheme as defined in [RFC7230]. 328 6.3. Authenticated Client Identity 330 The configuration workflow and corresponding YANG model described in 331 this draft allow for smooth IP peering between enterprise and SIP 332 service provider networks by encoding the essential session and media 333 characteristics. It is NOT RECOMMENDED to encode information that is 334 sensitive in nature. It is only required for the client (enterprise 335 edge element) to authenticate the SIP service provider. If however, 336 there is a need for the SIP service provider to authenticate the 337 enterprise edge element, client authentication mechanisms based on 338 OAuth 2.0 token are RECOMMENDED. The specifics of how the client 339 obtains such tokens is outside the scope of this draft. Section 11 340 provides an example of how clients may be authenticated using OAuth 341 2.0 tokens. 343 6.4. Encoding the Request 345 The edge element in the enterprise network generates a HTTPS GET 346 request such that the request-target is obtained using the procedure 347 outlined in section 6.6 The MIME types for the capability set 348 document defined in this draft are "application/peering-info+json" 349 and "application/peering-info+xml". Accordingly, the Accept header 350 field value MUST be restricted only to these MIME types. It is 351 possible that the edge element supports responses formatted in both 352 JSON and XML. In such situations, the edge element might generate a 353 HTTPS GET request such that the Accept header field includes both 354 MIME types along with the corresponding "qvalue" for each MIME type. 355 For implementations that require client authentication, the bearer 356 access token acquired by the client (see section 6.3) MUST be 357 presented to the capability server to the obtain the capability set 358 document. The bearer token is presented in the "Authorization" 359 header field of the GET request as specified in Section 2.1 of 360 [RFC6750]. 362 The generated HTTPS GET request MUST NOT use the "Expect" and "Range" 363 header fields. The requests also MUST NOT use any conditional 364 request. 366 6.5. Generating the Response 368 Capability servers include the capability set documents in the body 369 of a successful response. Capability set documents MUST be formatted 370 in XML or JSON. For requests that are incorrectly formatted, the 371 capability server SHOULD generate a "400 Bad Request" response. If 372 the client (enterprise edge element) includes any other MIME types in 373 Accept header field other than "application/peering-info+json" or 374 "application/peering-info+xml", the capability set MUST reject the 375 request with a "406 Not Acceptable" response. 377 The capability server can respond to client requests with redirect 378 responses, specifically, the server can respond with the following 379 redirect responses: 381 1. 301 Moved Temporarily 383 2. 302 Found 384 3. 307 Temporary Redirect 386 The server SHOULD include the Location header field in such 387 responses. 389 For requests that carry an invalid bearer token in the Authorization 390 header field, the capability server SHOULD respond with a HTTP 401 391 status code. 393 6.6. Identifying the Request Target 395 HTTPS GET requests from enterprise edge elements MUST carry a valid 396 request-target. The enterprise edge element might obtain the URL of 397 the resource hosted on the capability server in one of two ways: 399 1. Manual Configuration 400 2. Using the WebFinger Protocol 402 The complete HTTPS URLs to be used when authenticating the enterprise 403 edge element (optional) and obtaining the SIP service provider 404 capability set can be obtained from the SIP service provider 405 beforehand and entered into the edge element manually via some 406 interface - for example, a CLI or GUI. 408 However, if the resource URL is unknown to the administrator (and by 409 extension of that to the edge element), the WebFinger protocol 410 [RFC7033] may be leveraged. From the perspective of this draft, 411 three link relation types (rel) are defined, namely: 413 1. Capability Server: The base URL of the capability server hosting 414 the capability set document. 415 2. Authorization Endpoint: The URL of the authorization endpoint to 416 be used for OAuth 2.0 417 3. Token Endpoint: The URL of the token endpoint to be used for 418 OAuth 2.0 420 The corresponding link relation type values are as follows: 422 1. Capability Server: " 423 2. Authorization Endpoint: " 424 3. Token Endpoint: " 426 If an enterprise edge element attempts to discover the URL of the 427 endpoints hosted in the ssp1.example.com domain, it issues the 428 following request (line wraps are for display purposes only) 429 GET /.well-known/webfinger? 430 resource=http%3A%2F%2Fssp1.example.com 431 &rel=http%3A%2f%2fsipserviceprovider%2fcapserver 432 &rel=http%3A%2f%2fsipserviceprovider%2auth 433 &rel= http%3A%2f%2fsipserviceprovider%2token 434 HTTP/1.1 435 Host: ssp1.example.com 437 The response to the above request might be as follows: 439 HTTP/1.1 200 OK 440 Access-Control-Allow-Origin: * 441 Content-Type: application/jrd+json 442 { 443 "subject" : "http://ssp1.example.com", 444 "links" : 445 [ 446 { 447 "rel" : "http://sipserviceprovider/capserver", 448 "href" : "https://capserver.ssp1.com" 449 }, 450 { 451 "rel" : "http://sipserviceprovider/auth", 452 "href" : "https://ssp1.com/authorize" 453 }, 454 { 455 "rel" : "http://sipserviceprovider/token", 456 "href" : "https://ssp1.com/token" 457 } 458 ] 459 } 461 SIP service providers MUST support the "https" URI and "acct" URI 462 [link] schemes in WebFinger queries. The "acct" URI scheme might be 463 used in the WebFinger query, if the enterprise adminsitrator is 464 provided with a username by the SIP service provider. The SIP 465 service provider might provide a unique username for each SIP trunk 466 purchased by the enterprise network or a single username that is 467 applicable to all the trunks purchased by the enterprise network. 468 This draft does not require SIP service providers or enterprise 469 networks to favor one URI scheme over the other; rather, the choice 470 of which scheme to use is left to the discretion of the SIP service 471 provider. The security considerations of using the "acct" URI is 472 provided in section 5 of [RFC7565]. 474 The base URL of the capability server returned in the WebFinger 475 response SHOULD not contain a path or query component. Once the base 476 URL is obtained, the enterprise edge element builds on the base URL 477 to identify the capability set document on the capability server. 478 The general format for identifying resources on a capability server 479 is as follows: 481 //? 483 scheme: Is always HTTPS in the context of this draft. 485 baseURL: The base URL of the capability server discovered as a result 486 of the WebFinger query. 488 path: The path expression identifying the capability set document on 489 the capability server. The path expression MUST be set to the static 490 string of "capdoc". 492 query: A query string identifying a specific representation of the 493 capability set document. The format of the query string is in the 494 form of a "name=value" pair. This draft defines the following 495 optional query parameter: 497 trunkid: A parameter uniquely identifying the SIP trunk for which the 498 capability set document is sought. 500 The "trunkid" is useful in situations in which an enterprise SIP 501 network has multiple SIP trunks with the SIP service provider, such 502 that parameters for such trunks vary, perhaps because of the 503 geographical distribution of these sites. The value of the "trunkid" 504 parameter is generated by the SIP service provider and communicated 505 to the enterprise SIP network by some out-of-band mechanism, for 506 example, it may be provided in an email to the enterprise 507 administrator after the trunk is purchased. It is RECOMMENDED that 508 SIP service providers generate unique trunk identifiers across 509 enterprise networks. 511 It is RECOMMENDED that SIP service provider networks support the 512 "trunkid" query parameter. SIP service providers expose varying 513 capability sets to different enterprise SIP telephony networks. 514 Using the "trunkid" query parameter not only helps the SIP service 515 provider capability server to uniquely identify the trunk/enterprise/ 516 edge element for which the capability set document is being request, 517 but also, it is helpful in generating unique URL strings for 518 capability set documents. These unique URL strings are helpful in 519 HTTP content caching. 521 7. State Deltas 523 Given that the service provider capability set is largely expected to 524 remain static, the work needed to implement an asynchronous push 525 mechanism to encode minor changes in the capability set document 526 (state deltas) is not commensurate with the benefits. Rather, 527 enterprise edge elements can poll capability servers at pre-defined 528 intervals to obtain the full capability set document. It is 529 RECOMMENDED that capability servers are polled every 24 hours. 531 8. Encoding the Service Provider Capability Set 533 In the context of this draft, the capability set of a service 534 provider refers collectively to a set of characteristics which when 535 communicated to an enterprise network, provides it with sufficient 536 information to directly peer with the service provider network. The 537 capability set document is not designed to encode extremely granular 538 details of all features, services, and protocol extensions that are 539 supported by the service provider network. For example, it is 540 sufficient to encode that the service provider uses T.38 relay for 541 faxing, it is not required to know the value of the 542 "T38FaxFillBitRemoval" parameter. 544 The parameters within the capability set document represent a wide 545 array of characteristics, such that these characteristics 546 collectively disseminate sufficient information to enable direct IP 547 peering between enterprise and service provider networks. The 548 various parameters represented in the capability set are chosen based 549 on existing practises and common problem sets typically seen between 550 enterprise and service provider SIP networks. 552 9. Data Model for Capability Set 554 This section defines a YANG module for encoding the service provider 555 capability set. Section 9.1 provides the tree diagram, which is 556 followed by a description of the various nodes within the module 557 defined in this draft. 559 9.1. Tree Diagram 561 This section provides a tree diagram [RFC8340] for the "ietf- 562 capability-set" module. The interpretation of the symbols appearing 563 in the tree diagram is as follows: 565 o Brackets "[" and "]" enclose list keys. 567 o Abbreviations before data node names: "rw" means configuration 568 (read-write), and "ro" means state data (read-only). 570 o Symbols after data node names: "?" means an optional node, "!" 571 means a presence container, and "*" denotes a list and leaf-list. 573 o Parentheses enclose choice and case nodes, and case nodes are also 574 marked with a colon (":"). 576 o Ellipsis ("...") stands for contents of subtrees that are not 577 shown. 579 The data model for the peering capability document has the following 580 structure: 582 module: ietf-sip-auto-peering 583 +--rw peering-info 584 +--rw variant string 585 +--rw transport-info 586 | +--rw transport? enumeration 587 | +--rw registrar* host-port 588 | +--rw registrarRealm? string 589 | +--rw callControl* host-port 590 | +--rw dns* inet:ip-address 591 | +--rw outboundProxy? host-port 592 +--rw call-specs 593 | +--rw earlyMedia? boolean 594 | +--rw signalingForking? boolean 595 | +--rw supportedMethods? string 596 +--rw media 597 | +--rw mediaTypeAudio 598 | | +--rw mediaFormat* string 599 | +--rw fax 600 | | +--rw protocol* enumeration 601 | +--rw rtp 602 | | +--rw RTPTrigger? boolean 603 | | +--rw symmetricRTP? boolean 604 | +--rw rtcp 605 | +--rw symmetricRTCP? boolean 606 | +--rw RTCPfeedback? boolean 607 +--rw dtmf 608 | +--rw payloadNumber? int8 609 | +--rw iteration? boolean 610 +--rw security 611 | +--rw signaling 612 | | +--rw type? string 613 | | +--rw version? string 614 | +--rw mediaSecurity 615 | +--rw keyManagement? string 616 +--rw extensions? string 618 9.2. YANG Model 620 This section defines the YANG module for the peering capability set 621 document. It imports modules (ietf-yang-types and ietf-inet-types) 622 from [RFC6991]. 624 module ietf-sip-auto-peering { 625 namespace "urn:ietf:params:xml:ns:ietf-sip-auto-peering"; 626 prefix "peering"; 628 description 629 "Data model for transmitting peering parameters from SP to Enterprise"; 631 revision 2019-05-06 { 632 description "Initial revision of peering-response doc."; 633 } 635 import ietf-inet-types { 636 prefix "inet"; 637 } 639 typedef ipv4-address-port { 640 type string { 641 pattern '(([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])\.){3}' 642 + '([0-9]|[1-9][0-9]|1[0-9][0-9]|2[0-4][0-9]|25[0-5])' 643 + ':^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]{2}|655[1-2][0-9]|6553[1-5])$'; 644 } 645 description "The ipv4-address-port type represents an IPv4 address in 646 dotted-quad notation followed by a port number."; 647 } 649 typedef ipv6-address-port { 650 type string { 651 pattern '((:|[0-9a-fA-F]{0,4}):)([0-9a-fA-F]{0,4}:){0,5}' 652 + '((([0-9a-fA-F]{0,4}:)?(:|[0-9a-fA-F]{0,4}))|' 653 + '(((25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])\.){3}' 654 + '(25[0-5]|2[0-4][0-9]|[01]?[0-9]?[0-9])))' 655 + ':^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]{2}|655[1-2][0-9]|6553[1-5])$'; 656 pattern 657 '(([^:]+:){6}(([^:]+:[^:]+)|(.*\..*)))|' 658 + '((([^:]+:)*[^:]+)?::(([^:]+:)*[^:]+)?)' 659 + ':^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]{2}|655[1-2][0-9]|6553[1-5])$'; 660 } 661 description 662 "The ipv6-address type represents an IPv6 address in full, 663 mixed, shortened, and shortened-mixed notation followed by a port number."; 664 } 665 typedef ip-address-port { 666 type union { 667 type ipv4-address-port; 668 type ipv6-address-port; 669 } 670 description 671 "The ip-address-port type represents an IP address:port number 672 and is IP version neutral."; 673 } 675 typedef domain-name-port { 676 type string { 677 pattern 678 '((([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.)*' 679 + '([a-zA-Z0-9_]([a-zA-Z0-9\-_]){0,61})?[a-zA-Z0-9]\.?)' 680 + '|\.' 681 + ':^()([1-9]|[1-5]?[0-9]{2,4}|6[1-4][0-9]{3}|65[1-4][0-9]{2}|655[1-2][0-9]|6553[1-5])$'; 682 length "1..258"; 683 } 684 description 685 "The domain-name-port type represents a DNS domain name followed by a port number. 686 The name SHOULD be fully qualified whenever possible."; 687 } 689 typedef host-port { 690 type union { 691 type ip-address-port; 692 type domain-name-port; 693 } 694 description 695 "The host type represents either an IP address or a DNS 696 domain name followed by a port number."; 697 } 699 container peering-info { 700 leaf variant { 701 type string; 702 mandatory true; 703 description "Variant of peering-response document"; 704 } 706 container transport-info { 707 leaf transport { 708 type enumeration { 709 enum "TCP"; 710 enum "TLS"; 711 enum "UDP"; 712 enum "TCP;TLS"; 713 enum "TCP;TLS;UDP"; 714 enum "TCP;UDP"; 715 } 716 description "Transport Protocol(s) used in SIP communication"; 717 } 719 leaf-list registrar { 720 type host-port; 721 max-elements 3; 722 description "List of service provider registrar servers"; 723 } 725 leaf registrarRealm { 726 type string; 727 description "Realm for REGISTER requests carrying credentials"; 728 } 730 leaf-list callControl { 731 type host-port; 732 max-elements 3; 733 description "List of service provider call control servers"; 734 } 736 leaf-list dns { 737 type inet:ip-address; 738 max-elements 2; 739 description "IP address of the DNS Server(s) hosted by the service provider"; 740 } 742 leaf outboundProxy { 743 type host-port; 744 description "SIP Outbound Proxy"; 745 } 746 } 748 container call-specs { 749 leaf earlyMedia { 750 type boolean; 751 description "Flag indicating whether the service provider is expected 752 to deliver early media."; 753 } 755 leaf signalingForking { 756 type boolean; 757 description "Flag indicating whether the service provider is capable 758 of forking incoming calls "; 759 } 760 leaf supportedMethods { 761 type string; 762 description "Leaf/Leaf List indicating the different SIP methods 763 support by the service provider."; 764 } 765 } 767 container media { 768 container mediaTypeAudio { 769 leaf-list mediaFormat { 770 type string; 771 description "Leaf List indicating the audio media formats supported."; 772 } 773 } 775 container fax { 776 leaf-list protocol { 777 type enumeration { 778 enum "pass-through"; 779 enum "t38"; 780 } 781 max-elements 2; 782 description "Leaf List indicating the different fax protocols 783 supported by the service provider."; 784 } 785 } 787 container rtp { 788 leaf RTPTrigger { 789 type boolean; 790 description "Flag indicating whether the service provider expects to 791 receive the first media packet."; 792 } 794 leaf symmetricRTP { 795 type boolean; 796 description "Flag indicating whether the service provider expects 797 symmetric RTP defined in [@RFC4961]"; 798 } 799 } 801 container rtcp { 802 leaf symmetricRTCP { 803 type boolean; 804 description " Flag indicating whether the service provider expects 805 symmetric RTP defined in [@RFC4961]."; 806 } 807 leaf RTCPfeedback { 808 type boolean; 809 description "Flag Indicating support for RTP profile extension for 810 RTCP-based feedback, as defined in [@RFC4585]"; 811 } 812 } 813 } 815 container dtmf { 816 leaf payloadNumber { 817 type int8 { 818 range "96..127"; 819 } 820 description "Leaf that indicates the payload number(s) supported by 821 the service provider for DTMF relay via Named-Telephony-Events"; 822 } 824 leaf iteration { 825 type boolean; 826 description "Flag identifying whether the service provider supports 827 NTE DTMF relay using the procedures of [@RFC2833] or [@RFC4733] ."; 828 } 829 } 831 container security { 832 container signaling { 833 leaf type { 834 type string { 835 pattern "TLS"; 836 } 837 description "Type of signaling security supported."; 838 } 840 leaf version { 841 type string { 842 pattern "([1-9]\.[0-9])(;[1-9]\.[0-9])?|(NULL)"; 843 } 844 description "Indicates TLS version for SIP signaling"; 845 } 846 } 848 container mediaSecurity { 849 leaf keyManagement { 850 type string { 851 pattern "(SDES(;DTLS-SRTP,version=[1-9]\.[0-9](,[1-9]\.[0-9])?)?)|(DTLS-SRTP,version=[1-9]\.[0-9](,[1-9]\.[0-9])?)|(NULL)"; 852 } 853 description "Leaf that identifies the key management methods 854 supported by the service provider for SRTP."; 856 } 857 } 858 } 860 leaf extensions { 861 type string; 862 description "Lists the various SIP extensions supported by SP"; 863 } 864 } 865 } 867 9.3. Node Definitions 869 This sub-sections provides the definition and encoding rules of the 870 various nodes of the YANG module defined in section 9.2 872 o *capability-set*: This node serves as a container for all the 873 other nodes in the YANG module; the capability-set node is akin to 874 the root element of an XML schema. 876 o *variant*: This node identifies the version number of the 877 capability set document. This draft defines the parameters for 878 variant 1.0; future specifications might define a richer parameter 879 set, in which case the variant can be changed to 2.0, 3.0 and so 880 on. Future extensions to the capability set document MUST also 881 ensure that the corresponding YANG module is defined. 883 o *transport-info*: The transport-info node is a container that 884 encapsulates transport characteristics of SIP sessions between 885 enterprise and service provider networks. 887 o *transport*: A leaf node that enumerates the different Transport 888 Layer protocols supported by the SIP service provider. Valid 889 transport layer protocols include: UDP, TCP, TLS or a combination 890 of them (with the exception of TLS and UDP). 892 o *registrar*: A leaf-list that specifies the transport address of 893 one or more registrar servers in the service provider network. 894 The transport address of the registrar can be provided using a 895 combination of a valid IP address and port number, or a subdomain 896 of the SIP service provider network, or the fully qualified domain 897 name (FQDN) of the SIP service provider network. If the transport 898 address of a registrar is specified using either a subdomain or a 899 fully qualified domain name, the DNS element needs to be populated 900 with one or more valid DNS server IP addresses. 902 o *callControl*: A leaf-list that specifies the transport address of 903 the call server(s) in the service provider network. The 904 enterprise network MUST use an applicable transport protocol in 905 conjunction with the call control server(s) transport address when 906 transmitting call setup requests. The transport address of a call 907 server(s) within the service provider network can be specified 908 using a combination of a valid IP address and port number, or a 909 subdomain of the SIP service provider network, or a fully 910 qualified domain name of the SIP service provider network. If the 911 transport address of a call control server(s) is specified using 912 either a subdomain or a fully qualified domain name, the DNS 913 element MUST be populated with one or more valid DNS server IP 914 addresses. The transport address specified in this element can 915 also serve as the target for non-call requests such as SIP 916 OPTIONS. 918 o *dns*: A leaf list that encodes the IP address of one or more DNS 919 servers hosted by the SIP service provider. If the enterprise 920 network is unaware of the IP address, port number, and transport 921 protocol of servers within the service provider network (for 922 example, the registrar and call control server), it MUST use DNS 923 NAPTR and SRV. Alternatively, if the enterprise network has the 924 fully qualified domain name of the SIP service provider network, 925 it MUST use DNS to resolve the said FQDN to an IP address. The 926 dns element encodes the IP address of one or more DNS servers 927 hosted in the service provider network. If however, either the 928 registrar or callControl elements or both are populated with a 929 valid IP address and port pair, the dns element MUST be set to the 930 quadruple octet of 0.0.0.0. 932 o *outboundProxy*: A leaf list that specifies the transport address 933 of one or more outbound proxies. The transport address can be 934 specified by using a combination of an IP address and a port 935 number, a subdomain of the SIP service provider network, or a 936 fully qualified domain name and port number of the SIP service 937 provider network. If the outbound-proxy sub-element is populated 938 with a valid transport address, it represents the default 939 destination for all outbound SIP requests and therefore, the 940 registrar and callControl elements MUST be populated with the 941 quadruple octet of 0.0.0.0. 943 o *call-specs*: A container that encapsulates information about call 944 specifications, restrictions and additional handling criteria for 945 SIP calls between the enterprise and service provider network. 947 o *earlyMedia*: A leaf that specifies whether the service provider 948 network is expected to deliver in-band announcements/tones before 949 call connect. The P-Early-Media header field can be used to 950 indicate pre-connect delivery of tones and announcements on a per- 951 call basis. However, given that signalling and media could 952 traverse a large number of intermediaries with varying 953 capabilities (in terms of handling of the P-Early-Media header 954 field) within the enterprise, such devices can be appropriately 955 configured for media cut through if it is known before-hand that 956 early media is expected for some or all of the outbound calls. 957 This element is a Boolean type, where a value of 1/true signifies 958 that the service provider is capable of early media. A value of 959 0/false signifies that the service provider is not expected to 960 generate early media. 962 o *signalingForking*: A leaf that specifies whether outbound call 963 requests from the enterprise might be forked on the service 964 provider network leading to multiple early dialogs. This 965 information would be useful to the enterprise network in 966 appropriately handling multiple early dialogs reliably and in 967 enforcing local policy. This element is a Boolen type, where a 968 value of 1/true signifies that the service provider network can 969 potentially fork outbound call requests from the enterprise. A 970 value of 0/false indicates that the service provider will not fork 971 outbound call requests. 973 o *supportedMethods*: A leaf node that specifies the various SIP 974 methods supported by the SIP service provider. The list of 975 supported methods help to appropriately configuration various 976 devices within the enterprise network. For example, if the 977 service provider enumerates support for the OPTIONS method, the 978 enterprise network could periodically send OPTIONS requests as a 979 keep-alive mechanism. 981 o *media*: A container that is used to collectively encapsulate the 982 characteristics of UDP-based audio streams. A future 983 extension to this draft may extend the media container to describe 984 other media types. The media container is also used to 985 encapsulate basic information about Real-Time Transport Protocol 986 (RTP) and Real-Time Transport Control Protocol (RTCP) from the 987 perspective of the service provider network. 989 o *mediaTypeAudio*: A container for the mediaFormat leaf-list. This 990 container collectively encapsulates the various audio media 991 formats supported by the SIP service provider. 993 o *mediaFormat*: A leaf-list encoding the various audio media 994 formats supported by the SIP service provider. The relative 995 ordering of different media format leaf nodes from left to right 996 indicates preference from the perspective of the service provider. 997 Each mediaFormat node begins with the encoding name of the media 998 format, which is the same encoding name as used in the "RTP/AVP" 999 and "RTP/SAVP" profiles. The encoding name is followed by 1000 required and optional parameters for the given media format as 1001 specified when the media format is registered [RFC4855]. Given 1002 that the parameters of media formats can vary from one 1003 communication session to another, for example, across two separate 1004 communication sessions, the packetization time (ptime) used for 1005 the PCMU media format might vary from 10 to 30 ms, the parameters 1006 included in the format element MUST be the ones that are expected 1007 to be invariant from the perspective of the service provider. 1008 Providing information about supported media formats and their 1009 respective parameters, allows enterprise networks to configure the 1010 media plane characteristics of various devices such as endpoints 1011 and middleboxes. The encoding name, one or more required 1012 parameters, one or more optional parameters are all separated by a 1013 semicolon. The formatting of a given media format parameter, MUST 1014 follow the formatting rules as specified for that media format. 1016 o *fax*: A container that encapsulates the fax protocol(s) supported 1017 by the SIP service provider. The fax container encloses a leaf- 1018 list (named protocol) that enumerates whether the service provider 1019 supports t38 relay, protocol-based fax passthrough or both. The 1020 relative ordering of leaf nodes within the leaf lists indicates 1021 preference. 1023 o *rtp*: A container that encapsulates generic characteristics of 1024 RTP sessions between the enterprise and service provider network. 1025 This node is a container for the "RTPTrigger" and "SymmetricRTP" 1026 leaf nodes. 1028 o *RTPTrigger*: A leaf node indicating whether the SIP service 1029 provider network always expects the enterprise network to send the 1030 first RTP packet for an established communication session. This 1031 information is useful in scenarios such as "hairpinned" calls, in 1032 which the caller and callee are on the service provider network 1033 and because of sub-optimal media routing, an enterprise device 1034 such as an SBC is retained in the media path. Based on the 1035 encoding of this node, it is possible to configure enterprise 1036 devices such as SBCs to start streaming media (possibly filled 1037 with silence payloads) toward the address:port tuples provided by 1038 caller and callee. This node is a Boolean type. A value of 1/ 1039 true indicates that the service provider expects the enterprise 1040 network to send the first RTP packet, whereas a value of 0/false 1041 indicates that the service provider network does not require the 1042 enterprise network to send the first media packet. While the 1043 practise of preserving the enterprise network in a hairpinned call 1044 flow is fairly common, it is RECOMMENDED that SIP service 1045 providers avoid this practise. In the context of a hairpinned 1046 call, the enterprise device retained in the call flow can easily 1047 eavesdrop on the conversation between the offnet parties. 1049 o *symmetricRTP*: A leaf node indicating whether the SIP service 1050 provider expects the enterprise network to use symmetric RTP as 1051 defined in [RFC4961]. Uncovering this expectation is useful in 1052 scenarios where "latching" [RFC3762] is implemented in the service 1053 provider network. This node is a Boolean type, a value of 1/true 1054 indicates that the service provider expects the enterprise network 1055 to use symmetric RTP, whereas a value of 0/false indicates that 1056 the enterprise network can use asymmetric RTP. 1058 o *rtcp*: A container that encapsulates generic characteristics of 1059 RTCP sessions between the enterprise and service provider network. 1060 This node is a container for the "RTCPFeedback" and 1061 "SymmetricRTCP" leaf nodes. 1063 o *RTCPFeedback*: A leaf node that indicates whether the SIP service 1064 provider supports the RTP profile extension for RTCP-based 1065 feedback [RFC4585]. Media sessions spanning enterprise and 1066 service provider networks, are rarely made to flow directly 1067 between the caller and callee, rather, it is often the case that 1068 media traffic flows through network intermediaries such as SBCs. 1069 As a result, RTCP traffic from the service provider network is 1070 intercepted by these intermediaries, which in turn can either pass 1071 across RTCP traffic unmodified or modify RTCP traffic before it is 1072 forwarded to the endpoint in the enterprise network. Modification 1073 of RTCP traffic would be required, for example, if the 1074 intermediary has performed media payload transformation operations 1075 such as transcoding or transrating. In a similar vein, for the 1076 RTCP-based feedback mechanism as defined in [RFC4585] to be truly 1077 effective, intermediaries MUST ensure that feedback messages are 1078 passed reliably and with the correct formatting to enterprise 1079 endpoints. This might require additional configuration and 1080 considerations that need to be dealt with at the time of 1081 provisioning the intermediary device. This node is a Boolean 1082 type, a value of 1/true indicates that the service provider 1083 supports the RTP profile extension for RTP-based feedback and a 1084 value of 0/false indicates that the service provider does not 1085 support the RTP profile extension for RTP-based feedback. 1087 o *symmetricRTCP*: A leaf node indicating whether the SIP service 1088 provider expects the enterprise network to use symmetric RTCP as 1089 defined in [RFC4961]. This node is a Boolean type, a value of 1 1090 indicates that the service provider expects symmetric RTCP 1091 reports, whereas a value of 0 indicates that the enterprise can 1092 use asymmetric RTCP. 1094 o *dtmf*: A container that describes the various aspects of DTMF 1095 relay via RTP Named Telephony Events. The dtmf container allows 1096 SIP service providers to specify two facets of DTMF relay via 1097 Named Telephony Events: 1099 1. The payload type number using the payloadNumber leaf node. 1100 2. Support for [RFC2833] or [RFC4733] using the iteration leaf node. 1102 In the context of named telephony events, senders and receivers may 1103 negotiate asymmetric payload type numbers. For example, the sender 1104 might advertise payload type number 97 and the receiver might 1105 advertise payload type number 101. In such instances, it is either 1106 required for middleboxes to interwork payload type numbers or allow 1107 the endpoints to send and receive asymmetric payload numbers. The 1108 behaviour of middleboxes in this context is largely dependent on 1109 endpoint capabilities or on service provider constraints. Therefore, 1110 the payloadNumber leaf node can be used to determine middlebox 1111 configuration before-hand. 1113 [RFC4733]iterates over [RFC2833] by introducing certain changes in 1114 the way NTE events are transmitted. SIP service providers can 1115 indicate support for [RFC4733] by setting the iteration flag to 1 or 1116 indicating support for [RFC2833] by setting the iteration flag to 0. 1118 o *security*: A container that encapsulates characteristics about 1119 encrypting signalling streams between the enterprise and SIP 1120 service provider networks. 1122 o *signaling*: A container that encapsulates the type of security 1123 protocol for the SIP communication between the enterprise SBC and 1124 the service provider. 1126 o *type*: A leaf node that specifies the protocol used for 1127 protecting SIP signalling messages between the enterprise and 1128 service provider network. The value of the type leaf node is only 1129 defined for Transport Layer Security (TLS). Accordingly, if TLS 1130 is allowed for SIP sessions between the enterprise and service 1131 provider network, the type leaf node is set to the string "tls". 1133 o *version*: A leaf node that specifies the version(s) of TLS 1134 supported in decimal format. If multiple versions of TLS are 1135 supported, they MUST be separated by semi-colons. If the service 1136 provide does not support TLS for protecting SIP sessions, the 1137 signalling element is set to the string "NULL". 1139 o *mediaSecurity*: A container that describes the various 1140 characteristics of securing media streams between enterprise and 1141 service provider networks. 1143 o *keyManagement*: A leaf node that specifies the key management 1144 method used by the service provider. Possible values of this node 1145 include: "SDES" and "DTLS-SRTP". A value of "SDES" signifies that 1146 the SIP service provider uses the methods defined in [RFC4568] for 1147 the purpose of key management. A value of "DTLS-SRTP" signifies 1148 that the SIP service provider uses the methods defined in 1149 [RFC5764] for the purpose of key management. If the value of this 1150 leaf node is set to "DTLS-SRTP", the various versions of DTLS 1151 supported by the SIP service provider MUST be encoded as per the 1152 formatting rules of Section 9.2. If the service provider does not 1153 support media security, the keyManagement node MUST be set to 1154 "NULL". 1156 o *extensions*: A leaf node that is a semicolon separated list of 1157 all possible SIP option tags supported by the service provider 1158 network. These extensions MUST be referenced using name 1159 registered under IANA. If the service provider network does not 1160 support any extensions to baseline SIP, the extensions node MUST 1161 be set to "NULL". 1163 9.4. Extending the Capability Set 1165 There are situations in which equipment manufactures or service 1166 providers would benefit from extending the YANG module defined in 1167 this draft. For example, service providers could extend the YANG 1168 module to include information that further simplifies direct IP 1169 peering. Such information could include: trunk group identifiers, 1170 direct-inward-dial (DID) number ranges allocated to the enterprise, 1171 customer/enterprise account numbers, service provider support 1172 numbers, among others. 1174 Extension of the module can be achieved by importing the module 1175 defined in this draft. An example is provided below: 1177 Consider a new YANG module "vendorA" specified for VendorA's 1178 enterprise SBC. The "vendorA-config" YANG module is configured as 1179 follows: 1181 module vendorA-config { 1182 namespace "urn:ietf:params:xml:ns:yang:vendorA-config"; 1183 prefix "vendorA"; 1185 description 1186 "Data model for configuring VendorA Enterprise SBC"; 1188 revision 2020-05-06 { 1189 description "Initial revision of VendorA Enterprise SBC configuration data model"; 1190 } 1192 import ietf-peering { 1193 prefix "peering"; 1194 } 1196 augment "/peering:peering-info" { 1197 container vendorAConfig { 1198 leaf vendorAConfigParam1 { 1199 type int32; 1200 description "vendorA configuration parameter 1 (SBC Device ID)"; 1201 } 1203 leaf vendorAConfigParam2 { 1204 type string; 1205 description "vendorA configuration parameter 2 (SBC Device name)"; 1206 } 1207 description "Container for vendorA SBC configuration"; 1208 } 1209 } 1210 } 1212 In the example above, a custom module named "vendorA-config" uses the 1213 "augment" statement as defined in Section 4.2.8 of [RFC7950] to 1214 extend the module defined in this draft. 1216 10. Example Capability Set Document Encoding 1218 This section provides examples of how capability set documents that 1219 leverage the YANG module defined in this document can be encoded over 1220 JSON or XML. 1222 10.1. JSON Capability Set Document 1223 { 1224 "peering-info:variant": "1.0", 1225 "transport-info": { 1226 "transport": "TCP;TLS;UDP", 1227 "registrar": ["registrar1.voip.example.com:5060", "registrar2.voip.example.com:5060"], 1228 "registrarRealm": "voip.example.com", 1229 "callControl": ["callServer1.voip.example.com:5060", "192.168.12.25:5065"], 1230 "dns": [8.8.8.8, 208.67.222.222], 1231 "outboundProxy": "0.0.0.0" 1232 }, 1233 "call-specs": { 1234 "earlyMedia": "true", 1235 "signalingForking": "false", 1236 "supportedMethods": "INVITE;OPTIONS;BYE;CANCEL;ACK;PRACK;SUBSCRIBE;NOTIFY;REGISTER" 1237 }, 1238 "media": { 1239 "mediaTypeAudio": { 1240 "mediaFormat": ["PCMU;rate=8000;ptime=20","G729;rate=8000;annexb=yes","G722;rate=8000;bitrate=56k,64k"] 1241 }, 1242 "fax": { 1243 "protocol": ["pass-through", "t38"] 1244 }, 1245 "rtp": { 1246 "RTPTrigger": "false", 1247 "symmetricRTP": "true" 1248 }, 1249 "rtcp": { 1250 "symmetricRTCP": "true", 1251 "RTCPFeedback": "true" 1252 } 1253 }, 1254 "dtmf": { 1255 "payloadNumber": "101", 1256 "iteration": "0" 1257 }, 1258 "security": { 1259 "signaling": { 1260 "type": "TLS", 1261 "version": "1.0;1.2" 1262 }, 1263 "mediaSecurity": { 1264 "keyManagement": "SDES;DTLS-SRTP,version=1.2" 1265 } 1266 }, 1267 "extensions": "timer;rel100;gin;path" 1268 } 1270 10.2. XML Capability Set Document 1272 1275 1.0 1276 1277 TCP;TLS;UDP 1278 registrar1.voip.example.com:5060 1279 registrar2.voip.example.com:5060 1280 voip.example.com 1281 callServer1.voip.example.com:5060 1282 192.168.12.25:5065 1283 8.8.8.8 1284 208.67.222.222 1285 0.0.0.0 1286 1287 1288 true 1289 false 1290 INVITE;OPTIONS;BYE;CANCEL;ACK;PRACK;SUBSCRIBE;NOTIFY;REGISTER 1291 1292 1293 1294 PCMU;rate=8000;ptime=20 1295 G729;rate=8000;annexb=yes 1296 G722;rate=8000;bitrate=56k,64k 1297 1298 1299 pass-through 1300 t38 1301 1302 1303 true 1304 true 1305 1306 1307 true 1308 true 1309 1310 1311 1312 101 1313 0 1314 1315 1316 1317 TLS 1318 1.0;1.2 1319 1320 1321 SDES;DTLS-SRTP,version=1.2 1322 1323 1324 timer;rel100;gin;path 1325 1327 11. Example Exchange 1329 This section depicts an example of the configuration flow that 1330 ultimately results in the enterprise edge element obtaining the 1331 capability set document from the SIP service provider. 1333 Assuming the enterprise edge element isn't pre-configured with the 1334 request target for the capability set document and is required to 1335 authenticate with the SIP service provider capability server, the 1336 following sequence of events are put into motion to obtain the 1337 capability set document: 1339 The enterprise edge element generates a WebFinger query to discover 1340 endpoints hosted in the ssp1.example.com domain (line wraps are for 1341 display purposes only) 1343 GET /.well-known/webfinger? 1344 resource=http%3A%2F%2Fssp1.example.com 1345 &rel=http%3A%2f%2fsipserviceprovider%2fcapserver 1346 &rel=http%3A%2f%2fsipserviceprovider%2auth 1347 &rel= http%3A%2f%2fsipserviceprovider%2token 1348 HTTP/1.1 1349 Host: ssp1.example.com 1351 The resulting WebFinger response, contains the URLs of the capability 1352 server, the OAuth 2.0 authorization endpoint and OAuth 2.0 token 1353 endpoint. 1355 HTTP/1.1 200 OK 1356 Access-Control-Allow-Origin: * 1357 Content-Type: application/jrd+json 1358 { 1359 "subject" : "http://ssp1.example.com", 1360 "links" : 1361 [ 1362 { 1363 "rel" : "http://sipserviceprovider/capserver", 1364 "href" : "https://capserver.ssp1.com" 1365 }, 1366 { 1367 "rel" : "http://sipserviceprovider/auth", 1368 "href" : "https://ssp1.com/authorize" 1369 }, 1370 { 1371 "rel" : "http://sipserviceprovider/token", 1372 "href" : "https://ssp1.com/token" 1373 }, 1374 ] 1375 } 1377 The endpoint URLs returned in the WebFinger response are stored by the 1378 edge element and referenced when required. Then, the administrator logs 1379 into the GUI of the edge element and initiates the download of the 1380 service provider capability set (perhaps by clicking on a button). This 1381 triggers the edge element to redirect the administrator to the OAuth 2.0 1382 authorization endpoint (discovered via WebFinger). Once the 1383 administrator is authenticated and provides authorization, flow is 1384 redirected to the callback URL of the edge element application. The edge 1385 element then contacts the OAuth 2.0 token endpoint (discovered via 1386 WebFinger) to authenticate itself and obtain access and refresh tokens. 1387 Accordingly, the edge element mints a JWT bearer token to authenticate 1388 itself with the token endpoint and obtain an access and refresh token. 1389 Below is an example of client authentication using a JWT during the 1390 presentation of an authorization code grant for an access token request 1391 (line wraps are for display purposes only). 1393 POST /token HTTP/1.1 1394 Host: ssp1.com 1395 Content-Type: application/x-www-form-urlencoded 1397 grant_type=authorization_code& 1398 code=n0esc3NRze7LTCu7iYzS6a5acc3f0ogp4& 1399 client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3A 1400 client-assertion-type%3Ajwt-bearer& 1401 client_assertion=eyJhbGciOiJSUzI1NiIsImtpZCI6IjIyIn0. 1402 eyJpc3Mi[...omitted for brevity...]. 1403 cC4hiUPo[...omitted for brevity...] 1405 If the request is acceptable to the token endpoint, an access token and 1406 a refresh token is provided in the response. For example: 1408 HTTP/1.1 200 OK 1409 Content-Type: application/json;charset=UTF-8 1410 Cache-Control: no-store 1411 Pragma: no-cache 1413 { 1414 "access_token":"sF_9.B5f-4.1JqM", 1415 "token_type":"Bearer", 1416 "expires_in":86400, 1417 "refresh_token":"hGzv3JOkF0XG5Qx2TlKWIA" 1418 } 1420 The obtained bearer access token can subsequently be used to obtain the 1421 capability set document for the capability server. The edge element 1422 generates a HTTPS GET request with the bearer token included in the 1423 Authorization header field. 1425 GET //capdoc?trunkid=trunkent1456 HTTP/1.1 1426 Host: capserver.ssp1.com 1427 Authorization: Bearer mF_9.B5f-4.1JqM 1428 Accept:application/peering-info+xml 1430 The capability set document is obtained in the body of the response and 1431 is encoded in XML. 1433 HTTP/1.1 200 OK 1434 Content-Type: application/peering-info+xml 1435 Content-Length: nnn 1437 1438 ... 1439 1441 12. Security Considerations 1443 Capability set documents have a significant bearing on the quality of 1444 the peering relationship between an enterprise and service provider 1445 network. These documents can be modified by an attacker to 1446 drastically impact the quality of communication sessions between 1447 enterprise and service provider networks. Additionally, capability 1448 set documents contain parameters that may be considered sensitive 1449 from the perspective of the SIP service provider. For example, the 1450 YANG model defined in this document might be extended by SIP service 1451 providers to include account sensitive information such as the 1452 username and password to used when generating an MD5 response to 1453 401/407 SIP challenges. 1455 To ensure the problems discussed in the previous paragraph are 1456 accounted for, the following considerations MUST be taken into 1457 account: 1459 o Integrity and Confidentiality 1461 Request and responses for the capability set documents are defined 1462 over HTTP. However, due to the sensitive nature of information 1463 transmitted between client and server, it is required to secure HTTP 1464 using Transport Layer Security. The enterprise edge element and 1465 capability server MUST be compliant to [RFC7235]. The enterprise 1466 edge element and capability server MUST support the use of the https 1467 uri scheme as defined in [RFC7230]. 1469 o Authenticated Client Identity 1471 While this draft does not enforce client authentication, there are 1472 situations in which client need to authenticated by SIP service 1473 providers before they are provided capability set documents. In such 1474 situations client MUST be authenticated using the procedures outlined 1475 in section 6.3 of this draft. 1477 o The "trunkid" parameter 1478 It is RECOMMENDED that enterprise edge elements use the "trunkid" 1479 parameter in query strings when requesting for the capability set 1480 documents. The value of "trunkid" parameter is generated by the SIP 1481 service provider and provided to the administrator via some out-of- 1482 band mechanism. SIP service providers MUST ensure that value of the 1483 "trunkid" parameters does not inadvertently communicate sensitive 1484 information to an attacker such as a username or password credential. 1486 In addition to the considerations listed above, all the security 1487 considerations that are part of the WebFinger and OAuth 2.0 1488 specifications are applicable to this draft. 1490 13. Acknowledgments 1492 TBD 1494 14. References 1496 14.1. Normative References 1498 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1499 Requirement Levels", BCP 14, RFC 2119, 1500 DOI 10.17487/RFC2119, March 1997, 1501 . 1503 [RFC6020] Bjorklund, M., Ed., "YANG - A Data Modeling Language for 1504 the Network Configuration Protocol (NETCONF)", RFC 6020, 1505 DOI 10.17487/RFC6020, October 2010, 1506 . 1508 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 1509 RFC 6991, DOI 10.17487/RFC6991, July 2013, 1510 . 1512 14.2. Informative References 1514 [RFC2833] Schulzrinne, H. and S. Petrack, "RTP Payload for DTMF 1515 Digits, Telephony Tones and Telephony Signals", RFC 2833, 1516 DOI 10.17487/RFC2833, May 2000, 1517 . 1519 [RFC3762] Levin, O., "Telephone Number Mapping (ENUM) Service 1520 Registration for H.323", RFC 3762, DOI 10.17487/RFC3762, 1521 April 2004, . 1523 [RFC4568] Andreasen, F., Baugher, M., and D. Wing, "Session 1524 Description Protocol (SDP) Security Descriptions for Media 1525 Streams", RFC 4568, DOI 10.17487/RFC4568, July 2006, 1526 . 1528 [RFC4585] Ott, J., Wenger, S., Sato, N., Burmeister, C., and J. Rey, 1529 "Extended RTP Profile for Real-time Transport Control 1530 Protocol (RTCP)-Based Feedback (RTP/AVPF)", RFC 4585, 1531 DOI 10.17487/RFC4585, July 2006, 1532 . 1534 [RFC4733] Schulzrinne, H. and T. Taylor, "RTP Payload for DTMF 1535 Digits, Telephony Tones, and Telephony Signals", RFC 4733, 1536 DOI 10.17487/RFC4733, December 2006, 1537 . 1539 [RFC4855] Casner, S., "Media Type Registration of RTP Payload 1540 Formats", RFC 4855, DOI 10.17487/RFC4855, February 2007, 1541 . 1543 [RFC4961] Wing, D., "Symmetric RTP / RTP Control Protocol (RTCP)", 1544 BCP 131, RFC 4961, DOI 10.17487/RFC4961, July 2007, 1545 . 1547 [RFC5764] McGrew, D. and E. Rescorla, "Datagram Transport Layer 1548 Security (DTLS) Extension to Establish Keys for the Secure 1549 Real-time Transport Protocol (SRTP)", RFC 5764, 1550 DOI 10.17487/RFC5764, May 2010, 1551 . 1553 [RFC6241] Enns, R., Ed., Bjorklund, M., Ed., Schoenwaelder, J., Ed., 1554 and A. Bierman, Ed., "Network Configuration Protocol 1555 (NETCONF)", RFC 6241, DOI 10.17487/RFC6241, June 2011, 1556 . 1558 [RFC6665] Roach, A., "SIP-Specific Event Notification", RFC 6665, 1559 DOI 10.17487/RFC6665, July 2012, 1560 . 1562 [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization 1563 Framework: Bearer Token Usage", RFC 6750, 1564 DOI 10.17487/RFC6750, October 2012, 1565 . 1567 [RFC7033] Jones, P., Salgueiro, G., Jones, M., and J. Smarr, 1568 "WebFinger", RFC 7033, DOI 10.17487/RFC7033, September 1569 2013, . 1571 [RFC7230] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1572 Protocol (HTTP/1.1): Message Syntax and Routing", 1573 RFC 7230, DOI 10.17487/RFC7230, June 2014, 1574 . 1576 [RFC7231] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1577 Protocol (HTTP/1.1): Semantics and Content", RFC 7231, 1578 DOI 10.17487/RFC7231, June 2014, 1579 . 1581 [RFC7235] Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer 1582 Protocol (HTTP/1.1): Authentication", RFC 7235, 1583 DOI 10.17487/RFC7235, June 2014, 1584 . 1586 [RFC7565] Saint-Andre, P., "The 'acct' URI Scheme", RFC 7565, 1587 DOI 10.17487/RFC7565, May 2015, 1588 . 1590 [RFC7950] Bjorklund, M., Ed., "The YANG 1.1 Data Modeling Language", 1591 RFC 7950, DOI 10.17487/RFC7950, August 2016, 1592 . 1594 [RFC8340] Bjorklund, M. and L. Berger, Ed., "YANG Tree Diagrams", 1595 BCP 215, RFC 8340, DOI 10.17487/RFC8340, March 2018, 1596 . 1598 Authors' Addresses 1600 Kaustubh Inamdar 1601 Cisco Systems 1603 Email: kinamdar@cisco.com 1605 Sreekanth Narayanan 1606 Cisco Systems 1608 Email: sreenara@cisco.com 1610 Cullen Jennings 1611 Cisco Systems 1613 Email: fluffy@iii.ca