RFC 7544

Mapping and Interworking of Diversion Information between Diversion and History-Info Header Fields in the Session Initiation Protocol (SIP)

📅 published August 2015, from ietf

RFC 7544: Mapping and Interworking of Diversion Information between Diversion and History-Info Header Fields in the Session Initiation Protocol (SIP) ✨

okay bestie, title block first! 🎀

  • Stream: Independent Submission
  • Author: M. Mohali (Orange) 💼
  • Date: August 2015 📅
  • Category: Informational 🌸
  • ISSN: 2070-1721
  • Obsoletes: RFC 6044 (so this one replaces it) 🦋

Abstract

okay so the SIP History-Info header field from RFC 7044 is the official IETF fix 👑, but the Diversion header field from RFC 5806 (marked Historic) is already out there in real networks doing its thing for call-diversion info 💅. Nobody is ripping it out, so we need a way for the two to talk to each other. 🫶

RFC 7044 obsoletes the original RFC 4244 and redefines History-Info so it can capture history info in requests. 🧚

Since Diversion is already running in existing networks, its interworking with the standardized History-Info solution is needed. This doc gives a recommended interworking guideline between Diversion and History-Info for handling call diversion info. The whole point is helping people migrate from the non-standard stuff to IETF spec-based implementations. It's giving migration era 🚀✨

This document obsoletes RFC 6044, which covered interworking between the Diversion header field from RFC 5806 and the History-Info header field from RFC 4244 (now obsoleted). 🌈

Status of This Memo

not gonna lie, this part is a little dry, but it matters 🙈

This document is not an Internet Standards Track specification. It's published for informational purposes. 📚

It's a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor picked to publish it at their discretion and makes no statement about its value for implementation or deployment. Documents the RFC Editor approves for publication are not candidates for any level of Internet Standard (see Section 2 of RFC 5741). 💖

For the current status, any errata, and how to give feedback, check http://www.rfc-editor.org/info/rfc7544. 🔗

Copyright (c) 2015 IETF Trust and the persons identified as the document authors. All rights reserved. ©️

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the publication date. Please read them carefully, because they spell out your rights and restrictions for this document. 🧾

Table of Contents 🗂️

1. Introduction ....................................................4
   1.1. Overview ...................................................4
   1.2. Background .................................................4
   1.3. From RFC 4244 to RFC 7044 ..................................5
2. Problem Statement ...............................................5
3. Interworking Recommendations ....................................7
   3.1. General Recommendations ....................................7
   3.2. Privacy Considerations .....................................8
   3.3. Headers in SIP Method .....................................10
   3.4. SIP Network/Terminal Using Diversion Header Field
        to SIP Network/Terminal Using History-Info Header Field ...10
   3.5. SIP Network/Terminal Using History-Info Header
        Field to SIP Network/Terminal Using Diversion
        Header Field ..............................................12
4. Reminder of the Syntax for Header Fields .......................13
   4.1. History-Info Header Field Syntax ..........................13
   4.2. Diversion Header Field Syntax .............................16
5. Diversion Header Field to History-Info Header Field ............16
6. History-Info Header Field to Diversion Header Field ............20
7. Examples .......................................................22
  7.1.  Example with Diversion Header Field Changed into
        History-Info Header Field .................................22
  7.2.  Example with History-Info Header Field Changed into
        Diversion Header Field ....................................22
  7.3.  Example with Two SIP Networks Using History-Info Header
        Field Interworking with a SIP Network Using Diversion
        Header Field ..............................................22
  7.4.  Additional Interworking Cases .............................24
8. Backward Compatibility .........................................26
9. Security Considerations ........................................26
10. References ....................................................26
   10.1. Normative References .....................................26
   10.2. Informative References ...................................27
Appendix A.  Interworking between Diversion Header Field and
             Voicemail URI ........................................29
  A.1.  Diversion Header Field to Voicemail URI ...................29
  A.2.  Voicemail URI to Diversion Header Field ...................29
Acknowledgements ..................................................30
Author's Address ..................................................30

1. Introduction ✨

1.1. Overview

okay so for some VoIP services (like voicemail, IVR, or automatic call distribution), it's really helpful for the called SIP user agent to know who diverted the session and why 🕵️‍♀️. For that info to be useful to service providers and apps, it has to travel through the network. There are two SIP header fields that can do this: History-Info, defined in [RFC7044], and the historic Diversion header field, defined in [RFC5806]. Both can carry diversion info in SIP signaling. 🦋

Diversion was never standardized, but it got widely implemented 💅. So it's useful to have guidelines that let it interwork with the standard History-Info header field.

Heads up: new implementation and deployment of the Diversion header field are strongly discouraged. 🙅‍♀️

This document gives a way to translate header field content between Diversion and History-Info. 🔁

This document obsoletes [RFC6044]. 🌸

1.2. Background

The obsoleted History-Info header field [RFC4244], plus its extension for forming SIP service URIs (including the Voicemail URI) [RFC4458], used to be what IETF recommended for conveying redirection info. They were also recommended in the Communication Diversion (CDIV) 3GPP specification [TS_24.604]. 📡

Diversion was first described in a document submitted to the SIP Working Group. It was eventually published as an Independent Submission, [RFC5806], for the historical record, and it's the reference for this RFC. 📜

This header field holds a list of diverting URIs plus associated info giving the specific reason for the call diversion. Most of the first SIP-based implementations went with Diversion because there was no standard solution ready to deploy yet 🥲. The IETF later standardized History-Info, partly because it can carry general history info, not just diversion stuff. ✨

That lets the receiving party figure out how and why the session arrived. Since History-Info can hold more than diversion info, it's really important not to lose anything 🙀. To pull out the relevant data, use the retargeting cause URI parameter described in [RFC4458] to carry the call forwarding reason.

Diversion and History-Info have different syntaxes, which this document describes. The big difference is direction: History-Info is a chronological header, while Diversion runs in reverse chronology (the first diversion entry you read is the last diverting user) 🔄. Plot twist, right?

Appendix A has an interworking guideline between Diversion and the Voicemail URI, which is another way to convey diversion info without using History-Info. The Voicemail URI is defined in [RFC4458]. 📬

