idnits 2.17.1 draft-holmberg-dispatch-received-realm-09.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 (November 23, 2016) is 2710 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) == Unused Reference: 'RFC2104' is defined on line 591, but no explicit reference was found in the text Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 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: May 27, 2017 China Mobile 6 November 23, 2016 8 Session Initiation Protocol (SIP) Via header field parameter to indicate 9 received realm 10 draft-holmberg-dispatch-received-realm-09.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 May 27, 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 . . . . . . . . . . . . . . . . . 13 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 not attached to 209 the serialized JWS conveyed in the header field parameter, as 210 described in Appendix F of [RFC7515]. The operator identifier and 211 the 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 = *base64-char 328 signature = *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 operator MUST change the key on a frequent basis. The operator 467 also needs to take great care in ensuring that the key used to 468 calculate the JWS signature value is only known by the network entry 469 point adding the received-realm Via header field parameter to a SIP 470 message and the entities that use the parameter value. 472 A SIP entity MUST NOT use the adjacent network information if there 473 is a mismatch between the JWS signature received in the SIP header 474 field and the JWS signature calculated by the receiving entity. 476 A SIP entity MUST use different key values for each parameter value 477 that it recognizes and use to trigger actions. 479 Generic security considerations for JWS are defined in [RFC7515]. 481 10. Acknowledgments 483 Thanks to Adam Roach and Richard Barnes for providing comments and 484 feedback on the document. Francis Dupoint performed the Gen-ART 485 review. 487 11. Change Log 489 [RFC EDITOR NOTE: Please remove this section when publishing] 491 Changes from draft-holmberg-dispatch-received-realm-08 493 o Editorial fixed based on Gen-ART review. 495 o Editorial fixes based on comments from IANA Service Operator 496 review. 498 o - Quotes removed from sip_date value. 500 Changes from draft-holmberg-dispatch-received-realm-07 502 o Editorial changes. 504 Changes from draft-holmberg-dispatch-received-realm-06 505 o Changes based on AD review by Ben Campbell: 507 o - operator-id added to JSON Payload 509 Changes from draft-holmberg-dispatch-received-realm-05 511 o Editorial fixes. 513 Changes from draft-holmberg-dispatch-received-realm-04 515 o JSON serialization procedure added. 517 Changes from draft-holmberg-dispatch-received-realm-03 519 o ABNF correction. 521 Changes from draft-holmberg-dispatch-received-realm-02 523 o JWT replaced with JWS. 525 o Appendix F of RFC 7515 applied. 527 Changes from draft-holmberg-dispatch-received-realm-01 529 o Define received-realm parameter value as a JSON Web Token (JWT). 531 Changes from draft-holmberg-dispatch-received-realm-00 533 o New version due to expiration of previous version. 535 Changes from draft-holmberg-received-realm-04 537 o Changed IETF WG from sipcore do dispatch. 539 o HMAC value added to the parameter. 541 Changes from draft-holmberg-received-realm-03 543 o New version due to expiration. 545 Changes from draft-holmberg-received-realm-02 547 o New version due to expiration. 549 Changes from draft-holmberg-received-realm-01 551 o New version due to expiration. 553 Changes from draft-holmberg-received-realm-00 555 o New version due to expiration. 557 12. References 559 12.1. Normative References 561 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 562 Requirement Levels", BCP 14, RFC 2119, 563 DOI 10.17487/RFC2119, March 1997, 564 . 566 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 567 A., Peterson, J., Sparks, R., Handley, M., and E. 568 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 569 DOI 10.17487/RFC3261, June 2002, 570 . 572 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 573 Specifications: ABNF", STD 68, RFC 5234, 574 DOI 10.17487/RFC5234, January 2008, 575 . 577 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 578 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 579 2015, . 581 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 582 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 583 . 585 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 586 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 587 2015, . 589 12.2. Informative References 591 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 592 Hashing for Message Authentication", RFC 2104, 593 DOI 10.17487/RFC2104, February 1997, 594 . 596 [RFC3968] Camarillo, G., "The Internet Assigned Number Authority 597 (IANA) Header Field Parameter Registry for the Session 598 Initiation Protocol (SIP)", BCP 98, RFC 3968, 599 DOI 10.17487/RFC3968, December 2004, 600 . 602 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 603 DOI 10.17487/RFC7518, May 2015, 604 . 606 [TS.3GPP.23.228] 607 3GPP, "IP Multimedia Subsystem (IMS); Stage 2", 3GPP 608 TS 23.228 14.1.0, September 2016. 610 Authors' Addresses 612 Christer Holmberg 613 Ericsson 614 Hirsalantie 11 615 Jorvas 02420 616 Finland 618 Email: christer.holmberg@ericsson.com 620 Yi Jiang 621 China Mobile 622 No.32 Xuanwumen West Street 623 Beijing Xicheng District 100053 624 P.R. China 626 Email: jiangyi@chinamobile.com