idnits 2.17.1 draft-holmberg-dispatch-received-realm-02.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 (May 25, 2016) is 2892 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: November 26, 2016 China Mobile 6 May 25, 2016 8 Via header field parameter to indicate received realm 9 draft-holmberg-dispatch-received-realm-02.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 November 26, 2016. 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. Vie 'received-realm' header field parameter . . . . . . . . . 4 61 5.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 5 62 5.2. Header . . . . . . . . . . . . . . . . . . . . . . . . . 5 63 5.3. Payload claims . . . . . . . . . . . . . . . . . . . . . 5 64 5.4. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 5.4.1. General . . . . . . . . . . . . . . . . . . . . . . . 6 66 5.4.2. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 6 67 6. User Agent and Proxy behavior . . . . . . . . . . . . . . . . 6 68 6.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 6 69 6.2. Behavior of a SIP entity acting as a network entry point 7 70 6.3. Behavior of a SIP entity consuming the received-network 71 value . . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 74 8.1. 'received-realm' Via header field parameter . . . . . . . 8 75 8.2. JSON Web Token Claims Registration . . . . . . . . . . . 8 76 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 77 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 78 11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 80 12.1. Normative References . . . . . . . . . . . . . . . . . . 11 81 12.2. Informative References . . . . . . . . . . . . . . . . . 11 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 84 1. Introduction 86 1.1. General 88 When SIP sessions are established between networks belonging to 89 different operators, or between interconnected networks belonging to 90 the same operator (or enterprise), the SIP requests might traverse 91 transit network. 93 Such transit networks might provide different kind of services. In 94 order to do that, a transit network often needs to know to which 95 operator (or enterprise) the adjacent upstream network, from which 96 the SIP session initiation request is received, belongs. 98 This specification defines a new Session Initiation Protocol (SIP) 99 Via header field parameter, "received-realm", which allows a SIP 100 entity acting as an entry point to a transit network to indicate from 101 which adjacent upstream network a SIP request is received, using a 102 network realm value associated with the adjacent network. 104 NOTE: As the adjacent network can be an enterprise network, an Inter 105 Operator Identifier (IOI) cannot be used to identity the network, as 106 IOIs are not defined for enterprise networks. 108 The following sections describe use-case where the information is 109 needed. 111 1.2. Use-Case: Transit Network Application Services 113 The 3rd Generation Partnership Project (3GPP) TS 23.228 specifies how 114 an IP Multimedia Subsystem (IMS) network can be used to provide 115 transit functionality. An operator can use its IMS network to 116 provide transit functionality e.g. to non-IMS customers, to 117 enterprise networks, and to other network operators. 119 The transit network operator can provide application services to the 120 networks for which it is providing transit functionality. Transit 121 application services are typically not provided per user basis, as 122 the transit network does not have access to the user profiles of the 123 networks for which the application services are provided. Instead, 124 the application services are provided per served network. 126 When a SIP entity that provides application services (e.g. an 127 Application Server) within a transit network receives a SIP request, 128 in order to apply the correct services it needs to know the adjacent 129 upstream network from which the SIP request is received. 131 1.3. Use-Case: Transit Network Routing 133 A transit network operator normally interconnects to many diferent 134 operators, including other transit network operators, and provides 135 transit routing of SIP requests received from one operator network 136 towards the destination. The destination can be within an operator 137 network to which the transit network operator has a direct 138 interconnect, or within an operator network that only can be reached 139 via one or more interconnected transit operators. 141 For each customer, i.e. interconnected network operator for which, 142 the transit network operator routes SIP requests towards the 143 requested destination a set of transit routing polices are defined. 144 These policies are used to determine how a SIP request shall be 145 routed towards the requested destination to meet the agreement the 146 transit network operator has with its customer. 148 When a SIP entity that performs the transit routing functionality 149 receives a SIP request, in order to apply the correct set of transit 150 routing policies, it needs to know from which of its customers, i.e. 151 adjacent upstream network, the SIP request is received. 153 2. Applicability 155 The mechanism defined in this specification MUST only be used by SIP 156 entities that are able to verify from which adjacent upstream network 157 a SIP request is received. 159 The mechanism for verifying from which adjacent upstream network a 160 SIP request is received is outside the scope of this specification. 162 3. Conventions 164 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 165 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 166 document are to be interpreted as described in BCP 14, RFC 2119 167 [RFC2119]. 169 4. Definitions 171 SIP entity: SIP User Agent (UA), or SIP proxy, as defined in RFC 172 3261. 174 Adjacent upstream SIP network: The adjacent SIP network in the 175 direction from which a SIP request is received. 177 Network entry point: A SIP entity on the border of network, which 178 receives SIP requests from adjacent upstream networks. 180 Inter Operator Identifier (IOI): A globally unique identifier to 181 correlate billing information generated within the IP Multimedia 182 Subsystem (IMS). 184 JWT: JSON Web Token, as defined in RFC 7519. 186 5. Vie 'received-realm' header field parameter 187 5.1. General 189 The Via 'received-realm' header field parameter value is represented 190 as a JSON Web Token (JTW) [RFC7519]. The JWT payload contains SIP 191 header filed values, and the value representing the adjacent network. 193 The procedures for encoding the JWT and calculating the signature are 194 defined in [RFC7519]. 196 5.2. Header 198 The following header parameters MUST be included in the JWT. 200 o The "typ" parameter MUST have a "JWT" value. 202 o The "alg" parameter MUST have the value of the algorithm used to 203 calculate the JWT signature. 205 NOTE: Operators need to agree on the set of supported algorithms for 206 calculating the JWT signature. 208 Example: 210 { 211 "typ":"JWT", 212 "alg":"HS256" 213 } 215 5.3. Payload claims 217 The follwoing payload claims MUST be included in the JWT. 219 o The "adjacent_network" claim has the value representing the 220 adjacent network. 222 o The "sip_from_tag" claim has the value of the From 'tag' header 223 field parameter of the SIP message. 225 o The "sip_date" claim has the value of the Date header field in the 226 SIP message. 228 o The "sip_callid" claim has have value of the Call-ID header field 229 in the SIP message. 231 o The "sip_cseq_num" claim has the numeric value of the CSeq header 232 field in the SIP message. 234 o the "sip_via_branch" claim has value of the Via branch header 235 field parameter of the Via header field, in the SIP message, to 236 which the received-realm header parameter is attached. 238 Example: 240 { 241 "adjacent_network":"operator_1.com", 242 "sip_from_tag":"1928301774", 243 "sip_date":"Fri, 20 May 2016 06:41:47 GMT", 244 "sip_callid":"a84b4c76e66710@pc33.atlanta.com", 245 "sip_cseq_num":"314159", 246 "sip_via_branch":"z9hG4bK776asdhds" 247 } 249 5.4. Syntax 251 5.4.1. General 253 This section describes the syntax extensions to the ABNF syntax 254 defined in [RFC3261], by defining a new Via header field parameter, 255 "received-realm". The ABNF defined in this specification is 256 conformant to RFC 5234 [RFC5234]. "EQUAL", "LDQUOT", "RDQUOT" and 257 "ALPHA" are defined in [RFC3261]. "DIGIT" is defined in [RFC5234]. 259 5.4.2. ABNF 261 via-params =/ received-realm 262 received-realm = "received-realm" EQUAL jwt 263 jtw = LDQUOT header "." payload "." signature RDQUOT 264 header = *base64-char 265 payload = *base64-char 266 signature = *base64-char 267 base64-char = ALPHA / DIGIT / "/" / "+" 269 6. User Agent and Proxy behavior 271 6.1. General 273 This section describes how a SIP entity, acting as an entry point to 274 a network, uses the "received-realm" Via header field parameter. 276 6.2. Behavior of a SIP entity acting as a network entry point 278 When a SIP entity, acting as a network entry point, forwards a SIP 279 request, or initiates a SIP request on its own (e.g. a PSTN gateway), 280 the SIP entity adds a Via header field to the SIP request, according 281 to the procedures in RFC 3261 [RFC3261]. In addition, if the SIP 282 entity is able to assert the adjacent upstream network, and if the 283 SIP entity is aware of a network realm value defined for that 284 network, the SIP entity can add a "received-realm" Via header field 285 parameter, conveying the network realm value, to the Via header field 286 added to the SIP request. 288 When the SIP entity adds a "received-realm" Via header field 289 parameter to a SIP request, it MUST also calculate a Hash-based 290 message authentication code (HMAC) [RFC2104] value from the parameter 291 value, using a secret key which is shared between the SIP entity and 292 any SIP entity which will use the parameter value. The HMAC is then 293 added to the parameter. 295 When the receiver decodes the JWT, it MUST compare the JWT claims 296 with the corresponding SIP header field information. If there is a 297 mismatch, the receiver MUST discard the received-realm header field 298 parameter. 300 6.3. Behavior of a SIP entity consuming the received-network value 302 When a SIP entity receives a Via 'received-network' header field 303 parameter, and intends to perform actions based on the header field 304 parameter value, it MUST first check whether the values of the JWT 305 claims representing SIP header field values match the associated SIP 306 header field values within the SIP request. If the values of the JWT 307 claims representing SIP header field values do not match the values 308 of the associated SIP header field values the SIP entity MUST discard 309 the adjacent network information present in the JWT. The SIP entity 310 MAY take also take additional actions (e.g. rejecting the SIP 311 request) based on local policy. 313 7. Example 314 Operator 1 T_EP T_AS 316 - INVITE ------> 317 Via: IP_UA 318 - INVITE ----------------------------> 319 Via: IP_TEP; received-realm="eyJhbG.eyJpc3.03f329" 320 Via: IP_UA; received=IP_UA 322 <- 200 OK ---------------------------- 323 Via: IP_TEP; received-realm="eyJhbG.eyJpc3.03f329" 324 Via: IP_UA; received=IP_UA 326 <- 200 OK------ 327 Via: IP_UA; received=IP_UA 329 8. IANA Considerations 331 8.1. 'received-realm' Via header field parameter 333 This specification defines a new Via header field parameter called 334 received-realm in the "Header Field Parameters and Parameter Values" 335 sub-registry as per the registry created by [RFC3968]. The syntax is 336 defined in Section 5.4. The required information is: 338 Predefined 339 Header Field Parameter Name Values Reference 340 ---------------------- --------------------- ---------- --------- 341 Via received-realm No RFCXXXX 343 8.2. JSON Web Token Claims Registration 345 This specification defines new JSON Web Token claims in the "JSON Web 346 Token Claims" sub-registry as per the registry created by [RFC7519]. 348 o Claim Name: "adjacent_network" 350 o Claim Descritpoin: Adjacent network from where a SIP request is 351 received 353 o Change Controller: IESG 355 o Specification Document(s): RFC XXXX 357 o Claim Name: "sip_from_tag" 359 o Claim Descritpoin: SIP From tag header field parameter value 360 o Change Controller: IESG 362 o Specification Document(s): RFC XXXX, RFC 3261 364 o Claim Name: "sip_date" 366 o Claim Descritpoin: SIP Date header field value 368 o Change Controller: IESG 370 o Specification Document(s): RFC XXXX, RFC 3261 372 o Claim Name: "sip_callid" 374 o Claim Descritpoin: SIP Call-Id header field value 376 o Change Controller: IESG 378 o Specification Document(s): RFC XXXX, RFC 3261 380 o Claim Name: "sip_cseq_num" 382 o Claim Descritpoin: SIP CSeq numeric header field parameter value 384 o Change Controller: IESG 386 o Specification Document(s): RFC XXXX, RFC 3261 388 o Claim Name: "sip_via_branch" 390 o Claim Descritpoin: SIP Via branch header field parameter value 392 o Change Controller: IESG 394 o Specification Document(s): RFC XXXX, RFC 3261 396 9. Security Considerations 398 As the received-realm Via header field parameter can be used to 399 trigger applications, it is important to ensure that the parameter 400 has not been added to the SIP message by an unauthorized SIP entity. 402 The operator MUST change the key on a frequent basis. The operator 403 also needs to take great care in ensuring that the key used to 404 calculate the JWT signature value is only known by the network entry 405 point adding the received-realm Via header field parameter to a SIP 406 message and the entities that use the parameter value. 408 A SIP entity MUST NOT use the adjacent network information if the 409 values of the JWT claims representing SIP header field values do not 410 match the values of the associated SIP header field values. 412 A SIP entity MUST use different key values for each parameter value 413 that it recognizes and use to trigger actions. 415 10. Acknowledgements 417 Thanks to Adam Roach and Richard Barnes for providing comments and 418 feedback on the document. 420 11. Change Log 422 [RFC EDITOR NOTE: Please remove this section when publishing] 424 Changes from draft-holmberg-dispatch-received-realm-01 426 o Define received-realm parameter value as a JSON Web Token (JWT). 428 Changes from draft-holmberg-dispatch-received-realm-00 430 o New version due to expiration of previous version. 432 Changes from draft-holmberg-received-realm-04 434 o Changed IETF WG from sipcore do dispatch. 436 o HMAC value added to the parameter. 438 Changes from draft-holmberg-received-realm-03 440 o New version due to expiration. 442 Changes from draft-holmberg-received-realm-02 444 o New version due to expiration. 446 Changes from draft-holmberg-received-realm-01 448 o New version due to expiration. 450 Changes from draft-holmberg-received-realm-00 452 o New version due to expiration. 454 12. References 456 12.1. Normative References 458 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 459 Requirement Levels", BCP 14, RFC 2119, 460 DOI 10.17487/RFC2119, March 1997, 461 . 463 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 464 A., Peterson, J., Sparks, R., Handley, M., and E. 465 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 466 DOI 10.17487/RFC3261, June 2002, 467 . 469 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 470 Specifications: ABNF", STD 68, RFC 5234, 471 DOI 10.17487/RFC5234, January 2008, 472 . 474 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 475 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 476 . 478 12.2. Informative References 480 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 481 Hashing for Message Authentication", RFC 2104, 482 DOI 10.17487/RFC2104, February 1997, 483 . 485 [RFC3968] Camarillo, G., "The Internet Assigned Number Authority 486 (IANA) Header Field Parameter Registry for the Session 487 Initiation Protocol (SIP)", BCP 98, RFC 3968, 488 DOI 10.17487/RFC3968, December 2004, 489 . 491 Authors' Addresses 493 Christer Holmberg 494 Ericsson 495 Hirsalantie 11 496 Jorvas 02420 497 Finland 499 Email: christer.holmberg@ericsson.com 500 Yi Jiang 501 China Mobile 502 No.32 Xuanwumen West Street 503 Beijing Xicheng District 100053 504 P.R. China 506 Email: jiangyi@chinamobile.com