1.3. From RFC 4244 to RFC 7044

The full story of why and how [RFC4244] got obsoleted by [RFC7044] is in Section 16 of [RFC7044] 📖.

These are the main changes for implementing History-Info:

  1. The header field parameters mp, rc, and np were added to capture the specific method used to determine a target. 🎯
  2. You can now show a gap in the History-Info header field by using a 0 in the index. 🕳️
  3. For privacy, entries get anonymized instead of removed. 🫥
  4. Many SHOULDs were changed into MUSTs to make the header more reliable. 💪

Backward-compatibility aspects are covered in Section 8 of this document. 🌈

2. Problem Statement ✨

okay bestie, this section is the vocab check 📚 It sets up the words we use for the rest of the doc and says how far the interworking goes 🎀

There are so many ways SIP signaling can change where a session is headed before it connects 🦋 and so many reasons to do it. The stuff downstream that has to keep handling the session can act differently depending on why the destination changed. Like, is it just a simple proxy routing the call, or is an application server (AS) giving a supplementary service? 🤔 The Diversion header field and the History-Info header field tackle this problem in different ways, so they have kinda different vibes 💅

Okay, here's the vocab we're using ✨

  • Retarget/redirect 🎯: these words mean a Proxy Server/User Agent Client (UAC) changing a Request-URI (Section 7.1 of [RFC3261]) in a request, which changes where the request is going. That includes changing the Request-URI because of a location service lookup and redirect processing. It also includes changes a proxy/SIP intermediary makes to the URI internally before forwarding the request. The term "retarget" is defined in [RFC7044].
  • Call forwarding/call diversion/communication diversion 📞: these all mean the same thing 💕 and they refer to the Communications Diversion (CDIV) supplementary services. Those are based on the ISDN Communication diversion supplementary services and defined in 3GPP [TS_24.604]. They apply to entities that are meant to change the original destination of an IP multimedia session during or before session establishment.

This doc doesn't try to say when or how History-Info or Diversion should be used 🙅‍♀️ It just explains the context where interworking is needed 🫶

The Diversion header field has exactly the same scope as the call diversion service, and each header field entry reflects one call diversion invocation ✨ It's used to record call forwarding info that could be useful to network entities downstream. Right now, several manufacturers implement this header and it's deployed in networks 🌍

The History-Info header field stores all retargeting info, call diversion included 🧠 So the History-Info header field [RFC7044] conveys call-diversion info by using a cause URI parameter [RFC4458] in the relevant entry.

BUT (ngl, this is the important part 🚨) using the cause URI parameter [RFC4458] in a History-Info entry for call diversion is specific to the 3GPP spec [TS_24.604]. [RFC4458] focuses on retargeting toward a voicemail server and doesn't say whether the cause URI parameter should be added in a URI for other cases. So implementations that don't use the cause URI parameter for call forwarding info aren't considered for the mapping in this doc 🙃 Still, some recommendations come later on how to avoid losing non-mapped info at the boundary between a network region using History-Info and one using Diversion 🌉

[RFC7044] defines three header field parameters: rc, mp, and np 🧩 The rc and mp parameters indicate the mechanism by which a new target for a request is determined. The np parameter reflects that the target has not changed. Every parameter contains an index whose value refers to the hi-index of the hi-entry, which holds a hi-targeted-to-uri that represents the Request-URI that was retargeted.

Since both header fields handle call forwarding, diverting info could get mixed up or be inconsistent if both show up uncoordinated in the INVITE request 😬 So Diversion and History-Info must not independently coexist in the same session signaling 🚫 This doc covers how to convert info between the two, and when and how to preserve both header fields to cover additional cases.

For consistent diversion info to travel downstream, the two header fields need to interwork 🔁 Interworking between them is introduced in Sections 5 and 6. Since the coexistence scenario varies from one use case to another, guidelines on how the header fields interact are proposed in Section 3.

3. Interworking Recommendations 🌷

3.1. General Recommendations

Interworking function (IWF) 🛠️

In a normal case, the network topology assumption is that the interworking described in this doc should be performed by a specific SIP border device. That device is aware, by configuration, that it sits at the border between two regions: one using the History-Info header field and one using the Diversion header field 🧱

As the History-Info header field is a standard solution, a network using the Diversion header field must be able to provide information to a network using the History-Info header field 🤝 In this case, to avoid coexistence of header fields, it is required to replace the Diversion header field with the History-Info header field in the INVITE request during the interworking, as often as possible 🔄

Since the History-Info header field has a wider scope than the Diversion header field, it may be used for needs and services other than call diversion 🌈 On top of that, to trace call diversion info, the History-Info header field also acts as a session history and can store all successive Request-URI values 📜 So even though it would be better to remove the History-Info header field after the Diversion header field is created, to avoid confusion, the History-Info header field must remain unmodified in the SIP signaling if it contains supplementary (non-diversion) information 🙌 It's possible to have History-Info header fields whose values can't be mapped into the Diversion header field. In that case, no interworking with the Diversion header field should be performed, and it must be defined per implementation what to do. That point is out of scope for this doc 🙊

In conclusion, it is recommended to have local policies that minimize the loss of information and find the best way to keep it up to the terminating user agent 💖

The following sections describe the basic use cases. Additional interworking cases are described in Section 7.4 ✨

3.2. Privacy Considerations

When a SIP message is forwarded to a domain the SIP intermediary isn't responsible for, a Privacy Service at the boundary of the domain applies the appropriate privacy, based on the value of the Privacy header field in the message header or in the privacy parameter within the concerned header 🔐

  1. For the History-Info header field, it is the Privacy header field included as the "headers" component of the hi-targeted-to-uri in the individual hi-entries with the priv-value "history".
  2. For the Diversion header field, it is the diversion-privacy parameter "privacy" in each Diversion header field.

