idnits 2.17.1 draft-holmberg-dispatch-received-realm-08.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 (October 26, 2016) is 2738 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 578, 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: April 29, 2017 China Mobile 6 October 26, 2016 8 Via header field parameter to indicate received realm 9 draft-holmberg-dispatch-received-realm-08.txt 11 Abstract 13 This specification defines a new Session Initiation Protocol (SIP) 14 Via header field parameter, "received-realm", which allows a SIP 15 entity acting as an entry point to a transit network to indicate from 16 which adjacent upstream network a SIP request is received, using a 17 network realm value associated with the adjacent network. 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at http://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on April 29, 2017. 36 Copyright Notice 38 Copyright (c) 2016 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents 43 (http://trustee.ietf.org/license-info) in effect on the date of 44 publication of this document. Please review these documents 45 carefully, as they describe your rights and restrictions with respect 46 to this document. Code Components extracted from this document must 47 include Simplified BSD License text as described in Section 4.e of 48 the Trust Legal Provisions and are provided without warranty as 49 described in the Simplified BSD License. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 54 1.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 2 55 1.2. Use-Case: Transit Network Application Services . . . . . 3 56 1.3. Use-Case: Transit Network Routing . . . . . . . . . . . . 3 57 2. Applicability . . . . . . . . . . . . . . . . . . . . . . . . 4 58 3. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 59 4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 5. Via 'received-realm' header field parameter . . . . . . . . . 5 61 5.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 5.2. Operator Identifier . . . . . . . . . . . . . . . . . . . 5 63 5.3. JWS Header . . . . . . . . . . . . . . . . . . . . . . . 5 64 5.4. JWS Payload . . . . . . . . . . . . . . . . . . . . . . . 6 65 5.5. JWS Serialization . . . . . . . . . . . . . . . . . . . . 7 66 5.6. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 5.6.1. General . . . . . . . . . . . . . . . . . . . . . . . 7 68 5.6.2. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 7 69 5.7. Example . . . . . . . . . . . . . . . . . . . . . . . . . 8 70 6. User Agent and Proxy behavior . . . . . . . . . . . . . . . . 8 71 6.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 8 72 6.2. Behavior of a SIP entity acting as a network entry point 8 73 6.3. Behavior of a SIP entity consuming the received-network 74 value . . . . . . . . . . . . . . . . . . . . . . . . . . 9 75 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 76 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 77 8.1. 'received-realm' Via header field parameter . . . . . . . 9 78 8.2. JSON Web Token Claims Registration . . . . . . . . . . . 10 79 9. Security Considerations . . . . . . . . . . . . . . . . . . . 11 80 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 11 81 11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 11 82 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 12 83 12.1. Normative References . . . . . . . . . . . . . . . . . . 13 84 12.2. Informative References . . . . . . . . . . . . . . . . . 13 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 14 87 1. Introduction 89 1.1. General 91 When SIP sessions are established between networks belonging to 92 different operators, or between interconnected networks belonging to 93 the same operator (or enterprise), the SIP requests might traverse 94 transit network. 96 Such transit networks might provide different kinds of services. In 97 order to do that, a transit network often needs to know to which 98 operator (or enterprise) the adjacent upstream network, from which 99 the SIP session initiation request is received, belongs. 101 This specification defines a new Session Initiation Protocol (SIP) 102 Via header field parameter, "received-realm", which allows a SIP 103 entity acting as an entry point to a transit network to indicate from 104 which adjacent upstream network a SIP request is received, using a 105 network realm value associated with the adjacent network. 107 NOTE: As the adjacent network can be an enterprise network, an Inter 108 Operator Identifier (IOI) cannot be used to identity the network, as 109 IOIs are not defined for enterprise networks. 111 The following sections describe use-cases where the information is 112 needed. 114 1.2. Use-Case: Transit Network Application Services 116 The 3rd Generation Partnership Project (3GPP) TS 23.228 117 [TS.3GPP.23.228] specifies how an IP Multimedia Subsystem (IMS) 118 network can be used to provide transit functionality. An operator 119 can use its IMS network to provide transit functionality e.g. to non- 120 IMS customers, to enterprise networks, and to other network 121 operators. 123 The transit network operator can provide application services to the 124 networks for which it is providing transit functionality. Transit 125 application services are typically not provided on a per user basis, 126 as the transit network does not have access to the user profiles of 127 the networks for which the application services are provided. 128 Instead, the application services are provided per served network. 130 When a SIP entity that provides application services (e.g. an 131 Application Server) within a transit network receives a SIP request, 132 in order to apply the correct services, it needs to know the adjacent 133 upstream network from which the SIP request is received. 135 1.3. Use-Case: Transit Network Routing 137 A transit network operator normally interconnects to many different 138 operators, including other transit network operators, and provides 139 transit routing of SIP requests received from one operator network 140 towards the destination. The destination can be within an operator 141 network to which the transit network operator has a direct 142 interconnect, or within an operator network that only can be reached 143 via one or more interconnected transit operators. 145 For each customer, i.e., interconnected network operator, for which 146 the transit network operator routes SIP requests towards the 147 requested destination, a set of transit routing polices are defined. 148 These policies are used to determine how a SIP request shall be 149 routed towards the requested destination to meet the agreement the 150 transit network operator has with its customer. 152 When a SIP entity that performs the transit routing functionality 153 receives a SIP request, in order to apply the correct set of transit 154 routing policies, it needs to know from which of its customers, i.e. 155 adjacent upstream network, the SIP request is received. 157 2. Applicability 159 The mechanism defined in this specification MUST only be used by SIP 160 entities that are able to verify from which adjacent upstream network 161 a SIP request is received. 163 The mechanism for verifying from which adjacent upstream network a 164 SIP request is received is outside the scope of this specification. 165 Such mechanism might be based e.g., on receiving the SIP request on 166 an authenticated Virtual Private Network (VPN), receiving the SIP 167 request on a specific IP address, or on a specific network access. 169 3. Conventions 171 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 172 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 173 document are to be interpreted as described in BCP 14, RFC 2119 174 [RFC2119]. 176 4. Definitions 178 SIP entity: SIP User Agent (UA), or SIP proxy, as defined in RFC 179 3261. 181 Adjacent upstream SIP network: The adjacent SIP network in the 182 direction from which a SIP request is received. 184 Network entry point: A SIP entity on the border of network, which 185 receives SIP requests from adjacent upstream networks. 187 Inter Operator Identifier (IOI): A globally unique identifier to 188 correlate billing information generated within the IP Multimedia 189 Subsystem (IMS). 191 JWS: JSON Web Signature, as defined in [RFC7515]. 193 5. Via 'received-realm' header field parameter 195 5.1. General 197 The Via 'received-realm' header field parameter value is represented 198 as a combination of an operator identifier, whose value represents 199 the adjacent network, and a serialized JSON Web Signature (JWS) 200 [RFC7515]. The JWS Payload consists of the operator identifier and 201 other SIP information element values. 203 The procedures for encoding the JWS and calculating the signature are 204 defined in [RFC7515]. As the JWS Payload information is found in 205 other SIP information elements, the JWS Payload is not attached to 206 the serialized JWS conveyed in the header field parameter, as 207 described in Appendix F of [RFC7515]. The operator identifier and 208 the serialized JWS are separated using a colon character. 210 5.2. Operator Identifier 212 The Operator Identifier is a token value that represents the adjacent 213 operator. The scope of the value is only within the network that 214 inserts the value. 216 The Operator Identifier value is case-insensitive. 218 5.3. JWS Header 220 The following header parameters MUST be included in the JWS. 222 o The "typ" parameter MUST have a "JWT" value. 224 o The "alg" parameter MUST have the value of the algorithm used to 225 calculate the JWS. 227 NOTE: Operators need to agree on the set of supported algorithms for 228 calculating the JWT signature. 230 NOTE: The "alg" parameter values for specific algorithms are listed 231 in the IANA JSON Web Signature and Encryption Algorithms sub-registry 232 of the JSON Object Signing and Encryption (JOSE) registry. Operators 233 need to use algorithms for which an associated "alg" parameter value 234 has been registered. The proceudres for defining new values are 235 defined in [RFC7518]. 237 Example: 239 { 240 "typ":"JWT", 241 "alg":"HS256" 242 } 244 5.4. JWS Payload 246 The following claims MUST be included in the JWS Payload: 248 o The "sip_from_tag" claim has the value of the From 'tag' header 249 field parameter of the SIP message. 251 o The "sip_date" claim has the value of the Date header field in the 252 SIP message, quoted and encoded in JSON NumericDate format 253 [RFC7519]. 255 o The "sip_callid" claim has have value of the Call-ID header field 256 in the SIP message. 258 o The "sip_cseq_num" claim has the numeric value of the CSeq header 259 field in the SIP message. 261 o the "sip_via_branch" claim has value of the Via branch header 262 field parameter of the Via header field, in the SIP message, to 263 which the received-realm header field parameter is attached. 265 o the "sip_via_opid" claim has value of the operator identifier part 266 of the Via received-realm header field parameter of the Via header 267 field, in the SIP message, to which the received-realm header 268 field parameter is attached. 270 Example: 272 { 273 "sip_from_tag":"1928301774", 274 "sip_date":"1472815523", 275 "sip_callid":"a84b4c76e66710@pc33.atlanta.com", 276 "sip_cseq_num":"314159", 277 "sip_via_branch":"z9hG4bK776asdhds", 278 "sip_via_opid":"myoperator" 279 } 281 5.5. JWS Serialization 283 As the JWS Payload is not carried in the received-realm parameter, in 284 order to make sure that the sender and the receiver construct the JWS 285 Payload object in the same way, the JSON representation of the JWS 286 Payload object it MUST be computed as follows: 288 o All claims MUST be encoded using lower case characters. 290 o The claims MUST be in the same order as listed in [Section 5.4]. 292 o All claims except "sip_date" MUST be encoded as StringOrURI JSON 293 string value [RFC7519]. 295 o The "sip_date" claim MUST be encoded as a JSON NumericDate value 296 [RFC7519]. 298 o The JWS Payload MUST follow the rules for the construction of the 299 thumbprint of a JSON Web Key (JWK) as defined in [RFC7638] 300 Section 3 Step 1 only. 302 Example: 304 NOTE: Line breaks for display purpose only 306 {"sip_from_tag":"1928301774","sip_date":"1472815523", 307 "sip_callid":"a84b4c76e66710@pc33.atlanta.com","sip_cseq_num":"314159", 308 "sip_via_branch":"z9hG4bK776asdhds","sip_via_opid":"myoperator"} 310 5.6. Syntax 312 5.6.1. General 314 This section describes the syntax extensions to the ABNF syntax 315 defined in [RFC3261], by defining a new Via header field parameter, 316 "received-realm". The ABNF defined in this specification is 317 conformant to RFC 5234 [RFC5234]. "EQUAL", "LDQUOT", "RDQUOT" and 318 "ALPHA" are defined in [RFC3261]. "DIGIT" is defined in [RFC5234]. 320 5.6.2. ABNF 321 via-params =/ received-realm 322 received-realm = "received-realm" EQUAL LDQUOT op-id COLON jws RDQUOT 323 op-id = token 324 jws = header ".." signature 325 header = *base64-char 326 signature = *base64-char 327 base64-char = ALPHA / DIGIT / "/" / "+" 329 EQUAL, COLON, token, LDQUOT, RDQUOT, ALPHA and DIGIT 330 as defined in [RFC3261]. 332 NOTE: The two adjacent dots in the jws part is due to the detached 333 payload being replaced by an empty string [RFC7515]. 335 5.7. Example 337 Via: SIP/2.0/UDP pc33.example.com;branch=z9hG4bK776; 338 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1N.. 339 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" 341 NOTE: Line breaks for display purpose only 343 6. User Agent and Proxy behavior 345 6.1. General 347 This section describes how a SIP entity, acting as an entry point to 348 a network, uses the "received-realm" Via header field parameter. 350 6.2. Behavior of a SIP entity acting as a network entry point 352 When a SIP entity, acting as a network entry point, forwards a SIP 353 request, or initiates a SIP request on its own (e.g. a PSTN gateway), 354 the SIP entity adds a Via header field to the SIP request, according 355 to the procedures in RFC 3261 [RFC3261]. In addition, if the SIP 356 entity is able to assert the adjacent upstream network, and if the 357 SIP entity is aware of a network realm value defined for that 358 network, the SIP entity can add a "received-realm" Via header field 359 parameter, conveying the network realm value as the operator 360 identifier (Section 5.2) part of the header field parameter, to the 361 Via header field added to the SIP request. 363 In addition the SIP entity MUST also calculate a JWS (Section 5.4) 364 and add the calculated JWS Header and JWS Signature as the jws part 365 of the Via header field parameter. 367 6.3. Behavior of a SIP entity consuming the received-network value 369 When a SIP entity receives a Via 'received-network' header field 370 parameter, and intends to perform actions based on the header field 371 parameter value, it MUST first re-calculate the JWS and check whether 372 the result matches the JWS received. If there is not a match, the 373 SIP entity MUST discard the received 'received-network' header field 374 parameter. The SIP entity MAY take also take additional actions 375 (e.g. rejecting the SIP request) based on local policy. 377 7. Example 379 Operator 1 T_EP T_AS 381 - INVITE ------> 382 Via: SIP/2.0/UDP IP_UA 383 -- INVITE ----------------------------> 384 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 385 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJh 386 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 387 1gFWFOEjXk" 388 Via: SIP/2.0/UDP IP_UA; received=IP_UA 390 <- 200 OK ---------------------------- 391 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 392 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJh 393 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 394 1gFWFOEjXk" 395 Via: SIP/2.0/UDP IP_UA; received=IP_UA 397 <- 200 OK------ 398 Via: SIP/2.0/UDP IP_UA; received=IP_UA 400 8. IANA Considerations 402 8.1. 'received-realm' Via header field parameter 404 This specification defines a new Via header field parameter called 405 received-realm in the "Header Field Parameters and Parameter Values" 406 sub-registry as per the registry created by [RFC3968]. The syntax is 407 defined in Section 5.6. The required information is: 409 Predefined 410 Header Field Parameter Name Values Reference 411 ---------------------- --------------------- ---------- --------- 412 Via received-realm No RFCXXXX 414 8.2. JSON Web Token Claims Registration 416 This specification defines new JSON Web Token claims in the "JSON Web 417 Token Claims" sub-registry as per the registry created by [RFC7519]. 419 Claim Name: "sip_from_tag" 421 Claim : SIP From tag header field parameter value 423 Change Controller: IESG 425 Specification Document(s): RFC XXXX, RFC 3261 427 Claim Name: "sip_date" 429 Claim Description: SIP Date header field value 431 Change Controller: IESG 433 Specification Document(s): RFC XXXX, RFC 3261 435 Claim Name: "sip_callid" 437 Claim Description: SIP Call-Id header field value 439 Change Controller: IESG 441 Specification Document(s): RFC XXXX, RFC 3261 443 Claim Name: "sip_cseq_num" 445 Claim Description: SIP CSeq numeric header field parameter value 447 Change Controller: IESG 449 Specification Document(s): RFC XXXX, RFC 3261 451 Claim Name: "sip_via_branch" 453 Claim Description: SIP Via branch header field parameter value 455 Change Controller: IESG 456 Specification Document(s): RFC XXXX, RFC 3261 458 9. Security Considerations 460 As the received-realm Via header field parameter can be used to 461 trigger applications, it is important to ensure that the parameter 462 has not been added to the SIP message by an unauthorized SIP entity. 464 The operator MUST change the key on a frequent basis. The operator 465 also needs to take great care in ensuring that the key used to 466 calculate the JWS signature value is only known by the network entry 467 point adding the received-realm Via header field parameter to a SIP 468 message and the entities that use the parameter value. 470 A SIP entity MUST NOT use the adjacent network information if there 471 is a mismatch between the JWS signature received in the SIP header 472 field and the JWS signature calculated by the receiving entity. 474 A SIP entity MUST use different key values for each parameter value 475 that it recognizes and use to trigger actions. 477 Generic security considerations for JWS are defined in [RFC7515]. 479 10. Acknowledgements 481 Thanks to Adam Roach and Richard Barnes for providing comments and 482 feedback on the document. 484 11. Change Log 486 [RFC EDITOR NOTE: Please remove this section when publishing] 488 Changes from draft-holmberg-dispatch-received-realm-07 490 o Editorial changes. 492 Changes from draft-holmberg-dispatch-received-realm-06 494 o Changes based on AD review by Ben Campbell: 496 o - operator-id added to JSON Payload 498 Changes from draft-holmberg-dispatch-received-realm-05 500 o Editorial fixes. 502 Changes from draft-holmberg-dispatch-received-realm-04 503 o JSON serialization procedure added. 505 Changes from draft-holmberg-dispatch-received-realm-03 507 o ABNF correction. 509 Changes from draft-holmberg-dispatch-received-realm-02 511 o JWT replaced with JWS. 513 o Appendix F of RFC 7515 applied. 515 Changes from draft-holmberg-dispatch-received-realm-01 517 o Define received-realm parameter value as a JSON Web Token (JWT). 519 Changes from draft-holmberg-dispatch-received-realm-00 521 o New version due to expiration of previous version. 523 Changes from draft-holmberg-received-realm-04 525 o Changed IETF WG from sipcore do dispatch. 527 o HMAC value added to the parameter. 529 Changes from draft-holmberg-received-realm-03 531 o New version due to expiration. 533 Changes from draft-holmberg-received-realm-02 535 o New version due to expiration. 537 Changes from draft-holmberg-received-realm-01 539 o New version due to expiration. 541 Changes from draft-holmberg-received-realm-00 543 o New version due to expiration. 545 12. References 546 12.1. Normative References 548 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 549 Requirement Levels", BCP 14, RFC 2119, 550 DOI 10.17487/RFC2119, March 1997, 551 . 553 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 554 A., Peterson, J., Sparks, R., Handley, M., and E. 555 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 556 DOI 10.17487/RFC3261, June 2002, 557 . 559 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 560 Specifications: ABNF", STD 68, RFC 5234, 561 DOI 10.17487/RFC5234, January 2008, 562 . 564 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 565 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 566 2015, . 568 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 569 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 570 . 572 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 573 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 574 2015, . 576 12.2. Informative References 578 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 579 Hashing for Message Authentication", RFC 2104, 580 DOI 10.17487/RFC2104, February 1997, 581 . 583 [RFC3968] Camarillo, G., "The Internet Assigned Number Authority 584 (IANA) Header Field Parameter Registry for the Session 585 Initiation Protocol (SIP)", BCP 98, RFC 3968, 586 DOI 10.17487/RFC3968, December 2004, 587 . 589 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 590 DOI 10.17487/RFC7518, May 2015, 591 . 593 [TS.3GPP.23.228] 594 3GPP, "IP Multimedia Subsystem (IMS); Stage 2", 3GPP 595 TS 23.228 14.1.0, September 2016. 597 Authors' Addresses 599 Christer Holmberg 600 Ericsson 601 Hirsalantie 11 602 Jorvas 02420 603 Finland 605 Email: christer.holmberg@ericsson.com 607 Yi Jiang 608 China Mobile 609 No.32 Xuanwumen West Street 610 Beijing Xicheng District 100053 611 P.R. China 613 Email: jiangyi@chinamobile.com