idnits 2.17.1 draft-holmberg-dispatch-received-realm-05.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 : ---------------------------------------------------------------------------- == There are 1 instance of lines with non-RFC2606-compliant FQDNs in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 6, 2016) is 2759 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 (~~), 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 9, 2017 China Mobile 6 October 6, 2016 8 Via header field parameter to indicate received realm 9 draft-holmberg-dispatch-received-realm-05.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 9, 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. Vie '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 . . . . . . . . . . . . . . . . . . . . 6 66 5.6. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 7 67 5.6.1. General . . . . . . . . . . . . . . . . . . . . . . . 7 68 5.6.2. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 7 69 5.7. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 8 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 . . . . . . . . . . . 9 79 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 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 kind 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-case 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 specifies how 117 an IP Multimedia Subsystem (IMS) network can be used to provide 118 transit functionality. An operator can use its IMS network to 119 provide transit functionality e.g. to non-IMS customers, to 120 enterprise networks, and to other network operators. 122 The transit network operator can provide application services to the 123 networks for which it is providing transit functionality. Transit 124 application services are typically not provided per user basis, as 125 the transit network does not have access to the user profiles of the 126 networks for which the application services are provided. Instead, 127 the application services are provided per served network. 129 When a SIP entity that provides application services (e.g. an 130 Application Server) within a transit network receives a SIP request, 131 in order to apply the correct services it needs to know the adjacent 132 upstream network from which the SIP request is received. 134 1.3. Use-Case: Transit Network Routing 136 A transit network operator normally interconnects to many diferent 137 operators, including other transit network operators, and provides 138 transit routing of SIP requests received from one operator network 139 towards the destination. The destination can be within an operator 140 network to which the transit network operator has a direct 141 interconnect, or within an operator network that only can be reached 142 via one or more interconnected transit operators. 144 For each customer, i.e. interconnected network operator for which, 145 the transit network operator routes SIP requests towards the 146 requested destination a set of transit routing polices are defined. 147 These policies are used to determine how a SIP request shall be 148 routed towards the requested destination to meet the agreement the 149 transit network operator has with its customer. 151 When a SIP entity that performs the transit routing functionality 152 receives a SIP request, in order to apply the correct set of transit 153 routing policies, it needs to know from which of its customers, i.e. 154 adjacent upstream network, the SIP request is received. 156 2. Applicability 158 The mechanism defined in this specification MUST only be used by SIP 159 entities that are able to verify from which adjacent upstream network 160 a SIP request is received. 162 The mechanism for verifying from which adjacent upstream network a 163 SIP request is received is outside the scope of this specification. 165 3. Conventions 167 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 168 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 169 document are to be interpreted as described in BCP 14, RFC 2119 170 [RFC2119]. 172 4. Definitions 174 SIP entity: SIP User Agent (UA), or SIP proxy, as defined in RFC 175 3261. 177 Adjacent upstream SIP network: The adjacent SIP network in the 178 direction from which a SIP request is received. 180 Network entry point: A SIP entity on the border of network, which 181 receives SIP requests from adjacent upstream networks. 183 Inter Operator Identifier (IOI): A globally unique identifier to 184 correlate billing information generated within the IP Multimedia 185 Subsystem (IMS). 187 JWS: JSON Web Signature, as defined in RFC 7515. 189 5. Vie 'received-realm' header field parameter 191 5.1. General 193 The Via 'received-realm' header field parameter value is represented 194 as a combination of an operator identyfier, which value represents 195 the adjacent network, and a serialized JSON Web Signature (JWS) 196 [RFC7515]. The JWS Payload consists of the operator identifier and 197 other SIP information element values. 199 The procedures for encoding the JWS and calculating the signature are 200 defined in [RFC7515]. As the JWS Payload information is found in 201 other SIP information elements the JWS payload is not included in the 202 serialized JWS conveyed in the header field parameter, as described 203 in Appendix F of [RFC7515]. The operator identifier and the 204 serialized JWS are separated using a comma character. 206 5.2. Operator Identifier 208 The Operator Identifier is a token value that represents the adjacent 209 operator. The scope of the value is only within the network that 210 inserts the value. 212 5.3. JWS Header 214 The following header parameters MUST be included in the JWS. 216 o The "typ" parameter MUST have a "JWT" value. 218 o The "alg" parameter MUST have the value of the algorithm used to 219 calculate the JWS. 221 NOTE: Operators need to agree on the set of supported algorithms for 222 calculating the JWT signature. 224 Example: 226 { 227 "typ":"JWT", 228 "alg":"HS256" 229 } 231 5.4. JWS Payload 233 The followoing claims MUST be included in the JWS Payload: 235 o The "sip_from_tag" claim has the value of the From 'tag' header 236 field parameter of the SIP message. 238 o The "sip_date" claim has the value of the Date header field in the 239 SIP message, quoted and encoded in JSON NumericDate format 240 [RFC7519]. 242 o The "sip_callid" claim has have value of the Call-ID header field 243 in the SIP message. 245 o The "sip_cseq_num" claim has the numeric value of the CSeq header 246 field in the SIP message. 248 o the "sip_via_branch" claim has value of the Via branch header 249 field parameter of the Via header field, in the SIP message, to 250 which the received-realm header field parameter is attached. 252 Example: 254 { 255 "sip_from_tag":"1928301774", 256 "sip_date":"1472815523", 257 "sip_callid":"a84b4c76e66710@pc33.atlanta.com", 258 "sip_cseq_num":"314159", 259 "sip_via_branch":"z9hG4bK776asdhds" 260 } 262 5.5. JWS Serialization 264 As the JWS Payload is not carried in the received-realm parameter, in 265 order to make sure that the sender and the receiver construct the JWS 266 Payload object in the same way, the JSON representation of the JWS 267 Payload object it MUST be computed as follows: 269 o All claims MUST be encoded using lower case characters. 271 o The claims MUST be in the same order as listed in [Section 5.4]. 273 o All claims except "sip_date" MUST be encoded as StringOrURI JSON 274 string value [RFC7519]. 276 o The "sip_date" claim MUST be encoded as a JSON NumericDate value 277 [RFC7519]. 279 o The JWS Payload MUST follow the rules for the construction of the 280 thumbprint of a JSON Web Key (JWK) as defined in [RFC7638] 281 Section 3 Step 1 only. 283 Example: 285 (Line breaks used for display purposes only) 287 {"sip_from_tag":"1928301774","sip_date":"1472815523", 288 "sip_callid":"a84b4c76e66710@pc33.atlanta.com","sip_cseq_num":"314159", 289 "sip_via_branch":"z9hG4bK776asdhds"} 291 5.6. Syntax 293 5.6.1. General 295 This section describes the syntax extensions to the ABNF syntax 296 defined in [RFC3261], by defining a new Via header field parameter, 297 "received-realm". The ABNF defined in this specification is 298 conformant to RFC 5234 [RFC5234]. "EQUAL", "LDQUOT", "RDQUOT" and 299 "ALPHA" are defined in [RFC3261]. "DIGIT" is defined in [RFC5234]. 301 5.6.2. ABNF 303 via-params =/ received-realm 304 received-realm = "received-realm" EQUAL LDQUOT op-id COLON jws RDQUOT 305 op-id = token 306 jws = header "." "." signature 307 header = *base64-char 308 signature = *base64-char 309 base64-char = ALPHA / DIGIT / "/" / "+" 311 EQUAL, COLON, token, LDQUOT, RDQUOT, ALPHA and DIGIT 312 as defined in RFC 3261. 314 5.7. Example 315 Via: SIP/2.0/UDP pc33.atlanta.com;branch=z9hG4bK776; 316 received-realm=myoperator:"eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1N.. 317 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" 319 NOTE: Line breaks for display purpose only 321 6. User Agent and Proxy behavior 323 6.1. General 325 This section describes how a SIP entity, acting as an entry point to 326 a network, uses the "received-realm" Via header field parameter. 328 6.2. Behavior of a SIP entity acting as a network entry point 330 When a SIP entity, acting as a network entry point, forwards a SIP 331 request, or initiates a SIP request on its own (e.g. a PSTN gateway), 332 the SIP entity adds a Via header field to the SIP request, according 333 to the procedures in RFC 3261 [RFC3261]. In addition, if the SIP 334 entity is able to assert the adjacent upstream network, and if the 335 SIP entity is aware of a network realm value defined for that 336 network, the SIP entity can add a "received-realm" Via header field 337 parameter, conveying the network realm value, to the Via header field 338 added to the SIP request. 340 When the SIP entity adds a "received-realm" Via header field 341 parameter to a SIP request, it MUST also calculate a Hash-based 342 message authentication code (HMAC) [RFC2104] value from the parameter 343 value, using a secret key which is shared between the SIP entity and 344 any SIP entity which will use the parameter value. The HMAC is then 345 added to the parameter. 347 When the receiver decodes the JWT, it MUST compare the JWT claims 348 with the corresponding SIP header field information. If there is a 349 mismatch, the receiver MUST discard the received-realm header field 350 parameter. 352 6.3. Behavior of a SIP entity consuming the received-network value 354 When a SIP entity receives a Via 'received-network' header field 355 parameter, and intends to perform actions based on the header field 356 parameter value, it MUST first re-calculate the JWS and check whether 357 the result matches the JWS received. If there is not a match the SIP 358 entity MUST discard the received 'received-network' header field 359 parameter. The SIP entity MAY take also take additional actions 360 (e.g. rejecting the SIP request) based on local policy. 362 7. Example 364 Operator 1 T_EP T_AS 366 - INVITE ------> 367 Via: SIP/2.0/UDP IP_UA 368 -- INVITE ----------------------------> 369 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 370 received-realm=myoperator:"eyJ0eXAiOiJKV1QiLA0KICJh 371 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 372 1gFWFOEjXk" 373 Via: SIP/2.0/UDP IP_UA; received=IP_UA 375 <- 200 OK ---------------------------- 376 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 377 received-realm=myoperator:"eyJ0eXAiOiJKV1QiLA0KICJh 378 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 379 1gFWFOEjXk" 380 Via: SIP/2.0/UDP IP_UA; received=IP_UA 382 <- 200 OK------ 383 Via: SIP/2.0/UDP IP_UA; received=IP_UA 385 8. IANA Considerations 387 8.1. 'received-realm' Via header field parameter 389 This specification defines a new Via header field parameter called 390 received-realm in the "Header Field Parameters and Parameter Values" 391 sub-registry as per the registry created by [RFC3968]. The syntax is 392 defined in Section 5.6. The required information is: 394 Predefined 395 Header Field Parameter Name Values Reference 396 ---------------------- --------------------- ---------- --------- 397 Via received-realm No RFCXXXX 399 8.2. JSON Web Token Claims Registration 401 This specification defines new JSON Web Token claims in the "JSON Web 402 Token Claims" sub-registry as per the registry created by [RFC7519]. 404 Claim Name: "sip_from_tag" 406 Claim : SIP From tag header field parameter value 407 Change Controller: IESG 409 Specification Document(s): RFC XXXX, RFC 3261 411 Claim Name: "sip_date" 413 Claim Description: SIP Date header field value 415 Change Controller: IESG 417 Specification Document(s): RFC XXXX, RFC 3261 419 Claim Name: "sip_callid" 421 Claim Description: SIP Call-Id header field value 423 Change Controller: IESG 425 Specification Document(s): RFC XXXX, RFC 3261 427 Claim Name: "sip_cseq_num" 429 Claim Description: SIP CSeq numeric header field parameter value 431 Change Controller: IESG 433 Specification Document(s): RFC XXXX, RFC 3261 435 Claim Name: "sip_via_branch" 437 Claim Description: SIP Via branch header field parameter value 439 Change Controller: IESG 441 Specification Document(s): RFC XXXX, RFC 3261 443 9. Security Considerations 445 As the received-realm Via header field parameter can be used to 446 trigger applications, it is important to ensure that the parameter 447 has not been added to the SIP message by an unauthorized SIP entity. 449 The operator MUST change the key on a frequent basis. The operator 450 also needs to take great care in ensuring that the key used to 451 calculate the JWS signature value is only known by the network entry 452 point adding the received-realm Via header field parameter to a SIP 453 message and the entities that use the parameter value. 455 A SIP entity MUST NOT use the adjacent network information if there 456 is a mismatch between the JWS value received in the SIP header field 457 and the JWS calculated by the receiving entity. 459 A SIP entity MUST use different key values for each parameter value 460 that it recognizes and use to trigger actions. 462 Generic security considerations for JWS are defined in [RFC7515]. 464 10. Acknowledgements 466 Thanks to Adam Roach and Richard Barnes for providing comments and 467 feedback on the document. 469 11. Change Log 471 [RFC EDITOR NOTE: Please remove this section when publishing] 473 Changes from draft-holmberg-dispatch-received-realm-04 475 o JSON serialization procedure added. 477 Changes from draft-holmberg-dispatch-received-realm-03 479 o ABNF correction. 481 Changes from draft-holmberg-dispatch-received-realm-02 483 o JWT replaced with JWS. 485 o Appendix F of RFC 7515 applied. 487 Changes from draft-holmberg-dispatch-received-realm-01 489 o Define received-realm parameter value as a JSON Web Token (JWT). 491 Changes from draft-holmberg-dispatch-received-realm-00 493 o New version due to expiration of previous version. 495 Changes from draft-holmberg-received-realm-04 497 o Changed IETF WG from sipcore do dispatch. 499 o HMAC value added to the parameter. 501 Changes from draft-holmberg-received-realm-03 502 o New version due to expiration. 504 Changes from draft-holmberg-received-realm-02 506 o New version due to expiration. 508 Changes from draft-holmberg-received-realm-01 510 o New version due to expiration. 512 Changes from draft-holmberg-received-realm-00 514 o New version due to expiration. 516 12. References 518 12.1. Normative References 520 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 521 Requirement Levels", BCP 14, RFC 2119, 522 DOI 10.17487/RFC2119, March 1997, 523 . 525 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 526 A., Peterson, J., Sparks, R., Handley, M., and E. 527 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 528 DOI 10.17487/RFC3261, June 2002, 529 . 531 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 532 Specifications: ABNF", STD 68, RFC 5234, 533 DOI 10.17487/RFC5234, January 2008, 534 . 536 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 537 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 538 2015, . 540 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 541 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 542 . 544 [RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK) 545 Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September 546 2015, . 548 12.2. Informative References 550 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 551 Hashing for Message Authentication", RFC 2104, 552 DOI 10.17487/RFC2104, February 1997, 553 . 555 [RFC3968] Camarillo, G., "The Internet Assigned Number Authority 556 (IANA) Header Field Parameter Registry for the Session 557 Initiation Protocol (SIP)", BCP 98, RFC 3968, 558 DOI 10.17487/RFC3968, December 2004, 559 . 561 Authors' Addresses 563 Christer Holmberg 564 Ericsson 565 Hirsalantie 11 566 Jorvas 02420 567 Finland 569 Email: christer.holmberg@ericsson.com 571 Yi Jiang 572 China Mobile 573 No.32 Xuanwumen West Street 574 Beijing Xicheng District 100053 575 P.R. China 577 Email: jiangyi@chinamobile.com