For the History-Info header field, as recommended in [RFC7044]:

  • If there is a Privacy header field in the message header of a request with a priv-value of "header" or "history", then all the hi-targeted-to-uris (in the hi-entries associated with the domain for which the SIP intermediary is responsible) are anonymized by the Privacy Service. The Privacy Service must change any hi-targeted-to-uri in these hi-entries that have not been anonymized to the anonymous SIP URI anonymous@anonymous.invalid, as recommended in Sections 4.1.1.2 and 4.1.1.3 of [RFC3323] 🫣
  • If there is a Privacy header field in the "headers" component of a hi-targeted-to-uri with a priv-value of "history", then all the concerned hi-entries must be anonymized as described above prior to forwarding 🙈

The Privacy Service must remove the Privacy header field from the "headers" component of the hi-targeted-to-uris of the concerned hi-entries, and the priv-value of "history" from the Privacy header field in the message header of the request, prior to forwarding 🧹 If there are no remaining priv-values in the Privacy header field, the Privacy Service must remove the Privacy header field from the request 💅

For the Diversion header field:

  • If there is a Privacy header field in the message header of a request with a priv-value of "header", then all the addresses in the Diversion header fields (associated with the domain for which the SIP intermediary is responsible) are anonymized by the Privacy Service, by changing each address to the anonymous SIP URI anonymous@anonymous.invalid, as recommended in Sections 4.1.1.2 and 4.1.1.3 of [RFC3323], prior to forwarding 🎭
  • For each Diversion header field or each entry in the Diversion header field, if there is a diversion-privacy parameter with a value set to "full", "uri", or "name", then the concerned Diversion header field address must be anonymized as described above prior to forwarding 🌙

In the concerned Diversion header field entries, the diversion-privacy parameter must be removed from the header 🧽

The privacy info interworking described in Sections 5 and 6 must only be considered within a trusted domain that ensures the privacy requirements are applied correctly 🏰

3.3. Headers in SIP Method

The recommended interworking presented in this doc should apply only to INVITE requests 📨

In 3xx responses:

Both History-Info and Diversion header fields could be present in 3xx responses 🦋

When a proxy wants to interwork with a network that supports the other header field, it should apply the interworking between the Diversion header field and the History-Info header field in the 3xx response 🔀

When a recursing proxy redirects an initial INVITE after receiving a 3xx response, it should add as a last entry either a Diversion header field or a History-Info header field (according to its capabilities) in the forwarded INVITE 🎀 Local policies could apply regarding whether or not to send the received header field in the next INVITE 📋

In SIP responses other than 100:

All SIP responses where the History-Info header field could be present are not used for the call forwarding service and should not be changed into the Diversion header field 🙅‍♀️ The destination network must be transparent to the received History-Info header field 🫥

Note: The following mapping is inspired by the ISDN User Part (ISUP) to SIP interworking described in [TS_29.163] 🌸

3.4. SIP Network/Terminal Using Diversion Header Field to SIP Network/Terminal Using History-Info Header Field 🦋

okay so when you're making a History-Info header from a Diversion header, the Diversion header must be removed from the outgoing INVITE 💅 it's assumed that everything in Diversion gets moved over into History-Info, so nothing is lost. no cap, that's the whole point 🎀

now, if the incoming INVITE has History-Info and Diversion, the two have to get mixed together 🫶 you only add the diversion info that isn't already in History-Info, and you tack it on as the last entry (aka the most recent one). you follow the creation process recommended in [RFC7044] for this, bestie ✨

here's a lowkey iconic example: an INVITE comes in from network_2 using Diversion, but it already went through network_1 using History-Info (or network_2 uses History-Info to carry along successive URI info), and now it's headed to network_3 using History-Info 🧚

                    IWF*                                  IWF*
  network_1          |                network_2            |network_3
 History-Info        |                 Diversion           |using
                     |                                     |History-
                     |                                     |Info
UA A    P1     AS B     |       P2     AS C    UA C   AS D    |     UA E
|       |       |       |       |       |       |     |       |        |
|INVITE |       |       |       |       |       |     |       |        |
|------>|       |       |       |       |       |     |       |        |
|       |       |       |       |       |       |     |       |        |
|       |INVITE |       |       |       |       |     |       |        |
|       |------>|       |       |       |       |     |       |        |
|       |Supported: histinfo    |       |       |     |       |        |
|       | History-Info:         |       |       |     |       |        |
|       | <sip:proxyP1>;index=1,|       |       |     |       |        |
|       | <sip:userB>;index=1.1;rc=1    |       |     |       |        |
|       |       |       |       |       |       |     |       |        |
|       |       |INVITE |       |       |       |     |       |        |
|       |       |------>|       |       |       |     |       |        |
|       |       |History-Info:  |       |       |     |       |        |
|       |       |<sip:proxyP1>;index=1, |       |     |       |        |
|       |       |<sip:userB>;index=1.1;rc=1,    |     |       |        |
|       |       |<sip:userC;cause=302>;index=1.1.1;mp=1.1     |        |

so in this case the incoming INVITE has both a Diversion header and a History-Info header 🌸 that means, as recommended in this document, network_3 needs one single History-Info header that gathers the existing info from both the History-Info and the Diversion headers you got. 😭 but also, network_2 (the IWF) is required to remove the Diversion header when the message is heading to a network that doesn't use Diversion. then network_3 can use the call forwarding info sitting in one header, and add its own diversion info if it needs to 💖

Notes:
  1. if a network can't either use only one header field each time or keep both headers up to date, the chronological order can't be certified 💀
  2. it's not possible to have only a Diversion header when History-Info holds more than call diversion info 🙈 if the previous policy recommendations are followed, the chronological order stays intact, because Diversion entries get inserted at the end of History-Info while respecting the Diversion internal chronology 👑

3.5. SIP Network/Terminal Using History-Info Header Field to SIP Network/Terminal Using Diversion Header Field 🌈

when you're turning History-Info into a Diversion header, you gotta be careful 🥹

if History-Info has only call forwarding info, it must be deleted after the interworking, bye bye 👋

if it has other stuff in it too, then only the info that matters to the diverting user gets used to make Diversion entries 🍓 and the History-Info header must be kept as received in the INVITE and forwarded downstream. 🫶

Note: History-Info can be used for stuff other than call diversion, like a service that needs to know if a specific AS has already been invoked in the signaling path 🧠 if the call gets forwarded later to a network that uses History-Info, it's way better to not lose that history just because it passed through a network that only does Diversion 😭 a recommended solution must not disrupt the standard behavior, and networks that don't implement History-Info must be transparent to a received History-Info header 🎀

