--- 1/draft-ietf-drinks-spp-protocol-over-soap-03.txt 2013-07-12 02:15:25.260893731 -0700 +++ 2/draft-ietf-drinks-spp-protocol-over-soap-04.txt 2013-07-12 02:15:25.388897036 -0700 @@ -1,202 +1,204 @@ DRINKS K. Cartwright Internet-Draft V. Bhatia Intended status: Standards Track TNS -Expires: April 26, 2013 J-F. Mule +Expires: January 13, 2014 J-F. Mule CableLabs A. Mayrhofer enum.at GmbH - October 23, 2012 + July 12, 2013 Session Peering Provisioning (SPP) Protocol over SOAP - draft-ietf-drinks-spp-protocol-over-soap-03 + draft-ietf-drinks-spp-protocol-over-soap-04 Abstract - The Session Peering Provisioning Framework (SPPF) is an XML framework - that exists to enable the provisioning of session establishment data - into Session Data Registries or SIP Service Provider data stores. - 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 protocol for SPPF 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 - SPPF XML structures over SOAP and HTTP(s). + The Session Peering Provisioning Framework (SPPF) specifies the data + model and the overall structure to provision session establishment + data into Session Data Registries and SIP Service Provider data + stores. To utilize this framework one needs a transport protocol. + Given that 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 + transport 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 +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 April 26, 2013. + This Internet-Draft will expire on January 13, 2014. Copyright Notice - Copyright (c) 2012 IETF Trust and the persons identified as the + Copyright (c) 2013 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. Table of Contents - 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 3. SOAP Features and Protocol Layering . . . . . . . . . . . . . 6 - 4. HTTP(s) Features and SPP Protocol over SOAP . . . . . . . . . 9 - 5. Authentication, Integrity and Confidentiality . . . . . . . . 10 - 6. Language Identification . . . . . . . . . . . . . . . . . . . 11 - 7. SPP Protocol SOAP Data Structures . . . . . . . . . . . . . . 12 - 7.1. Concrete Object Key Types . . . . . . . . . . . . . . . . 12 - 7.1.1. Generic Object Key . . . . . . . . . . . . . . . . . . 12 - 7.1.2. Public Identity Object Key . . . . . . . . . . . . . . 13 - 7.1.3. SED Group Offer Key . . . . . . . . . . . . . . . . . 14 - 7.2. Operation Request and Response Structures . . . . . . . . 15 - 7.2.1. Add Operation Structure . . . . . . . . . . . . . . . 15 - 7.2.2. Delete Operation Structure . . . . . . . . . . . . . . 18 - 7.2.3. Accept Operation Structure . . . . . . . . . . . . . . 21 - 7.2.4. Reject Operation Structure . . . . . . . . . . . . . . 24 - 7.2.5. Batch Operation Structure . . . . . . . . . . . . . . 27 - 7.2.6. Get Operation Structure . . . . . . . . . . . . . . . 30 - 7.2.7. Get SED Group Offers Operation Structure . . . . . . . 32 - 7.2.8. Generic Query Response . . . . . . . . . . . . . . . . 33 - 7.2.9. Get Server Details Operation Structure . . . . . . . . 34 - 7.3. Response Codes and Messages . . . . . . . . . . . . . . . 35 - 8. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 38 - 9. SPP Protocol over SOAP WSDL Definition . . . . . . . . . . . . 39 - 10. SPP Protocol over SOAP Examples . . . . . . . . . . . . . . . 51 - 10.1. Add Destination Group . . . . . . . . . . . . . . . . . . 51 - 10.2. Add SED Records . . . . . . . . . . . . . . . . . . . . . 53 - 10.3. Add SED Records -- URIType . . . . . . . . . . . . . . . 54 - 10.4. Add SED Group . . . . . . . . . . . . . . . . . . . . . . 55 - 10.5. Add Public Identity -- Successful COR claim . . . . . . . 57 - 10.6. Add LRN . . . . . . . . . . . . . . . . . . . . . . . . . 59 - 10.7. Add TN Range . . . . . . . . . . . . . . . . . . . . . . 60 - 10.8. Add TN Prefix . . . . . . . . . . . . . . . . . . . . . . 61 - 10.9. Enable Peering -- SED Group Offer . . . . . . . . . . . . 62 - 10.10. Enable Peering -- SED Group Offer Accept . . . . . . . . 64 - 10.11. Add Egress Route . . . . . . . . . . . . . . . . . . . . 65 - 10.12. Remove Peering -- SED Group Offer Reject . . . . . . . . 67 - 10.13. Get Destination Group . . . . . . . . . . . . . . . . . . 68 - 10.14. Get Public Identity . . . . . . . . . . . . . . . . . . . 70 - 10.15. Get SED Group Request . . . . . . . . . . . . . . . . . . 71 - 10.16. Get SED Group Offers Request . . . . . . . . . . . . . . 73 - 10.17. Get Egress Route . . . . . . . . . . . . . . . . . . . . 75 - 10.18. Delete Destination Group . . . . . . . . . . . . . . . . 77 - 10.19. Delete Public Identity . . . . . . . . . . . . . . . . . 78 - 10.20. Delete SED Group Request . . . . . . . . . . . . . . . . 80 - 10.21. Delete SED Group Offers Request . . . . . . . . . . . . . 81 - 10.22. Delete Egress Route . . . . . . . . . . . . . . . . . . . 82 - 10.23. Batch Request . . . . . . . . . . . . . . . . . . . . . . 83 - 11. Security Considerations . . . . . . . . . . . . . . . . . . . 86 - 11.1. Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 86 - 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 87 - 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 88 - 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 89 - 14.1. Normative References . . . . . . . . . . . . . . . . . . 89 - 14.2. Informative References . . . . . . . . . . . . . . . . . 89 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 91 + 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 + 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3. SOAP Features and Protocol Layering . . . . . . . . . . . . . 4 + 4. HTTP(s) Features and SPP Protocol over SOAP . . . . . . . . . 6 + 5. Authentication, Integrity and Confidentiality . . . . . . . . 7 + 6. Language Identification . . . . . . . . . . . . . . . . . . . 7 + 7. SPP Protocol SOAP Data Structures . . . . . . . . . . . . . . 7 + 7.1. Concrete Object Key Types . . . . . . . . . . . . . . . . 7 + 7.1.1. Generic Object Key . . . . . . . . . . . . . . . . . 8 + 7.1.2. Public Identity Object Key . . . . . . . . . . . . . 9 + 7.1.3. SED Group Offer Key . . . . . . . . . . . . . . . . . 10 + 7.2. Operation Request and Response Structures . . . . . . . . 11 + 7.2.1. Add Operation Structure . . . . . . . . . . . . . . . 11 + 7.2.2. Delete Operation Structure . . . . . . . . . . . . . 14 + 7.2.3. Accept Operation Structure . . . . . . . . . . . . . 17 + 7.2.4. Reject Operation Structure . . . . . . . . . . . . . 20 + 7.2.5. Batch Operation Structure . . . . . . . . . . . . . . 23 + 7.2.6. Get Operation Structure . . . . . . . . . . . . . . . 26 + 7.2.7. Get SED Group Offers Operation Structure . . . . . . 27 + 7.2.8. Generic Query Response . . . . . . . . . . . . . . . 29 + 7.2.9. Get Server Details Operation Structure . . . . . . . 29 + 7.3. Response Codes and Messages . . . . . . . . . . . . . . . 31 + 8. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 33 + 9. SPP Protocol over SOAP WSDL Definition . . . . . . . . . . . 33 + 10. SPP Protocol over SOAP Examples . . . . . . . . . . . . . . . 44 + 10.1. Add Destination Group . . . . . . . . . . . . . . . . . 45 + 10.2. Add SED Records . . . . . . . . . . . . . . . . . . . . 46 + 10.3. Add SED Records -- URIType . . . . . . . . . . . . . . . 48 + 10.4. Add SED Group . . . . . . . . . . . . . . . . . . . . . 49 + 10.5. Add Public Identity -- Successful COR claim . . . . . . 50 + 10.6. Add LRN . . . . . . . . . . . . . . . . . . . . . . . . 51 + 10.7. Add TN Range . . . . . . . . . . . . . . . . . . . . . . 53 + 10.8. Add TN Prefix . . . . . . . . . . . . . . . . . . . . . 54 + 10.9. Enable Peering -- SED Group Offer . . . . . . . . . . . 55 + 10.10. Enable Peering -- SED Group Offer Accept . . . . . . . . 56 + 10.11. Add Egress Route . . . . . . . . . . . . . . . . . . . . 57 + 10.12. Remove Peering -- SED Group Offer Reject . . . . . . . . 59 + 10.13. Get Destination Group . . . . . . . . . . . . . . . . . 60 + 10.14. Get Public Identity . . . . . . . . . . . . . . . . . . 61 + 10.15. Get SED Group Request . . . . . . . . . . . . . . . . . 62 + 10.16. Get SED Group Offers Request . . . . . . . . . . . . . . 64 + 10.17. Get Egress Route . . . . . . . . . . . . . . . . . . . . 65 + 10.18. Delete Destination Group . . . . . . . . . . . . . . . . 66 + 10.19. Delete Public Identity . . . . . . . . . . . . . . . . . 67 + 10.20. Delete SED Group Request . . . . . . . . . . . . . . . . 69 + 10.21. Delete SED Group Offers Request . . . . . . . . . . . . 70 + 10.22. Delete Egress Route . . . . . . . . . . . . . . . . . . 71 + 10.23. Batch Request . . . . . . . . . . . . . . . . . . . . . 72 + 11. Security Considerations . . . . . . . . . . . . . . . . . . . 74 + 11.1. Vulnerabilities . . . . . . . . . . . . . . . . . . . . 75 + 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 + 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 75 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 + 14.1. Normative References . . . . . . . . . . . . . . . . . . 76 + 14.2. Informative References . . . . . . . . . . . . . . . . . 76 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 77 1. Introduction SPPF, defined in [I-D.draft-ietf-drinks-spp-framework], 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 SPPF 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 SPPF is likely - to reside in a separate organization's network, resulting the SPPF + 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) + 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 over - SOAP and HTTP(s). + SOAP and HTTP(S). 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 applicable HTTP features, (3) security considerations, and perhaps most importantly, (4) the Web Services Description Language (WSDL) definition for SPP Protocol over SOAP, and (5) "transport" specific - XML schema type definitions + XML Schema type definitions 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]. 3. SOAP Features and Protocol Layering The list of SOAP features that are explicitly used and required for SPP Protocol over SOAP are limited. Most SOAP features are not necessary for SPPF. SPP Protocol 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 specifications, 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 [I-D.draft-ietf-drinks-spp-framework] and the - SPPF WSDL types specification described in this document. + the SOAP specifications [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 + [I-D.draft-ietf-drinks-spp-framework] and the SPPF WSDL types + specification described in this document and in + [I-D.draft-ietf-drinks-spp-framework]. 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 where the SPPF 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_ 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. + 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. +-------------+ (1) | Transport |Example: | Protocol | TCP, TLS, BEEP, etc. + +-------------+ | V +-------------+ (2) | Message |Example: | Envelope | HTTP, SOAP, None, etc. +-------------+ | V +--------------+ @@ -232,207 +234,200 @@ SOAP Messages The operations supported by SPP Protocol 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 SPP Protocol over SOAP. All success - and error responses are specified in the "Response Codes and - Messages" section 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. + 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. - SOAP 1.2 [SOAPREF] or higher and WSDL 1.1 [WSDLREF] or higher SHOULD - be used. + This document RECOMMENDS SOAP 1.2 [SOAPREF] or higher, and WSDL 1.1 + [WSDLREF] or higher. SPPF is a request/reply framework that allows a client application to submit provisioning data and query requests to a server. The SPPF data structures are designed to be protocol agnostic. Concerns regarding encryption, non-repudiation, and authentication are beyond - the scope of this document. For more details, please refer to the - "Transport Protocol Requirements" section in the framework document. + the scope of this document. For more details, please refer to + Section 4 ("Transport Protocol Requirements") of + [I-D.draft-ietf-drinks-spp-framework]. 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 below for SPP Protocol over SOAP. + and 6 for SPP Protocol over SOAP. 1. Layer 1: The transport protocol layer represents the communication mechanism between the client and server. SPPF 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. + basic requirements defined in Section 4 of + [I-D.draft-ietf-drinks-spp-framework]. 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. + SOAP are examples of messaging envelope technologies. - 3. Layers 3,4,5,6: The operation and message layers provides an + 3. Layers 3,4,5,6: The operation and message layers provide an envelope-independent and transport-independent wrapper for the SPPF data model objects that are being acted on (created, modified, queried). 4. HTTP(s) Features and SPP Protocol over SOAP - 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 + While SOAP is not tied to HTTP(S), for reasons described in the + introduction, HTTP(S) is a good choice as the transport mechanism 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 connections is an HTTPS connection where the relatively time - consuming SSL handshake has occurred. Persistent connections SHOULD - be used for the SPPF HTTP connections. + consuming SSL handshake has occurred. - HTTP 1.1 [RFC2616] or higher SHOULD be used. + Implementations compliant with this document MUST use HTTP 1.1 + [RFC2616] or higher. Also, implementations SHOULD use persistent + connections. 5. Authentication, Integrity and Confidentiality To accomplish authentication, conforming SPP Protocol over SOAP Clients and Servers MUST use HTTP Digest Authentication as defined in - [RFC2617] as the authentication mechanism. + [RFC2617]. To achieve integrity and privacy, conforming SPP Protocol over SOAP Clients and Servers MUST support Transport Layer Security (TLS) as defined in [RFC5246] as the secure transport mechanism. 6. Language Identification Section 9 of [I-D.draft-ietf-drinks-spp-framework] requires transport protocols to provide a mechanism to transmit language tags together with human-readable messages. When conforming SPP Protocol SOAP - servers use such tagging, the XML "lang" attribute (see Section 2.12 - of [W3C.REC-xml-20081126]) MUST be used for that purpose. Clients - MAY use the HTTP "Accept-Language" header field (see Section 14.4 of + 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 14.4 of [RFC2616]) in order to indicate their language preference. 7. SPP Protocol SOAP Data Structures SPP Protocol over SOAP uses a set of XML based data structures for all the supported operations and any parameters that those operations are applied to. As also mentioned earlier in this document, these XML structures are envelope-independent and transport-independent. - Refer the "Protocol Operations" section of this document for a + Refer the "Protocol Operations" (Section 8) of this document for a description of all the operations that MUST be supported. The following sections describe the definition all the XML data structures. 7.1. Concrete Object Key Types - 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 the any such object key in an abstract manner and delegates the concrete representation to any conforming transport protocol. The following sub-sections define the various types of concrete object key types used in various - operations in SPP Protocol over SOAP: + operations in SPP Protocol over SOAP. 7.1.1. Generic Object Key Most objects in SPP Protocol over SOAP are uniquely identified by the - attributes in the generic object key (Refer "Generic Object Key Type" - section of the framework document for details). The concrete XML - representation of ObjKeyType is as below: + attributes in the generic object key (Refer Section 5.2.1 "Generic + Object Key Type" of [I-D.draft-ietf-drinks-spp-framework] 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 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 same - Registrant Id "iana-en:222". 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". + object. For example, both a Destination Group and a SED Group can + have the same name "TestObj" and be associated with 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". - The object types in SPP Protocol over SOAP that MUST adhere to the - above definition of generic object key are defined as an enumeration - in the XML data structure. The structure of the the enumeration is - as follows: + The object types in SPP Protocol 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: 7.1.2. Public Identity Object Key Public Identity type objects can further be of various sub-types like - a TN, RN, TN Prefix, URI, or a TN Range and cannot be cleanly - identified with the attributes in the generic ObjKeyType. The - definition of PubIdKeyType is as below: + a Telephone Number (TN), Routing Number (RN), TN Prefix, URI, or a TN + Range and cannot be cleanly identified with the attributes in the + generic ObjKeyType. The definition of PubIdKeyType is as below: - - The PubIdKeyType has the data elements as described below: - - o rant: The identifier of the registrant organization that owns - the object. + The PubIdKeyType has data elements, as described below: - o dgName: The name of the Destination Group that a Public - Identifier is member of. Note that this is an optional - attribute of the key as Public Identifiers may or may not be - provisioned as members of a Destination Group. + o rant: The identifier of the registrant organization that owns the + object. - o number: An element of type NumberType (refer framework document) - that contains the value and type of a number . + o number: An element of type NumberType (refer Section 12 of + [I-D.draft-ietf-drinks-spp-framework]) that contains the value and + type of a number . - o range: An element of type NumberRangeType (refer framework - document) that contains a range of numbers. + o range: An element of type NumberRangeType (refer Section 12 of + [I-D.draft-ietf-drinks-spp-framework]) that contains a range of + numbers. o uri: A value that represents a Public Identifier. Any instance of PubIdKeyType MUST contain exactly one element from the following set of elements: "number", "range", "uri". 7.1.3. SED Group Offer Key In addition to the attributes in the generic ObjKeyType, a SED Group Offer object is uniquely identified by the organization ID of the @@ -452,41 +447,40 @@ The SedGrpOfferKeyType has the data elements as described below: o sedGrpKey: Identifies the SED Group that was offered. o offeredTo: The organization ID of the organization that was offered the SED Group object identified by the sedGrpKey. 7.2. Operation Request and Response Structures - An SPPF client interacts with an SPPF server by using one of the - supported transport mechanisms to send one or more requests to the - server and receive corresponding replies from the server. The basic - set of operations that an SPPF client can submit to an SPPF server - and the semantics of those operations are defined in the "Framework - Operations" section of the framework document. The following sub- - sections describe the XML data structures that are used for each of - those types of operations for a SPP Protocol over SOAP - implementation. + 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 Section 7 ("Framework Operations") of + [I-D.draft-ietf-drinks-spp-framework]. The following sub-sections + describe the XML data structures that are used for each of those + types of operations for a SPP Protocol over SOAP implementation. 7.2.1. Add Operation Structure In order to add (or modify) an object in the registry, an authorized entity can send the spppAddRequest to the registry. An SPP Protocol over SOAP Add request is wrapped within the element while an SPP Protocol over SOAP Add response is wrapped within an element. The following sub- sections describe the spppAddRequest and spppAddResponse elements. - Refer the "SPP Protocol over SOAP Examples" section of this document - for an example of Add operation on each type of SPPF object. + Refer to Section 10 for an example of Add operation on each type of + SPPF object. 7.2.1.1. Add Request An SPP Protocol over SOAP Add request definition is contained within the generic element. The data elements within the 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. 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. + track, log or correlate requests and their responses. 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, indicating the minor version of the SPPF 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 SPPF 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 SPPF server for the given major version. The - versions supported by a given SPPF server can be retrieved by - the client using the SPPF server menu operation described later - in the document. + versions supported by a given SPPF server can be retrieved by the + client using the "Get Server Details" operation described in + Section 7.2.9. o obj: One or more elements of abstract type BasicObjType (defined - in the framework document). Each element contains all the - attributes of an SPPF object that that the client is requesting - the SPPF server to add. Refer the "Framework Data Model - Objects" section of the framework document 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 handling of error conditions, conforming SPPP - SOAP servers MUST stop processing BasicObjType elements in the - request at the first error, and roll back any BasicObjType - elements that had already been processed for that add request - ("stop and rollback"). + in [I-D.draft-ietf-drinks-spp-framework]). Each element contains + all the attributes of an SPPF object that that the client is + requesting the SPPF server to add. Refer to section 3.1 of + [I-D.draft-ietf-drinks-spp-framework] 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 handling of error conditions, conforming SPPP SOAP servers MUST + stop processing BasicObjType elements in the request at the first + error, and roll back any BasicObjType elements that had already + been processed for that add request ("stop and rollback"). 7.2.1.2. Add Response An SPP Protocol over SOAP add response object is contained within the generic element. This response structure is used for all types of SPPF objects that are provisioned by the SPPF client. @@ -582,45 +574,45 @@ The data elements within the SPP Protocol 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 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. + 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 the - Response Code section for further details. + 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 the framework document) 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. + BasicObjType (as defined in [I-D.draft-ietf-drinks-spp-framework]) + 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. 7.2.2. Delete Operation Structure In order to remove an object from the registry, an authorized entity can send the spppDelRequest into the registry. An SPP Protocol over SOAP Delete request is wrapped within the element while a SPP Protocol over SOAP Delete response is wrapped within the generic element. The following sub-sections - describe the spppDelRequest and spppDelResponse elements. Refer the - "SPP Protocol over SOAP Examples" section of this document for an - example of Delete operation on each type of SPPF object. + describe the spppDelRequest and spppDelResponse elements. Refer to + Section 10 for an example of Delete operation on each type of SPPF + object. 7.2.2.1. Delete Request An SPP Protocol over SOAP Delete request definition is contained within the generic element. The data elements within the 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. 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. + track, log or correlate requests and their responses. 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, indicating the minor version of the SPPF 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 SPPF 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 SPPF server for the given major version. The - versions supported by a given SPPF server can be retrieved by - the client using the SPPF server menu operation described later - in the document. + versions supported by a given SPPF server can be retrieved by the + client using the Get Server Details Operation described in + Section 7.2.9. o objKey: One or more elements of abstract type ObjKeyType (as - defined in the framework document). Each element contains - attributes that uniquely identify the object that the client is - requesting the server to delete. Refer the "Concrete Object - Keys" section 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. The elements are processed by - the SPPF server in the order in which they are included in the - request. With respect to 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 rollback"). + defined in [I-D.draft-ietf-drinks-spp-framework]). 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 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 rollback"). 7.2.2.2. Delete Response An SPP Protocol over SOAP delete response object is contained within the generic element. This response structure is used for a delete request on all types of SPPF objects that are provisioned by the SPPF client. @@ -715,49 +706,48 @@ The data elements within the SPP Protocol 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 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. + 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 the - Response Code section for further details. + 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 the framework document) triplet. This - element will be present only if an 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 the Response - Code section for further details. + ObjKeyType (as defined in [I-D.draft-ietf-drinks-spp-framework]) + triplet. This element will be present only if an 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. 7.2.3. Accept Operation Structure In SPPF, a SED Group Offer can be accepted or rejected by, or on behalf of, the registrant to whom the SED Group has been offered - (refer "Framework Data Model Objects" section of the framework - document for a description of the SED Group Offer object). The - Accept operation is used to accept such SED Group Offers by, or on - behalf of, the Registrant. The request structure for an SPP Protocol - over SOAP Accept operation is wrapped within the - element while an SPP Protocol over SOAP Accept response is wrapped - within the generic element. The following sub- - sections describe the spppAcceptRequest and spppAcceptResponse - elements. Refer the "SPP Protocol over SOAP Examples" section of - this document for an example of Accept operation on a SED Group + (refer Section 3.1 of [I-D.draft-ietf-drinks-spp-framework] 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 SPP Protocol over SOAP + Accept operation is wrapped within the element + while an SPP Protocol over SOAP Accept response is wrapped within the + generic element. The following sub-sections + describe the spppAcceptRequest and spppAcceptResponse elements. + Refer to Section 10 for an example of Accept operation on a SED Group Offer. 7.2.3.1. Accept Request Structure An SPP Protocol over SOAP Accept request definition is contained within the generic element. @@ -770,47 +760,48 @@ maxOccurs="unbounded"/> The data elements within the 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. 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. + track, log or correlate requests and their responses. 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, indicating the minor version of the SPPF 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 SPPF 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 SPPF server for the given major version. The - versions supported by a given SPPF server can be retrieved by - the client using the SPPF server menu operation described later - in the document. + versions supported by a given SPPF server can be retrieved by the + client using the Get Server Details Operation described in + Section 7.2.9. 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 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 rollback"). + request. With respect to 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 rollback"). 7.2.3.2. Accept Response An SPP Protocol over SOAP accept response structure is contained within the generic element. This response structure is used for an Accept request on a SED Group Offer. @@ -851,49 +840,49 @@ The data elements within the SPP Protocol 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 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. + 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 the - Response Code section for further details. + 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 the - Response Code section for further details. + error. The response code will reflect the exact error. See + Section 7.3 for further details. 7.2.4. Reject Operation Structure In SPPF, SED Group Offer can be accepted or rejected by, or on behalf of, the registrant to whom the SED Group has been offered (refer - "Framework Data Model Objects" section of the framework document for - a description of the SED Group Offer object). The Reject operation - is used to reject such SED Group Offers by, or on behalf of, the - Registrant. The request structure for an SPP Protocol over SOAP - Reject operation is wrapped within the element - while an SPP Protocol over SOAP Reject response is wrapped within the - generic element. The following sub-sections - describe the spppRejectRequest and spppRejecResponse elements. Refer - the "SPP Protocol over SOAP Examples" section of this document for an - example of Reject operation on a SED Group Offer. + "Framework Data Model Objects" section of + [I-D.draft-ietf-drinks-spp-framework] 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 SPP Protocol over SOAP Reject operation is wrapped + within the element while an SPP Protocol over + SOAP Reject response is wrapped within the generic + element. The following sub-sections describe the + spppRejectRequest and spppRejecResponse elements. Refer to + Section 10 for an example of Reject operation on a SED Group Offer. 7.2.4.1. Reject Request An SPP Protocol over SOAP Reject request definition is contained within the generic element. The data elements within the 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. 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. + track, log or correlate requests and their responses. 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, indicating the minor version of the SPPF 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 SPPF 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 SPPF server for the given major version. The - versions supported by a given SPPF server can be retrieved by - the client using the SPPF server menu operation described later - in the document. + versions supported by a given SPPF server can be retrieved by the + client using the Get Server Details Operation described in + Section 7.2.9. 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 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 reject request ("stop and rollback"). + request. With respect to 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 rollback"). 7.2.4.2. Reject Response An SPP Protocol over SOAP reject response structure is contained within the generic element. This response structure is used for an Reject request on a SED Group Offer. @@ -983,47 +974,46 @@ The data elements within the SPP Protocol 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 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. + 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 the - Response Code section for further details. + 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 the - Response Code section for further details. + error. The response code will reflect the exact error. See + Section 7.3 for further details. 7.2.5. Batch Operation Structure An SPP Protocol over SOAP Batch request XML structure allows the SPPF client to send any of of 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 element while a SPPF Batch response is wrapped within the element. This following sub-sections describe the spppBatchRequest and spppBatchResponse elements. Refer - the "SPP Protocol over SOAP Examples" section of this document for an - example of a batch operation. + to Section 10 for an example of a batch operation. 7.2.5.1. Batch Request Structure An SPP Protocol over SOAP Batch request definition is contained within the generic element. The data elements within the 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. + 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. 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. + track, log or correlate requests and their responses. 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, indicating the minor version of the SPPF 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 SPPF 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 SPPF server for the given major version. The - versions supported by a given SPPF server can be retrieved by - the client using the SPPF server menu operation described later - in the document. + versions supported by a given SPPF server can be retrieved by the + client using the Get Server Details Operation described in + Section 7.2.9. 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. + o acceptSedGrpOffer: One or more elements of type SedGrpOfferKeyType + where each element identifies a SED Group Offer that needs to be + accepted. - o rejectSedGrpOffer: One or more elements of type - SedGrpOfferKeyType where each element identifies a SED Group - Offer that needs to be rejected. + 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 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 rollback"). 7.2.5.2. Batch Response An SPP Protocol over SOAP batch response structure is contained within the generic element. This response @@ -1121,34 +1111,34 @@ The data elements within the SPP Protocol 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 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. + 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 the - Response Code section for further details. + 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 that the result relates to. - o delResult: One or more elements of type ObjKeyResultCodeType - where each element identifies the result code, result message - and the specific object key that the result relates to. + o delResult: One or more elements of type ObjKeyResultCodeType where + each element identifies the result code, result message and the + specific object key that the result relates to. 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 that the result relates to. 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 that the result relates to. @@ -1156,23 +1146,23 @@ 7.2.6. Get Operation Structure 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 request structure for an SPP Protocol over SOAP Get operation is contained within the generic element while an SPP Protocol over SOAP Get response is wrapped within the generic element. The following sub-sections describe the - spppGetRequest and spppGetResponse element. Refer the examples - section for an example of SPP Protocol over SOAP Get operation on - each type of SPPF object + spppGetRequest and spppGetResponse element. Refer to Section 10 for + an example of SPP Protocol over SOAP Get operation on each type of + SPPF object 7.2.6.1. Get Request element are described as follows: o minorVer: Zero or one minor version identifier, indicating the minor version of the SPPF 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 SPPF 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 SPPF server for the given major version. The - versions supported by a given SPPF server can be retrieved by - the client using the SPPF server menu operation described later - in the document. + versions supported by a given SPPF server can be retrieved by the + client using the Get Server Details Operation described in + Section 7.2.9. o objKey: One or more elements of abstract type ObjKeyType (as - defined in the framework document). Each element contains - attributes that uniquely identify the object that the client is - requesting the server to query. Refer the "Concrete Object - Keys" section 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. + defined in [I-D.draft-ietf-drinks-spp-framework]). 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. 7.2.6.2. Get Response - The spppGetResponse element is described later in section titled - "Generic Query Response". + The spppGetResponse element is described in Section 7.2.8. 7.2.7. Get SED Group Offers Operation Structure In addition to the ability to query the details of one or more SED Group offers using an 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 element while the response is wrapped within the generic element. The following sub-sections describe the getSedGrpOffersRequest and spppGetResponse elements. 7.2.7.1. Get SED Group Offers Request Using the details passed into this structure, the server will attempt to find SED Group Offer objects that satisfy all the criteria passed - into the request. If no criteria is passed in then the server will - return the list of SED Group Offer objects that belongs to the + into the request. If no criteria is passed in then the SPPF Server + will return the list of SED Group Offer objects that belongs to the registrant. If there are no matching SED Group Offers found then an empty result set will be returned. @@ -1248,49 +1237,48 @@ The data elements within the element are described as follows: o minorVer: Zero or one minor version identifier, indicating the minor version of the SPPF 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 SPPF 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 SPPF server for the given major version. The - versions supported by a given SPPF server can be retrieved by - the client using the SPPF server menu operation described later - in the document. + versions supported by a given SPPF server can be retrieved by the + client using the Get Server Details Operation described in + Section 7.2.9. 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. + 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. + 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 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 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. 7.2.7.2. Get SED Group Offers Response - The spppGetResponse element is described later in section titled - "Generic Query Response". + The spppGetResponse element is described in Section 7.2.8. 7.2.8. Generic Query Response An SPP Protocol over SOAP query response object is contained within the generic element. An 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 SPP Protocol 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 the - Response Code section for further details. + 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). + 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). 7.2.9. Get Server Details Operation Structure - - In order to query certain details of the SPPF server, like the SPPF - server's status and the major/minor version supported by the server, - the Server Details operation structure SHOULD be used. This + 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 element - while a SPPF server status response is wrapped within the - element. This following sub-sections + whereas a SPPF server status response is wrapped within the + element. The following sub-sections describe the spppServerStatusRequest and spppServerStatusResponse elements. 7.2.9.1. Get Server Details Request The data elements within the element are described as follows: o minorVer: Zero or one minor version identifier, indicating the - minor version of the SPP Protocol 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 SPP Protocol 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 SPP Protocol over SOAP - supported by the SPPF server for the given major version. The - versions of SPP Protocol over SOAP supported by a given SPPF - server can be retrieved by the client using this same - spppServerStatusRequest without passing in the minorVer element. + minor version of the SPP Protocol 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 + SPP Protocol 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 SPP Protocol over SOAP supported by the + SPPF server for the given major version. The versions of SPP + Protocol over SOAP supported by a given SPPF server can be + retrieved by the client using this same spppServerStatusRequest + without passing in the minorVer element. 7.2.9.2. Get Server Details Response An SPP Protocol over SOAP server details response structure is contained within the generic element. The data elements within the element 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. + explicitly identifies the result of the request. See Section 7.3 + for further details. o svcMenu: Exactly one element of type SvcMenuType which in turn - contains the elements to return the server status and major/ - minor version of the SPP Protocol over SOAP supported by the - SPPF server (refer framework document for definition of - SvcMenuType) . + contains the elements to return the server status, the major and + minor versions of the SPP Protocol over SOAP supported by the SPPF + server (refer Section 12 of [I-D.draft-ietf-drinks-spp-framework] + for definition of SvcMenuType). 7.3. Response Codes and Messages 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 the section "Response - Message Types" of the framework document. + conformance with the response types defined in Section 5.3 of + [I-D.draft-ietf-drinks-spp-framework]. 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 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. + 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 SPPF responses, or object level response codes that may only be returned in the "detailResult" element of the SPPF responses. - +--------+--------------------------+-------------------------------+ - | Result | Result Message | Overall or Object Level | - | Code | | | - +--------+--------------------------+-------------------------------+ - | 1000 | Request Succeeded. | Overall Response Code | - | | | | - | 2000 | Request syntax invalid. | Overall Response Code | + +----------+------------------------------------------+-------------+ + | Result | Result Message | Overall or | + | Code | | Object | + | | | Level | + +----------+------------------------------------------+-------------+ + | 1000 | Request Succeeded. | Overall | + | | | Response | + | | | Code | | | | | - | 2001 | Request too large. | Overall Response Code | - | | MaxSupported:[Maximum | | - | | requests supported] | | + | 2000 | Request syntax invalid. | Overall | + | | | Response | + | | | Code | | | | | - | 2002 | Version not supported. | Overall Response Code | + | 2001 | Request too large. MaxSupported:[Maximum | Overall | + | | requests supported] | Response | + | | | Code | | | | | - | 2100 | Command invalid. | Overall Response Code | + | 2002 | Version not supported. | Overall | + | | | Response | + | | | Code | | | | | - | 2300 | System temporarily | Overall Response Code | - | | unavailable. | | + | 2100 | Command invalid. | Overall | + | | | Response | + | | | Code | | | | | - | 2301 | Unexpected internal | Overall Response Code | - | | system or server error. | | + | 2300 | System temporarily unavailable. | Overall | + | | | Response | + | | | Code | | | | | - | 2101 | Attribute value invalid. | Object Level Response Code | + | 2301 | Unexpected internal system or server | Overall | + | | error. | Response | + | | | Code | | | | | - | | AttrName:[AttributeName] | | - | | AttrVal:[AttributeValue] | | + | 2101 | Attribute value invalid. | Object | + | | AttrName:[AttributeName] | Level | + | | AttrVal:[AttributeValue] | Response | + | | | Code | | | | | - | 2102 | Object does not exist. | Object Level Response Code | - | | AttrName:[AttributeName] | | - | | AttrVal:[AttributeValue] | | + | 2102 | Object does not exist. | Object | + | | AttrName:[AttributeName] | Level | + | | AttrVal:[AttributeValue] | Response | + | | | Code | | | | | - | 2103 | Object status or | Object Level Response Code | - | | ownership does not allow | | - | | for operation. | | - | | AttrName:[AttributeName] | | - | | AttrVal:[AttributeValue] | | - +--------+--------------------------+-------------------------------+ - + | 2103 | Object status or ownership does not | Object | + | | allow for operation. | Level | + | | AttrName:[AttributeName] | Response | + | | AttrVal:[AttributeValue] | Code | + +----------+------------------------------------------+-------------+ Table 1: Response Codes Numbering Scheme and Messages 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. 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". The use of these parameters MUST adhere to the rules defined in - "Response Message Types" section of the framework document. + Section 5.3 of [I-D.draft-ietf-drinks-spp-framework]. 8. Protocol Operations - Refer the "Framework Operations" section of the framework document - for a description of all SPPF operations, and any necessary semantics - that MUST be adhered to in order to conform with the SPPF - specification. + Refer to Section 7 of [I-D.draft-ietf-drinks-spp-framework] for a + description of all SPPF operations, and any necessary semantics that + MUST be adhered to in order to conform with SPPF. 9. SPP Protocol over SOAP WSDL Definition The SPP Protocol over SOAP WSDL and data types are defined below. - The WSDL design approach is commonly referred to as _Generic WSDL_. + 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 + 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. + Notes: The following WSDL has been formatted (e.g. tabs, spaces) to + meet IETF document requirements. Deployments MUST replace + "REPLACE_WITH_ACTUAL_URL" in the WSDL below with the URI of the SPPF + Server instance. @@ -1550,22 +1547,20 @@ - @@ -2015,33 +2010,34 @@ Figure 2: WSDL 10. SPP Protocol over SOAP Examples This section shows XML message exchange between two SIP Service Providers (SSP) and a registry. The messages in this section are valid XML instances that conform to the SPP Protocol over SOAP schema - version within this document. This section relies on the XML data - structures defined in the base SPPF specification - [I-D.draft-ietf-drinks-spp-framework]. So refer to that document to - understand XML object types embedded in these example messages. + version within this document. This section also relies on the XML + data structures defined in the SPPF specification + [I-D.draft-ietf-drinks-spp-framework]. 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 SBE instances that are associated with the public identities that SSP2 has the - retail relationship with. Also, the two SBE instances for SSP1 are - used to show how to use SPPF to associate route preferences for the - destination ingress routes and exercise greater control on outbound - traffic to the peer's ingress SBEs. + retail relationship with. Also, the two Session Border Element + instances for SSP1 are used to show how to use SPPF to associate + route preferences for the destination ingress routes and exercise + greater control on outbound traffic to the peer's ingress SBEs. ---------------+ +------------------ | | +------+ +------+ | sbe1 | | sbe2 | +------+ +------+ SSP1 | | SSP2 +------+ +------+ | sbe3 | | sbe4 | +------+ +------+ @@ -2658,26 +2656,27 @@ iana-en:222 SED_GRP_SSP2_1 SedGrp iana-en:111 + Registry confirms that the request has been processed successfully. From this point forward, if SSP1 looks up a public identity through the query resolution server, where the public identity is part of the destination group by way of "SED_GRP_SSP2_1" session establishment - data association, SSP2 ingress SBE information will NOT be shared - with SSP1 and hence SSP2 ingress SBE will NOT be returned in the + data association, SSP2 ingress SBE information will not be shared + with SSP1 and hence SSP2 ingress SBE will not be returned in the query response. txn_1479 @@ -3023,21 +3020,20 @@ xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:ietf:params:xml:ns:sppf:soap:1" xmlns:urn1="urn:ietf:params:xml:ns:sppf:base:1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> iana-en:222 - DEST_GRP_SSP2_1 +12025556666 TN Registry completes the request successfully and returns a favorable @@ -3270,21 +3265,20 @@ iana-en:111 offered 2006-05-04T18:13:51.0Z iana-en:222 - +12025556666 TN iana-en:222 SED_GRP_SSP2_Previous SedGrp @@ -3333,64 +3327,64 @@ by the client, which is often accomplished using the TLS certificate exchange and validation described in [RFC2818]. 11.1. Vulnerabilities Section 5 describes the use of HTTP and TLS as the underlying transport protocols for SPP Protocol over SOAP. These underlying protocols may have various vulnerabilities, and these may be inherited by SPP Protocol over SOAP. SPP Protocol over SOAP itself may have vulnerabilities because an authorization model is not - explicitly specified in the current specification. + explicitly specified in this document. - During a TLS handshake, non-anonymous TLS servers can optionally - request a certificate from a TLS client; that option is not a - requirement for this protocol. This presents a denial of service - risk in which unauthenticated clients can consume server CPU - resources by creating TLS sessions. The risk is increased if the - server supports client-initiated renegotiation. This risk can be - mitigated by disabling client-initiated renegotiation on the server - and by ensuring that other means (such as firewall access control - lists) are used to restrict unauthenticated client access to servers. + 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 SPP Protocol 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. 12. IANA Considerations - This document uses URNs to describe XML namespaces and XML schemas + This document uses URNs to describe XML Namespaces and XML Schemas conforming to a registry mechanism described in [RFC3688]. - URN assignments requested are: urn:ietf:params:xml:ns:sppf:soap:1 + URN assignment requested is: urn:ietf:params:xml:ns:sppf:soap:1 13. Acknowledgements - This document is a result of various discussions held by the DRINKS - design team, with contributions from the following individuals, in - alphabetical order: Alexander Mayrhofer, David Schwartz, Deborah A - Guyton, Jean-Francois Mule Kenneth Cartwright, Lisa Dusseault, Manjul - Maharishi, Mickael Marrache, Otmar Lendl, Peter Saint-Andre, Richard - Shockey, Samuel Melloul, Scott Hollenbeck, Sumanth Channabasappa, - Syed Ali, and Vikas Bhatia . + 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: + Alexander Mayrhofer, David Schwartz, Deborah A Guyton, Jean-Francois + Mule Kenneth Cartwright, Lisa Dusseault, Manjul Maharishi, Mickael + Marrache, Otmar Lendl, Peter Saint-Andre, Richard Shockey, Samuel + Melloul, Scott Hollenbeck, Sumanth Channabasappa, Syed Ali, and Vikas + Bhatia . 14. References 14.1. Normative References [I-D.draft-ietf-drinks-spp-framework] Cartwright, K., Bhatia, V., Ali, S., and D. Schwartz, - "Session Peering Provisioning Framework", - draft-ietf-drinks-spp-framework-03 (work in progress), - October 2012. + "Session Peering Provisioning Framework ", draft-ietf- + drinks-spp-framework-04 (work in progress), October 2012. [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 @@ -3447,14 +3441,14 @@ CableLabs 858 Coal Creek Circle Louisville, CO 80027 USA Email: jfm@cablelabs.com Alexander Mayrhofer enum.at GmbH Karlsplatz 1/9 - Wien, A-1010 + Wien A-1010 Austria Email: alexander.mayrhofer@enum.at