Internet Engineering Task Force (IETF) K. Cartwright Request for Comments: 7878 V. Bhatia Category: Standards Track TNS ISSN: 2070-1721 J-F. Mule Apple Inc. A. Mayrhofer nic.at GmbH August 2016
Session Peering Provisioning (SPP) Protocol over SOAP
Abstract
The Session Peering Provisioning Framework (SPPF) specifies the data model and the overall structure to provision Session Establishment Data (SED) into Session Data Registries and SIP Service Provider data stores. To utilize this framework, one needs a substrate protocol. Given that the Simple Object Access Protocol (SOAP) is currently widely used for messaging between elements of such provisioning systems, this document specifies the usage of SOAP (via HTTPS) as the substrate protocol for SPPF. The benefits include leveraging prevalent expertise and a higher probability that existing provisioning systems will be able to easily migrate to using an SPPF- based protocol.
Status of This Memo
This is an Internet Standards Track document.
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7878.
Cartwright, et al. Standards Track [Page 1]
RFC 7878 SPP Protocol over SOAP August 2016
Copyright Notice
Copyright (c) 2016 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.
SPPF, defined in [RFC7877], is best supported by a transport and messaging infrastructure that is connection oriented, is request- response oriented, is easily secured, supports propagation through firewalls in a standard fashion, and is easily integrated into back- office systems. This is due to the fact that the client side of SPPF is likely to be integrated with organizations' operational support systems that facilitate transactional provisioning of user addresses and their associated SED. The server side of SPPF is likely to reside in a separate organization's network, resulting in the SPPF provisioning transactions traversing the Internet as they are propagated from the SPPF client to the SPPF server. Given the current state of industry practice and technologies, SOAP and HTTP(S) are well suited for this type of environment. This document describes the specification for transporting SPPF XML structures, using SOAP and HTTP(S) as substrates.
The specification in this document for transporting SPPF XML structures over SOAP and HTTP(S) is primarily comprised of five subjects: (1) a description of any applicable SOAP features, (2) any
Cartwright, et al. Standards Track [Page 3]
RFC 7878 SPP Protocol over SOAP August 2016
applicable HTTP features, (3) security considerations, (4) (perhaps most importantly) the Web Services Description Language (WSDL) definition for the SPP Protocol over SOAP, and (5) XML Schema Definition (XSD) types that are "substrate" specific.
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].
The list of SOAP features that are explicitly used and required for SPPP over SOAP are limited. Most SOAP features are not necessary for SPPF. SPPP over SOAP primarily uses SOAP simply as a standard message-envelope technology. The SOAP message envelope is comprised of the SOAP header and body. As described in the SOAP specification [SOAPREF], the SOAP header can contain optional, application- specific, information about the message. The SOAP body contains the SPPF message itself, whose structure is defined by the combination of one of the WSDL operations defined in this document and the SPPF XML data structures defined in this document and the SPPF document. SPPF does not rely on any data elements in the SOAP header. All relevant data elements are defined in the SPPF XML Schema described in [RFC7877] and the SPPF WSDL types specification described in Section 9 of this document.
WSDL is a widely standardized and adopted technology for defining the top-level structures of the messages that are transported within the body of a SOAP message. The WSDL definition for the SPPF SOAP messages is defined later in this document, which imports by reference the XML data types contained in the SPPF schema. The IANA registry where the SPPF schema resides is described in "The IETF XML Registry" [RFC3688].
There are multiple structural styles that WSDL allows. The best practice for this type of application is what is sometimes referred to as the "document/literal wrapped style". This style is generally regarded as an optimal approach that enhances maintainability, comprehension, portability, and, to a certain extent, performance. It is characterized by setting the soapAction binding style as "document", the soapAction encoding style as "literal", and then defining the SOAP messages to simply contain a single data element that "wraps" a data structure containing all the required input or output data elements. The figure below illustrates this high-level technical structure as conceptual layers 3 through 6.
Figure 1: Layering and Technical Structure of SPPP over SOAP Messages
Cartwright, et al. Standards Track [Page 5]
RFC 7878 SPP Protocol over SOAP August 2016
The operations supported by SPPP over SOAP are normatively defined later in this document. Each SOAP operation defines a request/input message and a response/output message. Each such request and response message then contains a single object that wraps the SPPF XML data types that comprise the inputs and the outputs, respectively, of the SOAP operation.
SOAP faults are not used by the SPPP over SOAP. All success and error responses are specified in Section 7.3 of this document. However, if a SOAP fault were to occur, perhaps due to failures in the SOAP message handling layer of a SOAP library, the client application should capture and handle the fault. Specifics on how to handle such SOAP faults, if they should occur, will be specific to the chosen SOAP implementation.
Implementations MUST use SOAP 1.2 [SOAPREF] or higher and MUST support SOAP 1.2. Implementations SHOULD use WSDL 1.1 [WSDLREF] and MUST NOT use earlier versions. Use of WSDL versions greater than 1.1 may introduce interoperability problems with implementations that use 1.1.
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 Section 4 ("Transport Substrate Protocol Requirements") of [RFC7877].
As illustrated in the previous diagram, SPPF can be viewed as a set of layers that collectively define the structure of an SPPF request and response. Layers 1 and 2 represent the transport, envelope, and authentication technologies. This document defines layers 3, 4, 5, and 6 for SPPP over SOAP.
1. Layer 1: The transport protocol layer represents the communication mechanism between the client and server. SPPF can be layered over any substrate protocol that provides a set of basic requirements defined in Section 4 of [RFC7877].
2. Layer 2: The message-envelope layer is optional but can provide features that are above the transport technology layer but below the application messaging layer. Technologies such as HTTP and SOAP are examples of message-envelope technologies.
3. Layers 3, 4, 5, and 6: The operation and message layers provide an envelope-independent and substrate-independent wrapper for the SPPF data model objects that are being acted on (created, modified, and queried).
While SOAP is not tied to HTTP(S), for reasons described in the Introduction, HTTP(S) is a good choice as the substrate protocol for the SPP Protocol SOAP messages. 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 connection is an HTTPS connection where the relatively time-consuming TLS handshake has occurred.
Implementations compliant with this document MUST use HTTP 1.1 [RFC7230] or higher. Also, implementations SHOULD use persistent connections.
To accomplish authentication, conforming SPPP over SOAP clients and servers MUST use HTTP Digest Authentication as defined in [RFC7235].
To achieve integrity and privacy, conforming SPPP over SOAP clients and servers MUST support TLS as defined in [RFC5246] as the secure transport mechanism. Use of TLS MUST follow the recommendations contained in [RFC7525]
Section 9 of [RFC7877] requires protocols to provide a mechanism to transmit language tags together with human-readable messages. When conforming SPPP SOAP servers use such tagging, the XML "lang" attribute ([W3C.REC-xml-20081126], Section 2.12) MUST be used. Clients MAY use the HTTP "Accept-Language" header field (see Section 5.3.5 of [RFC7231]) in order to indicate their language preference.
SPPP over SOAP uses a set of XML-based data structures for all the supported operations and any parameters to which those operations are applied. As also mentioned earlier in this document, these XML structures are envelope independent and substrate independent. Refer to "Protocol Operations" (Section 8) of this document for a description of all the operations that MUST be supported.
The following sections describe the definitions of all the XML data structures.
Certain operations in SPPF require an object key that uniquely identifies the object(s) on which a given operation needs to be performed. SPPF defines the XML structure of any such object key in an abstract manner and delegates the concrete representation to any conforming substrate protocol. The following subsections define the various types of concrete object key types used in various operations in SPPP over SOAP.
Most objects in SPPP over SOAP are uniquely identified by the attributes in the generic object key (Refer to "Generic Object Key Type", Section 5.2.1 of [RFC7877], for details). The concrete XML representation of ObjKeyType is as below:
The ObjKeyType has the data elements as described below:
o rant: The identifier of the Registrant organization that owns the object.
o name: The character string that contains the name of the object.
o type: The enumeration value that represents the type of SPPF object. For example, both a Destination Group and a SED Group can have the same name "TestObj" and be associated with the same Registrant ID. Hence, to uniquely identify the object that represents a Destination Group with the name "TestObj", the type "DestGrp" must be specified when using this concrete ObjKeyType structure to identify the Destination Group "TestObj".
Cartwright, et al. Standards Track [Page 8]
RFC 7878 SPP Protocol over SOAP August 2016
The object types in SPPP over SOAP MUST adhere to the above definition of generic object key and are defined as an enumeration in the XML data structure as follows:
Public Identifier type objects can further be of various sub-types like a Telephone Number (TN), Routing Number (RN), TN Prefix, URI, or TN Range and cannot be cleanly identified with the attributes in the generic ObjKeyType. The definition of PubIdKeyType is as below:
In addition to the attributes in the generic ObjKeyType, a SED Group Offer object is uniquely identified by the organization ID of the organization to whom a SED Group has been offered. The definition of SedGrpOfferKeyType is as below:
An SPPF client interacts with an SPPF server by sending one or more requests to the server and by receiving corresponding responses 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 "Framework Operations", Section 7 of [RFC7877]. The following subsections describe the XML data structures that are used for each of those types of operations for an SPPP over SOAP implementation.
In order to add (or modify) an object in the Registry, an authorized entity can send the spppAddRequest to the Registry.
Cartwright, et al. Standards Track [Page 10]
RFC 7878 SPP Protocol over SOAP August 2016
An SPPP over SOAP Add request is wrapped within the <spppAddRequest> element while an SPPP over SOAP Add response is wrapped within an <spppAddResponse> element. The following sub-sections describe the <spppAddRequest> and <spppAddResponse> elements. Refer to Section 10 for an example of an Add operation on each type of SPPF object.
The data elements within the <spppAddRequest> element are described as follows:
o clientTransId: Zero or one client-generated transaction ID that, within the context of the SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log, or correlate requests and their responses. The SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. The SPPF server will not check this value for uniqueness.
o minorVer: Zero or one minor version identifier, as defined in Section 7.4.
o obj: One or more elements of abstract type BasicObjType (defined in [RFC7877]). Each element contains all the attributes of an SPPF object that the client is requesting the SPPF server to add. Refer to Section 3.1 of [RFC7877] for the XML structure of all concrete types, for various SPPF objects, that extend from abstract BasicObjType and hence are eligible to be passed into this element. The elements are processed by the SPPF server in the order in which they are included in the request. With respect to the handling of error conditions, conforming SPPP SOAP servers MUST stop processing BasicObjType elements in the request at the
Cartwright, et al. Standards Track [Page 11]
RFC 7878 SPP Protocol over SOAP August 2016
first error and roll back any BasicObjType elements that had already been processed for that add request ("stop and roll back").
An SPPP over SOAP add response object is contained within the generic <spppAddResponse> element. This response structure is used for all types of SPPF objects that are provisioned by the SPPF client.
An <spppAddResponse> contains the elements necessary for the SPPF client to precisely determine the overall result of the request, and if an error occurs, it provides information about the specific object(s) that caused the error.
Cartwright, et al. Standards Track [Page 12]
RFC 7878 SPP Protocol over SOAP August 2016
The data elements within the SPPP over SOAP Add response are described as follows:
o clientTransId: Zero or one client transaction ID. This value is simply an echo of the client transaction ID that the SPPF client passed into the SPPF update request. When included in the request, the SPPF server MUST return it in the corresponding response message.
o serverTransId: Exactly one server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server.
o overallResult: Exactly one response code and message pair that explicitly identifies the result of the request. See Section 7.3 for further details.
o detailResult: An optional response code, response message, and BasicObjType (as defined in [RFC7877]) triplet. This element will be present only if an object-level error has occurred. It indicates the error condition and the exact request object that contributed to the error. The response code will reflect the exact error. See Section 7.3 for further details.
In order to remove an object from the Registry, an authorized entity can send the spppDelRequest into the Registry. An SPPP over SOAP Delete request is wrapped within the <spppDelRequest> element while an SPPP over SOAP Delete response is wrapped within the generic <spppDelResponse> element. The following subsections describe the <spppDelRequest> and <spppDelResponse> elements. Refer to Section 10 for an example of the Delete operation on each type of SPPF object.
The data elements within the <spppDelRequest> element are described as follows:
o clientTransId: Zero or one client-generated transaction ID that, within the context of the SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log, or correlate requests and their responses. The SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. SPPF server will not check this value for uniqueness.
o minorVer: Zero or one minor version identifier, as defined in Section 7.4.
o objKey: One or more elements of abstract type ObjKeyType (as defined in [RFC7877]). Each element contains attributes that uniquely identify the object that the client is requesting the server to delete. Refer to Section 7.1 for a description of all concrete object key types, for various SPPF objects, which are eligible to be passed into this element. The elements are processed by the SPPF server in the order in which they are included in the request. With respect to the handling of error conditions, conforming SPPP SOAP servers MUST stop processing ObjKeyType elements in the request at the first error and roll back any ObjKeyType elements that had already been processed for that Delete request ("stop and roll back").
An SPPP over SOAP delete response object is contained within the generic <sppDeleteResponse> element. This response structure is used for a Delete request on all types of SPPF objects that are provisioned by the SPPF client.
An <spppDelResponse> contains the elements necessary for the SPPF client to precisely determine the overall result of the request, and if an error occurs, it provides information about the specific object key(s) that caused the error.
Cartwright, et al. Standards Track [Page 15]
RFC 7878 SPP Protocol over SOAP August 2016
The data elements within the SPPP over SOAP Delete response are described as follows:
o clientTransId: Zero or one client transaction ID. This value is simply an echo of the client transaction ID that the SPPF client passed into the SPPF update request. When included in the request, the SPPF server MUST return it in the corresponding response message.
o serverTransId: Exactly one server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server.
o overallResult: Exactly one response code and message pair that explicitly identifies the result of the request. See Section 7.3 for further details.
o detailResult: An optional response code, response message, and ObjKeyType (as defined in [RFC7877]) triplet. This element will be present only if a specific object key level error has occurred. It indicates the error condition and the exact request object key that contributed to the error. The response code will reflect the exact error. See Section 7.3 for further details.
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 to Section 3.1 of [RFC7877] 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. The request structure for an SPPP over SOAP Accept operation is wrapped within the <spppAcceptRequest> element while an SPPP over SOAP Accept response is wrapped within the generic <spppAcceptResponse> element. The following subsections describe the <spppAcceptRequest> and <spppAcceptResponse> elements. Refer to Section 10 for an example of the Accept operation on a SED Group Offer.
The data elements within the <spppAcceptRequest> element are described as follows:
o clientTransId: Zero or one client-generated transaction ID that, within the context of the SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log, or correlate requests and their responses. The SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. The SPPF server will not check this value for uniqueness.
o minorVer: Zero or one minor version identifier, as defined in Section 7.4.
o sedGrpOfferKey: One or more elements of type SedGrpOfferKeyType (as defined in this document). Each element contains attributes that uniquely identify a SED Group Offer that the client is requesting the server to accept. The elements are processed by the SPPF server in the order in which they are included in the request. With respect to the handling of error conditions, conforming SPPP SOAP servers MUST stop processing SedGrpOfferKeyType elements in the request at the first error and roll back any SedGrpOfferKeyType elements that had already been processed for that Accept request ("stop and roll back").
An SPPP over SOAP accept response structure is contained within the generic <sppAcceptResponse> element. This response structure is used for an Accept request on a SED Group Offer.
An <spppAcceptResponse> contains the elements necessary for the SPPF client to precisely determine the overall result of the request, and if an error occurs, it provides information about the specific SED Group Offer key(s) that caused the error.
Cartwright, et al. Standards Track [Page 18]
RFC 7878 SPP Protocol over SOAP August 2016
The data elements within the SPPP over SOAP Accept response are described as follows:
o clientTransId: Zero or one client transaction ID. This value is simply an echo of the client transaction ID that the SPPF client passed into the SPPF update request. When included in the request, the SPPF server MUST return it in the corresponding response message.
o serverTransId: Exactly one server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server.
o overallResult: Exactly one response code and message pair that explicitly identifies the result of the request. See Section 7.3 for further details.
o detailResult: An optional response code, response message, and SedGrpOfferKeyType (as defined in this document) triplet. This element will be present only if any specific SED Group Offer key level error has occurred. It indicates the error condition and the exact request SED Group Offer key that contributed to the error. The response code will reflect the exact error. See Section 7.3 for further details.
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 to "Framework Data Model Objects", Section 6 of [RFC7877] 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. The request structure for an SPPP over SOAP Reject operation is wrapped within the <spppRejectRequest> element while an SPPP over SOAP Reject response is wrapped within the generic <spppRejecResponse> element. The following subsections describe the <spppRejectRequest> and <spppRejecResponse> elements. Refer to Section 10 for an example of the Reject operation on a SED Group Offer.
The data elements within the <spppRejectRequest> element are described as follows:
o clientTransId: Zero or one client-generated transaction ID that, within the context of the SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log, or correlate requests and their responses. The SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. The SPPF server will not check this value for uniqueness.
o minorVer: Zero or one minor version identifier, as defined in Section 7.4.
o sedGrpOfferKey: One or more elements of type SedGrpOfferKeyType (as defined in this document). Each element contains attributes that uniquely identify a SED Group Offer that the client is requesting the server to reject. The elements are processed by the SPPF server in the order in which they are included in the request. With respect to the handling of error conditions, conforming SPPF servers MUST stop processing SedGrpOfferKeyType elements in the request at the first error and roll back any SedGrpOfferKeyType elements that had already been processed for that Reject request ("stop and roll back").
An SPPP over SOAP reject response structure is contained within the generic <sppRejectResponse> element. This response structure is used for a Reject request on a SED Group Offer.
An <spppRejectResponse> contains the elements necessary for the SPPF client to precisely determine the overall result of the request, and if an error occurs, it provides information about the specific SED Group Offer key(s) that caused the error.
Cartwright, et al. Standards Track [Page 21]
RFC 7878 SPP Protocol over SOAP August 2016
The data elements within the SPPP over SOAP Reject response are described as follows:
o clientTransId: Zero or one client transaction ID. This value is simply an echo of the client transaction ID that the SPPF client passed into the SPPF update request. When included in the request, the SPPF server MUST return it in the corresponding response message.
o serverTransId: Exactly one server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server.
o overallResult: Exactly one response code and message pair that explicitly identifies the result of the request. See Section 7.3 for further details.
o detailResult: An optional response code, response message, and SedGrpOfferKeyType (as defined in this document) triplet. This element will be present only if any specific SED Group Offer key level error has occurred. It indicates the error condition and the exact request SED Group Offer key that contributed to the error. The response code will reflect the exact error. See Section 7.3 for further details.
An SPPP over SOAP Batch request XML structure allows the SPPF client to send any of the Add, Del, Accept, or Reject operations together in one single request. This gives an SPPF client the flexibility to use one single request structure to perform more than operations (verbs). The batch request structure is wrapped within the <spppBatchRequest> element while an SPPF Batch response is wrapped within the <spppBatchResponse> element. The following subsections describe the <spppBatchRequest> and <spppBatchResponse> elements. Refer to Section 10 for an example of a Batch operation.
The data elements within the <sppBatchRequest> element are described as follows:
o clientTransId: Zero or one client-generated transaction ID that, within the context of the SPPF client, identifies this request. This value can be used at the discretion of the SPPF client to track, log, or correlate requests and their responses. The SPPF server MUST echo back this value to the client in the corresponding response to the incoming request. The SPPF server will not check this value for uniqueness.
o minorVer: Zero or one minor version identifier, as defined in Section 7.4.
o addObj: One or more elements of abstract type BasicObjType where each element identifies an object that needs to be added.
o delObj: One or more elements of abstract type ObjKeyType where each element identifies a key for the object that needs to be deleted .
o acceptSedGrpOffer: One or more elements of type SedGrpOfferKeyType where each element identifies a SED Group Offer that needs to be accepted.
Cartwright, et al. Standards Track [Page 23]
RFC 7878 SPP Protocol over SOAP August 2016
o rejectSedGrpOffer: One or more elements of type SedGrpOfferKeyType where each element identifies a SED Group Offer that needs to be rejected.
With respect to the handling of error conditions, conforming SPPP SOAP servers MUST stop processing elements in the request at the first error and roll back any elements that had already been processed for that Batch request ("stop and roll back").
An SPPP over SOAP batch response structure is contained within the generic <sppBatchResponse> element. This response structure is used for a Batch request that contains many different types of SPPF operations.
An <spppBatchResponse> contains the elements necessary for an SPPF client to precisely determine the overall result of various operations in the request, and if an error occurs, it provides information about the specific objects or keys in the request that caused the error.
Cartwright, et al. Standards Track [Page 24]
RFC 7878 SPP Protocol over SOAP August 2016
The data elements within the SPPP over SOAP Batch response are described as follows:
o clientTransId: Zero or one client transaction ID. This value is simply an echo of the client transaction ID that the SPPF client passed into the SPPF update request. When included in the request, the SPPF server MUST return it in the corresponding response message.
o serverTransId: Exactly one server transaction ID that identifies this request for tracking purposes. This value MUST be unique for a given SPPF server.
o overallResult: Exactly one response code and message pair that explicitly identifies the result of the request. See Section 7.3 for further details.
o addResult: One or more elements of type ObjResultCodeType where each element identifies the result code, result message, and the specific object to which the result relates.
o delResult: One or more elements of type ObjKeyResultCodeType where each element identifies the result code, result message, and the specific object key to which the result relates.
o acceptResult: One or more elements of type SedGrpOfferKeyResultCodeType where each element identifies the result code, result message, and the specific SED Group Offer key to which the result relates.
o rejectResult: One or more elements of type SedGrpOfferKeyResultCodeType where each element identifies the result code, result message, and the specific SED Group Offer key to which the result relates.
In order to query the details of an object from the Registry, an authorized entity can send the spppGetRequest to the Registry with a GetRqstType XML data structure containing one or more object keys that uniquely identify the object whose details are being queried. The following subsections describe the <spppGetRequest> and <spppGetResponse> elements. Refer to Section 10 for an example of the SPPP over SOAP Get operation on each type of SPPF object.
The data elements within the <spppGetRequest> element are described as follows:
o minorVer: Zero or one minor version identifier, as defined in Section 7.4.
o objKey: One or more elements of abstract type ObjKeyType (as defined in [RFC7877]). Each element contains attributes that uniquely identify the object that the client is requesting the server to query. Refer to Section 7.1 of this document for a description of all concrete object key types, for various SPPF objects, which are eligible to be passed into this element.
In addition to the ability to query the details of one or more SED Group Offers using a SED Group Offer key in the spppGetRequest, this operation also provides an additional, more flexible, structure to query for SED Group Offer objects. This additional structure is contained within the <getSedGrpOffersRequest> element while the response is wrapped within the generic <spppGetResponse> element. The following subsections describe the <getSedGrpOffersRequest> and <spppGetResponse> elements.
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 are passed in, then the SPPF server will return the list of SED Group Offer objects that belong to the Registrant. If there are no matching SED Group Offers found, then an empty result set will be returned.
The data elements within the <getSedGrpOffersRequest> element are described as follows:
o minorVer: Zero or one minor version identifier, as defined in Section 7.4.
o offeredBy: Zero or more organization IDs. Only offers that are offered to the organization IDs in this list should be included in the result set. The result set is also subject to other query criteria in the request.
o offeredTo: Zero or more organization IDs. Only offers that are offered by the organization IDs in this list should be included in the result set. The result set is also subject to other query criteria in the request.
o status: The status of the offer, offered or accepted. Only offers in the specified status should be included in the result set. If this element is not present, then the status of the offer should not be considered in the query. The result set is also subject to other query criteria in the request.
Cartwright, et al. Standards Track [Page 27]
RFC 7878 SPP Protocol over SOAP August 2016
o sedGrpOfferKey: Zero or more SED Group Offer keys. Only offers having one of these keys should be included in the result set. The result set is also subject to other query criteria in the request.
An <spppGetResponse> contains the elements necessary for the SPPF client to precisely determine the overall result of the query and details of any SPPF objects that matched the criteria in the request.
The data elements within the SPPP over SOAP query response are described as follows:
o overallResult: Exactly one response code and message pair that explicitly identifies the result of the request. See Section 7.3 for further details.
o resultObj: The set of zero or more objects that matched the query criteria. If no objects matched the query criteria, then the result object(s) MUST be empty and the overallResult value MUST indicate success (if no matches are found for the query criteria, the response is considered a success).
In order to query certain details of the SPPF server, such as the SPPF server's status and the major/minor version supported by the server, the Server Details operation structure SHOULD be used. This structure is contained within the <spppServerStatusRequest> element whereas an SPPF server status response is wrapped within the <spppServerStatusResponse> element. The following subsections describe the <spppServerStatusRequest> and <spppServerStatusResponse> elements.
The data elements within the <spppServerStatusResponse> element are described as follows:
o overallResult: Exactly one response code and message pair that explicitly identifies the result of the request. See Section 7.3 for further details.
o svcMenu: Exactly one element of type SvcMenuType that, in turn, contains the elements to return the server status, the major and minor versions of SPPP over SOAP supported by the SPPF server (refer to Section 12 of [RFC7877] for the definition of SvcMenuType).
This section contains the listing of response codes and their corresponding human-readable text. These response codes are in conformance with the response types defined in Section 5.3 of [RFC7877].
The response code numbering scheme generally adheres to the theory formalized in Section 4.2.1 of [RFC5321]:
o The first digit of the response code can only be 1 or 2: 1 = a positive result, and 2 = a negative result.
o The second digit of the response code indicates the category: 0 = Protocol Syntax, 1 = Implementation Specific Business Rule, 2 = Security, and 3 = Server System.
o The third and fourth digits of the response code indicate the individual message event within the category defined by the first two digits.
The response codes are also categorized as to whether they are overall response codes that may only be returned in the overallResult data element in SPPF responses or object-level response codes that may only be returned in the detailResult element of the SPPF responses.
Table 1: Response Code Numbering Scheme and Messages
The response message for response code 2001 is "parameterized" with the following parameter: "[Maximum requests supported]". When the request is too large, this parameter MUST be used to indicate the maximum number of requests supported by the server in a single protocol operation.
Response code 2000 SHOULD be used when the XML Schema validation of requests fails.
Each of the object-level response messages are "parameterized" with the following parameters: "AttributeName" and "AttributeValue".
For example, if an SPPF client sends a request to delete a Destination Group with a name "TestDG", and it does not already exist, then the error message returned should be: "Attribute value invalid. AttrName:dgName AttrVal:TestDG".
Cartwright, et al. Standards Track [Page 31]
RFC 7878 SPP Protocol over SOAP August 2016
The use of these parameters MUST adhere to the rules defined in Section 5.3 of [RFC7877].
The minor version identifier element is defined as follows:
o minorVer: Zero or one minor version identifier, indicating the minor version of the SPPP over SOAP API that the client is attempting to use. This is used in conjunction with the major version identifier in the XML Namespace to identify the version of SPPP over SOAP that the client is using. If the element is not present, the server assumes that the client is using the latest minor version of SPPP over SOAP supported by the SPPF server for the given major version. The versions of SPPP over SOAP supported by a given SPPF server can be retrieved by the client using this same spppServerStatusRequest without passing in the minorVer element.
Refer to Section 7 of [RFC7877] for a description of all SPPF operations and any necessary semantics that MUST be adhered to in order to conform with SPPF.
The SPPP over SOAP WSDL and data types are defined below. The WSDL design approach is commonly referred to as "Generic WSDL". It is generic in the sense that there is not a specific WSDL operation defined for each object type that is supported by the SPPF protocol. There is a single WSDL structure for each type of SPPF operation. Each such WSDL structure contains exactly one input structure and one output structure that wraps any data elements that are part of the incoming request and the outgoing response, respectively. The spppSOAPBinding in the WSDL defines the binding style as "document" and the encoding as "literal". It is this combination of "wrapped" input and output data structures, "document" binding style, and "literal" encoding that characterize the Document Literal Wrapped style of WSDL specifications.
Notes: The following WSDL has been formatted (e.g., tabs, spaces) to meet IETF requirements. Deployments MUST replace "REPLACE_WITH_ACTUAL_URL" in the WSDL below with the URI of the SPPF server instance.
This section shows an XML message exchange between two SIP Service Providers (SSPs) and a Registry. The messages in this section are valid XML instances that conform to the SPPP over SOAP schema version within this document. This section also relies on the XML data structures defined in the SPPF specification [RFC7877], which should also be referenced 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 Signaling Path Border Element (SBE) instances that are associated with the Public Identities with which SSP2 has the retail relationship. 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.
SSP2 adds a Destination Group to the Registry for later use. 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.
The Registry processes the request and returns a favorable response confirming successful creation of the named Destination Group. In addition to returning a unique server transaction identifier, the Registry returns the matching client transaction identifier from the request message back to the SPPF client.
SSP2 creates the grouping of SED Records (e.g., Ingress Routes) and chooses a higher precedence for SED_SSP2_SBE2 by setting a lower number for the "priority" attribute, a protocol agnostic precedence indicator.
10.5. Add Public Identifier -- Successful COR Claim
SSP2 activates a TN Public Identifier by associating it with a valid Destination Group. Further, SSP2 puts forth a claim that it is the carrier-of-record (COR) for the TN.
Assuming that the Registry has access to TN authority data and it performs the required checks to verify that SSP2 is in fact the SP 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 the SSP2 claim as the carrier-of-record, and the <corDate> reflects the time when the carrier-of-record claim is processed.
If another entity that SSP2 shares SED (e.g., routes) with has access to Number Portability data, it may choose to perform route lookups by RN. Therefore, SSP2 associates an RN to a Destination Group in order to facilitate Ingress Route discovery.
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 bidirectional handshake to show mutual consent. To start the process, SSP2 initiates the peering handshake by offering SSP1 access to its SED Group.
The 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.
The Registry confirms that the request has been processed successfully. From this point forward, if SSP1 looks up a Public Identifier through the query resolution server, where the Public Identifier is part of the Destination Group by way of "SED_GRP_SSP2_1" SED association, SSP2 ingress SBE information will be shared with SSP1.
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".
Earlier, SSP1 had accepted having visibility to SSP2 SED. SSP1 now decides to no longer maintain this visibility; hence, it rejects the SED Group Offer.
The Registry confirms that the request has been processed successfully. From this point forward, if SSP1 looks up a Public Identifier through the query resolution server, where the Public Identifier is part of the Destination Group by way of "SED_GRP_SSP2_1" SED association, SSP2 ingress SBE information will not be shared with SSP1; hence, an SSP2 ingress SBE will not be returned in the query response.
The 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.
Following is an example of how some of the operations mentioned in previous sections MAY be performed by an SPPF client as a batch in one single SPPP over SOAP request.
In the sample request below, SSP1 wants to accept a SED Group Offer from SSP3, add a Destination Group, add a Naming Authority Pointer (NAPTR) SED Record, add a SED Group, add a SED Group Offer, delete a previously provisioned TN type Public Identifier, delete a previously provisioned SED Group, and reject a SED Group Offer from SSP4.
The base security considerations of SPPP outlined in Section 9 of [RFC7877] also apply to SPPP over SOAP implementations. Additionally, the following must be considered:
SPPP over SOAP 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].
Section 5 describes the use of HTTP and TLS as the underlying substrate protocols for SPPP over SOAP. These underlying protocols may have various vulnerabilities, and these may be inherited by SPPP over SOAP. SPPP over SOAP itself may have vulnerabilities because an authorization model is not explicitly specified in this document.
During a TLS handshake, 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 SPPP over SOAP 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.
[RFC7525] Sheffer, Y., Holz, R., and P. Saint-Andre, "Recommendations for Secure Use of Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS)", BCP 195, RFC 7525, DOI 10.17487/RFC7525, May 2015, <http://www.rfc-editor.org/info/rfc7525>.
[SOAPREF] Gudgin, M., Hadley, M., Moreau, J., and H. Nielsen, "SOAP Version 1.2 Part 1: Messaging Framework (Second Edition)", W3C Recommendation REC-SOAP12-part1-20070427, April 2007, <http://www.w3.org/TR/soap12-part1/>.
[W3C.REC-xml-20081126] Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E., and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", W3C Recommendation REC-xml-20081126, November 2008, <http://www.w3.org/TR/2008/REC-xml-20081126>.
[WSDLREF] Christensen, E., Curbera, F., Meredith, G., and S. Weerawarana, "Web Services Description Language (WSDL) 1.1", W3C Note NOTE-wsdl-20010315, March 2001, <http://www.w3.org/TR/2001/NOTE-wsdl-20010315>.
Acknowledgements
This document is a result of various discussions held with the IETF DRINKS working group, specifically the protocol design team, with contributions from the following individuals, in alphabetical order: Syed Ali, Vikas Bhatia, Kenneth Cartwright, Sumanth Channabasappa, Lisa Dusseault, Deborah A. Guyton, Scott Hollenbeck, Otmar Lendl, Manjul Maharishi, Mickael Marrache, Alexander Mayrhofer, Samuel Melloul, Jean-Francois Mule, Peter Saint-Andre, David Schwartz, and Richard Shockey.
Cartwright, et al. Standards Track [Page 82]
RFC 7878 SPP Protocol over SOAP August 2016
Authors' Addresses
Kenneth Cartwright TNS 10740 Parkridge Boulevard Reston, VA 20191 United States
Email: kcartwright@tnsi.com
Vikas Bhatia TNS 10740 Parkridge Boulevard Reston, VA 20191 United States
Email: vbhatia@tnsi.com
Jean-Francois Mule Apple Inc. 1 Infinite Loop Cupertino, CA 95014 United States
Email: jfmule@apple.com
Alexander Mayrhofer nic.at GmbH Karlsplatz 1/2/9 Wien A-1010 Austria