if the incoming INVITE has a Diversion header in addition to History-Info, then only the diversion info that's in History-Info but not in Diversion gets added, starting from the last entry (most recent) and going into the existing Diversion header, as recommended in [RFC5806] ✨

the chronological order could not be certified here 💀 if the previous policy recommendations were respected, this case should not happen, bestie.

Forking case: History-Info lets you record sequential forking for the same served user 🦋 when you interwork from History-Info to Diversion, entries that show a forking situation (the ones with an incremented "index" parameter) could get mapped if they have a call forwarding "cause" parameter 🔥 the interworking entity can either create only a Diversion entry or skip the interworking altogether, and that choice can be made according to local policy 🧚

the same logic applies for interworking with a Voicemail URI (see Appendix A) 📬

4. Reminder of the Syntax for Header Fields 💅

4.1. History-Info Header Field Syntax ✨

okay bestie, here's the ABNF [RFC5234] for the History-Info header field and its header field parameters 💖

History-Info       = "History-Info" HCOLON hi-entry *(COMMA hi-entry)
hi-entry           = hi-targeted-to-uri *(SEMI hi-param)
hi-targeted-to-uri = name-addr
hi-param           = hi-index/hi-target-param/hi-extension
hi-index           = "index" EQUAL index-val
index-val          =  number *("." number)
number             =  [ %x31-39 *DIGIT ] DIGIT
hi-target-param    = rc-param / mp-param / np-param
rc-param           = "rc" EQUAL index-val
mp-param           = "mp" EQUAL index-val
np-param           = "np" EQUAL index-val
hi-extension       = generic-param

The ABNF definitions for "generic-param", "name-addr", "HCOLON", "COMMA", "SEMI", and "EQUAL" come from [RFC3261] 🎀

The History-Info header field is specified in [RFC7044]. The top-most History-Info entry (the first one in the list) corresponds to the oldest history information 🌸

Cause URI parameter:

A hi-entry may contain a cause URI parameter that expresses the diversion reason. This cause URI parameter is defined in [RFC4458]. The ABNF grammar [RFC5234] for the cause-param parameter is shown below, because it has been subject to Erratum ID 1409 [Err1409] for [RFC4458]. The Status-Code is defined in [RFC3261] 🦋

cause-param = "cause=" Status-Code

The cause-param parameter is a SIP/SIPS URI parameter. It should be inserted in the History-Info entry (URI) of the diverted-to user in case of call diversion, as recommended in the 3GPP CDIV specification [TS_24.604]. The cause values used in the cause-param for the diverting reason are listed in [RFC4458]. Because it is a parameter dedicated to the call forwarding service, its presence is used to determine that a hi-entry belongs to a diverting user. More precisely, each diverting user is located in the hi-entry before the one that contains a cause-param with a cause value listed in [RFC4458] 💅

Reason header field:

The Reason header field defined in [RFC3326] should be escaped in the hi-entry of the diverting user when the call diversion is due to a received SIP response. The Reason header field contains a cause parameter set to the true SIP response code received (Status-Code) 🔥

So, in the case of call diversion due to a SIP response, both cause parameters should be used. The tricky part is that these parameters could be used at the same time in the History-Info header field, but not in the same hi-entry and not with the same meaning. Only the cause-param is dedicated to the call diversion service. The 'cause' Reason header field parameter is not taken into account in the mapping with a Diversion header field 🙈

Target URI parameter:

[RFC4458] also defines the 'target' URI parameter, which could be inserted in a Request-URI and, consequently, in the hi-targeted-to-uri. This parameter is used to keep the diverting user address in the downstream INVITE request in the Voicemail URI implementation. Since this information is already present in the hi-entries, the 'target' URI parameter is not taken into account regarding the interworking with the Diversion header field. From the Diversion header field, it could be possible to create the 'target' URI parameter in the hi-entries and/or in the Request-URI, but this possibility is based on local policies that are not described in this document 🧚

Privacy header field:

A Privacy header field as defined in [RFC3323] could also be embedded in hi-entries with the 'history' value defined in [RFC7044] 🌈

Index header field parameter:

The index parameter is a string of digits, separated by dots, that indicates the number of forward hops and retargets 🍓

Note: A history entry could contain the "gr" parameter. Regardless of the rules concerning the "gr" parameter defined in [TS_24.604], which must be applied, this parameter has no impact on the mapping and must only be copied with the served user address 👑

Missing entry:

If the request clearly has a gap in the hi-entries (i.e., the last hi-entry and the Request-URI differ), the entity adding a hi-entry must add a single index with a value of "0" (i.e., the non-negative integer zero) before adding the appropriate index for the action to be taken (e.g., Index=1.1.2.0.1). Before any application usage of the History-Info header field parameters, the SIP entity that processes the hi-entries must evaluate the hi-entries and determine whether there are any gaps in them 🫶

"histinfo" option tag:

According to [RFC7044], a proxy that receives a Request with the "histinfo" option tag in the Supported header field should return captured History-Info in subsequent, provisional, and final responses to the Request. The behavior depends on whether or not the local policy supports the capture of History-Info ⭐

Example:

History-Info:
<sip:diverting_user1_addr?Privacy=none&Reason=SIP%3Bcause%3D302>;
index=1,
<sip:diverting_user2_addr;cause=480?Privacy=history>;index=1.1;mp=1,
<sip:last_diversion_target;cause=486>;index=1.1.1;mp=1.1

4.2. Diversion Header Field Syntax 🌸

The following text restates the exact syntax that the production rules in [RFC5806] define, but written in ABNF [RFC5234] 💜

Diversion           = "Diversion" HCOLON diversion-params
                                 *(COMMA diversion-params)
diversion-params    = name-addr *(SEMI (diversion-reason /
                      diversion-counter / diversion-limit /
                      diversion-privacy / diversion-screen /
                      diversion-extension))
diversion-reason    = "reason" EQUAL ("unknown" / "user-busy" /
                      "no-answer" / "unavailable" / "unconditional"
                      / "time-of-day" / "do-not-disturb" /
                      "deflection" / "follow-me" / "out-of-service"
                      / "away" / token / quoted-string)
diversion-counter   = "counter" EQUAL 1*2DIGIT
diversion-limit     = "limit" EQUAL 1*2DIGIT
diversion-privacy   = "privacy" EQUAL ("full" / "name" / "uri" /
                      "off" / token / quoted-string)
diversion-screen    = "screen" EQUAL ("yes" / "no" / token /
                      quoted-string)
diversion-extension = token [EQUAL (token / quoted-string)]

Note: The Diversion header field could be used in the comma-separated format described below and in a header-separated format. Both formats could be combined in a received INVITE, as recommended in [RFC3261] 🦋

Example:

Diversion:
<sip:diverting_user2_addr>;reason=user-busy;counter=1;privacy=full,
<sip:diverting_user1_addr>;reason=unconditional;counter=1;privacy=off

5. Diversion Header Field to History-Info Header Field 💖

okay so this bit is only valid if there's no History-Info header field in the INVITE request 🎀 if at least one History-Info header field is already there, the interworking function must adapt its behavior to respect the chronological order. for the details, go check Section 3 🦋

the privacy info in the Diversion header field only gets mapped like this inside a trusted domain 🔒 for other domains, see the privacy considerations in Section 3.2 🫶

for N Diversion entries, N+1 History-Info entries must be created ✨ to build the History-Info entries in the same order as the original session setup, you map the Diversion entries from bottom-most to top-most 💅 each Diversion entry shall be mapped into one History-Info entry. then one extra History-Info entry (the last one) gets created with the diverted-to party address from the Request-URI of the received INVITE 👑 the full mapping is in the table below 🌸

the first entry created in the History-Info header field has:

  • a hi-targeted-to-uri with the name-addr parameter of the bottom-most Diversion header field.
  • if a privacy parameter is present in the bottom-most Diversion entry, then a Privacy header field must be escaped in the History-Info header field as described in the table below.
  • a hi-index set to 1.

for each of the remaining Diversion entries (bottom to top), the History-Info entries get created like this (top to bottom) 🧚

 Source                                   Destination
 Diversion header component:              History-Info header component:
 =======================================================================
 name-addr                                hi-targeted-to-uri

 =======================================================================
 reason of the previous                   cause URI parameter
 Diversion entry                          A cause-param "cause" is
                                          added in each hi-entry
                                          (except the first one)
 "unknown"----------------------------------404 (default 'cause' value)
 "unconditional"----------------------------302
 "user-busy"--------------------------------486
 "no-answer"--------------------------------408
 "deflection "------------------------------480 or 487
 "unavailable"------------------------------503
 "time-of-day"------------------------------404 (default)
 "do-not-disturb"---------------------------404 (default)
 "follow-me"--------------------------------404 (default)
 "out-of-service"---------------------------404 (default)
 "away"-------------------------------------404 (default)
 ======================================================================
 counter                                  hi-index
 "1" or parameter ------------------------The previous created index
 not present                              is extended with ".1"
 Superior to "1" -------------------------Create N-1 placeholder History
 (i.e., N)                                entry with the previous index
                                          extended with ".1"
                                          Then the History-Info header
                                          created with the Diversion
                                          entry with the previous index
                                          extended with ".1"
 ======================================================================
 privacy                                  Privacy header escaped in the
                                          hi-targeted-to-uri
 "full"-----------------------------------"history"
 "Off"------------------------------------Privacy header field
                                          absent or "none"
 "name"-----------------------------------"history"
 "uri"------------------------------------"history"
 ======================================================================
                                          hi-target-param
                                          An mp-param "mp" is added in
                                          each created hi-entry
                                          (except the first one)
                                          The "mp" parameter is set to
                                          the index value of the
                                          preceding hi-entry.
 =======================================================================

and then a last History-Info entry gets created with:

  • a hi-targeted-to-uri with the Request-URI of the INVITE request.
  • a cause-param from the top-most Diversion entry, mapped from the diversion-reason as described above.
  • an index set to the previous created index extended with a new level ".1" added at the end.
  • a hi-target-param set to "mp" equals to the index value of the previous hi-entry.

Notes 📝

  1. for other optional Diversion parameters, there's no recommendation, because the History-Info header field doesn't have equivalent parameters 🙈
  2. for values of the diversion-reason that are mapped with a recommended default value, it could also be possible to choose another value. the cause-param URI parameter offers fewer possible values than the diversion-reason parameter. however, it has been considered that the cause-param values list was sufficient to implement CDIV service as defined in 3GPP [TS_24.604] as it covers a large portion of cases 💜
  3. the Diversion header field can contain a "tel" URI as defined in [RFC3966] in the name-addr parameter. the History-Info header field can also contain an address that is a "tel" URI, but if this hi-entry has to be completed with either a SIP header field (e.g., Reason or Privacy) or a SIP URI parameter (e.g., 'cause' or 'target'), the "tel" URI must be converted into a SIP URI. [RFC3261] gives an indication as to the mapping between sip: and tel: URIs, but in this particular case, it is difficult to assign a valid hostport as the diversion occurred in a previous network and a valid hostport is difficult to determine. so, it is suggested that in case of "tel" URI in the Diversion header field, the History-Info header field should be created with a SIP URI with user=phone and a domain set to "unknown.invalid" 🌈
  4. the Diversion header field allows carrying of a counter that retains the information about the number of successive redirections. History-Info does not have an equivalent because to trace and count the number of diversions, it is necessary to count the cause parameter containing a value associated to a call diversion listed in [RFC4458]. reading the index value is not enough. with the use of the "placeholder" entry the History-Info header field, entries can reflect the real number of diversions that occurred, thanks to the cause-param 🧠

example of a placeholder entry in the History-Info header field 🍓

<sip:unknown@unknown.invalid;cause=xxx>;index=1.1

<sip:bob_addr;cause=404>;index=1.1.1;mp=1.1

"cause=xxx" reflects the diverting reason of a previous diverting user 💀 for a placeholder hi-entry, the value "404" must be taken for the cause-param and so, located in the next hi-entry 🫶

for recommendations on local policies about the coexistence of header fields in the INVITE request, see Sections 3 and 7.4 ✨

