RFC 3910
The SPIRITS (Services in PSTN requesting Internet Services) Protocol
The SPIRITS (Services in PSTN requesting Internet Services) Protocol 🧚
RFC 3910 is the spec for SPIRITS 📞✨ It's a Standards Track protocol from the Network Working Group, published October 2004. The lead editor is V. Gurbani, Ed., with co-authors A. Brusilovsky, I. Faynberg, J. Gato, H. Lu, and M. Unmehopa. Faynberg and Unmehopa are at Lucent Technologies, Inc., Gato is at Vodafone Espana, and Lu is at Bell Labs/Lucent Technologies. The header doesn't list anything this one obsoletes or updates, so it stands on its own 💅
Status of this Memo
Okay so this doc is an Internet standards track protocol for the Internet community, and the authors want feedback and suggestions for improvements 🫶 For where it stands, check the current "Internet Official Protocol Standards" (STD 1). Distribution of this memo is unlimited 🌸
Copyright Notice
Copyright (C) The Internet Society (2004) 🎀
Abstract
This doc describes SPIRITS, which stands for Services in PSTN (Public Switched Telephone Network) requesting Internet Services 🦋 The whole point is to support services that start in the cellular or wireline PSTN and need the PSTN and the Internet to talk to each other. On the PSTN side, these services usually kick off from Intelligent Network (IN) entities. Internet Call Waiting and Internet Caller-ID Delivery are SPIRITS services, and so are location-based services on the cellular network 📱 The protocol also gives you the building blocks that other services can be built from. It's giving toolbox 🧰✨
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Conventions used in this document. . . . . . . . . . . 3
2. Overview of operations. . . . . . . . . . . . . . . . . . . . 3
2.1. Terminology. . . . . . . . . . . . . . . . . . . . . . 6
3. Using XML for subscription and notification . . . . . . . . . 7
4. XML format definition . . . . . . . . . . . . . . . . . . . . 8
5. Call-related events . . . . . . . . . . . . . . . . . . . . . 10
5.1. IN-specific requirements . . . . . . . . . . . . . . . 11
5.2. Detection points and required parameters . . . . . . . 12
5.2.1. Originating-side DPs. . . . . . . . . . . . . 12
5.2.2. Terminating-side DPs. . . . . . . . . . . . . 14
5.3. Services through dynamic DPs . . . . . . . . . . . . . 15
5.3.1. Normative usage . . . . . . . . . . . . . . . 15
5.3.2. Event package name. . . . . . . . . . . . . . 16
5.3.3. Event package parameters. . . . . . . . . . . 16
5.3.4. SUBSCRIBE bodies. . . . . . . . . . . . . . . 16
5.3.5. Subscription duration . . . . . . . . . . . . 17
5.3.6. NOTIFY bodies . . . . . . . . . . . . . . . . 17
5.3.7. Notifier processing of SUBSCRIBE requests . . 18
5.3.8. Notifier generation of NOTIFY requests. . . . 18
5.3.9. Subscriber processing of NOTIFY requests. . . 19
5.3.10. Handling of forked requests . . . . . . . . . 19
5.3.11. Rate of notifications . . . . . . . . . . . . 19
5.3.12. State Agents. . . . . . . . . . . . . . . . . 20
5.3.13. Examples. . . . . . . . . . . . . . . . . . . 20
5.3.14. Use of URIs to retrieve state . . . . . . . . 25
5.4. Services through static DPs. . . . . . . . . . . . . . 25
5.4.1. Internet Call Waiting . . . . . . . . . . . . 26
5.4.2. Call disposition choices. . . . . . . . . . . 26
5.4.3. Accepting an ICW session using VoIP . . . . . 28
6. Non-call related events . . . . . . . . . . . . . . . . . . . 29
6.1. Non-call events and their required parameters. . . . . 29
6.2. Normative usage. . . . . . . . . . . . . . . . . . . . 30
6.3. Event package name . . . . . . . . . . . . . . . . . . 30
6.4. Event package parameters . . . . . . . . . . . . . . . 31
6.5. SUBSCRIBE bodies . . . . . . . . . . . . . . . . . . . 31
6.6. Subscription duration. . . . . . . . . . . . . . . . . 31
6.7. NOTIFY bodies. . . . . . . . . . . . . . . . . . . . . 32
6.8. Notifier processing of SUBSCRIBE requests. . . . . . . 32
6.9. Notifier generation of NOTIFY requests . . . . . . . . 32
6.10. Subscriber processing of NOTIFY requests . . . . . . . 33
6.11. Handling of forked requests. . . . . . . . . . . . . . 33
6.12. Rate of notifications. . . . . . . . . . . . . . . . . 33
6.13. State Agents . . . . . . . . . . . . . . . . . . . . . 33
6.14. Examples . . . . . . . . . . . . . . . . . . . . . . . 33
6.15. Use of URIs to retrieve state. . . . . . . . . . . . . 37
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
7.1. Registering event packages . . . . . . . . . . . . . . 38
7.2. Registering MIME type. . . . . . . . . . . . . . . . . 38
7.3. Registering URN. . . . . . . . . . . . . . . . . . . . 39
7.4. Registering XML schema . . . . . . . . . . . . . . . . 40
8. Security Considerations . . . . . . . . . . . . . . . . . . . 40
9. XML schema definition . . . . . . . . . . . . . . . . . . . . 42
10. Acknowledgements. . . . . . . . . . . . . . . . . . . . . . . 45
11. Acronyms. . . . . . . . . . . . . . . . . . . . . . . . . . . 45
12. References. . . . . . . . . . . . . . . . . . . . . . . . . . 46
13. Contributors. . . . . . . . . . . . . . . . . . . . . . . . . 48
14. Authors' Addresses. . . . . . . . . . . . . . . . . . . . . . 48
15. Full Copyright Statement. . . . . . . . . . . . . . . . . . . 501. Introduction 📞
SPIRITS (Services in the PSTN Requesting Internet Services) is an IETF architecture plus a protocol 🧠 It lets call processing elements in the telephone network send service requests, and those requests get handled on servers hosted on the Internet ☁️ "PSTN" here covers the wireline circuit-switched network and the wireless circuit-switched network, so it's a big umbrella 🌈
Before this, the IETF did PSTN/Internet Interworking (PINT), which produced RFC 2848. PINT handled services going the other way, from the Internet into the PSTN 🔄
This document was written in response to the SPIRITS WG chairs' call for SPIRITS Protocol proposals. It's built on a few things, including:
- Informational "Pre-SPIRITS implementations" [10]
- Informational "The SPIRITS Architecture" [1]
- Informational "SPIRITS Protocol Requirements" [4]
1.1. Conventions used in this document 🎀
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 [2]. These capitalised words are the ones that carry real weight, so read them carefully 🙈💖
2. Overview of operations ✨
okay so the whole point of SPIRITS 🦋 is letting the internet run services based on events happening in the PSTN (the old-school phone network). and when we say PSTN we mean ALL the switching, so wireline circuit-switched AND wireless circuit-switched. the full phone-network glow-up 📞💅
basically an internet host goes "hey, tell me when X happens" and when that event actually goes off in the PSTN, the PSTN pings the host. then the host can run whatever service it wants with that info. it's giving real-time notification queen 👑
+------+
| PSTN |
|Events|
+------+
/ \
/ \
+-------+ +--------+
|Call | |Non-Call|
|Related| |Related |
+-------+ +--+-----+
/ \ |
/ \ |
+---/--+ +---\---+ +--+-----------------+
|Static| |Dynamic| |Mobility Management/|
| | | | |Registration/De- |
+------+ +-------+ |registration |
+--------------------+
Figure 1: The SPIRITS Hierarchy.Figure 1 is the SPIRITS events family tree 🌳 and it splits events into two main groups for running services: stuff tied to setting up, tearing down, or keeping a call alive, and stuff that's totally unrelated to calls. the second group is things like geo-location mobility events that the cellular PSTN tracks. SPIRITS is going to spell out a framework that handles BOTH kinds, so nobody gets left on read 🙈✨
Call-related events, their subdivisions, and how they power services on the Internet are in Section 5 🎀. the non-call stuff (setup, teardown, and maintenance not involved) gets the deep dive in Section 6 💜.
okay and here's the SPIRITS architecture from [1] for reference 🧚 this doc is ONLY about interfaces B and C. interface D is a local policy thing: the PSTN operator might have a functional interface between the SPIRITS client or a message passing interface. this doc doesn't really go into D, so don't ask me to spill on it 🫶
+--------------+
| Subscriber's |
| IP Host | +--------------+
| | | |
| +----------+ | | +----------+ |
| | PINT | | A | | PINT | |
| | Client +<-------/-------->+ Gateway +<-----+
| +----------+ | | +----------+ | |
| | | | |
| +----------+ | | +----------+ | |
| | SPIRITS | | B | | SPIRITS | | |
| | Server +<-------/-------->+ Gateway | | |
| +----------+ | | +--------+-+ | |
| | | ^ | |
+--------------+ +----------|---+ |
| |
IP Network | |
------------------------------------------|--------|---
PSTN / C / E
| |
v |
+----+------+ |
| SPIRITS | |
| Client | v
+-------------------+ +---+-----D-----+-++
| Service Switching |INAP/SS7 | Service Control |
| Function +---------+ Function |
+----+--------------+ +------------------+
|
|line
+-+
[0] Subscriber's telephone
Figure 2: The SPIRITS Architecture.(Note: The interfaces A-E are described in detail in the SPIRITS Architecture document [1].)
Now the PSTN today runs the Intelligent Network (IN) model 🧠, where some features run locally on switching elements called Service Switching Points (SSPs). other features run on service elements called Service Control Points (SCPs). the SPIRITS architecture [1] lets those SCP elements act as smart entities that tap into Internet hosts and capabilities to level up the phone user's experience 🌈💖
The protocol on interfaces B and C is the SPIRITS protocol, and it's built on SIP and SIP event notification [3] 📡. the requirements for SPIRITS and why SIP was picked as the enabler are in [4] 🎀.
The SPIRITS protocol is a set of two "event packages" [3] 📦✨. it holds the procedural rules plus the semantic context you need to apply to those rules when handling SIP transactions. it has to carry subscriptions for events from the SPIRITS server to the SPIRITS client, and notifications of those events from the SPIRITS client back to the SPIRITS server. the subscriptions and notifications get codified in Extensible Markup Language (XML) [12] 💅
Okay now the naming is lowkey confusing 😭 the roles look reversed. the "SPIRITS server" is the one that ISSUES a subscription, and the "SPIRITS client" is the one that ACCEPTS it. so to clear the fog 🌫️, from here on we call the "SPIRITS server" a "SPIRITS subscriber" and the "SPIRITS client" a "SPIRITS notifier". this matches the naming in [3]. so in Figure 2, the SPIRITS server is a subscriber (issues subscriptions to events), and the SPIRITS client is a notifier (sends notifications whenever the event of interest happens). main character naming energy 👑
2.1. Terminology
for easy reference, here's a little glossary of the SPIRITS actors we talked about in the preceding above 📖🍓
Service Control Function (SCF): a PSTN entity that runs service logic. it gives you capabilities to influence the call processing happening in the Service Switching Function (SSF). if you want more on how an SCF fits into the SPIRITS architecture, check out Sections 5 and 5.1 🧚
SPIRITS client: just see SPIRITS notifier. 🫶
SPIRITS server: just see SPIRITS subscriber. 🫶
SPIRITS notifier: a User Agent (UA) in the PSTN that accepts subscriptions from SPIRITS subscribers. those subscriptions hold the events the subscribers want to get notified about. the SPIRITS notifier works with the Service Control Function so that when the event happens, a notification gets sent to the right SPIRITS subscriber 🔥
SPIRITS subscriber: a UA on the Internet that issues a subscription listing the PSTN events it wants notifications for 💜
3. Using XML for subscription and notification ✨
okay so the SPIRITS protocol requirements say that "SPIRITS-related parameters be carried in a manner consistent with SIP practices" 💅 (RFC3298:Section 3). SIP already has ways to describe the payload using headers like Content-Type and Content-Length 🎀. This doc creates a brand new MIME type, "application/spirits-event+xml", and registers it with IANA (Section 7) 🦋. That MIME type MUST be in the "Content-Type" header of SPIRITS requests and responses, and it tells you the XML document carries SPIRITS info 🫶.
This doc also sets up a base XML schema for subscriptions to PSTN events 💖. The list of events you can subscribe to lives in the SPIRITS protocol requirements document [4], and this doc gives it an XML schema 🌸. Every SPIRITS subscriber (any SPIRITS entity that can send a SUBSCRIBE, REGISTER, or INVITE request) MUST support this schema 🔥. Every SPIRITS notifier (any SPIRITS entity that can receive and process a SUBSCRIBE, REGISTER, or INVITE request) MUST support this schema too 👑. The schema lives in Section 9 ✨.
TheREGISTERsupport is there for PINT compatibility (RFC3298:Section 6) 🧚. TheINVITEsupport is mandated because the older SPIRITS implementations didn't use the SIP event notification scheme 💀. Instead, the first PSTN detection point always showed up through a SIPINVITErequest 🙈.
This doc also defines a base XML schema for event notifications (Section 9) 🌈. Every SPIRITS notifier MUST generate XML documents that match the base notification schema, and every SPIRITS subscriber MUST support XML documents that match this schema 💜.
Here's the tea ☕: which events you can subscribe to, and how much detail the PSTN entity sends back, can vary between PSTN operators 🍓. Some operators have a rich buffet of events, and others only have the basic primitive set from the SPIRITS protocol requirements document [4] 😭. This doc's base XML schema (in Section 9) MUST be used for subscribing to and notifying about that primitive set 💅. If you want a richer set, implementations MAY use extra XML namespaces that point to alternate schemas in a SPIRITS XML document ⭐. BUT every implementation MUST still support the base XML schema in Section 9 of this doc 🫶. The base schema keeps everyone interoperable, and the extra namespaces let people customize 🦋.
Here's a logical flow of the SPIRITS protocol, showing the order things happen over time (XML docs and the rest of the SPIRITS syntax get specified in later sections) 🎀. S is the SPIRITS subscriber and N is the SPIRITS notifier 💖. The SPIRIT Gateway is basically just a pure proxy, so it's left out to keep things simple ✨:
1 S->N Subscribe (events of interest in an XML document instance
using base subscription schema)
2 N->S 200 OK (Subscribe)
3 N->S Notify
4 S->N 200 OK (Notify communicating current resource state)
5 ...
6 N->S Notify (Notify communicating change in resource state;
payload is an XML document instance using
XML extensions to the base notification schema)
7 S->N 200 OK (Notify)On line 1, the subscriber subscribes to certain events with an XML doc built on this doc's base schema 🌸. On line 6, the notifier tells the subscriber that the event happened, using extensions to the base notification schema 🔥. This doc also has a base schema for event notification, and the notifier could have used it 🙈. Instead it picked extensions to the base notification schema 💅. If the subscriber understands those extensions, it can read the XML doc accordingly 🫶. BUT if the subscriber isn't programmed to understand the extensions, it MUST search the XML document for the mandatory elements 😭. Those elements MUST be present in ALL notification schemas and are detailed in Section 9 💜.
4. XML format definition 🎀
This section defines the XML-encoded SPIRITS payload format 💖. A payload like this is a well-formed XML document, made by SPIRITS notifiers and SPIRITS subscribers ✨.
The namespace URI for the elements in this doc is a Uniform Resource Name (URN) [14], using the 'ietf' namespace identifier defined in [15] and extended by [16] 🦋:
urn:ietf:params:xml:ns:spirits-1.0SPIRITS XML docs can have a default namespace, or they can use a namespace prefix following the XML namespaces convention [17] 🌈. Either way, the elements and attributes of SPIRITS XML docs MUST conform to the SPIRITS XML schema in Section 9 🔥.
The <spirits-event> element 👑
The root of a SPIRITS XML document (you can spot it by a Content-Type header of "application/spirits-event+xml">) is the <spirits-event> element 🧚. This element MUST contain a namespace declaration ('xmlns') to show which namespace the XML doc is based on 💅. XML docs that follow the SPIRITS protocol MUST contain the URN urn:ietf:params:xml:ns:spirits-1.0 in that namespace declaration 🫶. You can add other namespaces as needed ⭐.
The <spirits-event> element MUST contain at least one <Event> element, and it MAY contain more than one 🌸.
The <Event> element 🦋
The <Event> element has three attributes, and two of them are mandatory 💖. The first mandatory one is a 'type' attribute, which is either "INDPs" or "userprof" ✨.
Those types line up with the call-related events in Section 5 ("INDPs") and the non-call related events in Section 6 ("userprof") 🎀.
The second mandatory attribute is a 'name' attribute 🔥. Its values MUST be limited to the SPIRITS mnemonics defined in Section 5.2.1, Section 5.2.2, and Section 6.1 💜.
The third attribute is optional, and it's a 'mode' attribute 🌈. Its value is either "N" or "R", which mean (N)otification or (R)equest respectively (RFC3298:Section 4) 💅. If you don't set it, the default is "N" 🫶.
If the <Event> element's 'type' attribute is "INDPs", then it MUST contain at least one of these elements (unknown elements MAY be ignored): <CallingPartyNumber>, <CalledPartyNumber>, <DialledDigits>, or <Cause> 😭. These elements are defined in Section 5.2 🌸. They MUST not contain any attributes, and they MUST not be used further as parent elements 💀. They hold a string value, as described in Section 5.2.1 and 5.2.2 ✨.
If the <Event> element's 'type' attribute is "userprof", then it MUST contain a <CalledPartyNumber> element, and it MAY contain a <Cell-ID> element 🧚. None of these elements contain any attributes, and neither one must be used further as a parent element 🍓. They hold a string value, as described in Section 6.1 🎀. All other elements MAY be ignored if they aren't understood 🫶.
Here's a SPIRITS-compliant XML doc using the XML namespace from this doc, as an example 💖:
<?xml version="1.0" encoding="UTF-8"?>
<spirits-event xmlns="urn:ietf:params:xml:ns:spirits-1.0">
<Event type="INDPs" name="OD" mode="N">
<CallingPartyNumber>5551212</CallingPartyNumber>
</Event>
<Event type="INDPs" name="OAB" mode="N">
<CallingPartyNumber>5551212</CallingPartyNumber>
</Event>
</spirits-event>5. Call-related events 📞
Okay, for readers who aren't familiar with how services run in PSTN/IN, here's a quick tutorial 🎀. If you want the full deep dive, go check out [19] 🤓.
Services in PSTN/IN run on a call model 💅. A call model is a finite state machine that SSPs and other call processing elements use to track exactly what state a call is in at any moment 🌸. Call models are made of states, called PICs (Points In Call), and transitions between those states ✨. Transitions between states pass through elements called Detection Points, or DPs 🦋. DPs house one or more triggers 💜. Every trigger has firing criteria attached 🔥. When a trigger is armed (made active) and its firing criteria are met, it fires 🫶. What counts as firing criteria can change depending on which call model you're using 🌈.
When a trigger fires, the SSP formats a message with call state info and sends it to the SCP 💖. The SCP reads that call-related data and makes a response, which the SSP then uses to keep processing the call 🧚.
There are two types of Detection Points: TDPs (Trigger Detection Points) and EDPs (Event Detection Points) 🎀. TDPs come with statically armed triggers, which get armed through Service Management Tools 🍓. EDPs have dynamically armed triggers, which the SCP arms while call processing is happening ⭐. DPs can also be classified as "Request" or "Notification" DPs 💅. So you can end up with TDP-R's, TDP-N's, EDP-R's, and EDP-N's 👑.
"-R" DPs make the SSP suspend call processing when it starts talking to the SCP, and call processing picks back up once a response arrives 😭. "-N" DPs let the SSP keep going with call processing after the trigger fires and it sends the message to the SCP, just letting the SCP know an event happened 🫶.
Call models usually support different kinds of detection points 🌸. This doc uses INAP and the IN Capability Set (CS)-2 [7] call model as examples, and to make things easier to explain 💖. Other call models have similar properties though 🦋. For example, the Wireless Intelligent Network (WIN) call model also supports dynamically arming triggers 🔥. So this whole discussion doesn't just apply to wireline, it's just as true for wireless 💜.
When the SCP gets an INAP-formatted message from the SSP, and it supports the SPIRITS architecture, it can encode the INAP message contents into a SPIRITS protocol message and send it to SPIRITS-capable elements in the IP network ✨. And when responses come back from those SPIRITS-capable elements, it can reformat them into INAP and forward them back to SSPs 🧚. So converting between INAP parameters and the SPIRITS protocol (and encoding between them) is the main thing we care about here 🎀.
An SCP is the physical version of the Service Control Function 🍓. An SSP is the physical version of the Service Switching Function (and the Call Control Function) 🌈. To keep the naming consistent across the different SPIRITS drafts, this doc uses SCP and SCF interchangeably, and SSP and SSF interchangeably 💅✨
5.1. IN-specific requirements ✨
okay so first up, section 4 of [4] lays out the IN-related requirements for SPIRITS, and we're building on that 🧚. When a SUBSCRIBE request reaches the SPIRITS notifier, it MUST contain the events to be monitored (as a DP list), the mode (request or notification), and any DP-related parameters. The mode matters a LOT, bestie: with a request, the SPIRITS subscriber can influence subsequent call processing, and with a notification, no further influence is needed 💅.
Section 4 of [4] also lists the Capability Set 3 (CS-3) DPs for SPIRITS services 🎀. RFC3298:Section 4 says SPIRITS has to specify the relevant parameters of those DPs, and that's exactly what we do here. The DPs and their parameters carried in a SUBSCRIBE request are codified in an XML schema, and ALL SPIRITS subscribers MUST understand this schema so they can subscribe to DPs in the PSTN 🫶. The schema is defined in Section 9.
When a DP fires, a notification goes from the SPIRITS notifier to the SPIRITS subscriber, using a SIP NOTIFY request 🦋. That NOTIFY carries an XML document describing the DP that fired and any relevant parameters. The DPs and their parameters carried in a NOTIFY are also codified in an XML schema. ALL SPIRITS notifiers MUST understand this schema, and this schema MAY be extended 🌈. The schema is defined in Section 9.
Last bit: Appendices A and B of [6] have a select subset of CS-2 DPs that might be interesting to you 👀. BUT this document only refers to the CS-3 DPs outlined in [4], so that's the lane we're staying in 💜.
5.2. Detection points and required parameters 🌸
The IN CS-3 DPs envisioned for SPIRITS services (RFC3298:Section 4) are described next 💖. IN DPs have a TON of parameters, but not all of them are required, or even needed, by SPIRITS. This section is the cheat sheet: it lists the mandatory parameters for each DP that MUST be specified in subscriptions and notifications 🍓. Implementations can add extra parameters as XML extensions tied to a private (or public and standardized) namespace, so there's room to customize ✨.
The exhaustive list of IN CS-3 DPs and their parameters is in reference [13] 📚.
Each DP gets its own SPIRITS-specific mnemonic for use in subscriptions and notifications 🔥.
5.2.1. Originating-side DPs 📞
These are the DPs on the calling side of things 💅.
Origination Attempt Authorized
SPIRITS mnemonic: OAA
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
CallingPartyNumber: A string used to identify the calling party for
the call. The actual length and encoding of this parameter depend on
the particulars of the dialing plan used.
CalledPartyNumber: A string containing the number (e.g., called
directory number) used to identify the called party. The actual
length and encoding of this parameter depend on the particulars of
the dialing plan used.
Collected Information
SPIRITS mnemonic: OCI
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, DialledDigits
DialledDigits: This parameter contains non-translated address
information collected/received from the originating user/line/trunk
Analyzed Information
SPIRITS mnemonic: OAI
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, DialledDigits
Origination Answer
SPIRITS mnemonic: OA
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
Origination Term Seized
SPIRITS mnemonic: OTS
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber, CalledPartyNumber
Origination No Answer
SPIRITS mnemonic: ONA
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber, CalledPartyNumber
Origination Called Party Busy
SPIRITS mnemonic: OCPB
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
Route Select Failure
SPIRITS mnemonic: ORSF
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber, CalledPartyNumber
Origination Mid Call
SPIRITS mnemonic: OMC
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber
Origination Abandon
SPIRITS mnemonic: OAB
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber
Origination Disconnect
SPIRITS mnemonic: OD
Mandatory parameter in SUBSCRIBE: CallingPartyNumber
Mandatory parameter in NOTIFY: CallingPartyNumber, CalledPartyNumber5.2.2. Terminating-side DPs 📲
And now the receiving side, where the call gets picked up or dropped 💫.
Termination Answer
SPIRITS mnemonic: TA
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
Termination No Answer
SPIRITS mnemonic: TNA Mandatory parameter in SUBSCRIBE:
CalledPartyNumber
Mandatory parameters in NOTIFY: CallingPartyNumber, CalledPartyNumber
Termination Mid-Call
SPIRITS mnemonic: TMC
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber
Termination Abandon
SPIRITS mnemonic: TAB
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber
Termination Disconnect
SPIRITS mnemonic: TD
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameters in NOTIFY: CalledPartyNumber, CallingPartyNumber
Termination Attempt Authorized
SPIRITS mnemonic: TAA
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameters in NOTIFY: CalledPartyNumber, CallingPartyNumber
Termination Facility Selected and Available
SPIRITS mnemonic: TFSA
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber
Termination Busy
SPIRITS mnemonic: TB
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameters in NOTIFY: CalledPartyNumber,
CallingPartyNumber, Cause
Cause: This parameter contains a string value of either "Busy" or
"Unreachable". The difference between these is translated as a
requirement (RFC3298:Section 5) to aid in the SPIRITS subscriber in
determining if the called party is indeed busy (engaged), or if the
called party is unavailable (as it would be if it were on the
cellular PSTN and the mobile subscriber was not registered with the
network).5.3. Services through dynamic DPs ⚡
Okay this part is my fave 🥹. Triggers in the PSTN can be armed dynamically, often outside the context of a call, so the SIP event notification mechanism [3] is a super convenient thing to use when triggers housed in EDPs fire (see section 3 of [4]) 🎀. Heads up: [4] uses the term "persistent" to refer to call-related DP arming and its associated interactions.
The SIP Events Package lets IP endpoints (or hosts) subscribe to events happening in the PSTN and receive notifications about them ✨. Looking at Figure 2, this covers communication on the interfaces marked "B" and "C" 🦋.
5.3.1. Normative usage 📜
A subscriber sends a SUBSCRIBE request that names a set of events (DPs) it wants notifications for 💌. That set MUST contain at least one DP, and it MAY contain more than one. The SUBSCRIBE request gets routed to the notifier, which accepts it, pending a successful authentication 🔐.
When any DP in that set fires, the notifier formats a NOTIFY request and sends it toward the subscriber 🚀. The NOTIFY carries info about the event that was triggered. DPs that haven't been encountered MUST be subsequently dis-armed by the SPIRITS notifier and/or the SCF 🧹.
The dialog set up by the SUBSCRIBE ends once the event of interest happens and the NOTIFY gets passed to the subscriber 🏁. If the subscriber still wants to know about future occurrences of that same event, it MUST issue a new SUBSCRIBE request, which sets up a new dialog 🔁.
When the subscriber gets a NOTIFY, it can then choose to act however makes sense for that notification 💅.
The remaining sections fill in the specific package responsibilities raised in RFC3265 [3], Section 4.4 📚.
5.3.2. Event package name 🏷️
This document defines two event packages. The first one is defined in this section and is called "spirits-INDPs" 💖. This package MUST be used for events that correspond to IN detection points in the cellular or wireline PSTN. ALL entities that implement the SPIRITS protocol and support IN detection points MUST set the "Event" request header [3] to "spirits-INDPs." Also, the "Allow-Events" general header [3] MUST include the token "spirits-INDPs" if the entity implements the SPIRITS protocol and supports IN detection points 🫶.
Event: spirits-INDPs
Allow-Events: spirits-INDPsThe second event package is defined and discussed in Section 6 ✨.
5.3.3. Event package parameters 🎀
The "spirits-INDPs" event package doesn't support any additional parameters to the Event header. Nothing extra, no cap 🙅♀️.
5.3.4. SUBSCRIBE bodies 🧾
SUBSCRIBE requests that terminate the subscription MAY contain an empty body 🫧. SUBSCRIBE requests that establish a dialog, though, MUST contain a body that encodes three pieces of information. Let's break it down bestie 👑:
- The set of events (DPs) being subscribed to. A subscriber MAY subscribe to multiple DPs in one SUBSCRIBE request, or MAY issue a different SUBSCRIBE request for each DP it wants notifications for. The protocol allows for both forms, but it recommends the former way of subscribing to DPs if the service depends on any of the DPs being triggered 🌈.
- Because of the requirement [4] that IN be informed whether the detection point is set as a request or a notification, every event in the "spirits-INDPs" package (but NOT in the "spirits-user-prof" package) is required to provide a "mode" parameter. Its values are "R" (for Request) and "N" for notification 🔥.
- A list of the values of the parameters associated with the event detection point. (Quick note: the word "event" here is about the IN usage. A dynamically armed DP is called an Event Detection Point 🧚.) Check Section 5.2.1 and Section 5.2.2 for the list of parameters associated with each DP 💜.
The default body type for SUBSCRIBEs in SPIRITS is the MIME type "application/spirits-event+xml" 💌. If the "Accept" header is present, it MUST include this MIME type 💅.
5.3.5. Subscription duration ⏳
For the "spirits-INDPs" package, the point of the SUBSCRIBE request is to arm the DP, because as far as IN is concerned, being armed is the first essential prerequisite 🛡️. A DP may be armed either statically (for instance, through service provisioning) or dynamically (by the SCF). A statically armed DP stays armed until it's disarmed proactively. A dynamically armed DP stays armed for the duration of a call (or, more accurately, no longer than the duration of a particular SSF-SCF relationship) 🌸.
Dynamically armed DPs get automatically disarmed when the event of interest happens in the notifier 💥. If the subscriber wants to, it's up to them to re-arm the DPs within the context of a call 🦋.
Statically armed DPs are considered outside the scope of the SPIRITS protocol requirements [4], so we won't be discussing them any further 🫶.
5.3.6. NOTIFY bodies ✨
okay so bodies in NOTIFY requests for the spirits-INDPs package are optional 🎀 but if you include one, it MUST be application/spirits-event+xml 💌 the body packs up three things the subscriber can use:
- the event that caused the NOTIFY to be generated (usually the same event as in the SUBSCRIBE request, but not always 👀)
- the
modeparameter, which just gets reflected back from the SUBSCRIBE request 🦋 - a list of values for the parameters tied to that event. which parameters show up depends on the event itself 💅
if the subscriber armed multiple DPs in one SUBSCRIBE request, every DP from that same SUBSCRIBE dialog that hasn't been encountered yet MUST be dis-armed by the SPIRITS notifier and/or the SCF/SCP 🫶
5.3.7. Notifier processing of SUBSCRIBE requests 🌸
when the notifier gets a SUBSCRIBE request, it MUST authenticate it and make sure the subscriber is allowed to access what they're subscribing to, which here is PSTN/IN events on a certain PSTN line 🔐
once the request is authenticated and authorized, the notifier talks to the SCF over interface D to arm the detection points that match the PSTN line in the SUBSCRIBE body. the particulars of interface D are out of scope for this document 🙈 so we'll just assume the notifier can arm (and disarm) triggers in the PSTN through interface D 💖
5.3.8. Notifier generation of NOTIFY requests 💜
if the notifier expects arming the triggers to take more than 200 ms, it MUST send a 202 response to the SUBSCRIBE request right away, accepting the subscription. after that it should send a NOTIFY request with an empty body, and this NOTIFY request MUST have aSubscription-Stateheader with a value ofpending.
this immediate empty NOTIFY is needed because the resource named in the SUBSCRIBE request doesn't have a meaningful state yet 🧚
once the notifier has successfully talked to the SCF, it MUST send a later NOTIFY request with an empty body and a Subscription-State header whose value is active ⭐
when the event of interest in the SUBSCRIBE request happens, the notifier sends a new NOTIFY request, and this one MUST contain a body (see Section 5.3.6) 🔥 the NOTIFY MUST have a Subscription-State header, and its value MUST be terminated with a reason parameter of fired 💀
5.3.9. Subscriber processing of NOTIFY requests 🎀
the exact steps the subscriber takes when it gets a NOTIFY depend on the service being built 🍓 as a general vibe, the UA on the subscriber's side should somehow share this info with the user through visual or auditory means, if at all possible ✨
if the NOTIFY had a Subscription-State header with a value of terminated and a reason parameter of fired, the UA on the subscriber's side MAY start a new subscription for the event that just got reported 🦋
whether or not to start a new subscription when an existing one expires is up to the service being implemented 💅 for instance, a user might set up her UA to always re-subscribe to the same event when it fires, but that is not necessarily the normative case 🙈
5.3.10. Handling of forked requests 🚫
forking SUBSCRIBE requests is prohibited 🙅♀️ since the SUBSCRIBE request is aimed at the PSTN, really irregular behavior happens if it's allowed to fork 😭 the normal SIP DNS lookup and routing rules [11] should end up with a target set of exactly one element: the notifier 👑
5.3.11. Rate of notifications 📬
okay, so the reason for this is security more than network traffic 🔒 it is RECOMMENDED that the notifier issues two or, at most, three NOTIFY requests for a subscription 💖 if the subscription was accepted with a 202 response, a NOTIFY goes out to the subscriber immediately. that NOTIFY tells the subscriber the request was accepted and is being acted on ✨
once the resource (the detection points) named in the SUBSCRIBE request has been initialized, the notifier MUST send a second NOTIFY request. this one carries the base state of the resource 🌈
when an event of interest happens that fires the trigger tied to the detection points in the SUBSCRIBE request, a final NOTIFY is sent to the subscriber. this NOTIFY has more info about the event of interest 🧚♀️
if the subscription was accepted with a 200 response, the notifier just sends two NOTIFY requests: one with the base state of the resource, and one with the info that led to the detection point firing 🫶
5.3.12. State agents 🙅♀️
State agents are not used in SPIRITS 💅
5.3.13. Examples ✨
okay so this section is basically a walkthrough of a SPIRITS service called Internet Caller-ID Delivery (ICID) 📞💖 It's one of the benchmark SPIRITS services from section 2.2 of [1], and the description goes:
This service allows the subscriber to see the caller's number or name or both while being connected to the Internet. If the subscriber has only one telephone line and is using the very line for the Internet connection, the service is a subset of the ICW service and follows the relevant description in Section 2.1. Otherwise, the subscriber's IP host serves as an auxiliary device of the telephone to which the call is first sent.
We're giving you an example call flow for it 🦋 Just a heads up: this is an example only, not a normative description of the Internet Caller-ID service, so don't treat it as the official rulebook 🙈
Everything from here on refers to Figure 3 🎀 The figure shows the 4 entities that are part of any SPIRITS service (the headings use the names from Figure 1 in [1]): the SPIRITS subscriber, the SPIRITS notifier, and the SCF. The SPIRITS gateway isn't in this figure. Logically, SPIRITS messages flow between the SPIRITS server and the SPIRITS client, and a gateway, if there is one, may act as a proxy 💅
SPIRITS server SPIRITS client SCF
("subscriber") ("notifier")
S N
| | |
| F1 SUBSCRIBE | |
+--------------------->+ |
| | |
| | F2 Arm DP |
| F3 200 OK (SUBS) +--------------->|
|<---------------------| |
| | |
| F4 NOTIFY | |
|<---------------------+ |
| | |
| F5 200 OK (NOT) | |
+--------------------->| |
| | |
~ ~ ~
~ ~ ~
| | F6 Evt. Not. |
| |<---------------+
| F7 NOTIFY + |
|<---------------------| |
| | |
| F8 200 OK (NOT) | |
+--------------------->| |
| | |
| | |
\|/ \|/ \|/
v v v
Figure 3: Sample call flowThis call flow shows a "subscriber" successfully subscribing to the IN Termination_Attempt_Authorized DP 🌸 The subscriber is assumed to be a user, possibly at work, who wants to know when they get a call on their home phone number. All of this happens across messages F1 through F8 in Figure 3. The user sends (F1) a SIP SUBSCRIBE request that names the DP they care about, plus zero or more parameters relevant to that DP (in this example, the Termination_Attempt_DP gets used). The SPIRITS notifier in turn talks to the SCF to arm the Termination_Attempt_DP for the service (F2). Then an immediate NOTIFY with the current state goes to the subscriber (F4, F5) ✨
Some time after all that, the PSTN gets a call to the user's phone 📱 The SSF tells the SCF about it when it hits an armed Termination_Attempt_DP (not shown in Figure 3), and the SCF tells the SPIRITS notifier (F6) 👀
When the SPIRITS notifier gets that event, it builds a SIP NOTIFY request and sends it to the SPIRITS subscriber (F7). This NOTIFY carries all the info needed to identify the caller. The subscriber gets the notification (F8) and might pop open a window showing the date, time, and the caller's number 🫶
The rest of this section goes through the SIP messages in Figure 3 in detail. For this example, the call flows assume the SPIRITS gateway is a SIP proxy. It works as the default outbound proxy for the notifier and as an ingress host of the myprovider.com domain for the subscriber. The subscriber and notifier may be in separate administrative domains 🌈
F1: S->N
SUBSCRIBE sip:myprovider.com SIP/2.0
From: <sip:vkg@example.com>;tag=8177-afd-991
To: <sip:16302240216@myprovider.com>
CSeq: 18992 SUBSCRIBE
Call-ID: 3329as77@host.example.com
Contact: <sip:vkg@host.example.com>
Via: SIP/2.0/UDP host.example.com;branch=z9hG4bK776asdhds
Expires: 3600
Event: spirits-INDPs
Allow-Events: spirits-INDPs, spirits-user-prof
Accept: application/spirits-event+xml
Content-Type: application/spirits-event+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<spirits-event xmlns="urn:ietf:params:xml:ns:spirits-1.0">
<Event type="INDPs" name="TAA" mode="N">
<CalledPartyNumber>6302240216</CalledPartyNumber>
</Event>
</spirits-event>The subscriber builds a SIP SUBSCRIBE request that says which DP it wants (here, the TAA DP) and which line it wants that DP armed for (here, the line tied to the phone number 6302240216) 💜 The request ends up at the SPIRITS notifier, N, which authenticates it (not shown) and sends back a successful response to the subscriber:
F3: N->S
SIP/2.0 200 OK
From: <sip:vkg@example.com>;tag=8177-afd-991
To: <sip:16302240216@myprovider.com>;tag=SPIRITS-TAA-6302240216
CSeq: 18992 SUBSCRIBE
Call-ID: 3329as77@host.example.com
Contact: <sip:notifier.myprovider.com>
Via: SIP/2.0/UDP host.example.com;branch=z9hG4bK776asdhds
Expires: 3600
Accept: application/spirits-event+xml
Content-Length: 0The notifier talks to the SCF to arm the DP, and it also sends an immediate NOTIFY to the subscriber so they know the current state of the notification 🔥
F4: N->S
NOTIFY sip:vkg@host.example.com SIP/2.0
From: <sip:16302240216@myprovider.com>;tag=SPIRITS-TAA-6302240216
To: <sip:vkg@example.com>;tag=8177-afd-991
Via: SIP/2.0/UDP gateway.myprovider.com;branch=z9hG4bK-9$0-1
Via: SIP/2.0/UDP notifier.myprovider.com;branch=z9hG4bKqo--9
Call-ID: 3329as77@host.example.com
Contact: <sip:notifier.myprovider.com>
Subscription-State: active
CSeq: 3299 NOTIFY
Accept: application/spirits-event+xml
Content-Length: 0F5: S->N
SIP/2.0 200 OK
From: <sip:16302240216@myprovider.com>;tag=SPIRITS-TAA-6302240216
To: <sip:vkg@example.com>;tag=8177-afd-991
Via: SIP/2.0/UDP gateway.myprovider.com;branch=z9hG4bK-9$0-1
Via: SIP/2.0/UDP notifier.myprovider.com;branch=z9hG4bKqo--9
Call-ID: 3329as77@host.example.com
Contact: <sip:vkg@host.example.com>
CSeq: 3299 NOTIFY
Accept: application/spirits-event+xml
Content-Length: 0At some later point (before the subscription from F1 expires at the notifier), a call comes in to the number in the XML body of F1, which is 6302240216 📞 The SCF tells the notifier about it (F6). That notification includes the relevant PSTN info, namely the phone number of the person trying to call 6302240216. The notifier uses that info to build a SIP NOTIFY request and sends it to the subscriber. This SIP NOTIFY has an XML body with the relevant PSTN info:
F7: N->S
NOTIFY sip:vkg@host.example.com SIP/2.0
From: <sip:16302240216@myprovider.com>;tag=SPIRITS-TAA-6302240216
To: <sip:vkg@example.com>;tag=8177-afd-991
Via: SIP/2.0/UDP notifier.myprovider.com;branch=z9hG4bK9inn-=u7
Call-ID: 3329as77@host.example.com
Contact: <sip:notifier.myprovider.com>
CSeq: 3300 NOTIFY
Subscription-State: terminated;reason=fired
Accept: application/spirits-event+xml
Event: spirits-INDPs
Allow-Events: spirits-INDPs, spirits-user-prof
Content-Type: application/spirits-event+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<spirits-event xmlns="urn:ietf:params:xml:ns:spirits-1.0">
<Event type="INDPs" name="TAA" mode="N">
<CalledPartyNumber>6302240216</CalledPartyNumber>
<CallingPartyNumber>3125551212</CallingPartyNumber>
</Event>
</spirits-event>Two important things to notice about the F7 flow 👑
- The body of the NOTIFY request carries the info the SPIRITS notifier got from the SCF. In this example, that's the phone number of the party (3125551212) who tried to call 6302240216.
- Because the notification happened, the subscription from F1 terminated, which you can see in the Subscription-State header. It ended normally because the DP tied to TAA fired, which is why the Subscription-State header has the reason code "fired". If the subscriber wants to hear about another call to 6302240216, they need to send a new SUBSCRIBE request to the notifier 💀
The subscriber can take whatever action makes sense once the NOTIFY in F7 arrives 🧚 A reasonable implementation might pop up a window filled with the info from the body of F12, along with a button asking the subscriber if they'd like to re-subscribe to the same event. Or the subscriber's UA could re-subscribe automatically, based on the user's preferences 🍓
To finish the protocol, the subscriber also sends a 200 OK message to the notifier:
F8: S->N
200 OK SIP/2.0
From: <sip:16302240216@myprovider.com>;tag=SPIRITS-TAA-6302240216
To: <sip:vkg@example.com>;tag=8177-afd-991
Via: SIP/2.0/UDP notifier.myprovider.com;z9hG4bK9inn-=u7
Call-ID: 3329as77@host.example.com
CSeq: 3300 NOTIFY
Content-Length: 05.3.14. Use of URIs to retrieve state 🦋
Here's the rule: the "spirits-INDPs" package MUST NOT use URIs to retrieve state 🙅♀️ The idea is that most of the state info for this package is compact enough to fit inside a SIP message. Still, to play it safe, implementations MUST follow the convention in Section 18.1.1 of [5] and use a congestion controlled transport if the size of the request is within 200 bytes of the path MTU when that's known, or if the request size is larger than 1300 bytes and the path MTU is unknown 🫶
5.4. Services through static DPs 🌸
okay so back in Section 5.1 we said the first trigger that fires during call processing is usually a TDP, because there isn't any existing control relationship between the SSF and the SCF yet 🫶 Some Internet hosts may have said "we're interested in running services based on TDPs" (through an a-priori arrangement that isn't part of this spec ✨). So the PSTN notifies those hosts. It does that by sending a SIP request (typically an INVITE) to the Internet host. The body of the SIP request MUST contain multi-part MIME with two MIME components: the first part is the normal payload of the request, if there is one, and the second part holds SPIRITS-specific info (e.g., the DP that fired) 💅 Responses to the INVITE, or later SUBSCRIBE messages from the Internet host to the PSTN within a current call context, may result in EDPs being armed 🦋
5.4.1. Internet Call Waiting (ICW)
ICW is the benchmark SPIRITS service, and it actually existed before SPIRITS did 👑 Pre-SPIRITS implementations of ICW are detailed in [10]. Here's the tea though: as that document notes, there's a whole diversity of implementations, and they are NOT interoperable 💀 When [10] was published, the industry didn't have as much experience with SIP as it does now. The use of SIP in [10] doesn't count as normative usage of SIP as described in [5]. For example, there's no mention of the SDP (if any) in the initial INVITE, especially since that pertains to the "accept the call using VoIP" case. So this section is here to give a normative description of ICW in SPIRITS 🎀
The ICW description is deceptively simple. It's a service that's most useful for single line phone subscribers who use that line to establish an Internet session. In a nutshell, the service lets a subscriber who's in an Internet dial-up session:
- be notified of an incoming call to the very same telephone line that's being used for the Internet connection,
- specify the desirable treatment of the call, and
- have the call handled as specified.
5.4.2. Call disposition choices
Section 2 of [10] details the call disposition outcomes of an ICW session. They're reproduced here as a numbered list for further discussion 📝
- Accepting the call over the PSTN line, thus terminating the Internet (modem) connection
- Accepting the call over the Internet using Voice over IP (VoIP)
- Rejecting the call
- Playing a pre-recorded message to the calling party and disconnecting the call
- Forwarding the call to voice mail
- Forwarding the call to another number
- Rejecting (or Forwarding) on no Response - If the subscriber fails to respond within a certain period of time after the dialog box has been displayed, the incoming call can be either rejected or handled based on the treatment pre-defined by the subscriber.
For the sake of completeness, ICW as a SPIRITS service isn't possible unless the SCP knows the subscriber line is being used for an Internet session 🫠 That awareness isn't part of the ICW service itself, it's just a prerequisite. One of the following three methods MUST be utilized to give the SCP this info:
- A. ICW subscriber based method: the ICW client on the subscriber's PC notifies the SCP of the Internet session by issuing a SIP REGISTER request.
- B. IN based method: the SCP maintains a list of Internet Service Provider (ISP) access numbers for a geographical area. When one of these numbers is dialed and connected to, it (the SCP) assumes that the calling party is engaged in an Internet session.
- C. Any combination of methods A and B.
ICW depends on a TDP being provisioned in the SSP ✨ When that TDP is encountered, the SSP suspends processing of the call and sends a request to the SPIRITS-capable SCP. The SCP determines that the subscriber line is being used for an Internet session, and then it instructs the SPIRITS notifier on the SCP to create a SIP INVITE request and send it to the SPIRITS subscriber running on the subscriber's IP host 🦋
The SPIRITS subscriber MUST return one of the possible call disposition outcomes catalogued in Section 5.4.2. Note that outcomes 1 and 4 through 7 can all be coalesced into one case, namely redirecting (using the SIP 3xx response code) the call to an alternative SIP URI 💖 In case of 1, the URI of the redirected call MUST match the very same number the customer used to get online. Rejecting the call means sending a non-2xx and non-3xx final response. The remaining outcomes result in the call being redirected to an alternate URI that provides the desired service (i.e., play a pre-recorded announcement, or record a voice message).
Once the SPIRITS notifier gets a final response, here's how the processing goes, summarized in steps 🍓
- If the response is a 4xx, 5xx, or 6xx class of response, generate and transmit an ACK request and instruct the SSP to play a busy tone to the caller.
- Else, for all 3xx responses, generate and transmit an ACK request, and compare the redirected URI to the subscriber's line number:
- 2a. If the comparison indicates a match, instruct the SSP to hold onto the call for just enough time to allow the SPIRITS subscriber to disconnect the modem, thus freeing up the line; and then continue with normal call processing, which will result in the subscriber's phone ringing.
- 2b. If the comparison fails, instruct the SSP to route the call to the redirected URI.
- Else, for a 2xx response, follow the steps in section 5.4.3.
5.4.3. Accepting an ICW session using VoIP
One call handling option in ICW is to "accept an incoming call using VoIP" 🎧 The SPIRITS notifier has no way of knowing ahead of time whether the subscriber (callee) will pick this option. Still, it has to account for that choice by adding an SDP in the body of the INVITE request. One way to do this is for the SPIRITS notifier to control a PSTN gateway and allocate appropriate resources on it. Once that's done, the SPIRITS notifier adds network information (the IP address of the gateway and the port numbers where media will be received) and codec information as the SDP portion of the body in the INVITE request. SPIRITS also requires the DP information to be carried in the request body, so the SPIRITS notifier MUST also add the information associated with the TDP that triggered the service. Thus, the body of the INVITE MUST contain multi-part MIME, with two components 🫶
The SPIRITS notifier transmits the INVITE request to the subscriber and then waits for a final response. Further processing when the SPIRITS subscriber returns a 200 OK MUST be handled as follows:
On the receipt of a 200 OK containing the SDP of the subscriber's UA, the SPIRITS notifier will instruct the SSP to terminate the call on a pre-allocated port on the gateway. This port MUST be correlated by the gateway to the SDP that was sent in the earlier INVITE.
The end result is that the caller and callee hold a voice session, with part of the session happening over VoIP 💜
6. Non-call related events ✨
There are network events that aren't about setting up, maintaining, or tearing down voice calls 🧚 These events happen on the cellular wireless network, and SPIRITS can use them to provide services. The SPIRITS protocol requirements explicitly include the following events, which need SPIRITS notification (RFC3298:Section 5(b)):
- Location update in the same Visitor Location Register (VLR) service area
- Location update in another VLR service area
- International Mobile Subscriber Identity (IMSI) attach
- Mobile Subscriber (MS) initiated IMSI detach
- Network initiated IMSI detach
6.1. Non-call events and their required parameters
Each of the five non-call related events gets its own SPIRITS-specific mnemonic for use in subscriptions and notifications 🌈
Location update in the same VLR area
SPIRITS mnemonic: LUSV
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber, Cell-IDCell-ID is a string used to identify the serving Cell-ID. Its actual length and representation depend on the particulars of the cellular provider's network 📡
Location update in different VLR area
SPIRITS mnemonic: LUDV
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber, Cell-IDIMSI attach
SPIRITS mnemonic: REG
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber, Cell-IDMS initiated IMSI detach
SPIRITS mnemonic: UNREGMS
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumberNetwork initiated IMSI detach
SPIRITS mnemonic: UNREGNTWK
Mandatory parameter in SUBSCRIBE: CalledPartyNumber
Mandatory parameter in NOTIFY: CalledPartyNumber6.2. Normative usage
A subscriber issues a SUBSCRIBE request that identifies a set of non-call related PSTN events it wants notifications for 🎀 This set MAY contain exactly one event, or it MAY contain multiple events. The SUBSCRIBE request is routed to the notifier, where it is accepted, pending a successful authentication.
When any of the events in the set occurs, the notifier formats a NOTIFY request and directs it towards the subscriber. The NOTIFY request contains information pertinent to the one event whose notification was requested 💅
The dialog established by the SUBSCRIBE persists until it expires normally, or until the subscriber explicitly expires it. This is different from the behavior for subscriptions associated with the "spirits-INDPs" package. In the cellular network, the events subscribed for can occur far more frequently than those on the wireline network (think about location updates as a cellular user moves around 🚶♀️). So it's much more expedient to let the subscription expire normally 🙈
When a subscriber receives a NOTIFY request, it can then choose to act in a manner appropriate to the notification ✨
The remaining sections fill in the specific package responsibilities raised in RFC3265 [3], Section 4.4.
6.3. Event package name
This document defines two event packages. The first was defined in Section 5.3. The second, defined in this section, is called "spirits-user-prof" 🦋 This package MUST be used for events corresponding to non-call related events in the cellular network. All entities that implement the SPIRITS protocol and support the non-call related events outlined in the SPIRITS protocol requirements (RFC3298:Section 5(b)) MUST set the "Event" header request header[3] to "spirits-user-prof." The "Allow-Events" general header [3] MUST include the token "spirits-user-prof" as well.
Example:
Event: spirits-user-prof
Allow-Events: spirits-user-prof, spirits-INDPs6.4. Event package parameters
The "spirits-user-prof" event package doesn't support any additional parameters to the Event header 🌸
6.5. SUBSCRIBE bodies ✨
okay so SUBSCRIBE requests that end the subscriptions MAY have an empty body 🫶, but SUBSCRIBE requests that set up a dialog MUST have a body that carries two pieces of info 💅:
- The set of events being subscribed to. A subscriber MAY subscribe to multiple events in one SUBSCRIBE request, or MAY issue a different SUBSCRIBE request for each event it wants notifications for 🦋. The protocol supports both ways. Just know that if one SUBSCRIBE covers multiple events, then an expiry for the dialog tied to that subscription hits all of those events at once 😭.
- A list of values for the parameters tied to the event. Check Section 6.1 for the parameters that go with each event 🌸.
The default body type for SUBSCRIBEs in SPIRITS is the MIME type "application/spirits-event+xml" 🎀. The "Accept" header, if present, MUST include this MIME type 💖.
6.6. Subscription duration ⏳
the dialog made by a SUBSCRIBE request only lasts as long as the expiration time the subscriber and notifier agreed on when it was set up 🕰️. If the subscriber wants to keep it alive, it MUST send a new SUBSCRIBE to refresh the dialog 🔄. You can end a dialog by sending a new SUBSCRIBE request with an "Expires" header value of 0, as outlined in [3] 🧚.
6.7. NOTIFY bodies 📬
Bodies in NOTIFY requests for the spirits-user-prof package are optional 🙈. If they show up, they MUST be of the MIME type "application/spirits-event+xml" 💅. The body in a NOTIFY request holds these two things, which the subscriber can use 👑:
- The event that caused the NOTIFY to be generated (usually, but not always, this is the same event that was in the matching SUBSCRIBE request).
- A list of values for the parameters tied to the event the NOTIFY is for. The parameters change depending on the actual event 🦋.
6.8. Notifier processing of SUBSCRIBE requests 🔐
When the notifier gets a SUBSCRIBE request, it MUST authenticate the request and make sure the subscriber is authorized to access the resource being subscribed to. In this case, that resource is non-call related cellular events for a mobile phone 📱.
Once the SUBSCRIBE request is authenticated and authorized, the notifier talks to the SCF over interface D to set marks in the HLR for the mobile phone number in the SUBSCRIBE body 🌈. The particulars of interface D are outside the scope of this document. Here we simply assume the notifier can set the right marks in the HLR 🫶.
6.9. Notifier generation of NOTIFY requests 🔔
If the notifier expects setting the marks in the HLR to take more than 200 ms, it MUST send a 202 response to the SUBSCRIBE request right away, accepting the subscription ⚡. It should then send a NOTIFY request with an empty body. This NOTIFY request MUST have a "Subscription-State" header with a value of "pending" 🌸.
This immediate NOTIFY with an empty body is needed since the resource identified in the SUBSCRIBE request does not have a meaningful state yet 🙈.
Once the notifier has successfully interfaced with the SCF, it MUST send a later NOTIFY request with an empty body and a "Subscription-State" header with a value of "active." 🎉 When the event of interest identified in the SUBSCRIBE request occurs, the notifier sends out a new NOTIFY request, which MUST contain a body as described in Section 6.7 💜.
6.10. Subscriber processing of NOTIFY requests 👀
The exact steps the subscriber takes when it gets a NOTIFY request depend on the service being implemented 💅. As a general rule, the UA on the subscriber side should somehow tell the user about this information by visual or auditory means, if at all possible 🔥.
6.11. Handling of forked requests 🍴
Forking of SUBSCRIBE requests is prohibited 🚫. Since the SUBSCRIBE request is aimed at the PSTN, highly irregular behaviors happen if it's allowed to fork 💀. The normal SIP DNS lookup and routing rules [11] should result in a target set with exactly one element: the notifier 🎯.
6.12. Rate of notifications 🐢
For reasons of congestion control, it's important that the rate of notifications doesn't get excessive 🚦. For example, if a subscriber subscribes to the location update event for a notifier zooming through the cellular network at high speed, it's totally possible the notifier could generate lots of NOTIFY requests in a tiny time frame 🏎️. So within this package, the location update event needs a proper throttling mechanism ✨.
Whenever a SPIRITS notifier sends a location update NOTIFY, it MUST start a timer (Tn) with a value of 15 seconds ⏱️. If a later location update NOTIFY request needs to go out before the timer has expired, it MUST be discarded 🗑️. Any future location update NOTIFY requests MUST be transmitted only if Tn has expired (i.e. 15 seconds have passed since the last NOTIFY request was send out) 💖. If a location update NOTIFY is send out, Tn should be reset to go off again in 15 seconds 🔁.
6.13. State agents 🙅♀️
State agents are not used in SPIRITS 💅.
6.14. Examples 🎀
okay so this section walks through a SPIRITS service that can update the presence status of a mobile user 📱 The call flow is in Figure 4 below 🦋
SPIRITS server SPIRITS client SCF
("subscriber") ("notifier")
S N
| | |
| F1 SUBSCRIBE | |
+--------------------->+ |
| | |
| | F2 Set HLR mark|
| F3 200 OK (SUBS) +--------------->|
|<---------------------| |
| | |
| F4 NOTIFY | |
|<---------------------+ |
| | |
| F5 200 OK (NOT) | |
+--------------------->| |
| | |
~ ~ ~
~ ~ ~
| | F6 Evt. Not. |
| |<---------------+
| F7 NOTIFY + |
|<---------------------| |
| | |
| F8 200 OK (NOT) | |
+--------------------->| |
| | |
| | |
\|/ \|/ \|/
v v v
Figure 4: Sample call flowso in F1 of Figure 4, the subscriber basically says "ping me when a mobile user registers with the cellular network" 📡 the cellular network notes that (F2) and confirms the subscription (F3-F5) 💖 then when the mobile user turns on her cell phone and registers, that event gets detected (F6) ✨ and the cellular network sends a notification to the subscriber telling it what happened (F7-F8) 🦋
alright, let's get into the deets 💅
In F1, the subscriber subscribes to the registration event (REG) of a cellular phone number. 📞
SUBSCRIBE sip:myprovider.com SIP/2.0
From: <sip:vkg@example.com>;tag=8177-afd-991
To: <sip:16302240216@myprovider.com>
CSeq: 18992 SUBSCRIBE
Call-ID: 3329as77@host.example.com
Contact: <sip:vkg@host.example.com>
Via: SIP/2.0/UDP host.example.com;branch=z9hG4bK776asdhdsa8
Expires: 3600
Event: spirits-user-prof
Allow-Events: spirits-INDPs, spirits-user-prof
Accept: application/spirits-event+xml
Content-Type: application/spirits-event+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<spirits-event xmlns="urn:ietf:params:xml:ns:spirits-1.0">
<Event type="userprof" name="REG">
<CalledPartyNumber>6302240216</CalledPartyNumber>
</Event>
</spirits-event>so the subscription hits the notifier, which authenticates the request (not shown) and talks to the SCF to update the subscribers database for this event 💜 then the notifier sends back a successful response 🌈
SIP/2.0 200 OK
From: <sip:vkg@example.com>;tag=8177-afd-991
To: <sip:16302240216@myprovider.com>;tag=SPIRITS-REG-16302240216
CSeq: 18992 SUBSCRIBE
Call-ID: 3329as77@host.example.com
Contact: <sip:notifier.myprovider.com>
Via: SIP/2.0/UDP host.example.com;branch=z9hG4bK776asdhdsa8
Expires: 3600
Allow-Events: spirits-INDPs, spirits-user-prof
Accept: application/spirits-event+xml
Content-Length: 0the notifier also sends a NOTIFY request to confirm the subscription 🙌
NOTIFY sip:vkg@host.example.com SIP/2.0
To: <sip:vkg@example.com>;tag=8177-afd-991
From: <sip:16302240216@myprovider.com>;tag=SPIRITS-REG-16302240216
CSeq: 9121 NOTIFY
Call-ID: 3329as77@host.example.com
Contact: <sip:notifier.myprovider.com>
Subscription-State: active
Via: SIP/2.0/UDP notifier.myprovider.com;branch=z9hG4bK7007-091a
Allow-Events: spirits-INDPs, spirits-user-prof
Accept: application/spirits-event+xml
Content-Length: 0and the subscriber confirms it got that NOTIFY 🫶
SIP/2.0 200 OK
To: <sip:vkg@example.com>;tag=8177-afd-991
From: <sip:16302240216@myprovider.com>;tag=SPIRITS-REG-16302240216
CSeq: 9121 NOTIFY
Call-ID: 3329as77@host.example.com
Contact: <sip:vkg@host.example.com>
Via: SIP/2.0/UDP notifier.myprovider.com;branch=z9hG4bK7007-091a
Content-Length: 0now F6, the big moment 😭 the mobile user with PSTN number "6302240216" turns on her phone, which makes it register with the cellular network. The network detects that, and since a subscriber has shown interest in this event, a SIP NOTIFY gets sent over to the subscriber 🚀
NOTIFY sip:vkg@host.example.com SIP/2.0
To: <sip:vkg@example.com>;tag=8177-afd-991
From: <sip:16302240216@myprovider.com>;tag=SPIRITS-REG-16302240216
CSeq: 9122 NOTIFY
Call-ID: 3329as77@host.example.com
Contact: <sip:notifier.myprovider.com>
Subscription-State: terminated;reason=fired
Via: SIP/2.0/UDP notifier.myprovider.com;branch=z9hG4bK7yi-p12
Event: spirits-user-prof
Allow-Events: spirits-INDPs, spirits-user-prof
Accept: application/spirits-event+xml
Content-Type: application/spirits-event+xml
Content-Length: ...
<?xml version="1.0" encoding="UTF-8"?>
<spirits-event xmlns="urn:ietf:params:xml:ns:spirits-1.0">
<Event type="userprof" name="REG">
<CalledPartyNumber>6302240216</CalledPartyNumber>
<Cell-ID>45987</Cell-ID>
</Event>
</spirits-event>the subscriber gets the notification and acknowledges it with a response 🌸
SIP/2.0 200 OK
To: <sip:vkg@example.com>;tag=8177-afd-991
From: <sip:16302240216@myprovider.com>;tag=SPIRITS-REG-16302240216
CSeq: 9122 NOTIFY
Call-ID: 3329as77@host.example.com
Via: SIP/2.0/UDP notifier.myprovider.com;branch=z9hG4bK7yi-p12
Content-Length: 0once the subscriber has that notification, it can run whatever services make sense 👑 in this example, the subscriber could be a presence service composer that flips the presence status of the user on phone number "6302240216" to "on" 🟢 also peep F7, where the notifier included a Cell ID in the notification 👀
the Cell ID can be used as a basis for location specific services 📍 but talking about those services is out of scope for this document, so we're leaving that for another day 🙈
6.15. Use of URIs to retrieve state 🧚
okay, this one's a rule 💅 the "spirits-user-prof" package MUST NOT use URIs to retrieve state. Honestly, most of this package's state is tiny enough to fit inside a SIP message 💜 but just to be safe, implementations MUST follow the convention in Section 18.1.1 of [5] and use a congestion controlled transport if the request size is within 200 bytes of the path MTU when that's known, or if the request size is bigger than 1300 bytes and the path MTU is unknown ⭐
7. IANA Considerations 🌈
so this document asks IANA to:
- register two new SIP Event Packages per [3].
- register a new MIME type per [20].
- register a new namespace URN per [16].
- register a new XML schema per [16].
7.1. Registering event packages 🌸
here are the two event packages, ready to go 💖
Package Name: spirits-INDPs
Type: package
Contact: Vijay K. Gurbani, vkg@lucent.com
Reference: RFC 3910
Package Name: spirits-user-prof
Type: package
Contact: Vijay K. Gurbani, vkg@lucent.com
Reference: RFC 39107.2. Registering MIME type 🎀
next up is the MIME type, and it's giving full registration energy 💅
MIME media type name: application
MIME subtype name: spirits-event+xml
Mandatory parameters: none
Optional parameters: charset (same semantics of charset parameter in
application/xml [9])
Encoding considerations: same as considerations outlined for
application/xml in [9].
Security considerations: Section 10 of [9] and Section 8 of this
document.
Interoperability considerations: none.
Published specifications: this document.
Applications which use this media type: SPIRITS aware entities which
adhere to this document.
Additional information:
Magic number(s): none.
File extension(s): none.
Macintosh file type code(s): none.
Object Identifier(s) or OID(s): none.
Person and email address for further information: Vijay K. Gurbani,
<vkg@lucent.com>
Intended usage: Common
Author/Change controller: The IETF7.3. Registering URN 💜
and here's the namespace URN, with its XML registration page 🧚
URI
urn:ietf:params:xml:ns:spirits-1.0
Description
This is the XML namespace URI for XML elements defined by this
document. Such elements describe the SPIRITS information in the
"application/ spirits-event+xml" content type.
Registrant Contact
IESG.
XML
BEGIN
<?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML Basic 1.0//EN"
"http://www.w3.org/TR/xhtml-basic/xhtml-basic10.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type"
content="text/html;charset=utf-8"/>
<title>Namespace for SPIRITS-related information</title>
</head>
<body>
<h1>Namespace for SPIRITS-related information</h1>
<h2>application/spirits-event+xml</h2>
<p>See <a href="[[[URL of published RFC]]]">RFC3910</a>.</p>
</body>
</html>
END7.4. Registering XML schema 🦋
last one: the XML schema registration ✨
URI
urn:ietf:params:xml:schema:spirits-1.0
Description
XML base schema for SPIRITS entities.
Registrant Contact
IESG.
XML
Please see XML schema definition in Section 9 of this document.8. Security Considerations ✨
okay bestie, this section is all about the security stuff that's unique to SPIRITS 🔐. The core SIP security stuff lives in the core SIP spec [5] and is outside this doc. SPIRITS builds on and strengthens SIP security [5]. For example, SPIRITS mandates support for S/MIME 💅. Beyond that, any other SIP security solution from [5], like TLS or HTTP Digest authentication, can be used by SPIRITS operators.
As Chapter 9 (Security Consideration) of RFC3298 [4] lays out, these security aspects apply to SPIRITS:
- Authentication 🪪
- Integrity 🧷
- Confidentiality 🤫
- Non-repudiation 📜
The SPIRITS architecture in Figure 1 has 5 interfaces, A, B, C, D, and E 🦋. Only two of them, B and C, are actually of interest to SPIRITS. Interfaces A and E are PINT interfaces, so they're assumed secured by the PINT RFC [8] 🙌. Security for interface D is out of scope here since it's mostly about the PSTN infrastructure 🏢. We'll talk about security on interfaces B and C, but with some assumptions attached.
A big driving assumption is that the SPIRITS gateway is owned by the same PSTN operator that owns the SPIRITS notifier 👑. So it's tempting to just hand off interface C security to the PSTN operator, and honestly there are real merits to that, since interface C crosses both the IP Network and PSTN boundaries 🌉. BUT, if you look closer, interfaces B and C both carry the SPIRITS protocol. So any security setup we pick for interface B can be applied to interface C too 🎀. That means you can secure interface C even when the SPIRITS gateway belongs to a different PSTN operator than the SPIRITS notifier 🫶.
The security talk that follows assumes the SPIRITS subscriber talks directly to the SPIRITS notifier (and vice-versa), and it lays out a security setup for that. Same setup works for talking through an intermediary, like the SPIRITS gateway: subscriber to intermediary, and that intermediary to the SPIRITS notifier 🧚.
Confidentiality is a must-have for SPIRITS 🙈. The info inside the protocol data units is sensitive, and if it leaks to unauthorized parties it can cause privacy problems 😭. The path between the SPIRITS notifier and the SPIRITS subscriber should be secured with S/MIME [18] to protect privacy, as described in the Security Consideration section of the core SIP spec [5] 🔒.
S/MIME is end-to-end. It encrypts the SPIRITS bodies so they can travel across an open network. Intermediaries don't need to know anything about S/MIME to route messages, since the routing headers travel in the clear 🛣️.
S/MIME covers every security aspect for SPIRITS we listed at the top of this section: authentication, message integrity, confidentiality, and non-repudiation 💖. The authentication piece means the recipient of a SPIRITS message can check that the SPIRITS payload really came from an authorized entity ✅. Encryption means only SPIRITS entities holding a particular decryption key can look inside the encapsulated SPIRITS bodies in a SIP request 🗝️.
All SPIRITS endpoints MUST support S/MIME signatures (CMS SignedData) and MUST support encryption (CMS EnvelopedData) 💅.
If the B and C interfaces belong to the same PSTN operator, public keys might get installed directly in the SPIRITS endpoints 🔑.
S/MIME has two ways of naming the public key needed to validate a signature: issuerAndSerialNumber and subjectKeyIdentifier 🏷️. subjectKeyIdentifier is the more flexible one, since it works with X.509 certificates and other schemes too. issuerAndSerialNumber only works with X.509 certificates 📇. If the administrator configures the necessary public keys and provides integrity through procedural means, S/MIME can be used without X.509 certificates at all 🧾.
All requests (and responses) between SPIRITS entities MUST be encrypted 🔐✨.
When a request shows up at a SPIRITS notifier from a SPIRITS subscriber, the SPIRITS notifier MUST authenticate the request 🚪. If authentication fails, the subscription (or registration) from that SPIRITS subscriber MUST be rejected 🙅♀️. If the SPIRITS subscriber successfully authenticated itself to the SPIRITS notifier, the SPIRITS notifier MUST, at the very least, make sure the SPIRITS subscriber is actually allowed to receive notifications for the events it's subscribing to 🎯.
Note that this document doesn't dictate how the SPIRITS notifier does this 🤷♀️. In practice it could be through access control lists (ACL) populated by a service management system in the PSTN, or through some kind of web interface.
Requests going from the SPIRITS notifier to SPIRITS subscribers MUST also be authenticated 🛡️. Otherwise a malicious party could fraudulently pose as a SPIRITS notifier and hijack a session 😱💀.
9. XML schema definition 🎀
The SPIRITS payload is specified in XML, and this section defines the base XML schema for the documents that make up the SPIRITS payload 📄. All SPIRITS entities that transport a payload with the MIME type "application/spirits-event+xml" MUST support documents that match the base schema below 💜.
Multiple versions of the base schema aren't expected 🙅♀️. Instead, any extra functionality (like conveying new PSTN events) has to be done by defining a new XML namespace and a matching schema 🌈. Elements from that new namespace then co-exist with elements from the base schema in the same document 🧩.
<xs:schema targetNamespace="urn:ietf:params:xml:ns:spirits-1.0"
xmlns:tns="urn:ietf:params:xml:ns:spirits-1.0"
xmlns:xs="http://www.w3.org/2001/XMLSchema"
elementFormDefault="qualified"
attributeFormDefault="unqualified">
<!-- This import brings in the XML language attribute xml:lang-->
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd"/>
<xs:annotation>
<xs:documentation xml:lang="en">
Describes SPIRITS events.
</xs:documentation>
</xs:annotation>
<xs:element name="spirits-event" type="tns:SpiritsEventType"/>
<xs:complexType name="SpiritsEventType">
<xs:sequence>
<xs:element name="Event" type="tns:EventType" minOccurs="1"
maxOccurs="unbounded"/>
<xs:any namespace="##other" processContents="lax"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="EventType">
<xs:sequence>
<xs:element name="CalledPartyNumber" type="xs:token"
minOccurs="0" maxOccurs="1"/>
<xs:element name="CallingPartyNumber" type="xs:token"
minOccurs="0" maxOccurs="1"/>
<xs:element name="DialledDigits" type="xs:token"
minOccurs="0" maxOccurs="1"/>
<xs:element name="Cell-ID" type="xs:token"
minOccurs="0" maxOccurs="1"/>
<xs:element name="Cause" type="tns:CauseType"
minOccurs="0" maxOccurs="1"/>
</xs:sequence>
<xs:attribute name="type" type="tns:PayloadType"
use="required"/>
<xs:attribute name="name" type="tns:EventNameType"
use="required"/>
<xs:attribute name="mode" type="tns:ModeType"
use="optional" default="N"/>
</xs:complexType>
<xs:simpleType name="PayloadType">
<!-- The <spirits-event> will contain either a list of -->
<!-- INDPs events or a list of userprof events -->
<xs:restriction base="xs:string">
<xs:enumeration value="INDPs"/>
<xs:enumeration value="userprof"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="EventNameType">
<xs:restriction base="xs:string">
<!-- These are the call related events (DPs). If the -->
<!-- PaylaodType is "INDPs", then the value of the "name" -->
<!-- attribute is one of these; example -->
<!-- <spirits-event type="INDPs" name="OCI"> -->
<xs:enumeration value="OAA"/>
<xs:enumeration value="OCI"/>
<xs:enumeration value="OAI"/>
<xs:enumeration value="OA"/>
<xs:enumeration value="OTS"/>
<xs:enumeration value="ONA"/>
<xs:enumeration value="OCPB"/>
<xs:enumeration value="ORSF"/>
<xs:enumeration value="OMC"/>
<xs:enumeration value="OAB"/>
<xs:enumeration value="OD"/>
<xs:enumeration value="TA"/>
<xs:enumeration value="TMC"/>
<xs:enumeration value="TAB"/>
<xs:enumeration value="TD"/>
<xs:enumeration value="TAA"/>
<xs:enumeration value="TFSA"/>
<xs:enumeration value="TB"/>
<!-- These are the non-call related events. If the -->
<!-- PayloadType is "user-prof", then the value of the -->
<!-- "name" attribute is one of these; example -->
<!-- <spirits-event type="userprof" name="LUDV"> -->
<xs:enumeration value="LUSV"/>
<xs:enumeration value="LUDV"/>
<xs:enumeration value="REG"/>
<xs:enumeration value="UNREGMS"/>
<xs:enumeration value="UNREGNTWK"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ModeType">
<!-- One of two values: "N"otification or "R"equest -->
<xs:restriction base="xs:string">
<xs:enumeration value="N"/>
<xs:enumeration value="R"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="CauseType">
<xs:restriction base="xs:string">
<xs:enumeration value="Busy"/>
<xs:enumeration value="Unreachable"/>
</xs:restriction>
</xs:simpleType>
</xs:schema>10. Acknowledgements 💌
The authors are super grateful to everyone in the SPIRITS WG who joined the discussions that shaped this work 🫶. Those folks include J-L. Bakker, J. Bjorkner, J. Buller, J-E. Chapron, B. Chatras, O. Cleuziou, L. Conroy, R. Forbes, F. Haerens, J. Humphrey, J. Kozik, W. Montgomery, S. Nyckelgard, M. O'Doherty, A. Roach, J. Rosenberg, H. Sinnreich, L. Slutsman, D. Varney, and W. Zeuch 🌸. The authors also want to shout out Steve Bellovin, Allison Mankin and Jon Peterson for helping out on the Security section 👑✨.
11. Acronyms ✨
okay bestie, here's the acronym glossary 💅 it's giving alphabet soup, so bookmark it 🔖
ACL Access Control List
CS Capability Set
DP Detection Point
DTD Document Type Definition
EDP Event Detection Point
EDP-N Event Detection Point "Notification"
EDP-R Event Detection Point "Request"
IANA Internet Assigned Numbers Authority
ICW Internet Call Waiting
IMSI International Mobile Subscriber Identity
IN Intelligent Network
INAP Intelligent Network Application Protocol
IP Internet Protocol
ISP Internet Service Provider
ITU International Telecommunications Union
MIME Multipurpose Internet Mail Extensions
MS Mobile Station (or Mobile Subscriber)
OBCSM Originating Basic Call State Model
PIC Point In Call
PINT PSTN/Internet Interworking
PSTN Public Switched Telephone Network
SCF Service Control Function
SCP Service Control Point
SDP Session Description Protocol
SIP Session Initiation Protocol
SIP-T SIP for Telephones
SPIRITS Services in the PSTN/IN Requesting InTernet
Services
SSF Service Switching Function
SSP Service Switching Point
STD State Transition Diagram
TBCSM Terminating Basic Call State Model
TDP Trigger Detection Point
TDP-N Trigger Detection Point "Notification"
TDP-R Trigger Detection Point "Request"
TLS Transport Layer Security
UA User Agent
VLR Visitor Location Register
WIN Wireless Intelligent Network
XML Extensible Markup Language12. References 📚
12.1. Normative References
These are the must-reads, the stuff you're basically signing up to if you implement this 🫶
- [1] Slutsman, L., Faynberg, I., Lu, H., and M. Weissman, "The SPIRITS Architecture", RFC 3136, June 2001.
- [2] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
- [3] Roach, A., "Session Initiation Protocol (SIP)-Specific Event Notification", RFC 3265, June 2002.
- [4] Faynberg, I., Gato, J., Lu, H., and L. Slutsman, "Service in the Public Switched Telephone Network/Intelligent Network (PSTN/IN) Requesting InTernet Service (SPIRITS) Protocol Requirements", RFC 3298, August 2002.
- [5] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, A., Peterson, J., Sparks, R., Handley, M., and E. Schooler, "SIP: Session Initiation Protocol", RFC 3261, June 2002.
12.2. Informative References
these ones are the extra context, the "ooh let me explain" section 🌸
- [6] M. Unmehopa, K. Vemuri, A. Brusilovsky, E. Dacloush, A. Zaki, F. Haerens, J-L. Bakker, B. Chatras, and J. Dobrowolski, "On selection of IN parameters to be carried by the SPIRITS Protocol", Work In Progress, January 2003.
- [7] Intelligent Network Capability Set 2. ITU-T, Recommendation Q.1228.
- [8] Petrack, S. and L. Conroy, "The PINT Service Protocol: Extensions to SIP and SDP for IP Access to Telephone Call Services", RFC 2848, June 2000.
- [9] Murata, M., St.Laurent, S., and D. Kohn, "XML Media Types", RFC 3023, January 2001.
- [10] Lu, H., Faynberg, I., Voelker, J., Weissman, M., Zhang, W., Rhim, S., Hwang, J., Ago, S., Moeenuddin, S., Hadvani, S., Nyckelgard, S., Yoakum, J., and L. Robart, "Pre-Spirits Implementations of PSTN-initiated Services", RFC 2995, November 2000.
- [11] Rosenberg, J. and H. Schulzrinne, "Session Initiation Protocol (SIP): Locating SIP Servers", RFC 3263, June 2002.
- [12] Thompson, H., Beech, D., Maloney, M. and N. Mendelsohn, "XML Schema Part 1: Structures", W3C REC REC-xmlschema-1-20010502, May 2001. <http://www.w3c.org/XML/>.
- [13] "Interface recommendations for intelligent network capability set 3: SCF-SSF interface", ITU-T Recommendation Q.1238.2, June 2000.
- [14] Moats, R., "URN Syntax", RFC 2141, May 1997.
- [15] Moats, R., "A URN Namespace for IETF Documents", RFC 2648, August 1999.
- [16] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.
- [17] Tim Bray, Dave Hollander, and Andrew Layman, "Namespaces in XML", W3C recommendation: xml-names, 14th January 1999, <http://www.w3.org/ TR/REC-xml-names>.
- [18] Ramsdell, B., "Secure/Multipurpose Internet Mail Extensions (S/MIME) Version 3.1 Message Specification", RFC 3851, July 2004.
- [19] Faynberg, I., L. Gabuzda, M. Kaplan, and N.Shah, "The Intelligent Network Standards: Their Application to Services", McGraw-Hill, 1997.
- [20] Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part One: Format of Internet Message Bodies", RFC 2045, November 1996.
- Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, November 1996.
- Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text ", RFC 2047, November 1996.
- Freed, N., Klensin, J., and J. Postel, "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures", BCP 13, RFC 2048, November 1996.
- Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Five: Conformance Criteria and Examples", RFC 2049, November 1996.
13. Contributors 🎀
a big shoutout to our contributor 🫶
Kumar Vemuri
Lucent Technologies, Inc.
2000 Naperville Rd.
Naperville, IL 60566
USA
EMail: vvkumar@lucent.com14. Authors' Addresses 💌
the whole squad, where to find them 🧚
Vijay K. Gurbani, Editor
2000 Lucent Lane
Rm 6G-440
Naperville, IL 60566
USA
EMail: vkg@lucent.comAlec Brusilovsky
2601 Lucent Lane
Lisle, IL 60532-3640
USA
EMail: abrusilovsky@lucent.comIgor Faynberg
Lucent Technologies, Inc.
101 Crawfords Corner Rd.
Holmdel, NJ 07733
USA
EMail: faynberg@lucent.comJorge Gato
Vodafone Espana
Isabel Colbrand, 22
28050 Madrid
Spain
EMail: jorge.gato@vodafone.comHui-Lan Lu
Bell Labs/Lucent Technologies
Room 4C-607A, 101 Crawfords Corner Road
Holmdel, New Jersey, 07733
Phone: (732) 949-0321
EMail: huilanlu@lucent.comMusa Unmehopa
Lucent Technologies, Inc.
Larenseweg 50,
Postbus 1168
1200 BD, Hilversum,
The Netherlands
EMail: unmehopa@lucent.com15. Full Copyright Statement ⚖️
legal stuff, but make it cute 🌈
Copyright (C) The Internet Society (2004).
This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/S HE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
ngl this part is about who owns what 👑 the IETF doesn't take a side on whether any rights in the technology are valid or how wide they reach, and it doesn't claim to have checked for any such rights either. the procedures for rights in IETF Documents are in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org.
Acknowledgement
and last but not least, a shoutout to whoever keeps the lights on 💖
Funding for the RFC Editor function is currently provided by the Internet Society. 🌸✨
📦 where this page comes from
- ietf: rfc3910 2004-10
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms