--- 1/draft-ietf-drinks-spp-protocol-over-soap-00.txt 2012-03-12 20:14:01.642755303 +0100 +++ 2/draft-ietf-drinks-spp-protocol-over-soap-01.txt 2012-03-12 20:14:01.766756079 +0100 @@ -1,18 +1,18 @@ DRINKS K. Cartwright Internet-Draft V. Bhatia Intended status: Standards Track TNS -Expires: August 2, 2012 January 30, 2012 +Expires: September 13, 2012 March 12, 2012 Session Peering Provisioning (SPP) Protocol over SOAP - draft-ietf-drinks-spp-protocol-over-soap-00 + draft-ietf-drinks-spp-protocol-over-soap-01 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 @@ -30,21 +30,21 @@ 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 August 2, 2012. + This Internet-Draft will expire on September 13, 2012. Copyright Notice Copyright (c) 2012 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -52,74 +52,74 @@ 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 SPPF . . . . . . . . . . . . . . . . . . 9 + 4. HTTP(s) Features and SPP Protocol over SOAP . . . . . . . . . 9 5. Authentication and Session Management . . . . . . . . . . . . 10 6. SPP Protocol SOAP Data Structures . . . . . . . . . . . . . . 11 6.1. Concrete Object Key Types . . . . . . . . . . . . . . . . 11 6.1.1. Generic Object Key . . . . . . . . . . . . . . . . . . 11 6.1.2. Public Identity Object Key . . . . . . . . . . . . . . 12 6.1.3. Route Group Offer Key . . . . . . . . . . . . . . . . 13 - 6.2. Operation Request and Response Structures . . . . . . . . 13 + 6.2. Operation Request and Response Structures . . . . . . . . 14 6.2.1. Add Operation Structure . . . . . . . . . . . . . . . 14 6.2.2. Delete Operation Structure . . . . . . . . . . . . . . 17 6.2.3. Accept Operation Structure . . . . . . . . . . . . . . 20 - 6.2.4. Reject Operation Structure . . . . . . . . . . . . . . 23 - 6.2.5. Batch Operation Structure . . . . . . . . . . . . . . 26 - 6.2.6. Get Operation Structure . . . . . . . . . . . . . . . 29 - 6.2.7. Get Route Group Offers Operation Structure . . . . . . 31 - 6.2.8. Generic Query Response . . . . . . . . . . . . . . . . 32 - 6.2.9. Get Server Details Operation Structure . . . . . . . . 33 - 6.3. Response Codes and Messages . . . . . . . . . . . . . . . 35 - 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 37 - 8. SPPF SOAP WSDL Definition . . . . . . . . . . . . . . . . . . 38 - 9. SPP Protocol over SOAP Examples . . . . . . . . . . . . . . . 49 - 9.1. Add Destination Group . . . . . . . . . . . . . . . . . . 49 - 9.2. Add Route Records . . . . . . . . . . . . . . . . . . . . 51 - 9.3. Add Route Records -- URIType . . . . . . . . . . . . . . . 52 - 9.4. Add Route Group . . . . . . . . . . . . . . . . . . . . . 53 - 9.5. Add Public Identity -- Successful COR claim . . . . . . . 55 - 9.6. Add LRN . . . . . . . . . . . . . . . . . . . . . . . . . 57 - 9.7. Add TN Range . . . . . . . . . . . . . . . . . . . . . . . 58 - 9.8. Add TN Prefix . . . . . . . . . . . . . . . . . . . . . . 59 - 9.9. Enable Peering -- Route Group Offer . . . . . . . . . . . 60 - 9.10. Enable Peering -- Route Group Offer Accept . . . . . . . . 62 - 9.11. Add Egress Route . . . . . . . . . . . . . . . . . . . . . 63 - 9.12. Remove Peering -- Route Group Offer Reject . . . . . . . . 65 - 9.13. Get Destination Group . . . . . . . . . . . . . . . . . . 66 - 9.14. Get Public Identity . . . . . . . . . . . . . . . . . . . 68 - 9.15. Get Route Group Request . . . . . . . . . . . . . . . . . 69 - 9.16. Get Route Group Offers Request . . . . . . . . . . . . . . 71 - 9.17. Get Egress Route . . . . . . . . . . . . . . . . . . . . . 73 - 9.18. Delete Destination Group . . . . . . . . . . . . . . . . . 74 - 9.19. Delete Public Identity . . . . . . . . . . . . . . . . . . 75 - 9.20. Delete Route Group Request . . . . . . . . . . . . . . . . 77 - 9.21. Delete Route Group Offers Request . . . . . . . . . . . . 78 - 9.22. Delete Egress Route . . . . . . . . . . . . . . . . . . . 79 - 9.23. Batch Request . . . . . . . . . . . . . . . . . . . . . . 80 - 10. Security Considerations . . . . . . . . . . . . . . . . . . . 83 - 10.1. Integrity, Privacy, and Authentication . . . . . . . . . . 83 - 10.2. Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 83 - 10.3. Deployment Environment Specifics . . . . . . . . . . . . . 83 - 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 84 - 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 85 - 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 86 - 13.1. Normative References . . . . . . . . . . . . . . . . . . . 86 - 13.2. Informative References . . . . . . . . . . . . . . . . . . 86 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 87 + 6.2.4. Reject Operation Structure . . . . . . . . . . . . . . 24 + 6.2.5. Batch Operation Structure . . . . . . . . . . . . . . 27 + 6.2.6. Get Operation Structure . . . . . . . . . . . . . . . 30 + 6.2.7. Get Route Group Offers Operation Structure . . . . . . 32 + 6.2.8. Generic Query Response . . . . . . . . . . . . . . . . 33 + 6.2.9. Get Server Details Operation Structure . . . . . . . . 34 + 6.3. Response Codes and Messages . . . . . . . . . . . . . . . 36 + 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 39 + 8. SPP Protocol over SOAP WSDL Definition . . . . . . . . . . . . 40 + 9. SPP Protocol over SOAP Examples . . . . . . . . . . . . . . . 52 + 9.1. Add Destination Group . . . . . . . . . . . . . . . . . . 52 + 9.2. Add Route Records . . . . . . . . . . . . . . . . . . . . 54 + 9.3. Add Route Records -- URIRteRecType . . . . . . . . . . . . 55 + 9.4. Add Route Group . . . . . . . . . . . . . . . . . . . . . 56 + 9.5. Add Public Identity -- Successful COR claim . . . . . . . 58 + 9.6. Add LRN . . . . . . . . . . . . . . . . . . . . . . . . . 60 + 9.7. Add TN Range . . . . . . . . . . . . . . . . . . . . . . . 61 + 9.8. Add TN Prefix . . . . . . . . . . . . . . . . . . . . . . 62 + 9.9. Enable Peering -- Route Group Offer . . . . . . . . . . . 63 + 9.10. Enable Peering -- Route Group Offer Accept . . . . . . . . 65 + 9.11. Add Egress Route . . . . . . . . . . . . . . . . . . . . . 66 + 9.12. Remove Peering -- Route Group Offer Reject . . . . . . . . 68 + 9.13. Get Destination Group . . . . . . . . . . . . . . . . . . 69 + 9.14. Get Public Identity . . . . . . . . . . . . . . . . . . . 71 + 9.15. Get Route Group Request . . . . . . . . . . . . . . . . . 72 + 9.16. Get Route Group Offers Request . . . . . . . . . . . . . . 74 + 9.17. Get Egress Route . . . . . . . . . . . . . . . . . . . . . 76 + 9.18. Delete Destination Group . . . . . . . . . . . . . . . . . 77 + 9.19. Delete Public Identity . . . . . . . . . . . . . . . . . . 78 + 9.20. Delete Route Group Request . . . . . . . . . . . . . . . . 80 + 9.21. Delete Route Group Offers Request . . . . . . . . . . . . 81 + 9.22. Delete Egress Route . . . . . . . . . . . . . . . . . . . 82 + 9.23. Batch Request . . . . . . . . . . . . . . . . . . . . . . 83 + 10. Security Considerations . . . . . . . . . . . . . . . . . . . 86 + 10.1. Integrity, Privacy, and Authentication . . . . . . . . . . 86 + 10.2. Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 86 + 10.3. Deployment Environment Specifics . . . . . . . . . . . . . 87 + 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 88 + 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 89 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 90 + 13.1. Normative References . . . . . . . . . . . . . . . . . . . 90 + 13.2. Informative References . . . . . . . . . . . . . . . . . . 90 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 91 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 @@ -269,21 +269,21 @@ 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 SPPF data model objects that are being acted on (created, modified, queried). -4. HTTP(s) Features and SPPF +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 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. @@ -312,95 +312,120 @@ description of all the operations that MUST be supported. The following sections describe the definition all the XML data structures. 6.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 abstact manner and delegates the concrete represenation to any + in an abstact 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: 6.1.1. Generic Object Key - Most objects in SPP Protocol over SOAP are unqiuely identified by the - attributes in the concrete ObjKeyType. The XML representation of - ObjKeyType is as below: + 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: - + The ObjKeyType has the data elements as described below: o rant: The identifier of the registrant organization that owns the object. o name: The character string that contains the name of the object. - o type: The enumeration vaue that represents the type of SPPF - object. + o type: The enumeration value that represents the type of SPPF + object. For example, both a Destination Group and a Route 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". + + 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: + + + + + + + + + 6.1.2. Public Identity Object Key Public Identity type objects can further be of various sub-types like - a TN, RN, TN Prefix, or a TN Range and cannot be cleanly identified - with the attributes in the generic ObjKeyType. The definition of - PubIdKeyType is as below: + 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: + The PubIdKeyType has the data elements as described below: o rant: The identifier of the registrant organization that owns the object. 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 number: An element of type NumberType (refer framework document) - that contains the value and type of a the number . + that contains the value and type of a number . o range: An element of type NumberRangeType (refer framework - document) that contains a rage of numbers. + document) that contains a range of numbers. - It is MUST that only one of the "number" and "range" elements appears - in a PubIdKeyType instance. + o uri: A value that represents a Public Identifier. + + It is MUST that only one of the "number", "range", and "uri" elements + appears in a PubIdKeyType instance. 6.1.3. Route Group Offer Key In addition to the attributes in the generic ObjKeyType, a Route Group Offer object is uniquely identified by the organization ID of the organization to whom an Route Group has been offered. The definition of RteGrpOfferKeyType is as below: @@ -431,52 +456,44 @@ sections describe the XML data structures that are used for each of those types of operations for a SPP Protocol over SOAP implementation. 6.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 SPPF Add response is wrapped within - an element. The following sub-sections describe - the spppAddRequest and spppAddResponse elements. Refer the "SPPF - SOAP Examples" section of this document for an example of Add - operation on each type of SPPF object. + 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. 6.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. @@ -520,21 +537,21 @@ for all types of SPPF objects that are provisioned by the SPPF client. - @@ -548,60 +565,60 @@ An contains the elements necessary for the SPPF client to precisely determine the overall result of the request, and if an error occurred, it provides information about the specific object(s) that caused the error. - The data elements within the SPPF Add response are described as - follows: + 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. 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 dtlResult: An optional response code, response message, and + 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. 6.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 Del request is wrapped within the element while - a SPPF Del response is wrapped within the generic - element. The following sub-sections describe the spppDelRequest and - spppDelResponse elements. Refer the "SPPF SOAP Examples" section of - this document for an example of Delete operation on each type of SPPF - object. + 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. 6.2.2.1. Delete Request - An SPP Protocol over SOAP Del request definition is contained within - the generic element. + An SPP Protocol over SOAP Delete request definition is contained + within the generic element. @@ -658,21 +675,21 @@ used for a delete request on all types of SPPF objects that are provisioned by the SPPF client. - @@ -686,59 +703,60 @@ An contains the elements necessary for the SPPF client to precisely determine the overall result of the request, and if an error occurred, it provides information about the specific object key(s) that caused the error. - The data elements within the SPPF Delete response are described as - follows: + 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. 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 dtlResult: An optional response code, response message, and + 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. 6.2.3. Accept Operation Structure In SPPF, a Route Group Offer can be accepted or rejected by, or on behalf of, the registrant to whom the Route Group has been offered (refer "Framework Data Model Objects" section of the framework document for a description of the Route Group Offer object). The Accept operation is used to accept such Route Group Offers by, or on - behalf of, the Registrant. The request structure for an SPPF Accept - operation is wrapped within the element while an - SPPF Accept response is wrapped within the generic - element. The following sub-sections describe - the spppAcceptRequest and spppAcceptResponse elements. Refer the - "SPPF SOAP Examples" section of this document for an example of - Accept operation on a Route Group Offer. + 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 Route Group + Offer. 6.2.3.1. Accept Request Structure An SPP Protocol over SOAP Accept request definition is contained within the generic element. element. This response structure is used for an Accept request on a Route Group Offer. - @@ -827,58 +844,59 @@ An contains the elements necessary for the SPPF client to precisely determine the overall result of the request, and if an error occurred, it provides information about the specific Route Group Offer key(s) that caused the error. - The data elements within the SPPF Accept response are described as - follows: + 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. 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 dtlResult: An optional response code, response message, and + o detailResult: An optional response code, response message, and RteGrpOfferKeyType (as defined in this document) triplet. This element will be present only if any specific Route Group Offer key level error has occurred. It indicates the error condition and the exact request Route Group Offer key that contributed to the error. The response code will reflect the exact error. See the Response Code section for further details. 6.2.4. Reject Operation Structure In SPPF, Route Group Offer can be accepted or rejected by, or on behalf of, the registrant to whom the Route Group has been offered - (refer "Framework Data Model Objects" section of this document for a - description of the Route Group Offer object). The Reject operation - is used to reject such Route Group Offers by, or on behalf of, the - Registrant. The request structure for an SPPF Reject operation is - wrapped within the element while an SPPF Reject - response is wrapped within the generic element. - The following sub-sections describe the spppRejectRequest and - spppRejecResponse elements. Refer the "SPPF SOAP Examples" section - of this document for an example of Reject operation on a Route Group + (refer "Framework Data Model Objects" section of the framerwork + document for a description of the Route Group Offer object). The + Reject operation is used to reject such Route 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 Route Group Offer. 6.2.4.1. Reject Request An SPP Protocol over SOAP Reject request definition is contained within the generic element. @@ -937,21 +955,21 @@ within the generic element. This response structure is used for an Reject request on a Route Group Offer. - @@ -966,57 +984,57 @@ An contains the elements necessary for the SPPF client to precisely determine the overall result of the request, and if an error occurred, it provides information about the specific Route Group Offer key(s) that caused the error. - The data elements within the SPPF Reject response are described as - follows: + 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. 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 dtlResult: An optional response code, response message, and + o detailResult: An optional response code, response message, and RteGrpOfferKeyType (as defined in this document) triplet. This element will be present only if any specific Route Group Offer key level error has occurred. It indicates the error condition and the exact request Route Group Offer key that contributed to the error. The response code will reflect the exact error. See the Response Code section for further details. 6.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 "SPPF SOAP Examples" section of this document for an example of a - batch operation. + the "SPP Protocol over SOAP Examples" section of this document for an + example of a batch operation. 6.2.5.1. Batch Request Structure An SPP Protocol over SOAP Batch request definition is contained within the generic element. An contains the elements necessary for an SPPF client to precisely determine the overall result of various operations in the request, and if an error occurred, it provides information about the specific objects or keys in the request that caused the error. - The data elements within the SPPF Batch response are described as - follows: + 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. @@ -1150,26 +1168,27 @@ RteGrpOfferKeyResultCodeType where each element identifies the result code, result message and the specific Route Group Offer key that the result relates to. 6.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 strcuture for an SPPF Get operation is contained within - the generic element while an SPPF 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 Get operation on each - type of SPPF object + The request strcuture 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 6.2.6.1. Get Request element while the response is wrapped within the generic element. The following sub-sections describe the getRteGrpOffersRequest and spppGetResponse elements. 6.2.7.1. Get Route Group Offers Request Using the details passed into this structure, the server will attempt to find Route Group Offer objects that satisfy all the criteria @@ -1296,22 +1315,22 @@ type="sppfb:BasicObjType" minOccurs="0" maxOccurs="unbounded"/> 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 SPPF query response are described as - follows: + 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. 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). @@ -1334,29 +1353,30 @@ 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 + 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 supported by a given SPPF server can be retrieved by - the client using this same spppServerStatusRequest without - passing in the minorVer element. + 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. 6.2.9.2. Get Server Details Response An SPP Protocol over SOAP server details response structure is contained within the generic element. @@ -1367,22 +1387,23 @@ 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. 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 SPPF supported by the SPPF server (refer - framework document for definition of SvcMenuType) . + minor version of the SPP Protocol over SOAP supported by the + SPPF server (refer framework document for definition of + SvcMenuType) . 6.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. The response code numbering scheme generally adheres to the theory formalized in section 4.2.1 of [RFC5321]: @@ -1394,89 +1415,102 @@ = 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 SPPF responses, or object level - response codes that may only be returned in the "dtlResult" element - of the SPPF responses. + 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 | | | | | - | 2001 | Request syntax invalid. | Overall Response Code | + | 2000 | Request syntax invalid. | Overall Response Code | | | | | - | 2002 | Request too large. | Overall Response Code | + | 2001 | Request too large. | Overall Response Code | + | | MaxSupported:[Maximum | | + | | requests supported] | | | | | | - | 2003 | Version not supported. | Overall Response Code | + | 2002 | Version not supported. | Overall Response Code | | | | | - | 2103 | Command invalid. | Overall Response Code | + | 2100 | Command invalid. | Overall Response Code | | | | | - | 2301 | System temporarily | Overall Response Code | + | 2300 | System temporarily | Overall Response Code | | | unavailable. | | | | | | - | 2302 | Unexpected internal | Overall Response Code | + | 2301 | Unexpected internal | Overall Response Code | | | system or server error. | | | | | | - | 2104 | Attribute value invalid. | Object Level Response Code | + | 2101 | Attribute value invalid. | Object Level Response Code | | | | | | | AttrName:[AttributeName] | | | | AttrVal:[AttributeValue] | | | | | | - | 2105 | Object does not exist. | Object Level Response Code | + | 2102 | Object does not exist. | Object Level Response Code | | | AttrName:[AttributeName] | | | | AttrVal:[AttributeValue] | | | | | | - | 2106 | Object status or | Object Level Response Code | + | 2103 | 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 + 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. 7. 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. -8. SPPF SOAP WSDL Definition +8. SPP Protocol over SOAP WSDL Definition - The SPPF WSDL and data types are defined below. The WSDL design - approach is commonly referred to as _Generic WSDL_. It is generic in - the sense that there is not a specific WSDL operation defined for - each object type that is supported by the SPPF protocol. There is a - single WSDL structure for each type of SPPF operation. Each such - WSDL structure contains exactly one input structure and one output - structure that wraps any data elements that are part of the incoming - request and the outgoing response respectively. The spppSOAPBinding - in the WSDL defines the binding style as _document_ and the encoding - as _literal_. It is this combination of _wrapped_ input and output - data structures, _document_ binding style, and _literal_ encoding - that characterize the Document Literal Wrapped style of WSDL - specifications. + The SPP Protocol over SOAP WSDL and data types are defined below. + The WSDL design approach is commonly referred to as _Generic WSDL_. + It is generic in the sense that there is not a specific WSDL + operation defined for each object type that is supported by the SPPF + protocol. There is a single WSDL structure for each type of SPPF + operation. Each such WSDL structure contains exactly one input + structure and one output structure that wraps any data elements that + are part of the incoming request and the outgoing response + respectively. The spppSOAPBinding in the WSDL defines the binding + style as _document_ and the encoding as _literal_. It is this + combination of _wrapped_ input and output data structures, _document_ + binding style, and _literal_ encoding that characterize the Document + Literal Wrapped style of WSDL specifications. Note: The following WSDL has been formatted (e.g., tabs, spaces) to meet I-D requirements. - + + + + + + + + + + @@ -1653,54 +1696,53 @@ - - - - @@ -1699,21 +1741,21 @@ - @@ -1757,24 +1799,48 @@ ---- Operation Result Type Definitions ---- - - + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -2065,20 +2130,21 @@ txn_1479 iana-en:222 iana-en:223 RTE_SSP2_SBE2 + true 10 u E2U+sip ^(.*)$ sip:\1@sbe2.ssp2.example.com @@ -2096,40 +2162,41 @@ txn_1479 tx_12345 1000 Request Succeeded. -9.3. Add Route Records -- URIType +9.3. Add Route Records -- URIRteRecType SSP2 adds another ingress routes in the registry and makes use of - URIType + URIRteRecType txn_1479 - + iana-en:222 iana-en:223 RTE_SSP2_SBE4 + true ^(.*)$ sip:\1;npdi@sbe4.ssp2.example.com The registry returns a success response. @@ -2142,21 +2209,21 @@ 1000 Request Succeeded. 9.4. Add Route Group - SSP2 creates the grouping of the ingress routes and choses higher + SSP2 creates the grouping of the ingress routes and chooses higher precedence for RTE_SSP2_SBE2 by setting a lower number for the "priority" attribute, a protocol agnostic precedence indicator. @@ -2246,36 +2313,36 @@ txn_1479 tx_12345 1000 Request Succeeded. - + 1000 Request Succeeded. iana-en:222 iana-en:223 2010-05-30T09:30:10Z DEST_GRP_SSP2_1 +12025556666 true true 2010-05-30T09:30:11Z - + 9.6. Add LRN If another entity that SSP2 shares the routes with has access to Number Portability data, it may choose to perform route lookups by routing number. Therefore, SSP2 associates a routing number to a destination group in order to facilitate ingress route discovery. @@ -2948,21 +3015,21 @@ 1000 Request Succeeded. 9.19. Delete Public Identity - SSP2 choses to de-activate the TN and remove it from the registry. + SSP2 chooses to de-activate the TN and remove it from the registry. @@ -3256,93 +3323,107 @@ 1000 Request Succeeded. 10. Security Considerations - SPPF 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]. SPPF data may include sensitive - information, routing data, lists of resolvable addresses, etc. So - when used in a production setting and across non-secure networks, - SPPF should only be used over communications channels that provide - strong encryption for data privacy. + SPP Protocol over SOAP is used to query and update session peering + data and addresses, so the ability to access this protocol should be + limited to users and systems that are authorized to query and update + this data. Because this data is sent in both directions, it may not + be sufficient for just the client or user to be authenticated with + the server. The identity of the server should also be authenticated + by the client, which is often accomplished using the TLS certificate + exchange and validation described in [RFC2818]. SPP Protocol over + SOAP messages may include sensitive information, routing data, lists + of resolvable addresses, etc. So when used in a production setting + and across non-secure networks, SPP Protocol over SOAP should only be + used over communications channels that provide strong encryption for + data privacy. 10.1. Integrity, Privacy, and Authentication - The SPPF 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 SPPF 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. + The SPP Protocol over 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 SPPF 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 SPP Protocol over SOAP implementations + At a minimum, all conforming SPP Protocol over SOAP implementations MUST support HTTPS. 10.2. Vulnerabilities The above protocols may have various vulnerabilities, and these may - be inherited by SPP Protocol over SOAP. And SPPF itself may have - vulnerabilities because an authorization model is not explicitly - specified in the current specification. + 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. - It is important that SPPF implementations implement an authorization - model that considers the source of each SPPF query or update request - and determines whether it is reasonable to authorize that source to - perform that specific query or update. + Sections 5 and 10.1 describe requirements for HTTPS support using + TLS. Non-anonymous TLS servers can optionally request a certificate + from a TLS client; that option is not a requirement for this + protocol. This presents a denial of service risk in which + unauthenticated clients can consume server CPU resources by creating + TLS sessions. The risk is increased if the server supports client- + initiated renegotiation. This risk can be mitigated by disabling + client-initiated renegotiation on the server and by ensuring that + other means (such as firewall access control lists) are used to + restrict unauthenticated client access to servers. + + In conjunction with the above, it is important that 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. 10.3. Deployment Environment Specifics Some deployments of SPP Protocol 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 SPPF messages in this type of deployment. + transported in this type of deployment. 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:sppf:soap + URN assignments requested are: urn:ietf:params:xml:ns:sppf:soap:1 12. Acknowledgements This document is a result of various discussions held by the DRINKS design team, which is comprised of 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, Sumanth Channabasappa, Syed Ali, and Vikas - Bhatia . + Shockey, Samuel Melloul, Scott Hollenbeck, Sumanth Channabasappa, + Syed Ali, and Vikas Bhatia . 13. References 13.1. Normative References [I-D.draft-ietf-drinks-spp-framework] Mule, J-F., Cartwright, K., Ali, S., Mayrhofer, A., and V. Bhatia, "Session Peering Provisioning Framework", - draft-ietf-drinks-spp-framework-00 (work in progress), - January 2012. + draft-ietf-drinks-spp-framework-01 (work in progress), + March 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