6. History-Info Header Field to Diversion Header Field 🦋

again, the privacy info for the History-Info header field only gets mapped like this within a trusted domain 🔒 for other domains, see the privacy considerations in Section 3.2 💅

to build the Diversion entries in the same order as the original session setup, you map the History-Info entries from top-most to bottom-most 👑 the first History-Info header field entry you select gets mapped into the last Diversion header field entry, and so on 🌸 one Diversion header field entry must be created for each History-Info entry that has a cause-param with a value listed in [RFC4458] ✨

Diversion information 🎀

the definitions of "Target_entry" and "Diverting_entry" are included below to help you read the History-Info mapping 🧚

the diversion information can be identified by finding the following hi-entries:

  • Target_entry: hi-entries containing a cause-param URI parameter with a value listed in [RFC4458] will contain the diversion reason and the address of the target of the concerned call forwarding. per [RFC7044], these hi-entries may also contain a hi-target-param set to "mp".
  • Diverting_entry: for each previously identified hi-entry:
    • if there is an "mp" header field parameter, the hi-entry whose hi-index matches the value of the hi-target-param "mp" will contain the diverting party address, its possible privacy, and/or SIP reason when the retargeting has been caused by a received SIP response.
    • if there is no "mp" header field parameter, the information of the diverting party address, privacy and/or SIP reason will be found in the hi-entry that precedes this identified hi-entry.

Note: per [RFC7044], all retargeting entries must point to a hi-entry that contains an "mp" parameter, but for backward-compatibility reasons, it may be absent from some of the received hi-entries. see Section 8 for more information on backward compatibility 💖

the History-Info header field must be mapped into the Diversion header field like this 💜

Source                                    Destination
History-Info header component:            Diversion header component:
=====================================================================
hi-targeted-to-uri                        name-addr
of the Diverting_entry.

=====================================================================
cause-param                               reason
of the Target_entry
404---------------------------------------"unknown" (default value)
302---------------------------------------"unconditional"
486---------------------------------------"user-busy"
408---------------------------------------"no-answer"
480 or 487--------------------------------"deflection "
503---------------------------------------"unavailable"
=====================================================================
hi-index                                  counter
Mandatory parameter for-------------------The counter is set to "1".
History-Info reflecting
the chronological order
of the information.
=====================================================================
Privacy header field escaped              privacy
in the hi-targeted-to-uri
of the Diverting_entry
"history"----------------------------------"full"
Privacy header field ----------------------"Off"
Absent or "none"
=====================================================================

Note: for other optional History-Info parameters, there's no recommendation, because the Diversion header field doesn't have equivalent parameters 🌷

for recommendations on local policies about the coexistence of header fields in the INVITE request, see Section 3 🍭

7. Examples ✨

7.1. Example with Diversion Header Field Changed into History-Info Header Field ✨

Okay bestie, this one's a diversion chain that gets translated into History-Info 💅. Here's the Diversion version first, then the History-Info version it turns into 🦋

INVITE sip:last_diverting_target
Diversion:
<sip:diverting_user3_address>;reason=unconditional;counter=1;
privacy=off,
<sip:diverting_user2_address>;reason=user-busy;counter=1;
privacy=full,
<sip:diverting_user1_address>;reason=no-answer;counter=1;
privacy=off

Mapped into:

History-Info:
<sip:diverting_user1_address?Privacy=none>;index=1,
<sip:diverting_user2_address;
cause=408?Privacy=history>;index=1.1;mp=1,
<sip:diverting_user3_address;
cause=486?Privacy=none>;index=1.1.1;mp=1.1,
<sip:last_diverting_target;cause=302>;index=1.1.1.1;mp=1.1.1

7.2. Example with History-Info Header Field Changed into Diversion Header Field 🌸

Now the reverse glow-up 🪞 This time we start with History-Info and map it back into Diversion.

INVITE sip:last_diverting_target; cause=486
History-Info:
<sip:diverting_user1_address?Privacy=history>;index=1,
<sip:diverting_user2_address;cause=302?Privacy=none>;index=1.1;mp=1,
<sip:last_diverting_target;cause=486>;index=1.1.1;mp=1.1

Mapped into:

Diversion:
<sip:diverting_user2_address>;reason=user-busy;counter=1;privacy=off,
<sip:diverting_user1_address>;reason=unconditional;counter=1;privacy=
full

7.3. Example with Two SIP Networks Using History-Info Header Field Interworking with a SIP Network Using Diversion Header Field 🧚

This is the big one, so grab a snack 🍓 The call goes from A to E, and it crosses two networks, one speaking History-Info and one speaking Diversion, with IWFs sitting at the boundaries 😭

The path looks like this:

A -> P1 -> B -> C -> P2 -> D-> E

Quick cast list: A, B, C, D and E are all users 💜 B, C and D each have call forwarding turned on 📞 P1 and P2 are proxies 🛰️ And we're only showing the parts of the call flow that matter, so no extra noise ✨

                      IWF*                                IWF*
 SIP network using     |           SIP network using       |SIP net.
   History-Info        |                Diversion          |using
                       |                                History-Info
                       |                                   |
