| DRINKS | M.M. Marrache |
| Internet-Draft | Jerusalem College of Technology |
| Intended status: Standards Track | D.S. Schwartz |
| Expires: April 02, 2013 | XConnect |
| S.A. Ali | |
| NeuStar | |
| October 2012 |
Session Peering Provisioning (SPP) Protocol over REST
draft-marrache-drinks-spp-protocol-rest-00
The Session Peering Provisioning Framework (SPPF) is an XML framework that exists to enable the provisioning of session establishment data into Session Data Registries or SIP Service Provider data stores. This SPP Protocol implementation follows the REST style widely used today in ditributed systems. The benefits include scalibility of the interactions between the involved components, ... This document describes the specification for performing SPPF operations over REST/HTTP.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http:/⁠/⁠datatracker.ietf.org/⁠drafts/⁠current/⁠.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 02, 2013.
Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http:/⁠/⁠trustee.ietf.org/⁠license-⁠info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
TBD
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 [RFC2119].
+-------------+
(1) | Transport |Example:
| Protocol | TCP, TLS, BEEP, etc.
+-------------+
|
V
+-------------+
| HTTP |
| Message |
+-------------+
(2) |
+-----------------------+
| |
V V
+----------------+ +----------------+
| HTTP Requests | | HTTP Responses |
| (with params) | | (with params) |
+----------------+ +----------------+
Uses | Uses |
V V
+-------------+ +-------------+
(3) | SPPF | | SPPF |
| XML Types | | XML Types |
+-------------+ +-------------+
Figure 1: Layering and Technical Structure of the SPP Protocol with REST/HTTP
The operations supported by the RESTful SPP Protocol are normatively defined later in this document. Each operation is performed using an HTTP request and an HTTP response. Each such request and response message may contain a single object that wraps the SPPF XML data types that comprise the inputs and the outputs, respectively, of the operation.
SPPF is a request/reply framework that allows a client application to submit provisioning data and query requests to a server. The SPPF data structures are designed to be protocol agnostic. Concerns regarding encryption, non-repudiation, and authentication are beyond the scope of this document. For more details, please refer to the "Transport Protocol Requirements" section in the framework document.
HTTP(s) is the transport mechanism used by RESTful systems. HTTP 1.1 includes the "persistent connection" feature, which allows multiple HTTP request/response pairs to be transported across a single HTTP connection. This is an important performance optimization feature, particularly when the connections is an HTTPS connection where the relatively time consuming SSL handshake has occurred. Persistent connections SHOULD be used for the SPPF HTTP connections.
HTTP 1.1 [RFC2616] or higher SHOULD be used.
To achieve integrity and privacy, conforming SPP Protocol Clients and Servers MUST support HTTP over TLS [RFC5246] as the secure transport mechanism. This combination of HTTP and TLS is referred to as HTTPS. And to accomplish authentication, conforming SPPF Clients and Servers MUST use HTTP Digest Authentication as defined in [RFC2617]. As a result, the communication session is established through the initial HTTP connection setup, the digest authentication, and the TLS handshake. When the HTTP connection is broken down, the communication session ends.
TBD
In the context of this RESTful SPP Protocol implementation, the different domain elements defined in [I-D.draft-ietf-drinks-spp-framework] are called resources. Each resource is identified by a Uniform Resource Identifier that follows a well defined structure.
Each SPPF domain element is identified by some of its attributes. Only these attributes that compose the key must be present in the URI identifying the resource. These attributes are represented in the URI as path parameters.
As mentioned in the framework document, a destination group is uniquely identified by the following attributes: the registrant and the destination group's name. Therefore, a destination group resource is identified by the URI:
BASE_URL/DestGroup/rant/{rant}/name/{name}
As mentioned in the framework document, a telephone number is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, and the telephone number. Therefore, a telephone number resource is identified by the URI:
BASE_URL/TN/rant/{rant}/dgName/{dgName}/tn/{tn}
As mentioned in the framework document, a telephone number prefix is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, and the telephone number prefix. Therefore, a telephone number prefix resource is identified by the URI:
BASE_URL/TNP/rant/{rant}/dgName/{dgName}/prefix/{prefix}
As mentioned in the framework document, a telephone number range is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, the telephone that starts the range and the one that ends the range. Therefore, a telephone number range resource is identified by the URI:
BASE_URL/TNR/rant/{rant}/dgName/{dgName}/startTn/{startTn}/endTn/{endTn}
As mentioned in the framework document, a routing number is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, and the routing number. Therefore, a routing number resource is identified by the URI:
BASE_URL/RN/rant/{rant}/dgName/{dgName}/rn/{rn}
As mentioned in the framework document, a public identifier URI is uniquely identified by the following attributes: the registrant, the name of the associated destination group if there is, and the URI. Therefore, a public identifier URI resource is identified by the URI:
BASE_URL/URIPubId/rant/{rant}/dgName/{dgName}/uri/{uri}
As mentioned in the framework document, a Sed Group URI is uniquely identified by the following attributes: the registrant and the Sed Group's name. Therefore, a Sed Group resource is identified by the URI:
BASE_URL/SedGroup/rant/{rant}/name/{name}
As mentioned in the framework document, a Sed Record is uniquely identified by the following attributes: the registrant and the Sed Record's name. Therefore, a Sed Record resource is identified by the URI:
BASE_URL/SedRecord/rant/{rant}/name/{name}
Note that there is no need to use one URI per type of Sed Record since their keys all use the same attributes. This is necessary for Public Identifiers since the subtypes don't all use the same key structure.
As mentioned in the framework document, a Sed Group Offer is uniquely identified by the following attributes: the offering registrant, the offered Sed Group's name and the registrant to which the Sed Group is offered. Therefore, a Sed Group Offer resource is identified by the URI:
BASE_URL/SedGrpOffr/rant/{rant}/sedGrpNam/{sedGrpNam}/offrTo/{offrTo}
The Server Status may be considered as a unique resource identified by the following URI:
BASE_URL/ServerStatus
This resource contains information about the server as described later.
An SPPF client interacts with an SPPF server by using one of the supported transport mechanisms to send one or more requests to the server and receive corresponding replies from the server. The basic set of operations that an SPPF client can submit to an SPPF server and the semantics of those operations are defined in the "Framework Operations" section of the framework document. The following sub-sections describe how these operations should be performed in the context of a RESTful SPP Protocol implementation.
In order to add (or modify) an object to (present in) the registry, an authorized entity sends an add/modify request to the registry. This request consists of an HTTP request on the URI that identifies the resource to add/modify, using the PUT HTTP method. The object to add/modify is carried in the HTTP request's body, encoded as XML. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. The following sub-sections describe the expected format of the HTTP requests and responses. Refer to the "RESTful SPP Protocol Examples" section of this document for an example of Add operation on each type of SPPF object.
The format of an HTTP request used to add (or modify) a domain element to (present in) the registry is as follows:
PUT BASE_URL/${ResourceURI}[?clientTransId=${ClientTransId}] HTTP/1.1
.....
[minorVer: ${MinorVersion}]
Content-Type: application/xml
.....
<XML Representation of the domain element to add/modify>
The data elements within the HTTP Add/Modify request are described as follows:
The format of an HTTP response to a add/modify request is as follows:
HTTP/1.1 ${Status Code}
....
[clientTransId: ${Client Trans. Id}]
serverTransId: ${Server Trans. Id}]
Content-Length: 0
The data elements within the HTTP Add/Modify response are described as follows:
In order to remove an object from the registry, an authorized entity sends a delete request to the registry. This request consists of an HTTP request on the URI that identifies the resource to delete, using the DELETE HTTP method. The body of the HTTP request is empty, the object (or resource) to delete is uniquely identified by the URI included in the request. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. The following sub-sections describe the expected format of the HTTP requests and responses. Refer to the "RESTful SPP Protocol Examples" section of this document for an example of Delete operation on each type of SPPF object.
The format of an HTTP request used to delete a SPPF object from the registry is as follows:
DELETE BASE_URL/${ResourceURI}[?clientTransId=${ClientTransId}] HTTP/1.1
.....
[minorVer: ${Minor Version}]
Content-Length: 0
The data elements within the HTTP Delete request are described as follows:
The format of an HTTP response to a delete request is as follows:
HTTP/1.1 ${Status Code}
....
[clientTransId: ${Client Trans. Id}]
serverTransId: ${Server Trans. Id}]
Content-Length: 0
The data elements within the HTTP Delete response are described as follows:
In SPPF, a SED Group Offer can be accepted or rejected by, or on behalf of, the registrant to whom the SED Group has been offered (refer "Framework Data Model Objects" section of the framework document for a description of the SED Group Offer object). The Accept operation is used to accept such SED Group Offers by, or on behalf of, the Registrant. This request consists of an HTTP request on the URI that identifies the Sed Group Offer to accept, using the POST HTTP method. The body of the HTTP request is empty, the Sed Grp Offer (resource) to accept is uniquely identified by the URI included in the request. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. The following sub-sections describe the expected format of the HTTP requests and responses. Refer to the "RESTful SPP Protocol Examples" section of this document for an example of Accept operation on a SED Group Offer.
The format of an HTTP request used to Accept a SED Group Offer is as follows:
POST BASE_URL/${SedGrpOffrURI}[?clientTransId=${ClientTransId}] HTTP/1.1
.....
[minorVer: ${Minor Version}]
Action: Accept
Content-Length: 0
The data elements within the HTTP Accept request are described as follows:
The format of an HTTP response to an Accept request is as follows:
HTTP/1.1 ${Status Code}
....
[clientTransId: ${Client Trans. Id}]
serverTransId: ${Server Trans. Id}]
Content-Length: 0
The data elements within the HTTP Accept response are described as follows:
In SPPF, SED Group Offer can be accepted or rejected by, or on behalf of, the registrant to whom the SED Group has been offered (refer "Framework Data Model Objects" section of the framework document for a description of the SED Group Offer object). The Reject operation is used to reject such SED Group Offers by, or on behalf of, the Registrant. This request consists of an HTTP request on the URI that identifies the Sed Group Offer to reject, using the POST HTTP method. The body of the HTTP request is empty, the Sed Grp Offer (resource) to delete is uniquely identified by the URI included in the request. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. The following sub-sections describe the expected format of the HTTP requests and responses. Refer to the "RESTful SPP Protocol Examples" section of this document for an example of Reject operation on a SED Group Offer.
The format of an HTTP request used to Reject a SED Group Offer is as follows:
POST BASE_URL/${SedGrpOffrURI}[?clientTransId=${ClientTransId}] HTTP/1.1
.....
[minorVer: ${Minor Version}]
Action: Reject
Content-Length: 0
The data elements within the HTTP Reject request are described as follows:
The format of an HTTP response to a Reject request is as follows:
HTTP/1.1 ${Status Code}
....
[clientTransId: ${Client Trans. Id}]
serverTransId: ${Server Trans. Id}]
Content-Length: 0
The data elements within the HTTP Reject response are described as follows:
In order to query the details of an object from the Registry, an authorized entity sends a get request to the registry. This request consists of an HTTP request on the URI that identifies the queried resource, using the GET HTTP method. After the operation is performed, the registry sends back an HTTP response to the client indicating if the request has been performed successfully, and if not, the reason of the failure. Moreover, if the queried object is found in the registry, the HTTP response's body contains the XML representation of the result object. The following sub-sections describe the expected format of the HTTP requests and responses. Refer to the "RESTful SPP Protocol Examples" section of this document for an example of Get operation on each type of SPPF object.
The format of an HTTP request to a Get request is as follows:
GET BASE_URL/${Resource URI} HTTP/1.1
.....
[minorVer: ${Minor Version}]
Content-Length: 0
The data elements within the HTTP Get request are described as follows:
The format of an HTTP response to a Get request is as follows:
HTTP/1.1 ${Status Code}
....
Content-Length:
<XML Representation of the queried resource if found>
In addition to the ability to query the details of one or more SED Group offers using a SED Group Offer key in a Get request, this operation also provides an additional, more flexible, structure to query for SED Group Offer objects.
Using the details passed into this structure, the server will attempt to find SED Group Offer objects that satisfy all the criteria passed into the request. If no criteria is passed in then the server will return the list of SED Group Offer objects that belongs to the registrant. If there are no matching SED Group Offers found then an empty result set will be returned.
TBD
TBD
In order to query certain details of the SPPF server, like the SPPF server's status and the major/minor version supported by the server, the Server Details operation structure SHOULD be used.
The format of an HTTP request corresponding to a Get Server Status request is as follows:
GET BASE_URL/ServerStatus HTTP/1.1
.....
[minorVer: ${Minor Version}]
Content-Length: 0
The data elements within the HTTP Get Server Status request are described as follows:
The format of an HTTP response to a Get Server Status request is as follows:
HTTP/1.1 ${Status Code}
....
Content-Length:
<XML Representation of the server status object (sppfb:SvcMenuType)>
The data elements within the HTTP Get Server Status response are described as follows:
TBD
Refer the "Framework Operations" section of the framework document for a description of all SPPF operations, and any necessary semantics that MUST be adhered to in order to conform with the SPPF specification.
The RESTful SPP Protocol WADL is defined below.
Note: The following WADL has been formatted (e.g., tabs, spaces) to meet I-D requirements.
<?xml version="1.0"?>
<application xmlns="http://wadl.dev.java.net/2009/02"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:sppfb="urn:ietf:params:xml:ns:sppf:base:1"
xmlns:sppfr="urn:ietf:params:xml:ns:sppf:rest:1"
xsi:schemaLocation="http://wadl.dev.java.net/2009/02
http://www.w3.org/Submission/wadl/wadl.xsd">
<grammars>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:sppfb="urn:ietf:params:xml:ns:sppf:base:1"
xmlns:sppfr="urn:ietf:params:xml:ns:sppf:rest:1"
targetNamespace="urn:ietf:params:xml:ns:sppf:rest:1">
<import namespace="urn:ietf:params:xml:ns:sppf:base:1"
schemaLocation="sppfbase.xsd" />
<element name="DestGroup" type="sppfb:DestGrpType" />
<element name="SedGroup" type="sppfb:SedGrpType" />
<element name="SedRecord" type="sppfb:SedRecType"
abstract="true" />
<element name="TN" type="sppfb:TNType" />
<element name="TNP" type="sppfb:TNPType" />
<element name="TNR" type="sppfb:TNRType" />
<element name="RN" type="sppfb:RNType" />
<element name="URIPubId" type="sppfb:URIPubIdType" />
<element name="SedGrpOffer" type="sppfb:SedGrpOfferType" />
<element name="SvcMenu" type="sppfb:SvcMenuType" />
</schema>
</grammars>
<resources base="REPLACE_WITH_THE_BASE_URL">
<resource id="SedRecordResource"
path="/SedRec/rant/{rant}/name/{name}">
<method id="getSedRecord" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="name" style="template" type="sppfb:ObjNameType"
required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:SedRecord" />
</response>
</method>
<method id="delSedRecord" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="name" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" required="false" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" />
</response>
</method>
<method id="saveSedRecord" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:SedRecord" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType"
required="true" />
</response>
</method>
</resource>
<resource id="TNResource"
path="/TN/rant/{rant}/dgName/{dgName}/tn={tn}">
<method id="getTelNumber" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="tn" style="template" type="sppfb:NumberValType"
required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:TN" />
</response>
</method>
<method id="delTelNumber" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="tn" style="template" type="sppfb:NumberValType"
required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" required="false" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" />
</response>
</method>
<method id="saveTelNumber" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:TN" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
</resource>
<resource id="TNPResource"
path="/TNP/rant/{rant}/dgName/{dgName}/prefix/{tnPrefix}">
<method id="getTelNumPrefix" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="tnPrefix" style="template"
type="sppfb:NumberValType" required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:TNP" />
</response>
</method>
<method id="delTelNumPrefix" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="tnPrefix" style="template"
type="sppfb:NumberValType" required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" required="false" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" />
</response>
</method>
<method id="saveTelNumPrefix" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:TNP" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
</resource>
<resource id="TNRResource"
path="/TNR/rant/{rant}/dgName/{dgName}/start/{startTn}/end/{endTn}">
<method id="getTelNumRange" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="startTn" style="template"
type="sppfb:NumberValType" required="true" />
<param name="endTn" style="template"
type="sppfb:NumberValType" required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:TNR" />
</response>
</method>
<method id="delTelNumRange" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="startTn" style="template"
type="sppfb:NumberValType" required="true" />
<param name="endTn" style="template"
type="sppfb:NumberValType" required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" required="false" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" />
</response>
</method>
<method id="saveTelNumRange" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:TNR" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
</resource>
<resource id="RNResource"
path="/RN/rant/{rant}/dgName/{dgName}/rn/{rn}">
<method id="getRoutingNumber" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="rn" style="template" type="sppfb:NumberValType"
required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:RN" />
</response>
</method>
<method id="delRoutingNumber" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="rn" style="template" type="sppfb:NumberValType"
required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" required="false" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" />
</response>
</method>
<method id="saveRoutingNumber" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:RN" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
</resource>
<resource id="UriPubIdResource"
path="/UriPubId/rant/{rant}/dgName/{dgName}/uri/{uri}">
<method id="getUriPubId" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="uri" style="template" type="xsd:anyURI"
required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:URIPubId" />
</response>
</method>
<method id="delUriPubId" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
<param name="uri" style="template" type="xsd:anyURI"
required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
<method id="saveUriPubId" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:URIPubId" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
</resource>
<resource id="DestGroupResource"
path="/DestGroup/rant/{rant}/dgName/{dgName}">
<method id="getDestGroup" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:DestGroup" />
</response>
</method>
<method id="delDestGroup" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="dgName" style="template" type="sppfb:ObjNameType"
required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
<method id="saveDestGroup" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType"
required="false" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:DestGroup" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
</resource>
<resource id="SedGroupResource"
path="/SedGroup/rant/{rant}/name/{sedGrpName}">
<method id="getSedGroup" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="sedGrpName" style="template"
type="sppfb:ObjNameType" required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:SedGroup" />
</response>
</method>
<method id="delSedGroup" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="sedGrpName" style="template"
type="sppfb:ObjNameType" required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
<method id="saveSedGroup" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:SedGroup" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
</resource>
<resource id="SedGroupOfferResource"
path="/SedGrpOffr/rant/{rant}/sedGrpNam/{sedGrpNam}/offrTo/{offrTo}">
<method id="getSedGroupOffer" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="sedGrpNam" style="template"
type="sppfb:ObjNameType" required="true" />
<param name="offrTo" style="template" type="sppfb:OrgIdType"
required="true" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:SedGrpOffer" />
</response>
</method>
<method id="delSedGroupOffer" name="DELETE">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="sedGrpNam" style="template"
type="sppfb:ObjNameType" required="true" />
<param name="offrTo" style="template" type="sppfb:OrgIdType"
required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
<method id="saveSedGroupOffer" name="PUT">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<representation mediaType="application/xml"
element="sppfr:SedGrpOffer" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
<method id="acceptSedGroupOffer" name="POST">
<request>
<param name="action" style="header" type="xsd:string" />
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="sedGrpNam" style="template"
type="sppfb:ObjNameType" required="true" />
<param name="offrTo" style="template" type="sppfb:OrgIdType"
required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
<method id="rejectSedGroupOffer" name="POST">
<request>
<param name="action" style="header" type="xsd:string" />
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
<param name="clientTransId" style="query"
type="sppfb:TransIdType" />
<param name="rant" style="template" type="sppfb:OrgIdType"
required="true" />
<param name="sedGrpNam" style="template"
type="sppfb:ObjNameType" required="true" />
<param name="offrTo" style="template" type="sppfb:OrgIdType"
required="true" />
</request>
<response status="200">
<param name="clientTransId" style="header"
type="sppfb:TransIdType" />
<param name="serverTransId" style="header"
type="sppfb:TransIdType" required="true" />
</response>
</method>
</resource>
<resource id="ServerStatusResource" path="ServerStatus">
<method id="getServerStatus" name="GET">
<request>
<param name="minorVer" style="header"
type="sppfb:MinorVerType" />
</request>
<response status="200">
<representation mediaType="application/xml"
element="sppfr:SvcMenu" />
</response>
</method>
</resource>
</resources>
</application>
Figure 2: WADL
This section shows examples of HTTP message exchange between two SIP Service Providers (SSP) and a registry. The messages in this section are HTTP requests/responses that may include XML content representing the SPPF objects defined in the framework document. This section relies on the XML data structures defined in the base SPPF specification [I-D.draft-ietf-drinks-spp-framework]. So refer to that document to understand XML object types embedded in these example messages.
In this sample use case scenario, SSP1 and SSP2 provision resource data in the registry and use SPPF constructs to selectively share the SED groups. In the figure below, SSP2 has two ingress SBE instances that are associated with the public identities that SSP2 has the retail relationship with. Also, the two SBE instances for SSP1 are used to show how to use SPPF to associate route preferences for the destination ingress routes and exercise greater control on outbound traffic to the peer's ingress SBEs.
---------------+ +------------------
| |
+------+ +------+
| sbe1 | | sbe2 |
+------+ +------+
SSP1 | | SSP2
+------+ +------+
| sbe3 | | sbe4 |
+------+ +------+
iana-en:111 | | iana-en:222
---------------+ +------------------
| |
| |
| SPPF +------------------+ SPPF |
+------->| Registry |<--------+
+------------------+
SSP2 adds a destination group to the registry for use later. The SSP2 SPPF client sets a unique transaction identifier 'txn_1479' for tracking purposes. The name of the destination group is set to DEST_GRP_SSP2_1
PUT /DestGroup/rant/iana-en:222/dgName/DEST_GRP_SSP2_1 \
?clientTransId=txn_1479 HTTP/1.1
...........
Content-Type: application/xml
Content-Length: 117
<DestGroup>
<rant>iana-en:222</rant>
<rar>iana-en:223</rar>
<dgName>DEST_GRP_SSP2_1</dgName>
</DestGroup>
The registry processes the request and return a favorable response confirming successful creation of the named destination group. Also, besides returning a unique server transaction identifier, Registry also returns the matching client transaction identifier from the request message back to the SPPF client.
HTTP/1.1 200 OK
...........
clientTransId: txn_1479
serverTransId: tx_12345
Content-Length: 0
SSP2 adds SED records in the form of ingress routes to the registry.
PUT /SedRec/rant/iana-en:222/name/SED_SSP2_SBE2 \
?clientTransId=txn_1479 HTTP/1.1
.............
Content-Type: application/xml
Content-Length: 298
<NAPTR>
<rant>iana-en:222</rant>
<rar>iana-en:223</rar>
<sedName>SED_SSP2_SBE2</sedName>
<isInSvc>true</isInSvc>
<order>10</order>
<flags>u</flags>
<svcs>E2U+sip</svcs>
<regx>
<ere>^(.*)$</ere>
<repl>sip:\1@sbe2.ssp2.example.com</repl>
</regx>
</NAPTR>
The registry returns a success response.
HTTP/1.1 200 OK
.............
clientTransId: txn_1479
serverTransId: tx_12345
Content-Length: 0
SSP2 adds another SED record to the registry and makes use of URIType
PUT /SedRec/rant/iana-en:222/name/SED_SSP2_SBE4 \
?clientTransId=txn_1479 HTTP/1.1
............
Content-Type: application/xml
Content-Length: 204
<URI>
<rant>iana-en:222</rant>
<rar>iana-en:223</rar>
<sedName>SED_SSP2_SBE4</sedName>
<isInSvc>true</isInSvc>
<ere>^(.*)$</ere>
<uri>sip:\1;npdi@sbe4.ssp2.example.com</uri>
</URI>
The registry returns a success response.
HTTP/1.1 200 OK
............
clientTransId: txn_1479
serverTransId: tx_12345
Content-Length: 0
SSP2 creates the grouping of SED records (e.g. ingress routes) and chooses higher precedence for SED_SSP2_SBE2 by setting a lower number for the "priority" attribute, a protocol agnostic precedence indicator.
PUT /SedGroup/rant/iana-en:222/name/SED_SSP2_SBE4 \
?clientTransId=txn_1479 HTTP/1.1
............
Content-Type: application/xml
Content-Length:
<XML document>
To confirm successful processing of this request, registry returns a well-known result code '1000' to the SSP2 client.
HTTP/1.1 200 OK
............
clientTransId: txn_1479
serverTransId: tx_12345
Content-Length: 0
SSP2 activates a TN public identity by associating it with a valid destination group. Further, SSP2 puts forth a claim that it is the carrier-of-record for the TN.
TBD
Assuming that the registry has access to TN authority data and it performs the required checks to verify that SSP2 is in fact the service provider of record for the given TN, the request is processed successfully. In the response message, the registry sets the value of <cor> to "true" in order to confirm SSP2 claim as the carrier of record and the <corDate> reflects the time when the carrier of record claim is processed.
TBD
If another entity that SSP2 shares session establishment information (e.g. routes) with has access to Number Portability data, it may choose to perform route lookups by routing number. Therefore, SSP2 associates a routing number to a destination group in order to facilitate ingress route discovery.
TBD
Registry completes the request successfully and returns a favorable response to the SPPF client.
TBD
Next, SSP2 activates a block of ten thousand TNs and associate it to a destination group.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
Next, SSP2 activates a block of ten thousand TNs using the TNPType structure and identifying a TN prefix.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
In order for SSP1 to complete session establishment for a destination TN where the target subscriber has a retail relationship with SSP2, it first requires an asynchronous bi-directional handshake to show mutual consent. To start the process, SSP2 initiates the peering handshake by offering SSP1 access to its SED group.
TBD
Registry completes the request successfully and confirms that the SSP1 will now have the opportunity to weigh in on the offer and either accept or reject it. The registry may employ out-of-band notification mechanisms for quicker updates to SSP1 so they can act faster, though this topic is beyond the scope of this document.
TBD
SSP1 responds to the offer from SSP2 and agrees to have visibility to SSP2 session establishment information (e.g. ingress routes).
TBD
Registry confirms that the request has been processed successfully. From this point forward, if SSP1 looks up a public identity through the query resolution server, where the public identity is part of the destination group by way of "SED_GRP_SSP2_1" session establishment data association, SSP2 ingress SBE information will be shared with SSP1.
TBD
SSP1 wants to prioritize all outbound traffic to the ingress route associated with the "SED_GRP_SSP2_1" SED Group record, through "sbe1.ssp1.example.com".
TBD
Since peering has already been established, the request to add the egress route has been successfully completed.
TBD
SSP1 had earlier accepted to have visibility to SSP2 session establishment data. SSP1 now decides to no longer maintain this visibility and hence rejects the SED Group Offer.
TBD
Registry confirms that the request has been processed successfully. From this point forward, if SSP1 looks up a public identity through the query resolution server, where the public identity is part of the destination group by way of "SED_GRP_SSP2_1" session establishment data association, SSP2 ingress SBE information will NOT be shared with SSP1 and hence SSP2 ingress SBE will NOT be returned in the query response.
TBD
SSP2 uses the 'spppGetRequest' operation to tally the last provisioned record for destination group DEST_GRP_SSP2_1.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
SSP2 obtains the last provisioned record associated with a given TN.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
SSP2 obtains the last provisioned record for the SED group SED_GRP_SSP2_1.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
SSP2 fetches the last provisioned SED group offer to the <peeringOrg> SSP1.
TBD
Registry processes the request successfully and returns a favorable response.
TBD
SSP1 wants to verify the last provisioned record for the egress route called EGR_RTE_01.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
SSP2 initiates a request to delete the destination group DEST_GRP_SSP2_1.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
SSP2 chooses to de-activate the TN and remove it from the registry.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
SSP2 removes the SED group called SED_GRP_SSP2_1.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
SSP2 no longer wants to share SED group SED_GRP_SSP2_1 with SSP1.
TBD
Registry completes the request successfully and returns a favorable response. Restoring this resource sharing will require a new SED group offer from SSP2 to SSP1 followed by a successful SED group accept request from SSP1.
TBD
SSP1 decides to remove the egress route with the label EGR_RTE_01.
TBD
Registry completes the request successfully and returns a favorable response.
TBD
RESTful SPP Protocol is used to query and update session peering data and addresses, so the ability to access this protocol should be limited to users and systems that are authorized to query and update this data. Because this data is sent in both directions, it may not be sufficient for just the client or user to be authenticated with the server. The identity of the server should also be authenticated by the client, which is often accomplished using the TLS certificate exchange and validation described in [RFC2818]. SPP Protocol messages may include sensitive information, routing data, lists of resolvable addresses, etc. So when used in a production setting and across non-secure networks, SPP Protocol should only be used over communications channels that provide strong encryption for data privacy.
TBD
The above protocols may have various vulnerabilities, and these may be inherited by the RESTful SPP Protocol. REST SPP Protocol itself may have vulnerabilities because an authorization model is not explicitly specified in the current specification.
Sections 5 and 10.1 describe requirements for HTTPS support using TLS. Non-anonymous TLS servers can optionally request a certificate from a TLS client; that option is not a requirement for this protocol. This presents a denial of service risk in which unauthenticated clients can consume server CPU resources by creating TLS sessions. The risk is increased if the server supports client-initiated renegotiation. This risk can be mitigated by disabling client-initiated renegotiation on the server and by ensuring that other means (such as firewall access control lists) are used to restrict unauthenticated client access to servers.
In conjunction with the above, it is important that REST SPP Protocol implementations implement an authorization model that considers the source of each query or update request and determines whether it is reasonable to authorize that source to perform that specific query or update.
Some deployments of REST SPP Protocol could choose to use transports without encryption. This presents vulnerabilities but could be selected for deployments involving closed networks or debugging scenarios. However, the vulnerabilities of such a deployment could be a lack of integrity and privacy of the data transported in this type of deployment.
This document uses URNs to describe XML namespaces and XML schemas conforming to a registry mechanism described in [RFC3688].
URN assignments requested are: urn:ietf:params:xml:ns:sppf:rest:1
TBD
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. |
| [RFC3688] | Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004. |
| [RFC5246] | Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. |
| [RFC2617] | Franks, J., Hallam-Baker, P.M., Hostetler, J.L., Lawrence, S.D., Leach, P.J., Luotonen, A. and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. |
| [RFC2616] | Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P. and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. |
| [I-D.draft-ietf-drinks-spp-framework] | Cartwright, K.C., Bhatia, V.B., Ali, S.A. and D.S. Schwartz, "Session Peering Provisioning Framework ", Internet-Draft draft-ietf-drinks-spp-framework-02, July 2012. |
| [RFC2818] | Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. |
| [RFC5321] | Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, October 2008. |
| [W3C.REC-xml-20081126] | Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E. and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC-xml-20081126, November 2008. |