DRINKS K. Cartwright
Internet-Draft TNS
Intended status: Standards Track October 31, 2011
Expires: May 3, 2012
SPPP Over SOAP and HTTP
draft-ietf-drinks-sppp-over-soap-06
Abstract
The Session Peering Provisioning Protocol (SPPP) is an XML protocol
that exists to enable the provisioning of session establishment data
into Session Data Registries or SIP Service Provider data stores.
Sending XML data structures over Simple Object Access Protocol (SOAP)
and HTTP(s) is a widely used, de-facto standard for messaging between
elements of provisioning systems. Therefore the combination of SOAP
and HTTP(s) as a transport for SPPP is a natural fit. The obvious
benefits include leveraging existing industry expertise, leveraging
existing standards, and a higher probability that existing
provisioning systems can be more easily integrated with this
protocol. This document describes the specification for transporting
SPPP XML structures over SOAP and HTTP(s).
Status of this Memo
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 May 3, 2012.
Copyright Notice
Copyright (c) 2011 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
Cartwright Expires May 3, 2012 [Page 1]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
(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.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. SOAP Features and Protocol Layering . . . . . . . . . . . . . 6
4. HTTP(s) Features and SPPP . . . . . . . . . . . . . . . . . . 9
5. Authentication and Session Management . . . . . . . . . . . . 10
6. Base Protocol Data Structures . . . . . . . . . . . . . . . . 11
6.1. Request and Response Structures . . . . . . . . . . . . . 11
6.1.1. Update Request and Response Structures . . . . . . . . 11
6.1.2. Query Request and Response Structures . . . . . . . . 14
6.2. Response Codes and Messages . . . . . . . . . . . . . . . 17
7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 20
7.1. Add Destination Group Operation . . . . . . . . . . . . . 20
7.2. Get Destination Groups Operation . . . . . . . . . . . . . 20
7.3. Add Public Identifier Operation . . . . . . . . . . . . . 21
7.4. Get Public Identifiers Operation . . . . . . . . . . . . . 22
7.5. Add Route Group Operation . . . . . . . . . . . . . . . . 23
7.6. Get Route Groups Operation . . . . . . . . . . . . . . . . 23
7.7. Add Route Record Operation . . . . . . . . . . . . . . . . 24
7.8. Get Route Records Operation . . . . . . . . . . . . . . . 25
7.9. Add Route Group Offer Operation . . . . . . . . . . . . . 25
7.10. Accept Route Group Offer Operation . . . . . . . . . . . . 26
7.11. Reject Route Group Offer Operation . . . . . . . . . . . . 27
7.12. Get Route Group Offers Operation . . . . . . . . . . . . . 28
7.13. Add Egress Route Operation . . . . . . . . . . . . . . . . 29
7.14. Get Egress Routes Operation . . . . . . . . . . . . . . . 30
7.15. Delete Operation . . . . . . . . . . . . . . . . . . . . . 31
8. SPPP SOAP WSDL Definition . . . . . . . . . . . . . . . . . . 33
9. SPPP SOAP Examples . . . . . . . . . . . . . . . . . . . . . . 44
10. Security Considerations . . . . . . . . . . . . . . . . . . . 46
10.1. Integrity, Privacy, and Authentication . . . . . . . . . . 46
10.2. Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 46
10.3. Deployment Environment Specifics . . . . . . . . . . . . . 46
11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47
12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 48
13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 49
13.1. Normative References . . . . . . . . . . . . . . . . . . . 49
13.2. Informative References . . . . . . . . . . . . . . . . . . 49
Cartwright Expires May 3, 2012 [Page 2]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 50
Cartwright Expires May 3, 2012 [Page 3]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
1. Introduction
SPPP, defined in [I-D.draft-ietf-drinks-spprov], is best supported by
a transport and messaging infrastructure that is connection oriented,
request-response oriented, easily secured, supports propagation
through firewalls in a standard fashion, and that is easily
integrated into back-office systems. This is due to the fact that
the client side of SPPP is likely to be integrated with
organizations' operational support systems that facilitate
transactional provisioning of user addresses and their associated
session establishment data. While the server side of SPPP is likely
to reside in a separate organization's network, resulting the SPPP
provisioning transactions traversing the Internet as they are
propagated from the SPPP client to the SPPP 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 SPPP XML structures over
SOAP and HTTP(s).
The specification in this document for transporting SPPP XML
structures over SOAP and HTTP(s) is primarily comprised of five
subjects: (1) a description of any applicable SOAP features, (2) any
applicable HTTP features, (3) security considerations, and perhaps
most importantly, (5) the Web Services Description Language (WSDL)
definition for SPPP over SOAP.
Cartwright Expires May 3, 2012 [Page 4]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
2. Terminology
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].
Cartwright Expires May 3, 2012 [Page 5]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
3. SOAP Features and Protocol Layering
The list of SOAP features that are explicitly used and required for
SPPP are limited. Most SOAP features are not necessary for SPPP.
SPPP 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 specifications, the SOAP
header can contain optional, application specific, information about
the message. The SOAP body contains the SPPP message itself, whose
structure is defined by the combination of one of the WSDL operations
defined in this document and the SPPP XML data structures defined in
the SPPP protocol document. SPPP does not rely on any data elements
in the SOAP header. All relevant data elements are defined in the
SPPP XML schema described in [I-D.draft-ietf-drinks-spprov] and the
SPPP WSDL specification described in 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 SPPP SOAP
messages is defined later in this document, which imports by
reference the XML data types contained in the SPPP schema. The IANA
registry where the SPPP schema resides is described in The IETF XML
Registry [RFC3688].
There are multiple structural styles that SOAP WSDL allows. But the
best practice for this type of application is what is sometimes
referred to as the Document Literal Wrapped style of designing SOAP
WSDL. 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_ that is 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.
Cartwright Expires May 3, 2012 [Page 6]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
+-------------+
(1) | Transport |Example:
| Protocol | TCP, TLS, BEEP, etc.
+-------------+
|
V
+-------------+
(2) | Message |Example:
| Envelope | HTTP, SOAP, None, etc.
+-------------+
|
V
+--------------+
+------| SOAP |-----+
| (3) | Operation | |
Contains | +--------------+ | Contains
| Example: |
V submitUpdateRqst V
+--------------+ +-------------+
|SOAP Request | |SOAP Response|
Example:| Message | (4) | Message | Example:
spppUpdate | (Operation | | (Operation |spppUpdate
RequestMsg | Input) | | Output) | ResponseMsg
+--------------+ +-------------+
| |
Contains | | Contains
| |
V V
+---------------+ +---------------+
Example:| Wrapped | (5) | Wrapped | Example:
spppUpdate |Request Object | |Response Object| spppUpdate
Request +---------------+ +---------------+ Response
| |
Contains | | Contains
| |
V V
+----------+ +-----------+
Example: | SPPP | | SPPP |
AddRteGrp |XML Types | (6) | XML Types |
RqstType +----------+ +-----------+
Figure 1: Layering and Technical Structure of the SPPP SOAP Messages
The SOAP operations supported by SPPP 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 SPPP
XML data types that comprise the inputs and the outputs,
Cartwright Expires May 3, 2012 [Page 7]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
respectively, of the SOAP operation.
SOAP faults are not used by the SPPP SOAP mapping. All SPPP success
and error responses are specified within the SPPP protocol
specification [I-D.draft-ietf-drinks-spprov]. 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.
SOAP 1.2 [SOAPREF] or higher and WSDL 1.1 [WSDLREF] or higher SHOULD
be used.
SPPP is a request/reply protocol that allows a client application to
submit provisioning data and query requests to a server. The SPPP
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.
As illustrated in the previous diagram, SPPP can be viewed as a set
of layers that collectively define the structure of an SPPP request
and response. Layers 1 and 2 represent the transport, envelope, and
authentication technologies. This document defines layers 3, 4, and
5 below.
1. Layer 1: The transport protocol layer represents the
communication mechanism between the client and server. SPPP can
be layered over any transport protocol that provides a set of
basic requirements defined in the Transport Protocol Requirements
section. But this document specifies the required mechanism.
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 messaging envelope technologies. This
document specifies the required envelope technology.
3. Layers 3,4,5,6: The operation and message layers provides an
envelope-independent and transport-independent wrapper for the
SPPP data model objects that are being acted on (created,
modified, queried).
Cartwright Expires May 3, 2012 [Page 8]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
4. HTTP(s) Features and SPPP
SOAP is not tied to HTTP(s), however, for reasons described in the
introduction, HTTP(s) is a good choice as the transport mechanism for
the SPPP 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
connections is an HTTPS connection where the relatively time
consuming SSL handshake has occurred. Persistent connections SHOULD
be used for the SPPP HTTP connections.
HTTP 1.1 [RFC2616] or higher SHOULD be used.
Cartwright Expires May 3, 2012 [Page 9]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
5. Authentication and Session Management
To achieve integrity and privacy, conforming SPPP SOAP Clients and
Servers MUST support SOAP over 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 SOAP SPPP
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.
Cartwright Expires May 3, 2012 [Page 10]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
6. Base Protocol Data Structures
SPPP uses a common model and a common set of data structures for most
of the supported operations. This section describes these common
operation data structures.
6.1. Request and Response Structures
An SPPP client interacts with an SPPP 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. There are
two generalized types of operations that an SPPP client can submit to
an SPPP server, updates and queries. The following two sub-sections
describe the generalized data structures that are used for each of
these two types of operations.
6.1.1. Update Request and Response Structures
An SPPP update request is wrapped within the <spppUpdateRequest>
element while an SPPP update response is wrapped within an
<spppUpdateResponse> element. The following two sub-sections
describe these two elements.
6.1.1.1. Update Request
An SPPP update request object is contained within the generic
<spppUpdateRequest> element.
<element name="spppUpdateRequest">
<complexType>
<sequence>
<element name="clientTransId" type="spppb:TransIdType"
minOccurs="0"/>
<element name="minorVer" type="spppb:MinorVerType"
minOccurs="0"/>
<element name="rqst" type="spppb:BasicUpdateRqstType"
maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
<simpleType name="TransIdType">
<restriction base="string"/>
</simpleType>
Cartwright Expires May 3, 2012 [Page 11]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<simpleType name="MinorVerType">
<restriction base="unsignedLong"/>
</simpleType>
The data elements within the <spppUpdateRequest> element are
described as follows:
o clientTransId: Zero or one client-generated transaction ID that,
within the context of the SPPP client, identifies this request.
This value can be used at the discretion of the SPPP client to
track, log or correlate requests and their responses. SPPP
server MUST echo back this value to the client in the
corresponding response to the incoming request. SPPP server
will not check this value for uniqueness.
o minorVer: Zero or one minor version identifier, indicating the
minor version of the SPPP 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
that the client is using. If the element is not present, the
server assumes that the client is using the latest minor version
supported by the SPPP server for the given major version. The
versions supported by a given SPPP server can be retrieved by
the client using the SPPP server menu operation described later
in the document.
o rqst: One or more BasicUpdateRqstType objects. These are the
actions that the client is requesting the SPPP server perform.
They are processed by the SPPP server in the order in which they
are included in the request. And with respect to handling error
conditions, it is a matter of policy whether the objects are
processed in a "stop and rollback" fashion or in a "stop and
commit" fashion. In the "stop and rollback" scenario, the SPPP
server would stop processing BasicUpdateRqstType object
instances in the request at the first error and roll back any
BasicUpdateRqstType object instances that had already been
processed for that update request. In the "stop and commit"
scenario the SPPP server would stop processing
BasicUpdateRqstType object instances in the request at the first
error but commit any BasicUpdateRqstType object instances that
had already been processed for that update request.
All update request objects extend the base type BasicUpdateRqstType.
This base type is defined as follows:
Cartwright Expires May 3, 2012 [Page 12]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<complexType name="BasicUpdateRqstType" abstract="true">
<sequence>
<element name="ext" type="spppb:ExtAnyType" minOccurs="0"/>
</sequence>
</complexType>
The BasicUpdateRqstType object primarily acts as an abstract base
type, and its only data element is described as follows:
o ext: This is the standard extension element for this object.
Refer to the Extensibility section of this document for more
details.
6.1.1.2. Update Response
An SPPP update response object is contained within the generic
<spppUpdateResponse> element.
<element name="spppUpdateResponse">
<complexType>
<sequence>
<element name="overallResult" type="spppb:ResultCodeType"/>
<element name="rqstObjResult" type="spppb:RqstObjResultCodeType"
minOccurs="0" maxOccurs="unbounded"/>
<element name="clientTransId" type="spppb:TransIdType"
minOccurs="0"/>
<element name="serverTransId" type="spppb:TransIdType"/>
</sequence>
</complexType>
</element>
<complexType name="ResultCodeType">
<sequence>
<element name="code" type="int"/>
<element name="msg" type="string"/>
</sequence>
</complexType>
<complexType name="RqstObjResultCodeType">
<complexContent>
<extension base="spppb:ResultCodeType">
<sequence>
<element name="rqstObj" type="spppb:BasicUpdateRqstType"/>
</sequence>
</extension>
Cartwright Expires May 3, 2012 [Page 13]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
</complexContent>
</complexType>
An <spppUpdateResponse> contains the elements necessary for the SPPP
client to precisely determine the overall result of the request, and
if an error occurred, it provides information about the specific
object, data element, or condition caused the error.
The data elements within the SPPP update 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 SPPP client
passed into the SPPP update request. When included in the
request, the SPPP 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 SPPP server.
o overallResult: Exactly one response code and message pair that
explicitly identifies the result of the request. See the
Response Code section for further details.
o rqstObjResult: An optional response code, response message, and
BasicRqstObject 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 the
Response Code section for further details.
o ext: This is the standard extension element for this object.
Refer to the Extensibility section for more details.
6.1.2. Query Request and Response Structures
At times, on behalf of the registrant, the registrar may need to have
access to SPPP objects that were previously provisioned in the
registry. A few examples include logging, auditing, and pre-
provisioning dependency checking. This query mechanism is limited to
aid provisioning scenarios and should not be confused with query
protocols provided as part of the resolution system (e.g. ENUM and
SIP).
An SPPP query request is wrapped within the <spppQueryRequest>
Cartwright Expires May 3, 2012 [Page 14]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
element while an SPPP query response is wrapped within an
<spppQueryResponse> element. The following two sub-sections describe
these two element structures.
6.1.2.1. Query Request
An SPPP query request object is contained within the generic
<spppQueryRequest> element.
<element name="spppQueryRequest">
<complexType>
<sequence>
<element name="minorVer" type="spppb:MinorVerType"
minOccurs="0"/>
<element name="rqst" type="spppb:BasicQueryRqstType"/>
</sequence>
</complexType>
</element>
The data elements within the <spppQueryRequest> element are described
as follows:
o minorVer: Zero or one minor version identifier, indicating the
minor version of the SPPP 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
that the client is using. If the element is not present, the
server assumes that the client is using the latest minor version
supported by the SPPP server for the given major version. The
versions supported by a given SPPP server can be retrieved by
the client using the SPPP server menu operation described later
in the document.
o rqst: One BasicQueryRqstType objects. This is the query that
the client is requesting the SPPP server perform.
All query request objects extend the base type BasicQueryRqstType.
This base type is defined as follows:
<complexType name="BasicQueryRqstType" abstract="true">
<sequence>
<element name="ext" type="spppb:ExtAnyType" minOccurs="0"/>
</sequence>
Cartwright Expires May 3, 2012 [Page 15]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
</complexType>
The BasicQueryRqstType object primarily acts as an abstract base
type, and its only data element is described as follows:
o ext: This is the standard extension element for this object.
Refer to the Extensibility section of this document for more
details.
6.1.2.2. Query Response
An SPPP query response object is contained within the generic
<spppQueryResponse> element.
<element name="spppQueryResponse">
<complexType>
<sequence>
<element name="overallResult" type="spppb:ResultCodeType"/>
<element name="resultSet" type="spppb:BasicObjType"
minOccurs="0" maxOccurs=" unbounded"/>
</sequence>
</complexType>
</element>
An <spppQueryResponse> contains the elements necessary for the SPPP
client to precisely determine the overall result of the query, and if
an error occurred, exactly what condition caused the error.
The data elements within the SPPP query response are described as
follows:
o overallResult: Exactly one response code and message pair that
explicitly identifies the result of the request. See the
Response Code section for further details.
o resultSet: The set of zero or more objects that matched the
query criteria. If no objects matched the query criteria then
this result set 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).
Cartwright Expires May 3, 2012 [Page 16]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
6.2. Response Codes and Messages
This section contains the listing of response codes and their
corresponding human-readable text.
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, 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, 3 = Server System.
o The third and fourth digits of the response code indicate the
individual message event within the category defines 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 SPPP responses, of object level
response codes that may only be returned in the "rqstObjResult"
element of the SPPP responses.
Cartwright Expires May 3, 2012 [Page 17]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
+--------+--------------------------+-------------------------------+
| Result | Result Message | Overall or Object Level |
| Code | | |
+--------+--------------------------+-------------------------------+
| 1000 | Request Succeeded. | Overall Response Code |
| | | |
| 2001 | Request syntax invalid. | Overall Response Code |
| | | |
| 2002 | Request too large. | Overall Response Code |
| | | |
| 2003 | Version not supported. | Overall Response Code |
| | | |
| 2103 | Command invalid. | Overall Response Code |
| | | |
| 2301 | System temporarily | Overall Response Code |
| | unavailable. | |
| | | |
| 2302 | Unexpected internal | Overall Response Code |
| | system or server error. | |
| | | |
| 2104 | Attribute value invalid. | Object Level Response Code |
| | | |
| | AttrName:[AttributeName] | |
| | AttrVal:[AttributeValue] | |
| | | |
| 2105 | Object does not exist. | Object Level Response Code |
| | AttrName:[AttributeName] | |
| | AttrVal:[AttributeValue] | |
| | | |
| 2106 | Object status or | Object Level Response Code |
| | ownership does not allow | |
| | for operation. | |
| | AttrName:[AttributeName] | |
| | AttrVal:[AttributeValue] | |
+--------+--------------------------+-------------------------------+
Table 1: Response Codes Numbering Scheme and Messages
Each of the object level response messages are "parameterized" with
the following parameters: "AttributeName" and "AttributeValue".
The use of these parameters MUST adhere to the following rules:
o All parameters within a response message are mandatory and MUST
be present.
o Any value provided for the "AttributeName" parameter MUST be an
exact XSD element name of the protocol data element that the
Cartwright Expires May 3, 2012 [Page 18]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
response message is referring to. For example, valid values for
"attribute name" are "dgName", "rgName", "rteRec", etc.
o The value for "AttributeValue" MUST be the value of the data
element to which the preceding "AttributeName" refers.
o Result code 2104 SHOULD be used whenever an element value does
not adhere to data validation rules.
o Result codes 2104 and 2105 MUST NOT be used interchangeably.
Response code 2105 SHOULD be returned by an update operation
when the data element(s) used to uniquely identify a pre-
existing object do not exist. If the data elements used to
uniquely identify an object are malformed, then response code
2104 SHOULD be returned.
Cartwright Expires May 3, 2012 [Page 19]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
7. Protocol Operations
This section provides a description of the specification of each
required operation (verb) for each SPPP data model object (the noun).
The specification of the data structures for the data model objects
is contianed in the protocol specification.
7.1. Add Destination Group Operation
The AddDestGrpRqstType operation creates or overwrites a Destination
Group object. If a Destination Group with the given name and
registrant ID (which together comprise the unique key for a
Destination Group) does not exist, then the server MUST create the
Destination Group. If a Destination Group with the given name and
registrant ID does exist, then the server MUST replace the current
properties of the Destination Group with the properties passed into
the AddDestGrpsRqstType operation. The XSD declarations of the
operation request object are as follows:
<complexType name="AddDestGrpRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="destGrp" type="spppb:DestGrpType"/>
</sequence>
</extension>
</complexContent>
</complexType>
The element passed into the spppUpdateRequest element for this
operation is an element of type AddDestGrpRqsttype, which extends
BasicUpdateRqstType and contains a DestGrpType object.
As with the responses to all update operations, the result of the
AddDestGrpRqstType operation is contained in the generic
spppUpdateResponse data structure described in an earlier sections of
this document. For a detailed description of the spppUpdateResponse
data structure refer to that section of the document.
7.2. Get Destination Groups Operation
The getDestGrpsRqst operation allows an SPPP client to get the
properties of Destination Group objects that a registrar is
authorized to view on behalf of the registrant. The server will
attempt to find a Destination Group object that has the registrant ID
Cartwright Expires May 3, 2012 [Page 20]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
and destination group name pair contained in each ObjKeyType object
instance. If there are no matching Destination Groups found then an
empty result set will be returned.
The element passed into the spppQueryRequest element for this
operation is an instance of type GetDestGrpsRqstType, which extends
BasicQueryRqstType and contains zero or more ObjKeyType objects. Any
limitation on the maximum number of objects that may be passed into
or returned by this operation is a policy decision and not limited by
the protocol. The XSD declaration of the operation is as follows:
<complexType name="GetDestGrpsRqstType">
<complexContent>
<extension base="spppb:BasicQueryRqstType">
<sequence>
<element name="objKey" type="spppb:ObjKeyType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
As described in an earlier section of this document, the result of
any spppQueryRequest operation is an spppQueryResponse element that
contains the overall response code and the query result set, if any.
Refer to that section of the document for a detailed description of
the spppQueryResponse element.
7.3. Add Public Identifier Operation
The AddPubIdRqstType operation creates or overwrites a Public
Identifier object of any of the concrete types specified in the
protocol data model specification. If a Public Identifier with the
given identity (refer to the data model specification for the
definition of how Public Identifiers are uniquely identified) does
not exist, then the server MUST create the Public Identifier. If a
Public Identifier with the given identity does exist, then the server
MUST replace the current properties of that Public Identifier with
the properties passed into the AddPubIdRqstType operation. The XSD
declarations of the operation request object are as follows:
Cartwright Expires May 3, 2012 [Page 21]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<complexType name="AddPubIdRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="pi" type="spppb:PubIdType"/>
</sequence>
</extension>
</complexContent>
</complexType>
7.4. Get Public Identifiers Operation
The GetPubIdsRqstType operation allows an SPPP client to get the
properties of Public Identifier objects that a registrar is
authorized to view on behalf of the registrant. The server will
attempt to find a Public Identifier object that has the properties of
the Public Identifier object passed into this operation. If there
are no matching Public Identifiers found then an empty result set
will be returned.
The element passed into the spppQueryRequest element for this
operation is an instance of type GetPubIdsRqstType, which extends
BasicQueryRqstType and contains one or more PubIDType objects. Any
limitation on the maximum number of objects that may be passed into
or returned by this operation is a policy decision and not limited by
the protocol. The XSD declaration of the operation is as follows:
<complexType name="GetPubIdsRqstType">
<complexContent>
<extension base="spppb:BasicQueryRqstType">
<sequence>
<element name="pi" type="spppb:PubIdType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
As described earlier in the document, the result of any
spppQueryRequest operation is a spppQueryResponse that contains the
response code and the query result set, if any.
Cartwright Expires May 3, 2012 [Page 22]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
7.5. Add Route Group Operation
The AddRteGrpRqstType operation creates or overwrites a Route Group
object. If a Route Group with the given name and registrant ID
(which together comprise the unique key or a Route Group) does not
exist, then the server MUST create the Route Group. If a Route Group
with the given name and registrant ID does exist, then the server
MUST replace the current properties of the Route Group with the
properties passed into the AddRteGrpRqstType operation. The XSD
declarations of the AddRteGrpRqstType operation request object are as
follows:
<complexType name="AddRteGrpRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="rteGrp" type="spppb:RteGrpType"/>
</sequence>
</extension>
</complexContent>
</complexType>
The element passed into the spppUpdateRequest element for this
operation is an instance of AddRteGrpRqstType, which extends
BasicUpdateRqstType and contains one RteGrpType object.
7.6. Get Route Groups Operation
The getRteGrpsRqst operation allows an SPPP client to get the
properties of Route Group objects that the registrar is authorized to
view on behalf of the registrant. The server will attempt to find a
Route Group object that has the registrant ID and route group name
pair contained in each ObjKeyType object instance passed into this
operation. If there are no matching Route Groups found then an empty
result set will be returned.
The element passed into the spppQueryRequest element for this
operation is an instance of type GetRteGrpsRqstType, which extends
BasicUpdateRqstType and contains zero or more ObjKeyType objects.
Any limitation on the maximum number of objects that may be passed
into or returned by this operation is a policy decision and not
limited by the protocol. The XSD declaration of the operation is as
follows:
Cartwright Expires May 3, 2012 [Page 23]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<complexType name="GetRteGrpsRqstType">
<complexContent>
<extension base="spppb:BasicQueryRqstType">
<sequence>
<element name="objKey" type="spppb:ObjKeyType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
As described in an earlier section of this document, the result of
any spppQueryRequest operation is an spppQueryResponse element that
contains the overall response code and the query result set, if any.
Refer to that section of the document for a detailed description of
the spppQueryResponse element.
7.7. Add Route Record Operation
The AddRteRecRqstType operation creates or overwrites a Route Record
object. If a Route Record with the given name and registrant ID
(which together comprise the unique key or a Route Record) does not
exist, then the server MUST create the Route Record. If a Route
Record with the given name and registrant ID does exist, then the
server MUST replace the current properties of the Route Record with
the properties passed into the AddRteRecRqstType operation. The XSD
declarations of the AddRteRecRqstType operation request object are as
follows:
<complexType name="AddRteRecRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="rteRec" type="spppb:RteRecType"/>
</sequence>
</extension>
</complexContent>
</complexType>
The element passed into the spppUpdateRequest element for this
operation is an instance of AddRteRecRqstType, which extends
BasicUpdateRqstType and contains one RteRecType object.
As with the responses to all update operations, the result of the
Cartwright Expires May 3, 2012 [Page 24]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
AddRteRecRqstType operation is contained in the generic
spppUpdateResponse data structure described in an earlier sections of
this document. For a detailed description of the spppUpdateResponse
data structure refer to that section of the document.
7.8. Get Route Records Operation
The getRteRecsRqst operation allows an SPPP client to get the
properties of Route Record objects that a registrar is authorized to
view on behalf of the registrant. The server will attempt to find a
Route Record object that has the registrant ID and route record name
pair contained in each ObjKeyType object instance. If there are no
matching Route Record found then an empty result set will be
returned.
The element passed into the spppQueryRequest element for this
operation is an instance of type GetRteRecsRqstType, which extends
BasicUpdateRqstType and contains zero or more ObjKeyType objects.
Any limitation on the maximum number of objects that may be passed
into or returned by this operation is a policy decision and not
limited by the protocol. The XSD declaration of the operation is as
follows:
<complexType name="GetRteRecsRqstType">
<complexContent>
<extension base="spppb:BasicQueryRqstType">
<sequence>
<element name="objKey" type="spppb:ObjKeyType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
As described in an earlier section of this document, the result of
any spppQueryRequest operation is an spppQueryResponse element that
contains the overall response code and the query result set, if any.
Refer to that section of the document for a detailed description of
the spppQueryResponse element.
7.9. Add Route Group Offer Operation
The AddRteGrpOffersRqstType operation creates or overwrites one or
more Route Group Offer objects. If a Route Group Offer for the given
Route Group object key and the <offeredTo> Org ID does not exist,
Cartwright Expires May 3, 2012 [Page 25]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
then the server creates the Route Group Offer object. If a such a
Route Group Offer does exist, then the server replaces the current
object with the new object. The XSD declarations of the operation
request object are as follows:
<complexType name="AddRteGrpOfferRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="rteGrpOffer" type="spppb:RteGrpOfferType"/>
</sequence>
</extension>
</complexContent>
</complexType>
The element passed into the spppUpdateRequest element for this
operation is an instance of AddRteGrpOfferRqstType, which extends
BasicUpdateRqstType and contains a RteGrpOfferType object.
As with the responses to all update operations, the result of the
AddRteGrpOfferRqstType operation is contained in the generic
spppUpdateResponse data structure described in an earlier sections of
this document. For a detailed description of the spppUpdateResponse
data structure refer to that section of the document.
7.10. Accept Route Group Offer Operation
The AcceptRteGrpOffersRqstType operation is called by, or on behalf
of, the data recipient to accept a Route Group Offer that is pending
in the "offered" status for the data recipient's organization ID. If
a Route Group Offer for the given Route Group Offer key (route name,
route registrant ID, data recipient's organization ID) exists, then
the server moves the Route Group Offer to the "accepted" status and
adds that data recipient's organization ID into the list of
peerOrgIds for that Route Group. If a such a Route Group Offer does
not exist, then the server returns the appropriate error code, 2105.
The XSD declarations for the operation request object are as follows:
Cartwright Expires May 3, 2012 [Page 26]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<complexType name="AcceptRteGrpOfferRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="rteGrpOfferKey" type="spppb:RteGrpOfferKeyType"/>
</sequence>
</extension>
</complexContent>
</complexType>
The element passed into the spppUpdateRequest element for this
operation is an instance of AcceptRteGrpOffersRqstType, which extends
BasicUpdateRqstType and contains a RteGrpOfferKeyType object.
As with the responses to all update operations, the result of the
AcceptRteGrpOfferRqstType operation is contained in the generic
spppUpdateResponse data structure described in an earlier sections of
this document. For a detailed description of the spppUpdateResponse
data structure refer to that section of the document.
7.11. Reject Route Group Offer Operation
The RejectRteGrpOffersRqstType operation is used for these purposes
and is called by, or on behalf of, the data recipient to accept a
Route Group Offer that is pending in the "offered" status or is in
the "accepted" status for the data recipient's organization ID. If a
Route Group Offer for the given Route Group Offer key (route name,
route registrant ID, data recipient's organization ID) exists in
either the offered or accepted status, then the server deletes that
Route Group Offer object, and, if appropriate, removes the data
recipient's organization ID from the list of peeringOrg IDs for that
Route Group. If the Route Group Offer does not exist, then the
server returns the appropriate error code, 2105. The XSD
declarations for the operation request object are as follows:
<complexType name="RejectRteGrpOfferRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="rteGrpOfferKey" type="spppb:RteGrpOfferKeyType"/>
</sequence>
</extension>
</complexContent>
</complexType>
Cartwright Expires May 3, 2012 [Page 27]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
The element passed into the spppUpdateRequest element for this
operation is an instance of RejectRteGrpOffersRqstType, which extends
BasicUpdateRqstType and contains a RteGrpOfferKeyType object.
As with the responses to all update operations, the result of the
RejectRteGrpOfferRqstType operation is contained in the generic
spppUpdateResponse data structure described in an earlier sections of
this document. For a detailed description of the spppUpdateResponse
data structure refer to that section of the document.
7.12. Get Route Group Offers Operation
The getRteGrpOffersRqst operation allows an SPPP client to get the
properties of zero or more Route Group Offer objects that registrar
is authorized to view on behalf of the registrant. The server will
attempt to find Route Group Offer objects that have all the
properties specified in the criteria passed into the operation. If
there are no matching Route Group Offers found then an empty result
set will be returned.
The element passed into the spppQueryRequest element for this
operation is an instance of GetRteGrpOffersRqstType, which extends
BasicQueryRqstType and contains the criteria that the returned Route
Group Offer objects must match. Any limitation on the maximum number
of objects that may be returned by this operation is a policy
decision and not limited by the protocol. The XSD declaration of the
operation is as follows:
<complexType name="GetRteGrpOffersRqstType">
<complexContent>
<extension base="spppb:BasicQueryRqstType">
<sequence>
<element name="offeredBy" type="spppb:OrgIdType"
minOccurs="0" maxOccurs="unbounded"/>
<element name="offeredTo" type="spppb:OrgIdType"
minOccurs="0" maxOccurs="unbounded"/>
<element name="status" type="spppb:RteGrpOfferStatusType"
minOccurs="0"/>
<element name="rteGrpOfferKey"
type="spppb:RteGrpOfferKeyType" minOccurs="0"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
Cartwright Expires May 3, 2012 [Page 28]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
The GetRteGrpOffersRqstType object is composed of the following
elements:
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.
o rteGrpOfferKey: Zero or more Route 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.
As described in an earlier section of this document, the result of
any spppQueryRequest operation is an spppQueryResponse element that
contains the overall response code and the query result set, if any.
Refer to that section of the document for a detailed description of
the spppQueryResponse element.
7.13. Add Egress Route Operation
The AddEgrRteRqstType operation creates or overwrites an Egress Route
object. If an Egress Route with the given name and registrant ID
(which together comprise the unique key or an Egress Route) does not
exist, then the server MUST create the Route Record. If a Route
Record with the given name and registrant ID does exist, then the
server MUST replace the current properties of the Route Record with
the properties passed into the AddEgrRteRqstType operation. The XSD
declarations of the AddEgrRteRqstType operation request object are as
follows:
Cartwright Expires May 3, 2012 [Page 29]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<complexType name="AddEgrRteRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="egrRte" type="spppb:EgrRteType"/>
</sequence>
</extension>
</complexContent>
</complexType>
The element passed into the spppUpdateRequest element for this
operation is an instance of AddEgrRteRqstType, which extends
BasicUpdateRqstType and contains one EgrRteType object.
As with the responses to all update operations, the result of the
AddEgrRteRqstType operation is contained in the generic
spppUpdateResponse data structure described in an earlier sections of
this document. For a detailed description of the spppUpdateResponse
data structure refer to that section of the document.
7.14. Get Egress Routes Operation
The GetEgrRtesRqstType operation allows an SPPP client to get the
properties of Egress Route objects that a registrar is authorized to
view on behalf of the registrant. The server will attempt to find a
Egress Route object that has the registrant ID and Egress Route name
pair contained in each ObjKeyType object instance. If there are no
matching Egress Routes found then an empty result set will be
returned.
The element passed into the spppQueryRequest element for this
operation is an instance of type GetEgrRtesRqstType, which extends
BasicUpdateRqstType and contains zero or more ObjKeyType objects.
Any limitation on the maximum number of objects that may be passed
into or returned by this operation is a policy decision and not
limited by the protocol. The XSD declaration of the operation is as
follows:
Cartwright Expires May 3, 2012 [Page 30]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<complexType name="GetEgrRtesRqstType">
<complexContent>
<extension base="spppb:BasicQueryRqstType">
<sequence>
<element name="objKey" type="spppb:ObjKeyType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
As described in an earlier section of this document, the result of
any spppQueryRequest operation is an spppQueryResponse element that
contains the overall response code and the query result set, if any.
Refer to that section of the document for a detailed description of
the spppQueryResponse element.
7.15. Delete Operation
In order to remove an object from the registry, an authorized entity
can send the <spppUpdateRequest> to the registry with a corresponding
delete BasicUpdateRqstType object. Each 'Add' operation in SPPP has
a corresponding 'Del' operation, which is used to delete the
respective object type from the registry. If the entity that issued
the command is not authorized to perform this operation an
appropriate error code will be returned in the <spppUpdateRespnonse>
message.
As an example, DelPubIdRqstType is used to delete Public Identifiers
The DelPubIdsRqstType object definition is shown below:
<complexType name="DelPubIdRqstType">
<complexContent>
<extension base="spppb:BasicUpdateRqstType">
<sequence>
<element name="pi" type="spppb:PubIdType"/>
</sequence>
</extension>
</complexContent>
</complexType>
When an object is deleted, any references to that object must of
course also be removed as the SPPP server implementation fulfills the
deletion request. Furthermore, the deletion of a composite object
Cartwright Expires May 3, 2012 [Page 31]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
must also result in the deletion of the objects it contains. As a
result, the following rules apply to the deletion of SPPP object
types:
o Destination Groups: When a destination group is deleted all
public identifiers within that destination group must also be
automatically deleted by the SPPP implementation as part of
fulfilling the deletion request. And any references between
that destination group and any route group must be automatically
removed by the SPPP implementation as part of fulfilling the
deletion request.
o Route Groups: When a route group is deleted any references
between that route group and any destination group must be
automatically removed by the SPPP implementation as part of
fulfilling the deletion request. Similarly any references
between that route group and any route records must be removed
by the SPPP implementation as part of fulfilling the deletion
request. Furthermore, route group offers relating that route
group must also be deleted as part of fulfilling the deletion
request.
o Route Records: When a route record is deleted any references
between that route record and any route group must be removed by
the SPPP implementation as part of fulfilling the deletion
request.
o Public Identifiers: When a public identifier is deleted any
references between that public identifier and its containing
destination group must be removed by the SPPP implementation as
part of fulfilling the deletion request. And any route records
contained directly within that Public Identifier must be deleted
by the SPPP implementation as part of fulfilling the deletion
request.
Cartwright Expires May 3, 2012 [Page 32]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
8. SPPP SOAP WSDL Definition
The SPPP 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 SPPP protocol. There is a
single WSDL update operation called submitUpdateRqst, and a single
WSDL query operation called submitQueryRqst. The submitUpdateRqst
operation takes as input an spppUpdateRequestMsg object and returns
as output an spppUpdateResponseMsg object. These objects _wrap_ the
spppUpdateRequest and spppUpdateResponse objects respectively. And
finally, 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.
Note: The following WSDL has been formatted (e.g., tabs, spaces) to
meet I-D requirements.
<?xml version="1.0" encoding="UTF-8"?>
<wsdl:definitions
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:spppb="urn:ietf:params:xml:ns:sppp:base:1"
xmlns:sppps="urn:ietf:params:xml:ns:sppp:soap:1"
targetNamespace="urn:ietf:params:xml:ns:sppp:soap:1">
<wsdl:types>
<xsd:schema
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:sppps="urn:ietf:params:xml:ns:sppp:soap:1"
targetNamespace="urn:ietf:params:xml:ns:sppp:soap:1">
<annotation>
<documentation>
---- Import base schema ----
</documentation>
</annotation>
<import namespace="urn:ietf:params:xml:ns:sppp:base:1"
schemaLocation="spppbase.xsd"/>
<annotation>
<documentation>
---- Key type(s) extended from base schema ----
</documentation>
Cartwright Expires May 3, 2012 [Page 33]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
</annotation>
<complexType name="ObjKeyType">
<complexContent>
<extension base="spppb:ObjKeyType">
<sequence>
<element name="rant" type="spppb:OrgIdType"/>
<element name="name" type="spppb:ObjNameType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="RteGrpOfferKeyType">
<complexContent>
<extension base="spppb:RteGrpOfferKeyType">
<sequence>
<element name="rteGrpKey"
type="sppps:ObjKeyType"/>
<element name="offeredTo"
type="spppb:OrgIdType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<annotation>
<documentation>
---- Base Request Type Definitions ----
</documentation>
</annotation>
<complexType name="BasicUpdateRqstType"
abstract="true">
<sequence>
<element name="ext" type="spppb:ExtAnyType"
minOccurs="0"/>
</sequence>
</complexType>
<complexType name="BasicQueryRqstType" abstract="true">
<sequence>
<element name="ext" type="spppb:ExtAnyType"
minOccurs="0"/>
</sequence>
</complexType>
<annotation>
<documentation>
-- Request Type definition for various SPPP Objects. --
</documentation>
</annotation>
<complexType name="AddRteGrpRqstType">
<complexContent>
Cartwright Expires May 3, 2012 [Page 34]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="rteGrp" type="spppb:RteGrpType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="DelRteGrpRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="rteGrpKey"
type="sppps:ObjKeyType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="GetRteGrpsRqstType">
<complexContent>
<extension base="sppps:BasicQueryRqstType">
<sequence>
<element name="rteGrpKey"
type="sppps:ObjKeyType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="AddRteRecRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="rteRec"
type="spppb:RteRecType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="DelRteRecRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="rteRecKey"
type="sppps:ObjKeyType"/>
</sequence>
</extension>
</complexContent>
</complexType>
Cartwright Expires May 3, 2012 [Page 35]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<complexType name="GetRteRecsRqstType">
<complexContent>
<extension base="sppps:BasicQueryRqstType">
<sequence>
<element name="rteRecKey"
type="sppps:ObjKeyType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="AddDestGrpRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="destGrp"
type="spppb:DestGrpType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="DelDestGrpRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="destGrpKey"
type="sppps:ObjKeyType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="GetDestGrpsRqstType">
<complexContent>
<extension base="sppps:BasicQueryRqstType">
<sequence>
<element name="destGrpKey"
type="sppps:ObjKeyType"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="AddPubIdRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="pi" type="spppb:PubIdType"/>
</sequence>
Cartwright Expires May 3, 2012 [Page 36]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
</extension>
</complexContent>
</complexType>
<complexType name="DelPubIdRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="pi" type="spppb:PubIdType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="GetPubIdsRqstType">
<complexContent>
<extension base="sppps:BasicQueryRqstType">
<sequence>
<element name="pi" type="spppb:PubIdType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="AddRteGrpOfferRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="rteGrpOffer"
type="spppb:RteGrpOfferType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="DelRteGrpOfferRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="rteGrpOfferKey"
type="sppps:RteGrpOfferKeyType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="AcceptRteGrpOfferRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="rteGrpOfferKey"
type="sppps:RteGrpOfferKeyType"/>
Cartwright Expires May 3, 2012 [Page 37]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="RejectRteGrpOfferRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="rteGrpOfferKey"
type="sppps:RteGrpOfferKeyType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="GetRteGrpOffersRqstType">
<complexContent>
<extension base="sppps:BasicQueryRqstType">
<sequence>
<element name="offeredBy"
type="spppb:OrgIdType"
minOccurs="0" maxOccurs="unbounded"/>
<element name="offeredTo"
type="spppb:OrgIdType"
minOccurs="0" maxOccurs="unbounded"/>
<element name="status"
type="spppb:RteGrpOfferStatusType"
minOccurs="0"/>
<element name="rteGrpOfferKey"
type="sppps:RteGrpOfferKeyType"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="AddEgrRteRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
<element name="egrRte"
type="spppb:EgrRteType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="DelEgrRteRqstType">
<complexContent>
<extension base="sppps:BasicUpdateRqstType">
<sequence>
Cartwright Expires May 3, 2012 [Page 38]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<element name="egrRteKey"
type="sppps:ObjKeyType"/>
</sequence>
</extension>
</complexContent>
</complexType>
<complexType name="GetEgrRtesRqstType">
<complexContent>
<extension base="sppps:BasicQueryRqstType">
<sequence>
<element name="egrRteKey"
type="sppps:ObjKeyType"
maxOccurs="unbounded"/>
</sequence>
</extension>
</complexContent>
</complexType>
<annotation>
<documentation>
--- Generic Request and Response Definitions ----
</documentation>
</annotation>
<element name="spppUpdateRequest">
<complexType>
<sequence>
<element name="clientTransId"
type="spppb:TransIdType" minOccurs="0"/>
<element name="minorVer"
type="spppb:MinorVerType"
minOccurs="0"/>
<element name="rqst"
type="sppps:BasicUpdateRqstType"
maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
<element name="spppUpdateResponse">
<complexType>
<sequence>
<element name="clientTransId"
type="spppb:TransIdType" minOccurs="0"/>
<element name="serverTransId"
type="spppb:TransIdType"/>
<element name="overallResult"
type="sppps:ResultCodeType"/>
<element name="rqstObjResult"
type="sppps:RqstObjResultCodeType" minOccurs="0"
maxOccurs="unbounded"/>
Cartwright Expires May 3, 2012 [Page 39]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
</sequence>
</complexType>
</element>
<element name="spppQueryRequest">
<complexType>
<sequence>
<element name="minorVer"
type="spppb:MinorVerType"
minOccurs="0"/>
<element name="rqst"
type="sppps:BasicQueryRqstType"/>
</sequence>
</complexType>
</element>
<element name="spppQueryResponse">
<complexType>
<sequence>
<element name="overallResult"
type="sppps:ResultCodeType"/>
<element name="resultSet"
type="spppb:BasicObjType"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
<element name="spppServerStatusRequest">
<complexType>
<sequence>
<element name="minorVer"
type="spppb:MinorVerType"
minOccurs="0"/>
</sequence>
</complexType>
</element>
<element name="spppServerStatusResponse">
<complexType>
<sequence>
<element name="overallResult"
type="sppps:ResultCodeType"/>
<element name="svcMenu"
type="spppb:SvcMenuType"/>
</sequence>
</complexType>
</element>
<annotation>
<documentation>
--- Operation Result Type Definitions ----
</documentation>
Cartwright Expires May 3, 2012 [Page 40]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
</annotation>
<complexType name="ResultCodeType">
<sequence>
<element name="code" type="int"/>
<element name="msg" type="token"/>
</sequence>
</complexType>
<complexType name="RqstObjResultCodeType">
<complexContent>
<extension base="sppps:ResultCodeType">
<sequence>
<element name="rqstObj"
type="sppps:BasicUpdateRqstType"/>
</sequence>
</extension>
</complexContent>
</complexType>
</xsd:schema>
</wsdl:types>
<wsdl:message name="spppUpdateRequestMsg">
<wsdl:part name="rqst"
element="sppps:spppUpdateRequest"/>
</wsdl:message>
<wsdl:message name="spppUpdateResponseMsg">
<wsdl:part name="rspns"
element="sppps:spppUpdateResponse"/>
</wsdl:message>
<wsdl:message name="spppQueryRequestMsg">
<wsdl:part name="rqst" element="sppps:spppQueryRequest"/>
</wsdl:message>
<wsdl:message name="spppQueryResponseMsg">
<wsdl:part name="rspns"
element="sppps:spppQueryResponse"/>
</wsdl:message>
<wsdl:message name="spppServerStatusRequestMsg">
<wsdl:part name="rqst"
element="sppps:spppServerStatusRequest"/>
</wsdl:message>
<wsdl:message name="spppServerStatusResponseMsg">
<wsdl:part name="rspns"
element="sppps:spppServerStatusResponse"/>
</wsdl:message>
<wsdl:portType name="spppPortType">
<wsdl:operation name="submitUpdateRqst">
<wsdl:input message="sppps:spppUpdateRequestMsg"/>
<wsdl:output
message="sppps:spppUpdateResponseMsg"/>
Cartwright Expires May 3, 2012 [Page 41]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
</wsdl:operation>
<wsdl:operation name="submitQueryRqst">
<wsdl:input message="sppps:spppQueryRequestMsg"/>
<wsdl:output message="sppps:spppQueryResponseMsg"/>
</wsdl:operation>
<wsdl:operation name="submitServerStatusRqst">
<wsdl:input
message="sppps:spppServerStatusRequestMsg"/>
<wsdl:output
message="sppps:spppServerStatusResponseMsg"/>
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="spppSoapBinding"
type="sppps:spppPortType">
<soap:binding style="document"
transport="http://schemas.xmlsoap.org/soap/http"/>
<wsdl:operation name="submitUpdateRqst">
<soap:operation soapAction="submitUpdateRqst"
style="document"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="submitQueryRqst">
<soap:operation soapAction="submitQueryRqst"
style="document"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
<wsdl:operation name="submitServerStatusRqst">
<soap:operation
soapAction="submitServerStatusRqst"
style="document"/>
<wsdl:input>
<soap:body use="literal"/>
</wsdl:input>
<wsdl:output>
<soap:body use="literal"/>
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
Cartwright Expires May 3, 2012 [Page 42]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<wsdl:service name="spppService">
<wsdl:port name="spppPort"
binding="sppps:spppSoapBinding">
<soap:address location="REPLACE_WITH_ACTUAL_URL"/>
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
Figure 2: WSDL
Cartwright Expires May 3, 2012 [Page 43]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
9. SPPP SOAP Examples
This section provides a few examples of SPPP SOAP messages. This
section of course relies on the XML data structures defined in the
SPPP protocol specification [I-D.draft-ietf-drinks-spprov]. So refer
to that document to understand XML object types embedded in these
example messages.
Note: The following examples have been formatted (e.g., tabs, spaces)
to meet I-D requirements.
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:spb="urn:ietf:params:xml:ns:sppp:base:1">
<soapenv:Header/>
<soapenv:Body>
<spb:spppUpdateRequest
xsi:schemaLocation="urn:ietf:params:xml:ns:sppp:base:1 sppp.xsd"
xmlns="urn:ietf:params:xml:ns:sppp:base:1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<spb:clientTransId>888</spb:clientTransId>
<spb:minorVer>1</spb:minorVer>
<spb:rqst xsi:type="spb:AddDestGrpRqstType">
<spb:destGrp>
<spb:rant>registrant2</spb:rant>
<spb:dgName>DEST_GRP_SPPP_5</spb:dgName>
</spb:destGrp>
</spb:rqst>
</spb:spppUpdateRequest>
</soapenv:Body>
</soapenv:Envelope>
Figure 3: Example 1 - SPPP Update Request - Add Destination Group
Cartwright Expires May 3, 2012 [Page 44]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:spb="urn:ietf:params:xml:ns:sppp:base:1">
<soapenv:Header/>
<soapenv:Body>
<spb:spppQueryRequest
xsi:schemaLocation="urn:ietf:params:xml:ns:sppp:base:1 sppp.xsd"
xmlns="urn:ietf:params:xml:ns:sppp:base:1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<spb:minorVer>1</spb:minorVer>
<spb:rqst xsi:type="spb:GetDestGrpsRqstType">
<spb:objKey>
<spb:rant>registrant2</spb:rant>
<spb:name>DEST_GRP_SPPP_5</spb:name>
</spb:objKey>
</spb:rqst>
</spb:spppQueryRequest>
</soapenv:Body>
</soapenv:Envelope>
Figure 4: Example 2 - SPPP Query Request - Get Destination Group
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:spb="urn:ietf:params:xml:ns:sppp:base:1">
<soapenv:Header/>
<soapenv:Body>
<spb:spppQueryRequest
xsi:schemaLocation="urn:ietf:params:xml:ns:sppp:base:1 sppp.xsd"
xmlns="urn:ietf:params:xml:ns:sppp:base:1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<spb:clientTransId>999</spb:clientTransId>
<spb:minorVer>1</spb:minorVer>
<spb:rqst xsi:type="spb:DelDestGrpRqstType">
<spb:objKey>
<spb:rant>registrant2</spb:rant>
<spb:name>DEST_GRP_SPPP_5</spb:name>
</spb:objKey>
</spb:rqst>
</spb:spppQueryRequest>
</soapenv:Body>
</soapenv:Envelope>
Figure 5: Example 2 - SPPP Query Request - Del Destination Group
Cartwright Expires May 3, 2012 [Page 45]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
10. Security Considerations
SPPP 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]. SPPP data may include sensitive
information, routing data, lists of resolvable addresses, etc. So
when used in a production setting and across non-secure networks,
SPPP should only be used over communications channels that provide
strong encryption for data privacy.
10.1. Integrity, Privacy, and Authentication
The SPPP SOAP binding relies on an underlying secure transport for
integrity and privacy. Such transports are expected to include TLS/
HTTPS. In addition to the application level authentication imposed
by an SPPP server, there are a number of options for authentication
within the transport layer and the messaging envelope. These include
TLS client certificates, HTTP Digest Access Authentication, and
digital signatures within SOAP headers.
At a miniumum, all conforming SPPP over SOAP implementations MUST
support HTTPS.
10.2. Vulnerabilities
The above protocols may have various vulnerabilities, and these may
be inherited by SPPP over SOAP. And SPPP itself may have
vulnerabilities because an authorization model is not explicitly
specified in the current specification.
It is important that SPPP implementations implement an authorization
model that considers the source of each SPPP query or update request
and determines whether it is reasonable to authorize that source to
perform that specific query or update.
10.3. Deployment Environment Specifics
Some deployments of SPPP over SOAP 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 over SPPP
messages in this type of deployment.
Cartwright Expires May 3, 2012 [Page 46]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
11. IANA Considerations
This document uses URNs to describe XML namespaces and XML schemas
conforming to a registry mechanism described in [RFC3688].
URN assignments are requested: urn:ietf:params:xml:ns:sppp:soap
Cartwright Expires May 3, 2012 [Page 47]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
12. Acknowledgements
This document is a result of various discussions held by the DRINKS
design team, which is comprised of the following individuals, in no
specific order: Syed Ali (NeuStar), Sumanth Channabasappa (Cable
Labs), David Schwartz (XConnect), Jean-Francois Mule (CableLabs),
Kenneth Cartwright (TNS, Inc.), Manjul Maharishi (TNS, Inc.),
Alexander Mayrhofer (enum.at GmbH).
Cartwright Expires May 3, 2012 [Page 48]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
13. References
13.1. Normative References
[I-D.draft-ietf-drinks-spprov]
Mule, J-F., Cartwright, K., Ali, S., and A. Mayrhofer,
"DRINKS Use cases and Protocol Requirements",
draft-ietf-drinks-spprov-09 (work in progress), June 2011.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[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.
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
Leach, P., Luotonen, A., and L. Stewart, "HTTP
Authentication: Basic and Digest Access Authentication",
RFC 2617, June 1999.
[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.
[SOAPREF] Gudgin, M., Hadley, M., Moreau, J., and H. Nielsen, "SOAP
Version 1.2 Part 1: Messaging Framework", W3C
Recommendation REC-SOAP12-part1-20030624, June 2002.
13.2. Informative References
[RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000.
[RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321,
October 2008.
[WSDLREF] Christensen, E., Curbera, F., Meredith, G., and S.
Weerawarana, "Web Services Description Language (WSDL)
1.1", W3C Note NOTE-wsdl-20010315, March 2001.
Cartwright Expires May 3, 2012 [Page 49]
Internet-Draft draft-ietf-drinks-sppp-over-soap October 2011
Author's Address
Kenneth Cartwright
TNS
1939 Roland Clarke Place
Reston, VA 20191
USA
Email: kcartwright@tnsi.com
Cartwright Expires May 3, 2012 [Page 50]
