idnits 2.17.1 draft-holmberg-dispatch-received-realm-03.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 (September 19, 2016) is 2775 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: March 23, 2017 China Mobile 6 September 19, 2016 8 Via header field parameter to indicate received realm 9 draft-holmberg-dispatch-received-realm-03.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 March 23, 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. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 6 66 5.5.1. General . . . . . . . . . . . . . . . . . . . . . . . 6 67 5.5.2. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 7 68 5.6. Example . . . . . . . . . . . . . . . . . . . . . . . . . 7 69 6. User Agent and Proxy behavior . . . . . . . . . . . . . . . . 7 70 6.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 7 71 6.2. Behavior of a SIP entity acting as a network entry point 7 72 6.3. Behavior of a SIP entity consuming the received-network 73 value . . . . . . . . . . . . . . . . . . . . . . . . . . 8 74 7. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 76 8.1. 'received-realm' Via header field parameter . . . . . . . 9 77 8.2. JSON Web Token Claims Registration . . . . . . . . . . . 9 78 9. Security Considerations . . . . . . . . . . . . . . . . . . . 10 79 10. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 10 80 11. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 10 81 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 11 82 12.1. Normative References . . . . . . . . . . . . . . . . . . 11 83 12.2. Informative References . . . . . . . . . . . . . . . . . 12 84 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 86 1. Introduction 88 1.1. General 90 When SIP sessions are established between networks belonging to 91 different operators, or between interconnected networks belonging to 92 the same operator (or enterprise), the SIP requests might traverse 93 transit network. 95 Such transit networks might provide different kind of services. In 96 order to do that, a transit network often needs to know to which 97 operator (or enterprise) the adjacent upstream network, from which 98 the SIP session initiation request is received, belongs. 100 This specification defines a new Session Initiation Protocol (SIP) 101 Via header field parameter, "received-realm", which allows a SIP 102 entity acting as an entry point to a transit network to indicate from 103 which adjacent upstream network a SIP request is received, using a 104 network realm value associated with the adjacent network. 106 NOTE: As the adjacent network can be an enterprise network, an Inter 107 Operator Identifier (IOI) cannot be used to identity the network, as 108 IOIs are not defined for enterprise networks. 110 The following sections describe use-case where the information is 111 needed. 113 1.2. Use-Case: Transit Network Application Services 115 The 3rd Generation Partnership Project (3GPP) TS 23.228 specifies how 116 an IP Multimedia Subsystem (IMS) network can be used to provide 117 transit functionality. An operator can use its IMS network to 118 provide transit functionality e.g. to non-IMS customers, to 119 enterprise networks, and to other network operators. 121 The transit network operator can provide application services to the 122 networks for which it is providing transit functionality. Transit 123 application services are typically not provided per user basis, as 124 the transit network does not have access to the user profiles of the 125 networks for which the application services are provided. Instead, 126 the application services are provided per served network. 128 When a SIP entity that provides application services (e.g. an 129 Application Server) within a transit network receives a SIP request, 130 in order to apply the correct services it needs to know the adjacent 131 upstream network from which the SIP request is received. 133 1.3. Use-Case: Transit Network Routing 135 A transit network operator normally interconnects to many diferent 136 operators, including other transit network operators, and provides 137 transit routing of SIP requests received from one operator network 138 towards the destination. The destination can be within an operator 139 network to which the transit network operator has a direct 140 interconnect, or within an operator network that only can be reached 141 via one or more interconnected transit operators. 143 For each customer, i.e. interconnected network operator for which, 144 the transit network operator routes SIP requests towards the 145 requested destination a set of transit routing polices are defined. 146 These policies are used to determine how a SIP request shall be 147 routed towards the requested destination to meet the agreement the 148 transit network operator has with its customer. 150 When a SIP entity that performs the transit routing functionality 151 receives a SIP request, in order to apply the correct set of transit 152 routing policies, it needs to know from which of its customers, i.e. 153 adjacent upstream network, the SIP request is received. 155 2. Applicability 157 The mechanism defined in this specification MUST only be used by SIP 158 entities that are able to verify from which adjacent upstream network 159 a SIP request is received. 161 The mechanism for verifying from which adjacent upstream network a 162 SIP request is received is outside the scope of this specification. 164 3. Conventions 166 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 167 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 168 document are to be interpreted as described in BCP 14, RFC 2119 169 [RFC2119]. 171 4. Definitions 173 SIP entity: SIP User Agent (UA), or SIP proxy, as defined in RFC 174 3261. 176 Adjacent upstream SIP network: The adjacent SIP network in the 177 direction from which a SIP request is received. 179 Network entry point: A SIP entity on the border of network, which 180 receives SIP requests from adjacent upstream networks. 182 Inter Operator Identifier (IOI): A globally unique identifier to 183 correlate billing information generated within the IP Multimedia 184 Subsystem (IMS). 186 JWS: JSON Web Signature, as defined in RFC 7515. 188 5. Vie 'received-realm' header field parameter 190 5.1. General 192 The Via 'received-realm' header field parameter value is represented 193 as a combination of an operator identyfier, which value represents 194 the adjacent network, and a serialized JSON Web Signature (JWS) 195 [RFC7515]. The JWS Payload consists of the operator identifier and 196 other SIP information element values. 198 The procedures for encoding the JWS and calculating the signature are 199 defined in [RFC7515]. As the JWS Payload information is found in 200 other SIP information elements the JWS payload is not included in the 201 serialized JWS conveyed in the header field parameter, as described 202 in Appendix F of [RFC7515]. The operator identifier and the 203 serialized JWS are separated using a comma character. 205 5.2. Operator Identifier 207 The Operator Identifier is a token value that represents the adjacent 208 operator. The scope of the value is only within the network that 209 inserts the value. 211 5.3. JWS Header 213 The following header parameters MUST be included in the JWS. 215 o The "typ" parameter MUST have a "JWT" value. 217 o The "alg" parameter MUST have the value of the algorithm used to 218 calculate the JWS. 220 NOTE: Operators need to agree on the set of supported algorithms for 221 calculating the JWT signature. 223 Example: 225 { 226 "typ":"JWT", 227 "alg":"HS256" 228 } 230 5.4. JWS Payload 232 The followoing claims MUST be included in the JWS Payload. 234 o The "sip_from_tag" claim has the value of the From 'tag' header 235 field parameter of the SIP message. 237 o The "sip_date" claim has the value of the Date header field in the 238 SIP message, quoted and encoded in JSON NumbericData format 239 [RFC7519]. 241 o The "sip_callid" claim has have value of the Call-ID header field 242 in the SIP message. 244 o The "sip_cseq_num" claim has the numeric value of the CSeq header 245 field in the SIP message. 247 o the "sip_via_branch" claim has value of the Via branch header 248 field parameter of the Via header field, in the SIP message, to 249 which the received-realm header field parameter is attached. 251 All claims MUST be encoded using lower case characters. 253 All claims except "sip_date" MUST be encoded as StringOrURI JSON 254 string value [RFC7519]. 256 The sip_date claim MUST be encoded as a JSON NumericData value 257 [RFC7519] 259 Example: 261 { 262 "sip_from_tag":"1928301774", 263 "sip_date":"1472815523", 264 "sip_callid":"a84b4c76e66710@pc33.atlanta.com", 265 "sip_cseq_num":"314159", 266 "sip_via_branch":"z9hG4bK776asdhds" 267 } 269 5.5. Syntax 271 5.5.1. General 273 This section describes the syntax extensions to the ABNF syntax 274 defined in [RFC3261], by defining a new Via header field parameter, 275 "received-realm". The ABNF defined in this specification is 276 conformant to RFC 5234 [RFC5234]. "EQUAL", "LDQUOT", "RDQUOT" and 277 "ALPHA" are defined in [RFC3261]. "DIGIT" is defined in [RFC5234]. 279 5.5.2. ABNF 281 via-params =/ received-realm 282 received-realm = "received-realm" EQUAL operator-id COLON jws 283 operator-id = token 284 jws = LDQUOT header "." "." signature RDQUOT 285 header = *base64-char 286 signature = *base64-char 287 base64-char = ALPHA / DIGIT / "/" / "+" 289 EQUAL, COLON, token, LDQUOT, RDQUOT, ALPHA and DIGIT 290 as defined in RFC 3261. 292 5.6. Example 294 Via: SIP/2.0/UDP pc33.atlanta.com;branch=z9hG4bK776; 295 received-realm=myoperator:"eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1N.. 296 dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk" 298 NOTE: Line breaks for display purpose only 300 6. User Agent and Proxy behavior 302 6.1. General 304 This section describes how a SIP entity, acting as an entry point to 305 a network, uses the "received-realm" Via header field parameter. 307 6.2. Behavior of a SIP entity acting as a network entry point 309 When a SIP entity, acting as a network entry point, forwards a SIP 310 request, or initiates a SIP request on its own (e.g. a PSTN gateway), 311 the SIP entity adds a Via header field to the SIP request, according 312 to the procedures in RFC 3261 [RFC3261]. In addition, if the SIP 313 entity is able to assert the adjacent upstream network, and if the 314 SIP entity is aware of a network realm value defined for that 315 network, the SIP entity can add a "received-realm" Via header field 316 parameter, conveying the network realm value, to the Via header field 317 added to the SIP request. 319 When the SIP entity adds a "received-realm" Via header field 320 parameter to a SIP request, it MUST also calculate a Hash-based 321 message authentication code (HMAC) [RFC2104] value from the parameter 322 value, using a secret key which is shared between the SIP entity and 323 any SIP entity which will use the parameter value. The HMAC is then 324 added to the parameter. 326 When the receiver decodes the JWT, it MUST compare the JWT claims 327 with the corresponding SIP header field information. If there is a 328 mismatch, the receiver MUST discard the received-realm header field 329 parameter. 331 6.3. Behavior of a SIP entity consuming the received-network value 333 When a SIP entity receives a Via 'received-network' header field 334 parameter, and intends to perform actions based on the header field 335 parameter value, it MUST first re-calculate the JWS and check whether 336 the result matches the JWS received. If there is not a match the SIP 337 entity MUST discard the received 'received-network' header field 338 parameter. The SIP entity MAY take also take additional actions 339 (e.g. rejecting the SIP request) based on local policy. 341 7. Example 343 Operator 1 T_EP T_AS 345 - INVITE ------> 346 Via: SIP/2.0/UDP IP_UA 347 -- INVITE ----------------------------> 348 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 349 received-realm=myoperator:"eyJ0eXAiOiJKV1QiLA0KICJh 350 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 351 1gFWFOEjXk" 352 Via: SIP/2.0/UDP IP_UA; received=IP_UA 354 <- 200 OK ---------------------------- 355 Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776; 356 received-realm=myoperator:"eyJ0eXAiOiJKV1QiLA0KICJh 357 bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW 358 1gFWFOEjXk" 359 Via: SIP/2.0/UDP IP_UA; received=IP_UA 361 <- 200 OK------ 362 Via: SIP/2.0/UDP IP_UA; received=IP_UA 364 8. IANA Considerations 366 8.1. 'received-realm' Via header field parameter 368 This specification defines a new Via header field parameter called 369 received-realm in the "Header Field Parameters and Parameter Values" 370 sub-registry as per the registry created by [RFC3968]. The syntax is 371 defined in Section 5.5. The required information is: 373 Predefined 374 Header Field Parameter Name Values Reference 375 ---------------------- --------------------- ---------- --------- 376 Via received-realm No RFCXXXX 378 8.2. JSON Web Token Claims Registration 380 This specification defines new JSON Web Token claims in the "JSON Web 381 Token Claims" sub-registry as per the registry created by [RFC7519]. 383 Claim Name: "sip_from_tag" 385 Claim : SIP From tag header field parameter value 387 Change Controller: IESG 389 Specification Document(s): RFC XXXX, RFC 3261 391 Claim Name: "sip_date" 393 Claim Description: SIP Date header field value 395 Change Controller: IESG 397 Specification Document(s): RFC XXXX, RFC 3261 399 Claim Name: "sip_callid" 401 Claim Description: SIP Call-Id header field value 403 Change Controller: IESG 405 Specification Document(s): RFC XXXX, RFC 3261 407 Claim Name: "sip_cseq_num" 409 Claim Description: SIP CSeq numeric header field parameter value 410 Change Controller: IESG 412 Specification Document(s): RFC XXXX, RFC 3261 414 Claim Name: "sip_via_branch" 416 Claim Description: SIP Via branch header field parameter value 418 Change Controller: IESG 420 Specification Document(s): RFC XXXX, RFC 3261 422 9. Security Considerations 424 As the received-realm Via header field parameter can be used to 425 trigger applications, it is important to ensure that the parameter 426 has not been added to the SIP message by an unauthorized SIP entity. 428 The operator MUST change the key on a frequent basis. The operator 429 also needs to take great care in ensuring that the key used to 430 calculate the JWS signature value is only known by the network entry 431 point adding the received-realm Via header field parameter to a SIP 432 message and the entities that use the parameter value. 434 A SIP entity MUST NOT use the adjacent network information if there 435 is a mismatch between the JWS value received in the SIP header field 436 and the JWS calculated by the receiving entity. 438 A SIP entity MUST use different key values for each parameter value 439 that it recognizes and use to trigger actions. 441 Generic security considerations for JWS are defined in [RFC7515]. 443 10. Acknowledgements 445 Thanks to Adam Roach and Richard Barnes for providing comments and 446 feedback on the document. 448 11. Change Log 450 [RFC EDITOR NOTE: Please remove this section when publishing] 452 Changes from draft-holmberg-dispatch-received-realm-02 454 o JWT replaced with JWS. 456 o Appendix F of RFC 7515 applied. 458 Changes from draft-holmberg-dispatch-received-realm-01 460 o Define received-realm parameter value as a JSON Web Token (JWT). 462 Changes from draft-holmberg-dispatch-received-realm-00 464 o New version due to expiration of previous version. 466 Changes from draft-holmberg-received-realm-04 468 o Changed IETF WG from sipcore do dispatch. 470 o HMAC value added to the parameter. 472 Changes from draft-holmberg-received-realm-03 474 o New version due to expiration. 476 Changes from draft-holmberg-received-realm-02 478 o New version due to expiration. 480 Changes from draft-holmberg-received-realm-01 482 o New version due to expiration. 484 Changes from draft-holmberg-received-realm-00 486 o New version due to expiration. 488 12. References 490 12.1. Normative References 492 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 493 Requirement Levels", BCP 14, RFC 2119, 494 DOI 10.17487/RFC2119, March 1997, 495 . 497 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 498 A., Peterson, J., Sparks, R., Handley, M., and E. 499 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 500 DOI 10.17487/RFC3261, June 2002, 501 . 503 [RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax 504 Specifications: ABNF", STD 68, RFC 5234, 505 DOI 10.17487/RFC5234, January 2008, 506 . 508 [RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web 509 Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 510 2015, . 512 [RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token 513 (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, 514 . 516 12.2. Informative References 518 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed- 519 Hashing for Message Authentication", RFC 2104, 520 DOI 10.17487/RFC2104, February 1997, 521 . 523 [RFC3968] Camarillo, G., "The Internet Assigned Number Authority 524 (IANA) Header Field Parameter Registry for the Session 525 Initiation Protocol (SIP)", BCP 98, RFC 3968, 526 DOI 10.17487/RFC3968, December 2004, 527 . 529 Authors' Addresses 531 Christer Holmberg 532 Ericsson 533 Hirsalantie 11 534 Jorvas 02420 535 Finland 537 Email: christer.holmberg@ericsson.com 539 Yi Jiang 540 China Mobile 541 No.32 Xuanwumen West Street 542 Beijing Xicheng District 100053 543 P.R. China 545 Email: jiangyi@chinamobile.com