idnits 2.17.1 draft-holmberg-dispatch-received-realm-12.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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 3, 2016) is 2693 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SIPCORE Working Group C. Holmberg 3 Internet-Draft Ericsson 4 Intended status: Standards Track J. Jiang 5 Expires: June 6, 2017 China Mobile 6 December 3, 2016 8 Session Initiation Protocol (SIP) Via header field parameter to indicate 9 received realm 10 draft-holmberg-dispatch-received-realm-12.txt 12 Abstract 14 This specification defines a new Session Initiation Protocol (SIP) 15 Via header field parameter, "received-realm", which allows a SIP 16 entity acting as an entry point to a transit network to indicate from 17 which adjacent upstream network a SIP request is received, using a 18 network realm value associated with the adjacent network. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at http://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on June 6, 2017. 37 Copyright Notice 39 Copyright (c) 2016 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (http://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 2 56 1.2. Use-Case: Transit Network Application Services . . . . . 3 57 1.3. Use-Case: Transit Network Routing . . . . . . . . . . . . 3 58 2. Applicability . . . . . . . . . . . . . . . . . . . . . . . . 4 59 3. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 61 5. Via 'received-realm' header field parameter . . . . . . . . . 5 62 5.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 5.2. Operator Identifier . . . . . . . . . . . . . . . . . . . 5 64 5.3. JWS Header . . . . . . . . . . . . . . . . . . . . . . . 5 65 5.4. JWS Payload . . . . . . . . . . . . . . . . . . . . . . . 6 66 5.5. JWS Serialization . . . . . . . . . . . . . . . . . . . . 7 67 5.6. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 7 68 5.6.1. General . . . . . . . . . . . . . . . . . . . . . . . 7 69 5.6.2. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 7 70 5.7. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 71 6. User Agent and Proxy behavior . . . . . . . . . . . . . . . . 8 72 6.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 8 73 6.2. Behavior of a SIP entity acting as a network entry point 8 74 6.3. Behavior of a SIP entity consuming the received-network 75 value . . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 78 8.1. 'received-realm' Via header field parameter . . . . . . . 9 79 8.2. JSON Web Token Claims Registration . . . . . . . . . . . 10 80 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 81 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 11 82 11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 11 83 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 13 84 12.1. Normative References . . . . . . . . . . . . . . . . . . 13 85 12.2. Informative References . . . . . . . . . . . . . . . . . 14 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 88 1. Introduction 90 1.1. General 92 When Session Initiation Protocol (SIP) [RFC3261] sessions are 93 established between networks belonging to different operators, or 94 between interconnected networks belonging to the same operator (or 95 enterprise), the SIP requests associated with the session might 96 traverse transit networks. 98 Such transit networks might provide different kinds of services. In 99 order to provide such services, a transit network often needs to know 100 to which operator (or enterprise) the adjacent upstream network from 101 which the SIP session initiation request is received belongs. 103 This specification defines a new Session Initiation Protocol (SIP) 104 Via header field parameter, "received-realm", which allows a SIP 105 entity acting as an entry point to a transit network to indicate from 106 which adjacent upstream network a SIP request is received, using a 107 network realm value associated with the adjacent network. 109 NOTE: As the adjacent network can be an enterprise network, an Inter 110 Operator Identifier (IOI) cannot be used to identity the network, as 111 IOIs are not defined for enterprise networks. 113 The following sections describe use-cases where the information is 114 needed. 116 1.2. Use-Case: Transit Network Application Services 118 The 3rd Generation Partnership Project (3GPP) TS 23.228 119 [TS.3GPP.23.228] specifies how an IP Multimedia Subsystem (IMS) 120 network can be used to provide transit functionality. An operator 121 can use its IMS network to provide transit functionality e.g., to 122 non-IMS customers, to enterprise networks, and to other network 123 operators. 125 The transit network operator can provide application services to the 126 networks for which it is providing transit functionality. Transit 127 application services are typically not provided on a per user basis, 128 as the transit network does not have access to the user profiles of 129 the networks for which the application services are provided. 130 Instead, the application services are provided per served network. 132 When a SIP entity that provides application services (e.g., an 133 Application Server) within a transit network receives a SIP request, 134 in order to apply the correct services, it needs to know the adjacent 135 upstream network from which the SIP request is received. 137 1.3. Use-Case: Transit Network Routing 139 A transit network operator normally interconnects to many different 140 operators, including other transit network operators, and provides 141 transit routing of SIP requests received from one operator network 142 towards the destination. The destination can be within an operator 143 network to which the transit network operator has a direct 144 interconnect, or within an operator network that only can be reached 145 via one or more interconnected transit operators. 147 For each customer, i.e., interconnected network operator, for which 148 the transit network operator routes SIP requests towards the 149 requested destination, a set of transit routing polices are defined. 150 These policies are used to determine how a SIP request shall be 151 routed towards the requested destination to meet the agreement the 152 transit network operator has with its customer. 154 When a SIP entity that performs the transit routing functionality 155 receives a SIP request, in order to apply the correct set of transit 156 routing policies, it needs to know from which of its customers, i.e., 157 adjacent upstream network, the SIP request is received. 159 2. Applicability 161 The mechanism defined in this specification MUST only be used by SIP 162 entities that are able to verify from which adjacent upstream network 163 a SIP request is received. 165 The mechanism for verifying from which adjacent upstream network a 166 SIP request is received is outside the scope of this specification. 167 Such mechanism might be based for instance on receiving the SIP 168 request on an authenticated Virtual Private Network (VPN), receiving 169 the SIP request on a specific IP address, or on a specific network 170 access. 172 3. Conventions 174 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 175 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 176 document are to be interpreted as described in BCP 14, RFC 2119 177 [RFC2119]. 179 4. Definitions 181 SIP entity: SIP User Agent (UA), or SIP proxy, as defined in RFC 182 3261. 184 Adjacent upstream SIP network: The adjacent SIP network in the 185 direction from which a SIP request is received. 187 Network entry point: A SIP entity on the border of network, which 188 receives SIP requests from adjacent upstream networks. 190 Inter Operator Identifier (IOI): A globally unique identifier to 191 correlate billing information generated within the IP Multimedia 192 Subsystem (IMS). 194 JWS: JSON Web Signature, as defined in [RFC7515]. 196 5. Via 'received-realm' header field parameter 198 5.1. General 200 The Via 'received-realm' header field parameter value is represented 201 as a combination of an operator identifier, whose value represents 202 the adjacent network, and a serialized JSON Web Signature (JWS) 203 [RFC7515]. The JWS Payload consists of the operator identifier and 204 other SIP information element values. 206 The procedures for encoding the JWS and calculating the signature are 207 defined in [RFC7515]. As the JWS Payload information is found in 208 other SIP information elements, the JWS Payload is detached from the 209 serialized JWS conveyed in the header field parameter, as described 210 in Appendix F of [RFC7515]. The operator identifier and the 211 serialized JWS are separated using a colon character. 213 5.2. Operator Identifier 215 The Operator Identifier is a token value that represents the adjacent 216 operator. The scope of the value is only within the network that 217 inserts the value. 219 The Operator Identifier value is case-insensitive. 221 5.3. JWS Header 223 The following header parameters MUST be included in the JWS. 225 o The "typ" parameter MUST have a "JWT" value. 227 o The "alg" parameter MUST have the value of the algorithm used to 228 calculate the JWS. 230 NOTE: Operators need to agree on the set of supported algorithms for 231 calculating the JWT signature. 233 NOTE: The "alg" parameter values for specific algorithms are listed 234 in the IANA JSON Web Signature and Encryption Algorithms sub-registry 235 of the JSON Object Signing and Encryption (JOSE) registry. Operators 236 need to use algorithms for which an associated "alg" parameter value 237 has been registered. The procedures for defining new values are 238 defined in [RFC7518]. 240 Example: 242 { 243 "typ":"JWT", 244 "alg":"HS256" 245 } 247 5.4. JWS Payload 249 The following claims MUST be included in the JWS Payload: 251 o The "sip_from_tag" claim has the value of the From 'tag' header 252 field parameter of the SIP message. 254 o The "sip_date" claim has the value of the Date header field in the 255 SIP message, encoded in JSON NumericDate format [RFC7519]. 257 o The "sip_callid" claim has have value of the Call-ID header field 258 in the SIP message. 260 o The "sip_cseq_num" claim has the numeric value of the CSeq header 261 field in the SIP message. 263 o the "sip_via_branch" claim has value of the Via branch header 264 field parameter of the Via header field, in the SIP message, to 265 which the received-realm header field parameter is attached. 267 o the "sip_via_opid" claim has value of the operator identifier part 268 of the Via received-realm header field parameter of the Via header 269 field, in the SIP message, to which the received-realm header 270 field parameter is attached. 272 Example: 274 { 275 "sip_from_tag":"1928301774", 276 "sip_date":1472815523, 277 "sip_callid":"a84b4c76e66710@pc33.atlanta.com", 278 "sip_cseq_num":"314159", 279 "sip_via_branch":"z9hG4bK776asdhds", 280 "sip_via_opid":"myoperator" 281 } 283 5.5. JWS Serialization 285 As the JWS Payload is not carried in the received-realm parameter, in 286 order to make sure that the sender and the receiver construct the JWS 287 Payload object in the same way, the JSON representation of the JWS 288 Payload object it MUST be computed as follows: 290 o All claims MUST be encoded using lower case characters. 292 o The claims MUST be in the same order as listed in [Section 5.4]. 294 o All claims except "sip_date" MUST be encoded as StringOrURI JSON 295 string value [RFC7519]. 297 o The "sip_date" claim MUST be encoded as a JSON NumericDate value 298 [RFC7519]. 300 o The JWS Payload MUST follow the rules for the construction of the 301 thumbprint of a JSON Web Key (JWK) as defined in [RFC7638] 302 Section 3 Step 1 only. 304 Example: 306 NOTE: Line breaks for display purpose only 308 {"sip_from_tag":"1928301774","sip_date":1472815523, 309 "sip_callid":"a84b4c76e66710@pc33.atlanta.com","sip_cseq_num":"314159", 310 "sip_via_branch":"z9hG4bK776asdhds","sip_via_opid":"myoperator"} 312 5.6. Syntax 314 5.6.1. General 316 This section describes the syntax extensions to the ABNF syntax 317 defined in [RFC3261], by defining a new Via header field parameter, 318 "received-realm". The ABNF defined in this specification is 319 conformant to RFC 5234 [RFC5234]. "EQUAL", "LDQUOT", "RDQUOT" and 320 "ALPHA" are defined in [RFC3261]. "DIGIT" is defined in [RFC5234]. 322 5.6.2. ABNF 323 via-params =/ received-realm 324 received-realm = "received-realm" EQUAL LDQUOT op-id COLON jws RDQUOT 325 op-id = token 326 jws = header ".." signature 327 header = 1*base64-char 328 signature = 1*base64-char 329 base64-char = ALPHA / DIGIT / "/" / "+" 331 EQUAL, COLON, token, LDQUOT, RDQUOT, ALPHA and DIGIT 332 as defined in [RFC3261]. 334 NOTE: The two adjacent dots in the jws part is due to the detached 335 payload being replaced by an empty string [RFC7515]. 337 5.7. Example 339 Via: SIP/2.0/UDP pc33.example.com;branch=z9hG4bK776; 340 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1N.. 341 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" 343 NOTE: Line breaks for display purpose only 345 6. User Agent and Proxy behavior 347 6.1. General 349 This section describes how a SIP entity, acting as an entry point to 350 a network, uses the "received-realm" Via header field parameter. 352 6.2. Behavior of a SIP entity acting as a network entry point 354 When a SIP entity, acting as a network entry point, forwards a SIP 355 request, or initiates a SIP request on its own (e.g., a PSTN 356 gateway), the SIP entity adds a Via header field to the SIP request, 357 according to the procedures in RFC 3261 [RFC3261]. In addition, if 358 the SIP entity is able to assert the adjacent upstream network, and 359 if the SIP entity is aware of a network realm value defined for that 360 network, the SIP entity can add a "received-realm" Via header field 361 parameter, conveying the network realm value as the operator 362 identifier (Section 5.2) part of the header field parameter, to the 363 Via header field added to the SIP request. 365 In addition the SIP entity MUST also calculate a JWS (Section 5.4) 366 and add the calculated JWS Header and JWS Signature as the jws part 367 of the Via header field parameter. 369 6.3. Behavior of a SIP entity consuming the received-network value 371 When a SIP entity receives a Via 'received-network' header field 372 parameter, and intends to perform actions based on the header field 373 parameter value, it MUST first re-calculate the JWS and check whether 374 the result matches the JWS received. If there is not a match, the 375 SIP entity MUST discard the received 'received-network' header field 376 parameter. The SIP entity MAY take also take additional actions 377 (e.g., rejecting the SIP request) based on local policy. 379 7. Example 381 Operator 1 T_EP T_AS 383 - INVITE ------> 384 Via: SIP/2.0/UDP IP_UA 385 -- INVITE ----------------------------> 386 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 387 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJh 388 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 389 1gFWFOEjXk" 390 Via: SIP/2.0/UDP IP_UA; received=IP_UA 392 <- 200 OK ---------------------------- 393 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 394 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJh 395 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 396 1gFWFOEjXk" 397 Via: SIP/2.0/UDP IP_UA; received=IP_UA 399 <- 200 OK------ 400 Via: SIP/2.0/UDP IP_UA; received=IP_UA 402 8. IANA Considerations 404 8.1. 'received-realm' Via header field parameter 406 This specification defines a new Via header field parameter called 407 received-realm in the "Header Field Parameters and Parameter Values" 408 sub-registry as per the registry created by [RFC3968]. The syntax is 409 defined in Section 5.6. The required information is: 411 Predefined 412 Header Field Parameter Name Values Reference 413 ---------------------- --------------------- ---------- --------- 414 Via received-realm No RFCXXXX 416 8.2. JSON Web Token Claims Registration 418 This specification defines new JSON Web Token claims in the "JSON Web 419 Token Claims" sub-registry as per the registry created by [RFC7519]. 421 Claim Name: "sip_from_tag" 423 Claim : SIP From tag header field parameter value 425 Change Controller: IESG 427 Specification Document(s): RFC XXXX, RFC 3261 429 Claim Name: "sip_date" 431 Claim Description: SIP Date header field value 433 Change Controller: IESG 435 Specification Document(s): RFC XXXX, RFC 3261 437 Claim Name: "sip_callid" 439 Claim Description: SIP Call-Id header field value 441 Change Controller: IESG 443 Specification Document(s): RFC XXXX, RFC 3261 445 Claim Name: "sip_cseq_num" 447 Claim Description: SIP CSeq numeric header field parameter value 449 Change Controller: IESG 451 Specification Document(s): RFC XXXX, RFC 3261 453 Claim Name: "sip_via_branch" 455 Claim Description: SIP Via branch header field parameter value 457 Change Controller: IESG 458 Specification Document(s): RFC XXXX, RFC 3261 460 9. Security Considerations 462 As the received-realm Via header field parameter can be used to 463 trigger applications, it is important to ensure that the parameter 464 has not been added to the SIP message by an unauthorized SIP entity. 466 The received-realm Via header field parameter is inserted, signed, 467 verified and consumed within an operator network. The operator MUST 468 discard parameters received from another network, and the parameter 469 MUST only be inserted by SIP entities that are able to verify from 470 which adjacent upstream network a SIP request is received. 472 The operator also needs to take great care in ensuring that the key 473 used to calculate the JWS signature value is only known by the 474 network entities signing and adding the JWS signature to the 475 received-realm Via header field parameter of a SIP message, and to 476 network entities verifying and consuming the parameter value. 478 The operator MUST use a key management policy that protects agains 479 unauthorised access to the stored keys within nodes where they keys 480 associated with the JWS signature are stored, and that protects 481 against crypto analysis attacks using captured data sent on the wire. 483 A SIP entity MUST NOT use the adjacent network information if there 484 is a mismatch between the JWS signature received in the SIP header 485 field and the JWS signature calculated by the receiving entity. 487 Generic security considerations for JWS are defined in [RFC7515]. 489 10. Acknowledgments 491 Thanks to Adam Roach and Richard Barnes for providing comments and 492 feedback on the document. Francis Dupoint performed the Gen-ART 493 review. 495 11. Change Log 497 [RFC EDITOR NOTE: Please remove this section when publishing] 499 Changes from draft-holmberg-dispatch-received-realm-11 501 o Editorial change based on IESG review. 503 Changes from draft-holmberg-dispatch-received-realm-10 505 o Changes based on IESG review. 507 o Changes based on SecDIR review. 509 o Changes based on IANA Service Operator review. 511 Changes from draft-holmberg-dispatch-received-realm-09 513 o Reference to RFC 2104 removed. 515 Changes from draft-holmberg-dispatch-received-realm-08 517 o Editorial fixed based on Gen-ART review. 519 o Editorial fixes based on comments from IANA Service Operator 520 review. 522 o - Quotes removed from sip_date value. 524 Changes from draft-holmberg-dispatch-received-realm-07 526 o Editorial changes. 528 Changes from draft-holmberg-dispatch-received-realm-06 530 o Changes based on AD review by Ben Campbell: 532 o - operator-id added to JSON Payload 534 Changes from draft-holmberg-dispatch-received-realm-05 536 o Editorial fixes. 538 Changes from draft-holmberg-dispatch-received-realm-04 540 o JSON serialization procedure added. 542 Changes from draft-holmberg-dispatch-received-realm-03 544 o ABNF correction. 546 Changes from draft-holmberg-dispatch-received-realm-02 548 o JWT replaced with JWS. 550 o Appendix F of RFC 7515 applied. 552 Changes from draft-holmberg-dispatch-received-realm-01 554 o Define received-realm parameter value as a JSON Web Token (JWT). 556 Changes from draft-holmberg-dispatch-received-realm-00 558 o New version due to expiration of previous version. 560 Changes from draft-holmberg-received-realm-04 562 o Changed IETF WG from sipcore do dispatch. 564 o HMAC value added to the parameter. 566 Changes from draft-holmberg-received-realm-03 568 o New version due to expiration. 570 Changes from draft-holmberg-received-realm-02 572 o New version due to expiration. 574 Changes from draft-holmberg-received-realm-01 576 o New version due to expiration. 578 Changes from draft-holmberg-received-realm-00 580 o New version due to expiration. 582 12. References 584 12.1. Normative References 586 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 587 Requirement Levels", BCP 14, RFC 2119, 588 DOI 10.17487/RFC2119, March 1997, 589 . 591 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 592 A., Peterson, J., Sparks, R., Handley, M., and E. 593 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 594 DOI 10.17487/RFC3261, June 2002, 595 . 597 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 598 Specifications: ABNF", STD 68, RFC 5234, 599 DOI 10.17487/RFC5234, January 2008, 600 . 602 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 603 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 604 2015, . 606 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 607 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 608 . 610 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 611 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 612 2015, . 614 12.2. Informative References 616 [RFC3968] Camarillo, G., "The Internet Assigned Number Authority 617 (IANA) Header Field Parameter Registry for the Session 618 Initiation Protocol (SIP)", BCP 98, RFC 3968, 619 DOI 10.17487/RFC3968, December 2004, 620 . 622 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 623 DOI 10.17487/RFC7518, May 2015, 624 . 626 [TS.3GPP.23.228] 627 3GPP, "IP Multimedia Subsystem (IMS); Stage 2", 3GPP 628 TS 23.228 14.1.0, September 2016. 630 Authors' Addresses 632 Christer Holmberg 633 Ericsson 634 Hirsalantie 11 635 Jorvas 02420 636 Finland 638 Email: christer.holmberg@ericsson.com 640 Yi Jiang 641 China Mobile 642 No.32 Xuanwumen West Street 643 Beijing Xicheng District 100053 644 P.R. China 646 Email: jiangyi@chinamobile.com