UA A    P1     AS B     |      P2     AS C    UA C   AS D   |    UA E
|       |       |       |      |       |       |     |      |       |
|INV B  |       |       |      |       |       |     |      |       |
|------>|       |       |      |       |       |     |      |       |
|       |       |       |      |       |       |     |      |       |
|       |INV B  |       |      |       |       |     |      |       |
|       |------>|       |      |       |       |     |      |       |
|       |Supported: histinfo   |       |       |     |      |       |
|       | History-Info:        |       |       |     |      |       |
|       | <sip:proxyP1>;index=1,       |       |     |      |       |
|       | <sip:userB>;index=1.1;rc=1   |       |     |      |       |
|       |       |       |      |       |       |     |      |       |
|       |       |INV C  |      |       |       |     |      |       |
|       |       |------>|      |       |       |     |      |       |
|       |       |History-Info: |       |       |     |      |       |
|       |       <sip:proxyP1>;index=1, |       |     |      |       |
|       |       <sip:userB>;index=1.1;rc=1,    |     |      |       |
|       |       <sip:proxyP2;cause=302>;index=1.1.1;mp=1.1  |       |
|       |       |       |      |       |       |     |      |       |
|       |       |       |INV C |       |       |     |      |       |
|       |       |       |----->|       |       |     |      |       |
|       |       | Diversion:   |       |       |     |      |       |
|       |     <sip:userB>;reason=unconditional;counter=1;privacy=off|
|       |       |       |History-Info: |       |     |      |       |
|       |       |       <sip:proxyP1>;index=1, |     |      |       |
|       |       |       <sip:userB>;index=1.1;rc=1,  |      |       |
|       |       |       <sip:proxyP2;cause=302>;index=1.1.1;mp=1.1  |
|       |       |       |      |       |       |     |      |       |
|       |       |       |      |INV C  |       |     |      |       |
|       |       |       |      |------>|       |     |      |       |
|       |       |       |     No modification of Diversion header   |
|       |       |       |      |       |       |     |      |       |
|       |       |       |      |       |INV C  |     |      |       |
|       |       |       |      |       |------>|     |      |       |
|       |       |       |      |       |       |     |      |       |
|       |       |       |      |       |<--180-|     |      |       |
|       |       |       |      |       |       |     |      |       |
|       |       |       |      |  No response timer expires |       |
|       |       |       |      |       |---INV D --->|      |       |
|       |       |Diversion:                          |      |       |
|       |     <sip:userC>;reason=no-answer;counter=1;privacy=full,  |
|       |     <sip:userB>;reason=unconditional;counter=1;privacy=off|
|       |       |    History-Info:                   |      |       |
|       |       |    <sip:proxyP1>;index=1,          |      |       |
|       |       |    <sip:userB>;index=1.1;rc=1,     |      |       |
|       |       |    <sip:proxyP2;cause=302>;index=1.1.1;mp=1.1     |
|       |       |       |      |       |       |     |      |       |
|       |       |       |      |       |       |     |INV E |       |
|       |       |       |      |       |       |     |----->|       |
|       |       |Diversion:                                 |       |
|       |     <sip:userD>;reason=time-of-day;counter=1;privacy=off, |
|       |     <sip:userC>;reason=no-answer;counter=1;privacy=full,  |
|       |     <sip:userB>;reason=unconditional;counter=1;privacy=off|
|       |       |     History-Info:                         |       |
|       |       |     <sip:proxyP1>;index=1,                |       |
|       |       |     <sip:userB>;index=1.1;rc=1,           |       |
|       |       |     <sip:proxyP2;cause=302>;index=1.1.1;mp=1.1    |
|       |       |       |      |       |       |     |      |       |
|       |       |       |      |       |       |     |      | INV E |
|       |       |       |      |       |       |     |      |------>|
|       |   History-Info:      |       |       |     |      |       |
|       |   <sip:proxyP1>;index=1,     |       |     |      |       |
|       |   <sip:userB>;index=1.1;rc=1,        |     |      |       |
|       |   <sip:proxyP2;cause=302>;index=1.1.1;mp=1.1,     |       |
|       |   <sip:userC ?Privacy=history>;index=1.1.1.0.1,   |       |
|<sip:userD;cause=408?Privacy=none>;index=1.1.1.0.1.1;mp=1.1.1.0.1, |
|       |<sip:userE;cause=404>;index=1.1.1.0.1.1.1;mp=1.1.1.0.1.1   |
|       |       |       |      |       |       |     |       |      |
|       |       |       |      |       |       |     |       |      |

Note: the IWF is an interworking function 🔧 It could be a standalone box that isn't defined in this document, or it could just be a proxy 🫶

7.4. Additional Interworking Cases 🦋

Even when both header fields could technically live together, it should be the network's local policy that decides how they play nice 💅 This section walks through a few situations and gives some recommendations on behaviour.

Picture one network with a mix of nodes, where some support Diversion and others support History-Info 🌈 The tricky bit is when a node handling a message doesn't know which node is going to handle it next 😬 That happens when the network has new and old nodes, with the older ones using Diversion and the newer ones using History-Info.

During a network replacement, there's going to be a stretch of time when both kinds of nodes are hanging out together 🕰️ If those nodes are serving different subscriber types because of their different capabilities, it gets even more important. In that case, the network needs to pass both the History-Info header field and the Diversion header field inside the core network.

These two header fields need to be equivalent so that whichever node gets the message, it still sees the right diversion information ✨ That means that no matter which header field arrived, the node has to be able to compare them and convert between them. Depending on what a node can do, it may be possible to make some assumptions about how this is handled 🎀

  • If it's known that an older node supporting the Diversion header field doesn't pass on any History-Info header field it receives, then the interworking gets easier 🍓 If a message only has Diversion header fields, it must have come from an old node. The equivalent History-Info entries can be created, and then they can be passed along together with the Diversion header field.
  • If a node creates a new History-Info header field for a call diversion, then an additional Diversion header field must be created 💜
  • If the next node is an old node, then that node will use the Diversion header field, and the History-Info entries will be removed from the message when it gets passed on 🧚
  • If the next node is a new node, then seeing both the Diversion header field and the History-Info header field means interworking has already happened, and the Diversion and History-Info entries must be considered equivalent 🫶
  • If both kinds of nodes pass on both the History-Info header field and the Diversion header field but only actively use one, then both types of nodes need to do the interworking and keep the two header fields equivalent 👑 This will eventually lead to the Diversion header field being deprecated, once every node in the network supports the History-Info header field 🥹
  • If a node that would create a new entry finds a gap in the History-Info header field, it shall add a single index with a value of 0 before adding the index for the action it's about to take 🙈

8. Backward Compatibility 🌷

Backward compatibility issues come from the History-Info header field changing from [RFC4244] to [RFC7044], as described in Section 1.3 of this document 💖 Backward compatibility is considered all the way through this document when it comes to interworking with the Diversion header field. You can find more details in the "Backwards Compatibility" section of [RFC7044] 📚

9. Security Considerations 🔐

The security considerations in [RFC7044] and [RFC5806] apply. This is serious, bestie 😭

The privacy considerations described in Section 3.2 apply too 🙈

