Diversion Info and History-Info Header Mapping
History-Info and Diversion are two headers commonly used in SIP signaling to convey information related to call transfer and call diversion. The Oracle® Enterprise Session Border Controller (ESBC) supports mapping and interworking between networks that support the History-Info versus the Diversion header. You implement this interworking on the ESBC using the diversion-info-mapping-mode parameter on egress sip-interface configuration elements. This interworking, and the subsequent header behaviors, comply with RFC 7544. When configured, the ESBC monitors signaling for the presence of History-info headers that comply with RFC 7044 and Diversion headers that comply with RFC 5806 to trigger the interworking. The ESBC also provides support for RFC 8119, with respect to the cause URI parameter.
The History-Info header is the standard solution adopted by the Internet Engineering Task Force (IETF) for storing re-targeting information. The non-standard Diversion header is also used in many existing network implementations. Individual networks typically use one or the other. As both headers address call forwarding needs but have different syntaxes, having both present in a signaling request can cause diverting information to be misinterpreted, thereby making an interworking solution necessary. In addition to using different syntaxes, these methods also use different reason codes for the diversions, different security flags, and list events using opposite chronology. The diversion header lists the last diversion first; the History-Info header lists the first diversion first.
The ESBC applies the configuration at the egress interface. You can configure the following header interworking modes:
- Diversion to History-Info
- History-info to Diversion
- A combination of Diversion to History-Info interworking and a forced insertion of the History-info header if the INVITE contains neither
When interworking from a History-Info header to a Diversion header, the ESBC initializes the new Diversion header with the value of the History-Info header.
History-Info and Diversion Header Interworking Operations
The Oracle® Enterprise Session Border Controller (ESBC) performs this interworking on the information provided in the initial INVITE. History-Info and Diversion header entries may arrive in any order and can be mixed. The ESBC supports interworking for interleaved entries and mixed input. History-Info has a much broader scope than Diversion header (not limited to call forwarding) so not all information can be interworked. The ESBC manages History-Info headers with or without cause parameter per RFC 7544.
At a high level, the ESBC performs the following tasks:
- When interworking
History-Info to Diversion headers:
- Supports the mp parameters in History-Info received and generated to the hi-targeted-to-URI to change the user. Examples include forwarding to a different call center technician.
- If received in the
INVITE, the
ESBC stores the rc and
np parameters:
- rc—Changes Request-URI, while the target user does not. Examples include forwarding to a user's voice mail.
- np—No change in the Request-URI. Examples include a proxy forwarding a request to a next-hop proxy when you are using loose routing.
- Interworks the History-Info 380 cause parameter to the Diversion header (cause=unknown), as described below.
- When interworking Diversion
headers to History-Info:
- Creates placeholder History-Info headers when the Diversion counter is greater than 1.
- Converts TEL-URIs to SIP-URIs.
- Forwards History-Info not related to call forwarding without change.
For both directions:
- Preserves unknown elements
of History-Info and Diversion headers, such as display name, parameters, and
enclosed headers adhering to the HI or DIV syntax. Specifically:
- If there are any unknown parameters/elements present in the URI part (in between "<" and ">") of HI/Diversion headers, the ESBC preserves those values in the converted entries.
- If there is any extra/unknown supplementary information outside the URI of an HI entry, the ESBC maps that HI entry, including the EXTRA info.
- If there is any extra/unknown supplementary information outside the URI of the Diversion entry, the ESBC maps that Diversion entry, but ignores the EXTRA information.
- Based on sip-config configuration, makes the Diversion and History-Info headers anonymous if the egress peer is untrusted.
Note:
If there is any information outside of the HI/DIV header syntax, the ESBC treats that information as unknown or supplementary information.You configure the ESBC for this interworking support at the egress interface. The applicable parameter, diversion-info-mapping-mode, assumes traffic egressing the interface supports either History-Info or Diversion. There are three modes of operation:
- History-Info to Diversion
Header Interworking (hist2div)
- If Diversion headers are already present, the ESBC considers them when building the egress request.
- The ESBC adds the unknown elements of History-Info headers to the generated Diversion headers (display-name, SIP parameters, SIP headers). See the specific functions presented above.
- The ESBC optionally converts History-Info with a "380" cause to a Diversion header (cause=unknown). By default, it forwards the History-Info cause=380 transparently.
- Existing Diversion headers received in the input appear at the end of the Diversion list.
- Converted History-Info entry with cause = 380, shall be at the top of newly created div headers. The ESBC adds other HI entries with different cause (other than 380) per the conversion.
- The ESBC retains HI entries if they don't have a cause parameter, and if that entry is not a target entry to any diverting entry.
- When configured, the
ESBC inserts the cause
380 History-Info as the topmost Diversion header, because it assumes the
applicable events happened before the call forwarding History-Info.
- When converting hist2div, the ESBC removes the last History-Info with a cause parameter if used to build a diversion header.
- If this cause parameter is 380 and option hist380todiv (hist-to-div-for-cause-380) is not present, then this History-Info header is not taken into account to build a Diversion because it is not recognized as a call forward. This results in the ESBC keeping the last History-Info header.
- If this cause parameter is 380 and option hist380todiv (hist-to-div-for-cause-380) is present, then this History-Info header is taken into account to build a Diversion because it is recognized as a call forward. In that case, the History-Info header removes the last History-Info header.
- Diversion Header to
History-Info Interworking (div2hist)
- The ESBC generates the mp-param parameter for History-Info headers.
- If the ESBC is adding converted History-Info headers to existing History-Info headers it manages both index and mp-param continuation.
- The ESBC integrates any existing History-Info headers to the top of the list in the resulting request.
- The ESBC adds the unknown R-URI elements of Diversion headers to the generated History-Info headers (display-name, SIP parameters, SIP headers). If there is any other extra info that cannot be mapped to History-Info header, the ESBC ignores it.
- If a Diversion header contains a TEL-URI, the ESBC converts it into a SIP-URI and inserts it into the resulting History-Info header.
- Tel-URI with additional parameters to SIP-URI. If a Diversion header contains a TEL-URI, the ESBC converts it into a SIP-URI and inserts it into the resulting History-Info header along with any additional Tel-URI parameters.
- The ESBC adds newly converted History-Info headers to the existing History-Info headers. If the last old/existing HI entry has cause 380, the ESBC removes the mp-param from the first HI entry in the list of converted HI entries that it is going to add.
- All Diversion headers are always converted to HI headers because information in diversion headers can always be converted.
- Forced Mode (force)
- This mode is similar to div2hist, but invokes additional actions by the ESBC.
- If History-Info headers are already present, the ESBC adds new History-Info header(s) to the existing set.
- The
ESBC retargeting
feature adds a History-Info entry as well as the expected Index and mp to an
outgoing INVITE when certain conditions are met:
- When force mode is set on the realm from which the 3xx or ENUM response came.
- When the ESBC gets a redirect response (3xx) or an ENUM response.
- When this response also contains the new URI and cause-param.
- When it receives a cause parameter in a SIP redirect reply.
- The ESBC extracts parameters for creating a History-Info header from the Contact header of the incoming SIP redirect reply. This Contact header must contain the URI and cause. The ESBC copies all this information for use in the History-Info it generates.
- Adds History-Info headers to a SIP INVITE if it has been re-targeted.
- For repeated re-targeting the ESBC keeps adding History-Info headers to each INVITE it sends out.
- The ESBC extracts information from a received Contact header from incoming re-direct replies. For this feature ESBC only uses the URI and cause.
- The ESBC ignores a hi-target-param if it is received as the Contact of a 3xx or via an ENUM response. The ESBC can not rely on that information.
The ESBC retains any added History-Info entry it adds to an outgoing retargeting request for ensuing retargeting requests.
History-Info to Diversion Header Interworking
When configured for this interworking, the ESBC performs the following steps for all History-Info headers except the last in the incoming initial INVITE:
- Create a new diversion header.
- If there is a subsequent HI
header, extract the cause parameter, map it to the corresponding reason
parameter, and add this reason parameter to the interworked Diversion header,
using the following conversion table.
History-Info Cause Diversion Reason 404 Unknown (default value) 302 unconditional 486 user-busy 408 no-answer 480 deflection 487 deflection 503 unavailable - If an HI entry includes a cause that is not in the list of valid causes, per RFC 7544, use the default value Unknown for the reason parameter.
- If the History-Info header
contains a privacy parameter, add a Privacy parameter to the Diversion header,
using the following conversion table.
History-Info Privacy Diversion Privacy history full Field absent or none Off (default value) - If there is no privacy parameter, use the default value Off in the Diversion header.
- Add a counter parameter with the value 1.
- Delete the History-Info header.
The diagram below provides an example flow and the header text used for this example.
Diversion to History-Info Header Interworking
When configured for this interworking, the ESBC takes the following steps for all Diversion headers in the incoming initial INVITE:
- Create a new History-Info header.
- Add the index header parameter.
- Set the value for the first header to 1. Append .1 to the value of the last_index_value for the subsequent headers.
- If the Diversion header
contains a privacy parameter, add the Privacy header parameter to the
History-Info header using the following conversion table.
Diversion Privacy History-Info Privacy full history name history uri history off none - If the previous Diversion
header contains a reason parameter, add the
cause header
parameter to the History-Info header using the following conversion table. The
ESBC does not add a
cause parameter to the first History-info entry.
Diversion Reason History-Info Cause unknown 404 (default value) unconditional 302 user-busy 486 no-answer 408 deflection 480 unavailable 404 time-of-day 404 do-not-disturb 404 follow-me 404 out-of-service 404 away 404 - If the presented reason parameter is not in the table above, set the parameter to the default value of 404.
- Remove the diversion header from the outgoing INVITE.
The diagram below provides an example flow and the header text used for this example.
Mapping the History-Info Cause Parameter
You can configure ESBC to map the History-Info's cause 380 parameter to the Diversion header's reason=unknown parameter. You can configure the applicable parameter, hist-to-div-for-cause-380, in both the sip-config and sip-interface, with the egress sip-interface setting taking precedence. This parameter only applies when you set the applicable sip-interface interworking mode to hist2div. The verify-config command informs you if there is a hist-to-div-for-cause-380 without a corresponding hist2div.
By default, the hist-to-div-for-cause-380 parameter is disabled, which causes the ESBC to transparently forward the Hisory-Info entry with cause 380. Enabling the parameter makes the ESBC interwork the parameter, allowing it to be understood by devices that support Diversion headers.
When using hist-to-div-for-cause-380 for 380 cause mapping, the ESBC places those headers at the top of the Diversion header list. This is true regardless of how many History-Info entries are present.
Anonymization of History and Diversion Information
The ESBC supports anonymization of entries for both History-Info and Diversion, independent of the interworking function. You configure this function separately from the interworking function. The ESBC applies anonymization rules as long as the circumstances meet all anonymization criteria. This anonymization configuration is global. For untrusted peers, the ESBC changes input header addresses to the anonymous SIP URI syntax sip:anonymous@anonymous.invalid.
This feature uses functionality independent of the IWF to confirm whether or not the remote target is trusted. The ESBC checks the session-agent trust mode. If the session-agent reports "trust-me", then assuming nothing else conflicts, the system trusts the agent. This functionality also refers to the IWF state.
If IWF is configured, the ESBC performs anonymization on the output generated after conversion per RFC 7544.
If IWF is not configured:
- Remote peer trusted - The ESBC does not anonymize the History-Info header or Diversion header. The Privacy header field values in incoming History-Info or Diversion header of INVITE shall be used likewise in outgoing header.
- Remote peer untrusted - The ESBC checks sip-config, anonymize-history-for-untrusted setting, introduced by this feature, to determine whether it should anonymize the entries in History-Info or Diversion headers with Privacy fields set to full/history. If anonymize-history-for-untrusted is configured, the ESBC anonymizes the input received in the initial INVITE.
The ESBC uses the following steps when it is sending messages to untrusted peer.
- Based on the mode set, do the conversion between headers.
- If mode is not set, check for History-Info and Diversion headers entries in outgoing message.
- For the entries where privacy value is other than "none" in History-Info and "off" in Diversion, anonymize the entries if anonymize-history-for-untrusted is set.
- For HI entries with a privacy value other than "none", and for diversion entries that have a privacy value other than "off", the ESBC does not anonymize entries if is not set.
- In case the entries have Privacy settings as "none" in History-Info or "off" in Diversion, do not anonymize the entries even if anonymize-history-for-untrusted is set.
If a privacy header is present in INVITE with value as "history" or "header" or "full" and the outgoing INVITE is going to untrusted remote side, then all the History-Info and Diversion entries shall be anonymized as per above section, given anonymize-history-for-untrusted is set.
The ESBC anonymizes all History-Info and Diversion entries regardless of the value of the privacy header of each History-Info or Diversion entry. If a privacy header with above values appears in incoming INVITE, every History-Info and Diversion entry will be anonymized.
Diversion and History-Info Headers Interworking Configuration
You can configure Oracle® Enterprise Session Border Controllers to map call transfer and call diversion information between Diversion and History-Info headers.