RFC 8055
Session Initiation Protocol (SIP) Via Header Field Parameter to Indicate Received Realm
Session Initiation Protocol (SIP) Via Header Field Parameter to Indicate Received Realm 🎀
okay bestie, this is RFC 8055 💖 It's a Standards Track doc from January 2017 (ISSN 2070-1721), written by C. Holmberg from Ericsson and Y. Jiang from China Mobile. The header doesn't list anything it obsoletes or updates, so it stands on its own ✨
Abstract ✨
okay so this spec defines a brand new SIP Via header field parameter called received-realm 🦋 It lets a SIP entity that's the entry point to a transit network say which adjacent upstream network a SIP request came in from, using a network realm value that belongs to that neighbouring network.
Status of This Memo 💅
this is an Internet Standards Track document 🔥
it's a product of the Internet Engineering Task Force (IETF) and it represents the consensus of the IETF community. it went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). if you want more on Internet Standards, check Section 2 of RFC 7841 🧚
info about the current status, any errata, and how to send feedback lives at http://www.rfc-editor.org/info/rfc8055 🌸
Copyright Notice 🫶
Copyright (c) 2017 IETF Trust and the persons identified as the document authors. All rights reserved.
this doc is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as they were on the date it was published. please actually read those, bestie, because they spell out your rights and restrictions for this document. any Code Components pulled out of this document have to include Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come with no warranty, as described in the Simplified BSD License 🙈
Table of Contents 🍓
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.2. Use Case: Transit Network Application Services . . . . . 3
1.3. Use Case: Transit Network Routing . . . . . . . . . . . . 4
2. Applicability . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Via 'received-realm' Header Field Parameter . . . . . . . . . 5
5.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 5
5.2. Operator Identifier . . . . . . . . . . . . . . . . . . . 5
5.3. JWS Header . . . . . . . . . . . . . . . . . . . . . . . 6
5.4. JWS Payload . . . . . . . . . . . . . . . . . . . . . . . 6
5.5. JWS Serialization . . . . . . . . . . . . . . . . . . . . 7
5.6. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.6.1. General . . . . . . . . . . . . . . . . . . . . . . . 8
5.6.2. ABNF . . . . . . . . . . . . . . . . . . . . . . . . 8
5.7. Example: SIP Via Header Field . . . . . . . . . . . . . . 8
6. User Agent and Proxy Behavior . . . . . . . . . . . . . . . . 8
6.1. General . . . . . . . . . . . . . . . . . . . . . . . . . 8
6.2. Behavior of a SIP Entity Acting as a Network Entry Point 8
6.3. Behavior of a SIP Entity Consuming the 'received-realm'
Value . . . . . . . . . . . . . . . . . . . . . . . . . . 9
7. Example: SIP INVITE Request and Response . . . . . . . . . . 9
8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
8.1. 'received-realm' Via Header Field Parameter . . . . . . . 10
8.2. JSON Web Token Claims Registration . . . . . . . . . . . 10
9. Security Considerations . . . . . . . . . . . . . . . . . . . 11
10. References . . . . . . . . . . . . . . . . . . . . . . . . . 11
10.1. Normative References . . . . . . . . . . . . . . . . . . 11
10.2. Informative References . . . . . . . . . . . . . . . . . 12
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 13
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 141. Introduction 🌈
1.1. General 💖
okay so when Session Initiation Protocol (SIP) [RFC3261] sessions get set up between networks owned by different operators, or between interconnected networks owned by the same operator (or enterprise), the SIP requests for that session might travel through transit networks 🦋
transit networks can offer all kinds of services ✨ to provide them, a transit network often needs to know which operator (or enterprise) owns the adjacent upstream network that the SIP session initiation request came from 👑
this spec defines a new SIP Via header field parameter, received-realm, which lets a SIP entity acting as an entry point to a transit network say which adjacent upstream network a SIP request came from, using a network realm value tied to that adjacent network 🎀
NOTE: As the adjacent network can be an enterprise network, an Inter Operator Identifier (IOI) cannot be used to identify the network because IOIs are not defined for enterprise networks.
the next sections describe use cases where this info is needed 🧚
1.2. Use Case: Transit Network Application Services 🫶
the Third Generation Partnership Project (3GPP) TS 23.228 [TS.3GPP.23.228] explains how an IP Multimedia Subsystem (IMS) network can be used to provide transit functionality 🔥 an operator can use its IMS network for transit, for example for non-IMS customers, enterprise networks, and other network operators 💅
the transit network operator can offer application services to the networks it provides transit for 🌸 transit application services usually aren't offered per user, because the transit network doesn't have access to the user profiles of those networks 🙈 so instead, the services are provided per served network ✨
when a SIP entity that provides application services (for example, an Application Server) inside a transit network gets a SIP request, it needs to know which adjacent upstream network the request came from, so it can apply the correct services 💜
1.3. Use Case: Transit Network Routing 🍓
a transit network operator usually interconnects with lots of different operators, including other transit network operators 🦋 it provides transit routing for SIP requests coming in from one operator's network and sends them on toward the destination 👑 the destination can sit inside an operator network that the transit operator has a direct interconnect with, or inside an operator network that can only be reached through one or more interconnected transit operators 🌈
for each customer (that is, each interconnected network operator) whose SIP requests the transit operator routes toward the requested destination, there's a set of transit routing policies 💅 those policies decide how a SIP request gets routed to the destination, so the transit operator keeps its agreement with that customer 🎀
when a SIP entity doing transit routing gets a SIP request, it needs to know which customer (that is, which adjacent upstream network) the request came from, so it can apply the right set of transit routing policies 🧚
2. Applicability ✨
okay so the mechanism in this spec MUST only be used by SIP entities that are able to verify which adjacent upstream network a SIP request came from 🔥
how you verify that is outside the scope of this spec 🙈 it could be based on things like receiving the SIP request over an authenticated Virtual Private Network (VPN), on a specific IP address, or on a specific network access 🫶
3. Conventions 🌸
the key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14, RFC 2119 [RFC2119] 💖
4. Definitions 💅
okay here's the vocab you need to know 🦋
SIP entity: a SIP User Agent (UA), or SIP proxy, as defined in RFC 3261 ✨
Adjacent upstream SIP network: the adjacent SIP network in the direction a SIP request is received from 👑
Network entry point: a SIP entity on the border of the network that receives SIP requests from adjacent upstream networks 🌈
Inter Operator Identifier (IOI): a globally unique identifier used to correlate billing information generated within the IP Multimedia Subsystem (IMS) 🎀
JWS: a JSON Web Signature, as defined in [RFC7515] 🧚
5. Via 'received-realm' Header Field Parameter 🔥
5.1. General 💜
the Via 'received-realm' header field parameter value is written as a combo of two things: an operator identifier whose value represents the adjacent network, and a serialized JSON Web Signature (JWS) [RFC7515] 🦋 the JWS Payload contains the operator identifier and other SIP information element values 💖
the procedures for encoding the JWS and calculating the signature are defined in [RFC7515] ✨ since the JWS Payload info already lives in other SIP information elements, the JWS Payload gets detached from the serialized JWS that rides along in the header field parameter, as described in Appendix F of [RFC7515] 🌸 the operator identifier and the serialized JWS are separated by a colon character 🫶
5.2. Operator Identifier 🌈
the operator identifier is a token value that represents the adjacent operator 💅 its scope is only within the network that inserts the value 🎀
the operator identifier value is case insensitive 🍓
5.3. JWS Header 👑
the following header parameters MUST be included in the JWS 🔥
- The "typ" parameter MUST have a "JWT" value.
- The "alg" parameter MUST have the value of the algorithm used to calculate the JWS.
NOTE: Operators need to agree on the set of supported algorithms for calculating the JWT signature.
NOTE: The "alg" parameter values for specific algorithms are listed in the IANA JSON Web Signature and Encryption Algorithms sub-registry of the JSON Object Signing and Encryption (JOSE) registry. Operators need to use algorithms for which an associated "alg" parameter value has been registered. The procedures for defining new values are defined in [RFC7518] 🧚
Example:
{
"typ":"JWT",
"alg":"HS256"
}5.4. JWS Payload 💖
okay so the JWS Payload is where all the juicy info lives 🫶 these claims MUST be included in it:
sip_from_tagholds the value of the From 'tag' header field parameter of the SIP message 🎀sip_dateholds the value of the Date header field in the SIP message, encoded in JSON NumericDate format [RFC7519] 🗓️sip_callidholds the value of the Call-ID header field in the SIP message 📞sip_cseq_numholds the numeric value of the CSeq header field in the SIP message 🔢sip_via_branchholds the value of the Via branch header field parameter of the Via header field in the SIP message, the one the 'received-realm' header field parameter is attached to 🌿sip_via_opidholds the operator identifier part of the Via 'received-realm' header field parameter of that same Via header field 👑
Example:
{
"sip_from_tag":"1928301774",
"sip_date":1472815523,
"sip_callid":"a84b4c76e66710@pc33.atlanta.com",
"sip_cseq_num":"314159",
"sip_via_branch":"z9hG4bK776asdhds",
"sip_via_opid":"myoperator"
}5.5. JWS Serialization 🧁
okay this part is so important, bestie. the JWS Payload isn't carried in the 'received-realm' parameter, so the sender and the receiver need to build the JWS Payload object in exactly the same way, or everything falls apart 😭 so the JSON representation of the JWS Payload object MUST be computed like this:
- All claims MUST be encoded using lowercase characters.
- The claims MUST be in the same order as listed in Section 5.4.
- All claims except "sip_date" MUST be encoded as StringOrURI JSON string value [RFC7519].
- The "sip_date" claim MUST be encoded as a JSON NumericDate value [RFC7519].
- The JWS Payload MUST follow the rules for the construction of the thumbprint of a JSON Web Key (JWK) as defined in Section 3, Step 1 only, of [RFC7638].
Example:
{"sip_from_tag":"1928301774","sip_date":1472815523,
"sip_callid":"a84b4c76e66710@pc33.atlanta.com",
"sip_cseq_num":"314159","sip_via_branch":"z9hG4bK776asdhds",
"sip_via_opid":"myoperator"}NOTE: Line breaks are for display purposes only.
5.6. Syntax 🎀
5.6.1. General 🌸
this section adds syntax to the ABNF already defined in [RFC3261] by introducing a brand new Via header field parameter, 'received-realm'. the ABNF in this spec is conformant to RFC 5234 [RFC5234]. "EQUAL", "LDQUOT", "RDQUOT", and "ALPHA" are defined in [RFC3261], and "DIGIT" is defined in [RFC5234] ✨
5.6.2. ABNF 🧩
via-params =/ received-realm
received-realm = "received-realm" EQUAL LDQUOT op-id COLON jws RDQUOT
op-id = token
jws = header ".." signature
header = 1*base64-char
signature = 1*base64-char
base64-char = ALPHA / DIGIT / "/" / "+"EQUAL, COLON, token, LDQUOT, RDQUOT, ALPHA, and DIGIT are as defined in [RFC3261].
NOTE: The two adjacent dots in the 'jws' part are due to the detached payload being replaced by an empty string [RFC7515].
5.7. Example: SIP Via Header Field 🦋
Via: SIP/2.0/UDP pc33.example.com;branch=z9hG4bK776;
received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJhbGciOiJIUzI1N..
dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"NOTE: Line breaks are for display purposes only.
6. User Agent and Proxy Behavior 🌈
6.1. General 🫧
this section covers how a SIP entity, acting as an entry point to a network, uses the 'received-realm' Via header field parameter 💅
6.2. Behavior of a SIP Entity Acting as a Network Entry Point 🚪
when a SIP entity acting as a network entry point forwards a SIP request, or starts a SIP request on its own (like a Public Switched Telephone Network (PSTN) gateway, for example), it adds a Via header field to the SIP request following the procedures in RFC 3261 [RFC3261]. lowkey the extra bit: if the SIP entity is able to assert the adjacent upstream network, and it knows about a network realm value defined for that network, it can add a 'received-realm' Via header field parameter. that parameter carries the network realm value as the operator identifier (Section 5.2) part of the header field parameter, and it goes on the Via header field added to the SIP request ✨
on top of that, the SIP entity MUST also calculate a JWS (Section 5.4) and add the calculated JWS Header and JWS Signature as the 'jws' part of the Via header field parameter 🔐
6.3. Behavior of a SIP Entity Consuming the 'received-realm' Value 🕵️♀️
so when a SIP entity gets a Via 'received-realm' header field parameter and wants to do something based on its value, it MUST first recalculate the JWS and check whether the result matches the JWS it received. if it doesn't match, the SIP entity MUST discard the received 'received-realm' header field parameter 🙅♀️ the SIP entity MAY also take additional actions (e.g., rejecting the SIP request) based on local policy 🫶
7. Example: SIP INVITE Request and Response 🎬
this section shows an example of a SIP INVITE request and the response that goes with it. the Via header field gets inserted into the request and removed from the response by the T_EP SIP proxy, and it carries a 'received-realm' header field parameter 🍿
Operator 1 T_EP T_AS
- INVITE ------>
Via: SIP/2.0/UDP IP_UA
-- INVITE ---------------------------->
Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776;
received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJh
bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW
1gFWFOEjXk"
Via: SIP/2.0/UDP IP_UA; received=IP_UA
<- 200 OK ----------------------------
Via: SIP/2.0/UDP IP_TEP;branch=z9hG4bK776;
received-realm="myoperator:eyJ0eXAiOiJKV1QiLA0KICJh
bGciOiJIUzI1N..dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW
1gFWFOEjXk"
Via: SIP/2.0/UDP IP_UA; received=IP_UA
<- 200 OK------
Via: SIP/2.0/UDP IP_UA; received=IP_UA8. IANA Considerations 📋
8.1. 'received-realm' Via Header Field Parameter 🗂️
this spec defines a new Via header field parameter called 'received-realm' in the "Header Field Parameters and Parameter Values" sub-registry created by [RFC3968]. its syntax is in Section 5.6. the required info is:
Predefined
Header Field Parameter Name Values Reference
---------------------- --------------------- ---------- ---------
Via received-realm No RFC 80558.2. JSON Web Token Claims Registration 🪪
this spec defines new JSON Web Token claims in the "JSON Web Token Claims" sub-registry created by [RFC7519] ✨
Claim Name: sip_from_tag
Claim Description: SIP From tag header field parameter value
Change Controller: IESG
Reference: RFC 8055, RFC 3261
Claim Name: sip_date
Claim Description: SIP Date header field value
Change Controller: IESG
Reference: RFC 8055, RFC 3261
Claim Name: sip_callid
Claim Description: SIP Call-Id header field value
Change Controller: IESG
Reference: RFC 8055, RFC 3261
Claim Name: sip_cseq_num
Claim Description: SIP CSeq numeric header field parameter value
Change Controller: IESG
Reference: RFC 8055, RFC 3261
Claim Name: sip_via_branch
Claim Description: SIP Via branch header field parameter value
Change Controller: IESG
Reference: RFC 8055, RFC 32619. Security Considerations 🚨
this one is serious, bestie. the 'received-realm' Via header field parameter can be used to trigger applications, so it is super important to make sure the parameter hasn't been added to the SIP message by an unauthorized SIP entity 😤
the 'received-realm' Via header field parameter is inserted, signed, verified, and consumed within an operator network. the operator MUST discard parameters received from another network, and the parameter MUST only be inserted by SIP entities that are able to verify from which adjacent upstream network a SIP request is received 🛡️
the operator also needs to take great care in making sure the key used to calculate the JWS Signature value is only known by the network entities that sign and add the JWS Signature to the 'received-realm' Via header field parameter of a SIP message, and by the network entities that verify and consume the parameter value 🔑
the operator MUST use a key management policy that protects against unauthorized access to the stored keys within the nodes where the keys associated with the JWS Signature are stored. it must also protect against cryptoanalysis attacks using captured data sent on the wire 🥺
a SIP entity MUST NOT use the adjacent network information if there is a mismatch between the JWS Signature received in the SIP header field and the JWS Signature calculated by the receiving entity 🙅♀️
generic security considerations for JWS are defined in [RFC7515] 🔐
10. References 📚
10.1. Normative References 🌷
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997,
<http://www.rfc-editor.org/info/rfc2119>.
[RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
A., Peterson, J., Sparks, R., Handley, M., and E.
Schooler, "SIP: Session Initiation Protocol", RFC 3261,
DOI 10.17487/RFC3261, June 2002,
<http://www.rfc-editor.org/info/rfc3261>.
[RFC5234] Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234,
DOI 10.17487/RFC5234, January 2008,
<http://www.rfc-editor.org/info/rfc5234>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <http://www.rfc-editor.org/info/rfc7515>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<http://www.rfc-editor.org/info/rfc7519>.
[RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK)
Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
2015, <http://www.rfc-editor.org/info/rfc7638>.10.2. Informative References 🌟
[RFC3968] Camarillo, G., "The Internet Assigned Number Authority
(IANA) Header Field Parameter Registry for the Session
Initiation Protocol (SIP)", BCP 98, RFC 3968,
DOI 10.17487/RFC3968, December 2004,
<http://www.rfc-editor.org/info/rfc3968>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015,
<http://www.rfc-editor.org/info/rfc7518>.
[TS.3GPP.23.228]
3GPP, "IP Multimedia Subsystem (IMS); Stage 2", 3GPP
TS 23.228 14.1.0, September 2016,
<http://www.3gpp.org/ftp/Specs/html-info/23228.htm>.Acknowledgements 🫶
thanks to Adam Roach and Richard Barnes for comments and feedback on the document 💜 Francis Dupoint performed the Gen-ART review 🎀
Authors' Addresses 🦋
Christer Holmberg
Ericsson
Hirsalantie 11
Jorvas 02420
Finland
Email: christer.holmberg@ericsson.com
Yi Jiang
China Mobile
No.32 Xuanwumen West Street
Beijing Xicheng District 100053
China
Email: jiangyi@chinamobile.com📦 where this page comes from
- ietf: rfc8055 2017-01
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms