idnits 2.17.1 draft-holmberg-dispatch-received-realm-07.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 2740 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: April 29, 2017 China Mobile 6 October 26, 2016 8 Via header field parameter to indicate received realm 9 draft-holmberg-dispatch-received-realm-07.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 . . . . . . . . . . . . . . . . . . 12 84 12.2. Informative References . . . . . . . . . . . . . . . . . 13 85 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 13 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 5.7. Example 334 Via: SIP/2.0/UDP pc33.example.com;branch=z9hG4bK776; 335 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1N.. 336 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" 338 NOTE: Line breaks for display purpose only 340 6. User Agent and Proxy behavior 342 6.1. General 344 This section describes how a SIP entity, acting as an entry point to 345 a network, uses the "received-realm" Via header field parameter. 347 6.2. Behavior of a SIP entity acting as a network entry point 349 When a SIP entity, acting as a network entry point, forwards a SIP 350 request, or initiates a SIP request on its own (e.g. a PSTN gateway), 351 the SIP entity adds a Via header field to the SIP request, according 352 to the procedures in RFC 3261 [RFC3261]. In addition, if the SIP 353 entity is able to assert the adjacent upstream network, and if the 354 SIP entity is aware of a network realm value defined for that 355 network, the SIP entity can add a "received-realm" Via header field 356 parameter, conveying the network realm value as the operator 357 identifier (Section 5.2) part of the header field parameter, to the 358 Via header field added to the SIP request. 360 In addition the SIP entity MUST also calculate a JWS (Section 5.4) 361 and add it to the Via header field parameter. 363 6.3. Behavior of a SIP entity consuming the received-network value 365 When a SIP entity receives a Via 'received-network' header field 366 parameter, and intends to perform actions based on the header field 367 parameter value, it MUST first re-calculate the JWS and check whether 368 the result matches the JWS received. If there is not a match, the 369 SIP entity MUST discard the received 'received-network' header field 370 parameter. The SIP entity MAY take also take additional actions 371 (e.g. rejecting the SIP request) based on local policy. 373 7. Example 375 Operator 1 T_EP T_AS 377 - INVITE ------> 378 Via: SIP/2.0/UDP IP_UA 379 -- INVITE ----------------------------> 380 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 381 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJh 382 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 383 1gFWFOEjXk" 384 Via: SIP/2.0/UDP IP_UA; received=IP_UA 386 <- 200 OK ---------------------------- 387 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 388 received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJh 389 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 390 1gFWFOEjXk" 391 Via: SIP/2.0/UDP IP_UA; received=IP_UA 393 <- 200 OK------ 394 Via: SIP/2.0/UDP IP_UA; received=IP_UA 396 8. IANA Considerations 398 8.1. 'received-realm' Via header field parameter 400 This specification defines a new Via header field parameter called 401 received-realm in the "Header Field Parameters and Parameter Values" 402 sub-registry as per the registry created by [RFC3968]. The syntax is 403 defined in Section 5.6. The required information is: 405 Predefined 406 Header Field Parameter Name Values Reference 407 ---------------------- --------------------- ---------- --------- 408 Via received-realm No RFCXXXX 410 8.2. JSON Web Token Claims Registration 412 This specification defines new JSON Web Token claims in the "JSON Web 413 Token Claims" sub-registry as per the registry created by [RFC7519]. 415 Claim Name: "sip_from_tag" 417 Claim : SIP From tag header field parameter value 419 Change Controller: IESG 421 Specification Document(s): RFC XXXX, RFC 3261 423 Claim Name: "sip_date" 425 Claim Description: SIP Date header field value 427 Change Controller: IESG 429 Specification Document(s): RFC XXXX, RFC 3261 431 Claim Name: "sip_callid" 433 Claim Description: SIP Call-Id header field value 435 Change Controller: IESG 437 Specification Document(s): RFC XXXX, RFC 3261 439 Claim Name: "sip_cseq_num" 441 Claim Description: SIP CSeq numeric header field parameter value 443 Change Controller: IESG 445 Specification Document(s): RFC XXXX, RFC 3261 447 Claim Name: "sip_via_branch" 449 Claim Description: SIP Via branch header field parameter value 451 Change Controller: IESG 452 Specification Document(s): RFC XXXX, RFC 3261 454 9. Security Considerations 456 As the received-realm Via header field parameter can be used to 457 trigger applications, it is important to ensure that the parameter 458 has not been added to the SIP message by an unauthorized SIP entity. 460 The operator MUST change the key on a frequent basis. The operator 461 also needs to take great care in ensuring that the key used to 462 calculate the JWS signature value is only known by the network entry 463 point adding the received-realm Via header field parameter to a SIP 464 message and the entities that use the parameter value. 466 A SIP entity MUST NOT use the adjacent network information if there 467 is a mismatch between the JWS signature received in the SIP header 468 field and the JWS signature calculated by the receiving entity. 470 A SIP entity MUST use different key values for each parameter value 471 that it recognizes and use to trigger actions. 473 Generic security considerations for JWS are defined in [RFC7515]. 475 10. Acknowledgements 477 Thanks to Adam Roach and Richard Barnes for providing comments and 478 feedback on the document. 480 11. Change Log 482 [RFC EDITOR NOTE: Please remove this section when publishing] 484 Changes from draft-holmberg-dispatch-received-realm-06 486 o Changes based on AD review by Ben Campbell: 488 o - operator-id added to JSON Payload 490 Changes from draft-holmberg-dispatch-received-realm-05 492 o Editorial fixes. 494 Changes from draft-holmberg-dispatch-received-realm-04 496 o JSON serialization procedure added. 498 Changes from draft-holmberg-dispatch-received-realm-03 499 o ABNF correction. 501 Changes from draft-holmberg-dispatch-received-realm-02 503 o JWT replaced with JWS. 505 o Appendix F of RFC 7515 applied. 507 Changes from draft-holmberg-dispatch-received-realm-01 509 o Define received-realm parameter value as a JSON Web Token (JWT). 511 Changes from draft-holmberg-dispatch-received-realm-00 513 o New version due to expiration of previous version. 515 Changes from draft-holmberg-received-realm-04 517 o Changed IETF WG from sipcore do dispatch. 519 o HMAC value added to the parameter. 521 Changes from draft-holmberg-received-realm-03 523 o New version due to expiration. 525 Changes from draft-holmberg-received-realm-02 527 o New version due to expiration. 529 Changes from draft-holmberg-received-realm-01 531 o New version due to expiration. 533 Changes from draft-holmberg-received-realm-00 535 o New version due to expiration. 537 12. References 539 12.1. Normative References 541 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 542 Requirement Levels", BCP 14, RFC 2119, 543 DOI 10.17487/RFC2119, March 1997, 544 . 546 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 547 A., Peterson, J., Sparks, R., Handley, M., and E. 548 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 549 DOI 10.17487/RFC3261, June 2002, 550 . 552 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 553 Specifications: ABNF", STD 68, RFC 5234, 554 DOI 10.17487/RFC5234, January 2008, 555 . 557 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 558 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 559 2015, . 561 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 562 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 563 . 565 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 566 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 567 2015, . 569 12.2. Informative References 571 [RFC3968] Camarillo, G., "The Internet Assigned Number Authority 572 (IANA) Header Field Parameter Registry for the Session 573 Initiation Protocol (SIP)", BCP 98, RFC 3968, 574 DOI 10.17487/RFC3968, December 2004, 575 . 577 [RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518, 578 DOI 10.17487/RFC7518, May 2015, 579 . 581 [TS.3GPP.23.228] 582 3GPP, "IP Multimedia Subsystem (IMS); Stage 2", 3GPP 583 TS 23.228 14.1.0, September 2016. 585 Authors' Addresses 587 Christer Holmberg 588 Ericsson 589 Hirsalantie 11 590 Jorvas 02420 591 Finland 593 Email: christer.holmberg@ericsson.com 594 Yi Jiang 595 China Mobile 596 No.32 Xuanwumen West Street 597 Beijing Xicheng District 100053 598 P.R. China 600 Email: jiangyi@chinamobile.com