Using the Diversion header field or the History-Info header field means every diverting user or entity's requested privacy and integrity have to be applied 🛡️ Without integrity, the privacy functions that were asked for could be downgraded or removed, which could expose identity information 💀 Without confidentiality, eavesdroppers on the network (or any intermediaries between the user and the Privacy Service) could see the very personal information the user asked the Privacy Service to hide 😱 Unauthorized insertion, deletion, or modification of those header fields can feed misleading information to users and applications 🚨 A SIP entity that can provide a redirection reason in a History-Info header field or a Diversion header field should be able to suppress it in line with the privacy requirements of the user concerned 💜

10. References 📖

10.1. Normative References

Okay, bestie, the references are where the receipts live 🧾✨ Here's every normative one, exactly as cited:

[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>.

[RFC3323]  Peterson, J., "A Privacy Mechanism for the Session
           Initiation Protocol (SIP)", RFC 3323,
           DOI 10.17487/RFC3323, November 2002,
           <http://www.rfc-editor.org/info/rfc3323>.

[RFC3326]  Schulzrinne, H., Oran, D., and G. Camarillo, "The Reason
           Header Field for the Session Initiation Protocol (SIP)",
           RFC 3326, DOI 10.17487/RFC3326, December 2002,
           <http://www.rfc-editor.org/info/rfc3326>.

[RFC3966]  Schulzrinne, H., "The tel URI for Telephone Numbers",
           RFC 3966, DOI 10.17487/RFC3966, December 2004,
           <http://www.rfc-editor.org/info/rfc3966>.

[RFC4244]  Barnes, M., Ed., "An Extension to the Session Initiation
           Protocol (SIP) for Request History Information", RFC 4244,
           DOI 10.17487/RFC4244, November 2005,
           <http://www.rfc-editor.org/info/rfc4244>.

[RFC5806]  Levy, S. and M. Mohali, Ed., "Diversion Indication in
           SIP", RFC 5806, DOI 10.17487/RFC5806, March 2010,
           <http://www.rfc-editor.org/info/rfc5806>.

[RFC7044]  Barnes, M., Audet, F., Schubert, S., van Elburg, J., and
           C. Holmberg, "An Extension to the Session Initiation
           Protocol (SIP) for Request History Information", RFC 7044,
           DOI 10.17487/RFC7044, February 2014,
           <http://www.rfc-editor.org/info/rfc7044>.

10.2. Informative References

And here are the informative ones, the "good to know" crew 🦋:

[Err1409]  RFC Errata, Erratum ID 1409, RFC 4458.

[RFC4458]  Jennings, C., Audet, F., and J. Elwell, "Session
           Initiation Protocol (SIP) URIs for Applications such as
           Voicemail and Interactive Voice Response (IVR)", RFC 4458,
           DOI 10.17487/RFC4458, April 2006,
           <http://www.rfc-editor.org/info/rfc4458>.

[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>.

[RFC6044]  Mohali, M., "Mapping and Interworking of Diversion
           Information between Diversion and History-Info Headers in
           the Session Initiation Protocol (SIP)", RFC 6044,
           DOI 10.17487/RFC6044, October 2010,
           <http://www.rfc-editor.org/info/rfc6044>.

[TS_24.604]
           3rd Generation Partnership Project, "Communication
           Diversion (CDIV) using IP Multimedia (IM) Core Network
           (CN) subsystem; Protocol specification", Release 13.1,
           3GPP TS 24.604, June 2015.

[TS_29.163]
           3rd Generation Partnership Project, "Interworking between
           the IP Multimedia (IM) Core Network (CN) subsystem and
           Circuit Switched (CS) networks", Release 13.2, 3GPP TS
           29.163, June 2015.

Appendix A. Interworking between Diversion Header Field and Voicemail URI

Okay, so this appendix is all about the Voicemail URI 📞💌. It's a mechanism from [RFC4458] that gives you a simple way to carry just one redirecting user address, plus the reason the diversion happened, inside the Request-URI of the INVITE request. Basically it's the go-to move for diverting a call to voicemail 🎀.

A.1. Diversion Header Field to Voicemail URI

Here's the before and after. Received first:

Received:
Diversion: userA-address;reason=user-busy;counter=1;privacy=full

And sent, with the Voicemail URI created in the R-URI line of the INVITE:

Sent (Voicemail URI created in the R-URI line of the INVITE):
sip: voicemail@example.com;target=userA-address;cause=486 SIP/2.0

The Redirection Reason mapping is the same as for the History-Info header field, with a default value set to 404 🌸.

If the Diversion header field has more than one Diversion entry, the network's local policy decides which redirecting user information goes into the URI 💅. For example, the criterion could be the destination of the forwarded INVITE request, meaning whether or not the voicemail serves that user.

Note: This interworking could be done in addition to the interworking of the Diversion header field into the History-Info header field. 🧚

A.2. Voicemail URI to Diversion Header Field

Real talk: with real voicemail, this way of interworking should not happen 🙈. But if it does for any reason, it is recommended to handle it like this:

Received:

INVITE sip: voicemail@example.com;\
target=sip:+33145454500%40example.com;user=phone;\
cause=302 SIP/2.0

Sent in the forwarded INVITE:

Diversion: sip:+33145454500%40example.com;user=phone;
reason=unconditional;counter=1

Acknowledgements

Huge shoutout to everyone who gave constructive feedback and support 🫶🌈: Steve Norreys, Jan Van Geel, Martin Dolly, Francisco Silva, Guiseppe Sciortino, Cinza Amenta, Christer Holmberg, Ian Elz, Jean-Francois Mule, Mary Barnes, Francois Audet, Erick Sasaki, Shida Schubert, Joel M. Halpern, Bob Braden, Robert Sparks, Merci a Lionel Morand, and Xavier Marjou et Philippe Fouquart. Y'all are the real MVPs 👑.

Author's Address

Here's where to find the author, Marianne Mohali 💜:

Marianne Mohali
Orange
38-40 rue du General Leclerc
Issy-Les-Moulineaux Cedex 9  92794
France

Phone: +33 1 45 29 45 14
Email: marianne.mohali@orange.com
📦 where this page comes from