idnits 2.17.1 draft-ietf-drinks-spp-protocol-over-soap-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 16, 2012) is 4300 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Outdated reference: A later version (-12) exists of draft-ietf-drinks-spp-framework-02 ** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231, RFC 7232, RFC 7233, RFC 7234, RFC 7235) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 5246 (Obsoleted by RFC 8446) -- Possible downref: Non-RFC (?) normative reference: ref. 'SOAPREF' -- Obsolete informational reference (is this intentional?): RFC 2818 (Obsoleted by RFC 9110) Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 DRINKS K. Cartwright 3 Internet-Draft V. Bhatia 4 Intended status: Standards Track TNS 5 Expires: January 17, 2013 J-F. Mule 6 CableLabs 7 A. Mayrhofer 8 enum.at GmbH 9 July 16, 2012 11 Session Peering Provisioning (SPP) Protocol over SOAP 12 draft-ietf-drinks-spp-protocol-over-soap-02 14 Abstract 16 The Session Peering Provisioning Framework (SPPF) is an XML framework 17 that exists to enable the provisioning of session establishment data 18 into Session Data Registries or SIP Service Provider data stores. 19 Sending XML data structures over Simple Object Access Protocol (SOAP) 20 and HTTP(s) is a widely used, de-facto standard for messaging between 21 elements of provisioning systems. Therefore the combination of SOAP 22 and HTTP(s) as a transport protocol for SPPF is a natural fit. The 23 obvious benefits include leveraging existing industry expertise, 24 leveraging existing standards, and a higher probability that existing 25 provisioning systems can be more easily integrated with this 26 protocol. This document describes the specification for transporting 27 SPPF XML structures over SOAP and HTTP(s). 29 Status of this Memo 31 This Internet-Draft is submitted in full conformance with the 32 provisions of BCP 78 and BCP 79. 34 Internet-Drafts are working documents of the Internet Engineering 35 Task Force (IETF). Note that other groups may also distribute 36 working documents as Internet-Drafts. The list of current Internet- 37 Drafts is at http://datatracker.ietf.org/drafts/current/. 39 Internet-Drafts are draft documents valid for a maximum of six months 40 and may be updated, replaced, or obsoleted by other documents at any 41 time. It is inappropriate to use Internet-Drafts as reference 42 material or to cite them other than as "work in progress." 44 This Internet-Draft will expire on January 17, 2013. 46 Copyright Notice 48 Copyright (c) 2012 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. Code Components extracted from this document must 57 include Simplified BSD License text as described in Section 4.e of 58 the Trust Legal Provisions and are provided without warranty as 59 described in the Simplified BSD License. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 65 3. SOAP Features and Protocol Layering . . . . . . . . . . . . . 6 66 4. HTTP(s) Features and SPP Protocol over SOAP . . . . . . . . . 9 67 5. Authentication and Session Management . . . . . . . . . . . . 10 68 6. Language Identification . . . . . . . . . . . . . . . . . . . 11 69 7. SPP Protocol SOAP Data Structures . . . . . . . . . . . . . . 12 70 7.1. Concrete Object Key Types . . . . . . . . . . . . . . . . 12 71 7.1.1. Generic Object Key . . . . . . . . . . . . . . . . . . 12 72 7.1.2. Public Identity Object Key . . . . . . . . . . . . . . 13 73 7.1.3. SED Group Offer Key . . . . . . . . . . . . . . . . . 14 74 7.2. Operation Request and Response Structures . . . . . . . . 15 75 7.2.1. Add Operation Structure . . . . . . . . . . . . . . . 15 76 7.2.2. Delete Operation Structure . . . . . . . . . . . . . . 18 77 7.2.3. Accept Operation Structure . . . . . . . . . . . . . . 21 78 7.2.4. Reject Operation Structure . . . . . . . . . . . . . . 24 79 7.2.5. Batch Operation Structure . . . . . . . . . . . . . . 27 80 7.2.6. Get Operation Structure . . . . . . . . . . . . . . . 30 81 7.2.7. Get SED Group Offers Operation Structure . . . . . . . 32 82 7.2.8. Generic Query Response . . . . . . . . . . . . . . . . 33 83 7.2.9. Get Server Details Operation Structure . . . . . . . . 34 84 7.3. Response Codes and Messages . . . . . . . . . . . . . . . 35 85 8. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 38 86 9. SPP Protocol over SOAP WSDL Definition . . . . . . . . . . . . 39 87 10. SPP Protocol over SOAP Examples . . . . . . . . . . . . . . . 51 88 10.1. Add Destination Group . . . . . . . . . . . . . . . . . . 51 89 10.2. Add SED Records . . . . . . . . . . . . . . . . . . . . . 53 90 10.3. Add SED Records -- URIType . . . . . . . . . . . . . . . 54 91 10.4. Add SED Group . . . . . . . . . . . . . . . . . . . . . . 55 92 10.5. Add Public Identity -- Successful COR claim . . . . . . . 57 93 10.6. Add LRN . . . . . . . . . . . . . . . . . . . . . . . . . 59 94 10.7. Add TN Range . . . . . . . . . . . . . . . . . . . . . . 60 95 10.8. Add TN Prefix . . . . . . . . . . . . . . . . . . . . . . 61 96 10.9. Enable Peering -- SED Group Offer . . . . . . . . . . . . 62 97 10.10. Enable Peering -- SED Group Offer Accept . . . . . . . . 64 98 10.11. Add Egress Route . . . . . . . . . . . . . . . . . . . . 65 99 10.12. Remove Peering -- SED Group Offer Reject . . . . . . . . 67 100 10.13. Get Destination Group . . . . . . . . . . . . . . . . . . 68 101 10.14. Get Public Identity . . . . . . . . . . . . . . . . . . . 70 102 10.15. Get SED Group Request . . . . . . . . . . . . . . . . . . 71 103 10.16. Get SED Group Offers Request . . . . . . . . . . . . . . 73 104 10.17. Get Egress Route . . . . . . . . . . . . . . . . . . . . 75 105 10.18. Delete Destination Group . . . . . . . . . . . . . . . . 76 106 10.19. Delete Public Identity . . . . . . . . . . . . . . . . . 77 107 10.20. Delete SED Group Request . . . . . . . . . . . . . . . . 79 108 10.21. Delete SED Group Offers Request . . . . . . . . . . . . . 80 109 10.22. Delete Egress Route . . . . . . . . . . . . . . . . . . . 81 110 10.23. Batch Request . . . . . . . . . . . . . . . . . . . . . . 82 111 11. Security Considerations . . . . . . . . . . . . . . . . . . . 85 112 11.1. Integrity, Privacy, and Authentication . . . . . . . . . 85 113 11.2. Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 85 114 11.3. Deployment Environment Specifics . . . . . . . . . . . . 86 115 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 87 116 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 88 117 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 89 118 14.1. Normative References . . . . . . . . . . . . . . . . . . 89 119 14.2. Informative References . . . . . . . . . . . . . . . . . 89 120 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 91 122 1. Introduction 124 SPPF, defined in [I-D.draft-ietf-drinks-spp-framework], is best 125 supported by a transport and messaging infrastructure that is 126 connection oriented, request-response oriented, easily secured, 127 supports propagation through firewalls in a standard fashion, and 128 that is easily integrated into back-office systems. This is due to 129 the fact that the client side of SPPF is likely to be integrated with 130 organizations' operational support systems that facilitate 131 transactional provisioning of user addresses and their associated 132 session establishment data. While the server side of SPPF is likely 133 to reside in a separate organization's network, resulting the SPPF 134 provisioning transactions traversing the Internet as they are 135 propagated from the SPPF client to the SPPF server. Given the 136 current state of industry practice and technologies, SOAP and HTTP(s) 137 are well suited for this type of environment. This document 138 describes the specification for transporting SPPF XML structures over 139 SOAP and HTTP(s). 141 The specification in this document for transporting SPPF XML 142 structures over SOAP and HTTP(s) is primarily comprised of five 143 subjects: (1) a description of any applicable SOAP features, (2) any 144 applicable HTTP features, (3) security considerations, and perhaps 145 most importantly, (4) the Web Services Description Language (WSDL) 146 definition for SPP Protocol over SOAP, and (5) "transport" specific 147 XML schema type definitions 149 2. Terminology 151 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 152 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 153 document are to be interpreted as described in [RFC2119]. 155 3. SOAP Features and Protocol Layering 157 The list of SOAP features that are explicitly used and required for 158 SPP Protocol over SOAP are limited. Most SOAP features are not 159 necessary for SPPF. SPP Protocol over SOAP primarily uses SOAP 160 simply as a standard message envelope technology. The SOAP message 161 envelope is comprised of the SOAP header and body. As described in 162 the SOAP specifications, the SOAP header can contain optional, 163 application specific, information about the message. The SOAP body 164 contains the SPPF message itself, whose structure is defined by the 165 combination of one of the WSDL operations defined in this document 166 and the SPPF XML data structures defined in this document and the 167 SPPF document. SPPF does not rely on any data elements in the SOAP 168 header. All relevant data elements are defined in the SPPF XML 169 schema described in [I-D.draft-ietf-drinks-spp-framework] and the 170 SPPF WSDL types specification described in this document. 172 WSDL is a widely standardized and adopted technology for defining the 173 top-level structures of the messages that are transported within the 174 body of a SOAP message. The WSDL definition for the SPPF SOAP 175 messages is defined later in this document, which imports by 176 reference the XML data types contained in the SPPF schema. The IANA 177 registry where the SPPF schema resides is described in The IETF XML 178 Registry [RFC3688]. 180 There are multiple structural styles that SOAP WSDL allows. But the 181 best practice for this type of application is what is sometimes 182 referred to as the Document Literal Wrapped style of designing SOAP 183 WSDL. This style is generally regarded as an optimal approach that 184 enhances maintainability, comprehension, portability, and, to a 185 certain extent, performance. It is characterized by setting the 186 soapAction binding style as _document_, the soapAction encoding style 187 as _literal_, and then defining the SOAP messages to simply contain a 188 single data element that _wraps_ a data structure containing all the 189 required input or output data elements. The figure below illustrates 190 this high level technical structure as conceptual layers 3 through 6. 192 +-------------+ 193 (1) | Transport |Example: 194 | Protocol | TCP, TLS, BEEP, etc. 195 +-------------+ 196 | 197 V 198 +-------------+ 199 (2) | Message |Example: 200 | Envelope | HTTP, SOAP, None, etc. 201 +-------------+ 202 | 203 V 204 +--------------+ 205 +----| SOAP |---+ 206 |(3) | Operation | | 207 Contains | +--------------+ | Contains 208 | Example: | 209 V submitAddRqst V 210 +--------------+ +-------------+ 211 |SOAP Request | |SOAP Response| 212 Example: | Message | (4) | Message | Example: 213 spppAdd | (Operation | | (Operation | spppAdd 214 RequestMsg | Input) | | Output) | ResponseMsg 215 +--------------+ +-------------+ 216 | | 217 Contains | | Contains 218 | | 219 V V 220 +---------------+ +---------------+ 221 Example: | Wrapped | (5) | Wrapped | Example: 222 spppAdd |Request Object | |Response Object| spppAdd 223 Request +---------------+ +---------------+ Response 224 | | 225 Contains | | Contains 226 | | 227 V V 228 +-------------+ +---------------+ 229 | SPPF | | SPPF | 230 |XML Types | (6) | XML Types | 231 +-------------+ +---------------+ 233 Figure 1: Layering and Technical Structure of the SPP Protocol over 234 SOAP Messages 236 The operations supported by SPP Protocol over SOAP are normatively 237 defined later in this document. Each SOAP operation defines a 238 request/input message and a response/output message. Each such 239 request and response message then contains a single object that wraps 240 the SPPF XML data types that comprise the inputs and the outputs, 241 respectively, of the SOAP operation. 243 SOAP faults are not used by the SPP Protocol over SOAP. All success 244 and error responses are specified in the "Response Codes and 245 Messages" section of this document. However, if a SOAP fault were to 246 occur, perhaps due to failures in the SOAP message handling layer of 247 a SOAP library, the client application should capture and handle the 248 fault. Specifics on how to handle such SOAP faults, if they should 249 occur, will be specific to the chosen SOAP implementation. 251 SOAP 1.2 [SOAPREF] or higher and WSDL 1.1 [WSDLREF] or higher SHOULD 252 be used. 254 SPPF is a request/reply framework that allows a client application to 255 submit provisioning data and query requests to a server. The SPPF 256 data structures are designed to be protocol agnostic. Concerns 257 regarding encryption, non-repudiation, and authentication are beyond 258 the scope of this document. For more details, please refer to the 259 "Transport Protocol Requirements" section in the framework document. 261 As illustrated in the previous diagram, SPPF can be viewed as a set 262 of layers that collectively define the structure of an SPPF request 263 and response. Layers 1 and 2 represent the transport, envelope, and 264 authentication technologies. This document defines layers 3, 4, 5, 265 and 6 below for SPP Protocol over SOAP. 267 1. Layer 1: The transport protocol layer represents the 268 communication mechanism between the client and server. SPPF can 269 be layered over any transport protocol that provides a set of 270 basic requirements defined in the Transport Protocol Requirements 271 section. But this document specifies the required mechanism. 273 2. Layer 2: The message envelope layer is optional, but can provide 274 features that are above the transport technology layer but below 275 the application messaging layer. Technologies such as HTTP and 276 SOAP are examples of messaging envelope technologies. This 277 document specifies the required envelope technology. 279 3. Layers 3,4,5,6: The operation and message layers provides an 280 envelope-independent and transport-independent wrapper for the 281 SPPF data model objects that are being acted on (created, 282 modified, queried). 284 4. HTTP(s) Features and SPP Protocol over SOAP 286 SOAP is not tied to HTTP(s), however, for reasons described in the 287 introduction, HTTP(s) is a good choice as the transport mechanism for 288 the SPP Protocol SOAP messages. HTTP 1.1 includes the "persistent 289 connection" feature, which allows multiple HTTP request/response 290 pairs to be transported across a single HTTP connection. This is an 291 important performance optimization feature, particularly when the 292 connections is an HTTPS connection where the relatively time 293 consuming SSL handshake has occurred. Persistent connections SHOULD 294 be used for the SPPF HTTP connections. 296 HTTP 1.1 [RFC2616] or higher SHOULD be used. 298 5. Authentication and Session Management 300 To achieve integrity and privacy, conforming SPP Protocol SOAP 301 Clients and Servers MUST support SOAP over HTTP over TLS [RFC5246] as 302 the secure transport mechanism. This combination of HTTP and TLS is 303 referred to as HTTPS. And to accomplish authentication, conforming 304 SOAP SPPF Clients and Servers MUST use HTTP Digest Authentication as 305 defined in [RFC2617]. As a result, the communication session is 306 established through the initial HTTP connection setup, the digest 307 authentication, and the TLS handshake. When the HTTP connection is 308 broken down, the communication session ends. 310 6. Language Identification 312 Section 9 of [I-D.draft-ietf-drinks-spp-framework] requires transport 313 protocols to provide a mechanism to transmit language tags together 314 with human-readable messages. When conforming SPP Protocol SOAP 315 servers use such tagging, the XML "lang" attribute (see Section 2.12 316 of [W3C.REC-xml-20081126]) MUST be used for that purpose. Clients 317 MAY use the HTTP "Accept-Language" header field (see Section 14.4 of 318 [RFC2616]) in order to indicate their language preference. 320 7. SPP Protocol SOAP Data Structures 322 SPP Protocol over SOAP uses a set of XML based data structures for 323 all the supported operations and any parameters that those operations 324 are applied to. As also mentioned earlier in this document, these 325 XML structures are envelope-independent and transport-independent. 326 Refer the "Protocol Operations" section of this document for a 327 description of all the operations that MUST be supported. 329 The following sections describe the definition all the XML data 330 structures. 332 7.1. Concrete Object Key Types 334 Certain operations in SPPF require an object key that uniquely 335 identifies the object(s) on which a given operation needs to be 336 performed. SPPF defines the XML structure of the any such object key 337 in an abstract manner and delegates the concrete representation to 338 any conforming transport protocol. The following sub-sections define 339 the various types of concrete object key types used in various 340 operations in SPP Protocol over SOAP: 342 7.1.1. Generic Object Key 344 Most objects in SPP Protocol over SOAP are uniquely identified by the 345 attributes in the generic object key (Refer "Generic Object Key Type" 346 section of the framework document for details). The concrete XML 347 representation of ObjKeyType is as below: 349 350 351 352 353 354 355 356 357 358 359 361 The ObjKeyType has the data elements as described below: 363 o rant: The identifier of the registrant organization that owns 364 the object. 366 o name: The character string that contains the name of the object. 368 o type: The enumeration value that represents the type of SPPF 369 object. For example, both a Destination Group and a SED Group 370 can have the same name "TestObj" and be associated with same 371 Registrant Id "iana-en:222". Hence, to uniquely identify the 372 object that represents a Destination Group with the name 373 "TestObj", the type "DestGrp" must be specified when using this 374 concrete ObjKeyType structure to identify the Destination Group 375 "TestObj". 377 The object types in SPP Protocol over SOAP that MUST adhere to the 378 above definition of generic object key are defined as an enumeration 379 in the XML data structure. The structure of the the enumeration is 380 as follows: 382 383 384 385 386 387 388 389 391 7.1.2. Public Identity Object Key 393 Public Identity type objects can further be of various sub-types like 394 a TN, RN, TN Prefix, URI, or a TN Range and cannot be cleanly 395 identified with the attributes in the generic ObjKeyType. The 396 definition of PubIdKeyType is as below: 398 399 400 401 402 403 405 406 408 410 412 413 414 415 416 418 The PubIdKeyType has the data elements as described below: 420 o rant: The identifier of the registrant organization that owns 421 the object. 423 o dgName: The name of the Destination Group that a Public 424 Identifier is member of. Note that this is an optional 425 attribute of the key as Public Identifiers may or may not be 426 provisioned as members of a Destination Group. 428 o number: An element of type NumberType (refer framework document) 429 that contains the value and type of a number . 431 o range: An element of type NumberRangeType (refer framework 432 document) that contains a range of numbers. 434 o uri: A value that represents a Public Identifier. 436 It is MUST that only one of the "number", "range", and "uri" elements 437 appears in a PubIdKeyType instance. 439 7.1.3. SED Group Offer Key 441 In addition to the attributes in the generic ObjKeyType, a SED Group 442 Offer object is uniquely identified by the organization ID of the 443 organization to whom an SED Group has been offered. The definition 444 of SedGrpOfferKeyType is as below: 446 447 448 449 450 451 452 453 454 455 457 The SedGrpOfferKeyType has the data elements as described below: 459 o sedGrpKey: Identifies the SED Group that was offered. 461 o offeredTo: The organization ID of the organization that was 462 offered the SED Group object identified by the sedGrpKey. 464 7.2. Operation Request and Response Structures 466 An SPPF client interacts with an SPPF server by using one of the 467 supported transport mechanisms to send one or more requests to the 468 server and receive corresponding replies from the server. The basic 469 set of operations that an SPPF client can submit to an SPPF server 470 and the semantics of those operations are defined in the "Framework 471 Operations" section of the framework document. The following sub- 472 sections describe the XML data structures that are used for each of 473 those types of operations for a SPP Protocol over SOAP 474 implementation. 476 7.2.1. Add Operation Structure 478 In order to add (or modify) an object in the registry, an authorized 479 entity can send the spppAddRequest to the registry. 481 An SPP Protocol over SOAP Add request is wrapped within the 482 element while an SPP Protocol over SOAP Add response 483 is wrapped within an element. The following sub- 484 sections describe the spppAddRequest and spppAddResponse elements. 485 Refer the "SPP Protocol over SOAP Examples" section of this document 486 for an example of Add operation on each type of SPPF object. 488 7.2.1.1. Add Request 490 An SPP Protocol over SOAP Add request definition is contained within 491 the generic element. 493 494 495 496 498 500 502 503 504 506 The data elements within the element are described 507 as follows: 509 o clientTransId: Zero or one client-generated transaction ID that, 510 within the context of the SPPF client, identifies this request. 511 This value can be used at the discretion of the SPPF client to 512 track, log or correlate requests and their responses. SPPF 513 server MUST echo back this value to the client in the 514 corresponding response to the incoming request. SPPF server 515 will not check this value for uniqueness. 517 o minorVer: Zero or one minor version identifier, indicating the 518 minor version of the SPPF API that the client is attempting to 519 use. This is used in conjunction with the major version 520 identifier in the XML namespace to identify the version of SPPF 521 that the client is using. If the element is not present, the 522 server assumes that the client is using the latest minor version 523 supported by the SPPF server for the given major version. The 524 versions supported by a given SPPF server can be retrieved by 525 the client using the SPPF server menu operation described later 526 in the document. 528 o obj: One or more elements of abstract type BasicObjType (defined 529 in the framework document). Each element contains all the 530 attributes of an SPPF object that that the client is requesting 531 the SPPF server to add. Refer the "Framework Data Model 532 Objects" section of the framework document for the XML structure 533 of all concrete types, for various SPPF objects, that extend 534 from abstract BasicObjType and hence are eligible to be passed 535 into this element. The elements are processed by the SPPF 536 server in the order in which they are included in the request. 537 With respect to handling of error conditions, conforming SPPP 538 SOAP servers MUST stop processing BasicObjType elements in the 539 request at the first error, and roll back any BasicObjType 540 elements that had already been processed for that add request 541 ("stop and rollback"). 543 7.2.1.2. Add Response 545 An SPP Protocol over SOAP add response object is contained within the 546 generic element. This response structure is used 547 for all types of SPPF objects that are provisioned by the SPPF 548 client. 550 551 552 553 555 556 557 559 560 561 563 564 565 566 567 568 570 571 572 573 574 575 576 577 579 581 An contains the elements necessary for the SPPF 582 client to precisely determine the overall result of the request, and 583 if an error occurred, it provides information about the specific 584 object(s) that caused the error. 586 The data elements within the SPP Protocol over SOAP Add response are 587 described as follows: 589 o clientTransId: Zero or one client transaction ID. This value is 590 simply an echo of the client transaction ID that SPPF client 591 passed into the SPPF update request. When included in the 592 request, the SPPF server MUST return it in the corresponding 593 response message. 595 o serverTransId: Exactly one server transaction ID that identifies 596 this request for tracking purposes. This value MUST be unique 597 for a given SPPF server. 599 o overallResult: Exactly one response code and message pair that 600 explicitly identifies the result of the request. See the 601 Response Code section for further details. 603 o detailResult: An optional response code, response message, and 604 BasicObjType (as defined in the framework document) triplet. 605 This element will be present only if an object level error has 606 occurred. It indicates the error condition and the exact 607 request object that contributed to the error. The response code 608 will reflect the exact error. See the Response Code section for 609 further details. 611 7.2.2. Delete Operation Structure 613 In order to remove an object from the registry, an authorized entity 614 can send the spppDelRequest into the registry. An SPP Protocol over 615 SOAP Delete request is wrapped within the element 616 while a SPP Protocol over SOAP Delete response is wrapped within the 617 generic element. The following sub-sections 618 describe the spppDelRequest and spppDelResponse elements. Refer the 619 "SPP Protocol over SOAP Examples" section of this document for an 620 example of Delete operation on each type of SPPF object. 622 7.2.2.1. Delete Request 624 An SPP Protocol over SOAP Delete request definition is contained 625 within the generic element. 627 628 629 630 632 634 636 637 638 640 The data elements within the element are described 641 as follows: 643 o clientTransId: Zero or one client-generated transaction ID that, 644 within the context of the SPPF client, identifies this request. 645 This value can be used at the discretion of the SPPF client to 646 track, log or correlate requests and their responses. SPPF 647 server MUST echo back this value to the client in the 648 corresponding response to the incoming request. SPPF server 649 will not check this value for uniqueness. 651 o minorVer: Zero or one minor version identifier, indicating the 652 minor version of the SPPF API that the client is attempting to 653 use. This is used in conjunction with the major version 654 identifier in the XML namespace to identify the version of SPPF 655 that the client is using. If the element is not present, the 656 server assumes that the client is using the latest minor version 657 supported by the SPPF server for the given major version. The 658 versions supported by a given SPPF server can be retrieved by 659 the client using the SPPF server menu operation described later 660 in the document. 662 o objKey: One or more elements of abstract type ObjKeyType (as 663 defined in the framework document). Each element contains 664 attributes that uniquely identify the object that the client is 665 requesting the server to delete. Refer the "Concrete Object 666 Keys" section of this document for a description of all concrete 667 object key types, for various SPPF objects, which are eligible 668 to be passed into this element. The elements are processed by 669 the SPPF server in the order in which they are included in the 670 request. With respect to handling of error conditions, 671 conforming SPPP SOAP servers MUST stop processing ObjKeyType 672 elements in the request at the first error, and roll back any 673 ObjKeyType elements that had already been processed for that 674 delete request ("stop and rollback"). 676 7.2.2.2. Delete Response 678 An SPP Protocol over SOAP delete response object is contained within 679 the generic element. This response structure is 680 used for a delete request on all types of SPPF objects that are 681 provisioned by the SPPF client. 683 684 685 686 688 689 690 692 693 694 696 697 698 699 700 701 703 704 705 706 707 708 709 710 712 714 An contains the elements necessary for the SPPF 715 client to precisely determine the overall result of the request, and 716 if an error occurred, it provides information about the specific 717 object key(s) that caused the error. 719 The data elements within the SPP Protocol over SOAP Delete response 720 are described as follows: 722 o clientTransId: Zero or one client transaction ID. This value is 723 simply an echo of the client transaction ID that SPPF client 724 passed into the SPPF update request. When included in the 725 request, the SPPF server MUST return it in the corresponding 726 response message. 728 o serverTransId: Exactly one server transaction ID that identifies 729 this request for tracking purposes. This value MUST be unique 730 for a given SPPF server. 732 o overallResult: Exactly one response code and message pair that 733 explicitly identifies the result of the request. See the 734 Response Code section for further details. 736 o detailResult: An optional response code, response message, and 737 ObjKeyType (as defined in the framework document) triplet. This 738 element will be present only if an specific object key level 739 error has occurred. It indicates the error condition and the 740 exact request object key that contributed to the error. The 741 response code will reflect the exact error. See the Response 742 Code section for further details. 744 7.2.3. Accept Operation Structure 746 In SPPF, a SED Group Offer can be accepted or rejected by, or on 747 behalf of, the registrant to whom the SED Group has been offered 748 (refer "Framework Data Model Objects" section of the framework 749 document for a description of the SED Group Offer object). The 750 Accept operation is used to accept such SED Group Offers by, or on 751 behalf of, the Registrant. The request structure for an SPP Protocol 752 over SOAP Accept operation is wrapped within the 753 element while an SPP Protocol over SOAP Accept response is wrapped 754 within the generic element. The following sub- 755 sections describe the spppAcceptRequest and spppAcceptResponse 756 elements. Refer the "SPP Protocol over SOAP Examples" section of 757 this document for an example of Accept operation on a SED Group 758 Offer. 760 7.2.3.1. Accept Request Structure 762 An SPP Protocol over SOAP Accept request definition is contained 763 within the generic element. 765 766 767 768 770 772 775 776 777 779 The data elements within the element are 780 described as follows: 782 o clientTransId: Zero or one client-generated transaction ID that, 783 within the context of the SPPF client, identifies this request. 784 This value can be used at the discretion of the SPPF client to 785 track, log or correlate requests and their responses. SPPF 786 server MUST echo back this value to the client in the 787 corresponding response to the incoming request. SPPF server 788 will not check this value for uniqueness. 790 o minorVer: Zero or one minor version identifier, indicating the 791 minor version of the SPPF API that the client is attempting to 792 use. This is used in conjunction with the major version 793 identifier in the XML namespace to identify the version of SPPF 794 that the client is using. If the element is not present, the 795 server assumes that the client is using the latest minor version 796 supported by the SPPF server for the given major version. The 797 versions supported by a given SPPF server can be retrieved by 798 the client using the SPPF server menu operation described later 799 in the document. 801 o sedGrpOfferKey: One or more elements of type SedGrpOfferKeyType 802 (as defined in this document). Each element contains attributes 803 that uniquely identify a SED Group Offer that the client is 804 requesting the server to accept. The elements are processed by 805 the SPPF server in the order in which they are included in the 806 request. With respect to handling of error conditions, 807 conforming SPPP SOAP servers MUST stop processing 808 SedGrpOfferKeyType elements in the request at the first error, 809 and roll back any SedGrpOfferKeyType elements that had already 810 been processed for that accept request ("stop and rollback"). 812 7.2.3.2. Accept Response 814 An SPP Protocol over SOAP accept response structure is contained 815 within the generic element. This response 816 structure is used for an Accept request on a SED Group Offer. 818 819 820 821 823 824 825 828 829 830 832 833 834 835 836 837 839 840 841 842 843 844 845 846 848 850 An contains the elements necessary for the SPPF 851 client to precisely determine the overall result of the request, and 852 if an error occurred, it provides information about the specific SED 853 Group Offer key(s) that caused the error. 855 The data elements within the SPP Protocol over SOAP Accept response 856 are described as follows: 858 o clientTransId: Zero or one client transaction ID. This value is 859 simply an echo of the client transaction ID that SPPF client 860 passed into the SPPF update request. When included in the 861 request, the SPPF server MUST return it in the corresponding 862 response message. 864 o serverTransId: Exactly one server transaction ID that identifies 865 this request for tracking purposes. This value MUST be unique 866 for a given SPPF server. 868 o overallResult: Exactly one response code and message pair that 869 explicitly identifies the result of the request. See the 870 Response Code section for further details. 872 o detailResult: An optional response code, response message, and 873 SedGrpOfferKeyType (as defined in this document) triplet. This 874 element will be present only if any specific SED Group Offer key 875 level error has occurred. It indicates the error condition and 876 the exact request SED Group Offer key that contributed to the 877 error. The response code will reflect the exact error. See the 878 Response Code section for further details. 880 7.2.4. Reject Operation Structure 882 In SPPF, SED Group Offer can be accepted or rejected by, or on behalf 883 of, the registrant to whom the SED Group has been offered (refer 884 "Framework Data Model Objects" section of the framework document for 885 a description of the SED Group Offer object). The Reject operation 886 is used to reject such SED Group Offers by, or on behalf of, the 887 Registrant. The request structure for an SPP Protocol over SOAP 888 Reject operation is wrapped within the element 889 while an SPP Protocol over SOAP Reject response is wrapped within the 890 generic element. The following sub-sections 891 describe the spppRejectRequest and spppRejecResponse elements. Refer 892 the "SPP Protocol over SOAP Examples" section of this document for an 893 example of Reject operation on a SED Group Offer. 895 7.2.4.1. Reject Request 897 An SPP Protocol over SOAP Reject request definition is contained 898 within the generic element. 900 901 902 903 905 907 910 911 913 The data elements within the element are 914 described as follows: 916 o clientTransId: Zero or one client-generated transaction ID that, 917 within the context of the SPPF client, identifies this request. 918 This value can be used at the discretion of the SPPF client to 919 track, log or correlate requests and their responses. SPPF 920 server MUST echo back this value to the client in the 921 corresponding response to the incoming request. SPPF server 922 will not check this value for uniqueness. 924 o minorVer: Zero or one minor version identifier, indicating the 925 minor version of the SPPF API that the client is attempting to 926 use. This is used in conjunction with the major version 927 identifier in the XML namespace to identify the version of SPPF 928 that the client is using. If the element is not present, the 929 server assumes that the client is using the latest minor version 930 supported by the SPPF server for the given major version. The 931 versions supported by a given SPPF server can be retrieved by 932 the client using the SPPF server menu operation described later 933 in the document. 935 o sedGrpOfferKey: One or more elements of type SedGrpOfferKeyType 936 (as defined in this document). Each element contains attributes 937 that uniquely identify a SED Group Offer that the client is 938 requesting the server to reject. The elements are processed by 939 the SPPF server in the order in which they are included in the 940 request. With respect to handling of error conditions, 941 conforming SPPP SOAP servers MUST stop processing 942 SedGrpOfferKeyType elements in the request at the first error, 943 and roll back any SedGrpOfferKeyType elements that had already 944 been processed for that reject request ("stop and rollback"). 946 7.2.4.2. Reject Response 948 An SPP Protocol over SOAP reject response structure is contained 949 within the generic element. This response 950 structure is used for an Reject request on a SED Group Offer. 952 953 954 955 957 958 959 962 963 964 966 967 968 969 970 971 973 974 975 976 977 978 979 980 981 982 An contains the elements necessary for the SPPF 983 client to precisely determine the overall result of the request, and 984 if an error occurred, it provides information about the specific SED 985 Group Offer key(s) that caused the error. 987 The data elements within the SPP Protocol over SOAP Reject response 988 are described as follows: 990 o clientTransId: Zero or one client transaction ID. This value is 991 simply an echo of the client transaction ID that SPPF client 992 passed into the SPPF update request. When included in the 993 request, the SPPF server MUST return it in the corresponding 994 response message. 996 o serverTransId: Exactly one server transaction ID that identifies 997 this request for tracking purposes. This value MUST be unique 998 for a given SPPF server. 1000 o overallResult: Exactly one response code and message pair that 1001 explicitly identifies the result of the request. See the 1002 Response Code section for further details. 1004 o detailResult: An optional response code, response message, and 1005 SedGrpOfferKeyType (as defined in this document) triplet. This 1006 element will be present only if any specific SED Group Offer key 1007 level error has occurred. It indicates the error condition and 1008 the exact request SED Group Offer key that contributed to the 1009 error. The response code will reflect the exact error. See the 1010 Response Code section for further details. 1012 7.2.5. Batch Operation Structure 1014 An SPP Protocol over SOAP Batch request XML structure allows the SPPF 1015 client to send any of of Add, Del, Accept or Reject operations 1016 together in one single request. This gives an SPPF Client the 1017 flexibility to use one single request structure to perform more than 1018 operations (verbs). The batch request structure is wrapped within 1019 the element while a SPPF Batch response is wrapped 1020 within the element. This following sub-sections 1021 describe the spppBatchRequest and spppBatchResponse elements. Refer 1022 the "SPP Protocol over SOAP Examples" section of this document for an 1023 example of a batch operation. 1025 7.2.5.1. Batch Request Structure 1027 An SPP Protocol over SOAP Batch request definition is contained 1028 within the generic element. 1030 1031 1032 1033 1035 1037 1038 1039 1040 1042 1044 1045 1046 1047 1049 The data elements within the element are described 1050 as follows: 1052 o clientTransId: Zero or one client-generated transaction ID that, 1053 within the context of the SPPF client, identifies this request. 1054 This value can be used at the discretion of the SPPF client to 1055 track, log or correlate requests and their responses. SPPF 1056 server MUST echo back this value to the client in the 1057 corresponding response to the incoming request. SPPF server 1058 will not check this value for uniqueness. 1060 o minorVer: Zero or one minor version identifier, indicating the 1061 minor version of the SPPF API that the client is attempting to 1062 use. This is used in conjunction with the major version 1063 identifier in the XML namespace to identify the version of SPPF 1064 that the client is using. If the element is not present, the 1065 server assumes that the client is using the latest minor version 1066 supported by the SPPF server for the given major version. The 1067 versions supported by a given SPPF server can be retrieved by 1068 the client using the SPPF server menu operation described later 1069 in the document. 1071 o addObj: One or more elements of abstract type BasicObjType where 1072 each element identifies an object that needs to be added. 1074 o delObj: One or more elements of abstract type ObjKeyType where 1075 each element identifies a key for the object that needs to be 1076 deleted . 1078 o acceptSedGrpOffer: One or more elements of type 1079 SedGrpOfferKeyType where each element identifies a SED Group 1080 Offer that needs to be accepted. 1082 o rejectSedGrpOffer: One or more elements of type 1083 SedGrpOfferKeyType where each element identifies a SED Group 1084 Offer that needs to be rejected. 1086 With respect to handling of error conditions, conforming SPPP SOAP 1087 servers MUST stop processing elements in the request at the first 1088 error, and roll back any elements that had already been processed for 1089 that batch request ("stop and rollback"). 1091 7.2.5.2. Batch Response 1093 An SPP Protocol over SOAP batch response structure is contained 1094 within the generic element. This response 1095 structure is used for an Batch request that contains many different 1096 types of SPPF operations. 1098 1099 1100 1101 1103 1104 1105 1106 1108 1110 1112 1114 1115 1116 1117 1119 An contains the elements necessary for an SPPF 1120 client to precisely determine the overall result of various 1121 operations in the request, and if an error occurred, it provides 1122 information about the specific objects or keys in the request that 1123 caused the error. 1125 The data elements within the SPP Protocol over SOAP Batch response 1126 are described as follows: 1128 o clientTransId: Zero or one client transaction ID. This value is 1129 simply an echo of the client transaction ID that SPPF client 1130 passed into the SPPF update request. When included in the 1131 request, the SPPF server MUST return it in the corresponding 1132 response message. 1134 o serverTransId: Exactly one server transaction ID that identifies 1135 this request for tracking purposes. This value MUST be unique 1136 for a given SPPF server. 1138 o overallResult: Exactly one response code and message pair that 1139 explicitly identifies the result of the request. See the 1140 Response Code section for further details. 1142 o addResult: One or more elements of type ObjResultCodeType where 1143 each element identifies the result code, result message and the 1144 specific object that the result relates to. 1146 o delResult: One or more elements of type ObjKeyResultCodeType 1147 where each element identifies the result code, result message 1148 and the specific object key that the result relates to. 1150 o acceptResult: One or more elements of type 1151 SedGrpOfferKeyResultCodeType where each element identifies the 1152 result code, result message and the specific SED Group Offer key 1153 that the result relates to. 1155 o rejectResult: One or more elements of type 1156 SedGrpOfferKeyResultCodeType where each element identifies the 1157 result code, result message and the specific SED Group Offer key 1158 that the result relates to. 1160 7.2.6. Get Operation Structure 1162 In order to query the details of an object from the Registry, an 1163 authorized entity can send the spppGetRequest to the registry with a 1164 GetRqstType XML data structure containing one or more object keys 1165 that uniquely identify the object whose details are being queried. 1166 The request structure for an SPP Protocol over SOAP Get operation is 1167 contained within the generic element while an SPP 1168 Protocol over SOAP Get response is wrapped within the generic 1169 element. The following sub-sections describe the 1170 spppGetRequest and spppGetResponse element. Refer the examples 1171 section for an example of SPP Protocol over SOAP Get operation on 1172 each type of SPPF object 1174 7.2.6.1. Get Request 1176 1177 1178 1179 1181 1184 1185 1186 1188 The data elements within the element are described 1189 as follows: 1191 o minorVer: Zero or one minor version identifier, indicating the 1192 minor version of the SPPF API that the client is attempting to 1193 use. This is used in conjunction with the major version 1194 identifier in the XML namespace to identify the version of SPPF 1195 that the client is using. If the element is not present, the 1196 server assumes that the client is using the latest minor version 1197 supported by the SPPF server for the given major version. The 1198 versions supported by a given SPPF server can be retrieved by 1199 the client using the SPPF server menu operation described later 1200 in the document. 1202 o objKey: One or more elements of abstract type ObjKeyType (as 1203 defined in the framework document). Each element contains 1204 attributes that uniquely identify the object that the client is 1205 requesting the server to query. Refer the "Concrete Object 1206 Keys" section of this document for a description of all concrete 1207 object key types, for various SPPF objects, which are eligible 1208 to be passed into this element. 1210 7.2.6.2. Get Response 1212 The spppGetResponse element is described later in section titled 1213 "Generic Query Response". 1215 7.2.7. Get SED Group Offers Operation Structure 1217 In addition to the ability to query the details of one or more SED 1218 Group offers using an a SED Group Offer key in the spppGetRequest, 1219 this operation also provides an additional, more flexible, structure 1220 to query for SED Group Offer objects. This additional structure is 1221 contained within the element while the 1222 response is wrapped within the generic element. 1223 The following sub-sections describe the getSedGrpOffersRequest and 1224 spppGetResponse elements. 1226 7.2.7.1. Get SED Group Offers Request 1228 Using the details passed into this structure, the server will attempt 1229 to find SED Group Offer objects that satisfy all the criteria passed 1230 into the request. If no criteria is passed in then the server will 1231 return the list of SED Group Offer objects that belongs to the 1232 registrant. If there are no matching SED Group Offers found then an 1233 empty result set will be returned. 1235 1236 1237 1238 1240 1242 1244 1246 1248 1249 1250 1252 The data elements within the element are 1253 described as follows: 1255 o minorVer: Zero or one minor version identifier, indicating the 1256 minor version of the SPPF API that the client is attempting to 1257 use. This is used in conjunction with the major version 1258 identifier in the XML namespace to identify the version of SPPF 1259 that the client is using. If the element is not present, the 1260 server assumes that the client is using the latest minor version 1261 supported by the SPPF server for the given major version. The 1262 versions supported by a given SPPF server can be retrieved by 1263 the client using the SPPF server menu operation described later 1264 in the document. 1266 o offeredBy: Zero or more organization IDs. Only offers that are 1267 offered to the organization IDs in this list should be included 1268 in the result set. The result set is also subject to other 1269 query criteria in the request. 1271 o offeredTo: Zero or more organization IDs. Only offers that are 1272 offered by the organization IDs in this list should be included 1273 in the result set. The result set is also subject to other 1274 query criteria in the request. 1276 o status: The status of the offer, offered or accepted. Only 1277 offers in the specified status should be included in the result 1278 set. If this element is not present then the status of the 1279 offer should not be considered in the query. The result set is 1280 also subject to other query criteria in the request. 1282 o sedGrpOfferKey: Zero or more SED Group Offer Keys. Only offers 1283 having one of these keys should be included in the result set. 1284 The result set is also subject to other query criteria in the 1285 request. 1287 7.2.7.2. Get SED Group Offers Response 1289 The spppGetResponse element is described later in section titled 1290 "Generic Query Response". 1292 7.2.8. Generic Query Response 1294 An SPP Protocol over SOAP query response object is contained within 1295 the generic element. 1297 1298 1299 1300 1302 1305 1307 1308 1310 An contains the elements necessary for the SPPF 1311 client to precisely determine the overall result of the query, and 1312 details of any SPPF objects that matched the criteria in the request. 1314 The data elements within the SPP Protocol over SOAP query response 1315 are described as follows: 1317 o overallResult: Exactly one response code and message pair that 1318 explicitly identifies the result of the request. See the 1319 Response Code section for further details. 1321 o resultObj: The set of zero or more objects that matched the 1322 query criteria. If no objects matched the query criteria then 1323 the result object(s) MUST be empty and the overallResult value 1324 MUST indicate success (if no matches are found for the query 1325 criteria, the response is considered a success). 1327 7.2.9. Get Server Details Operation Structure 1329 In order to query certain details of the SPPF server, like the SPPF 1330 server's status and the major/minor version supported by the server, 1331 the Server Details operation structure SHOULD be used. This 1332 structure is contained within the element 1333 while a SPPF server status response is wrapped within the 1334 element. This following sub-sections 1335 describe the spppServerStatusRequest and spppServerStatusResponse 1336 elements. 1338 7.2.9.1. Get Server Details Request 1340 1341 1342 1343 1345 1346 1347 1349 The data elements within the element are 1350 described as follows: 1352 o minorVer: Zero or one minor version identifier, indicating the 1353 minor version of the SPP Protocol over SOAP API that the client 1354 is attempting to use. This is used in conjunction with the 1355 major version identifier in the XML namespace to identify the 1356 version of SPP Protocol over SOAP that the client is using. If 1357 the element is not present, the server assumes that the client 1358 is using the latest minor version of SPP Protocol over SOAP 1359 supported by the SPPF server for the given major version. The 1360 versions of SPP Protocol over SOAP supported by a given SPPF 1361 server can be retrieved by the client using this same 1362 spppServerStatusRequest without passing in the minorVer element. 1364 7.2.9.2. Get Server Details Response 1366 An SPP Protocol over SOAP server details response structure is 1367 contained within the generic element. 1369 1370 1371 1372 1373 1374 1375 1376 1378 The data elements within the element are 1379 described as follows: 1381 o overallResult: Exactly one response code and message pair that 1382 explicitly identifies the result of the request. See the 1383 Response Code section for further details. 1385 o svcMenu: Exactly one element of type SvcMenuType which in turn 1386 contains the elements to return the server status and major/ 1387 minor version of the SPP Protocol over SOAP supported by the 1388 SPPF server (refer framework document for definition of 1389 SvcMenuType) . 1391 7.3. Response Codes and Messages 1393 This section contains the listing of response codes and their 1394 corresponding human-readable text. These response codes are in 1395 conformance with the response types defined in the section "Response 1396 Message Types" of the framework document. 1398 The response code numbering scheme generally adheres to the theory 1399 formalized in section 4.2.1 of [RFC5321]: 1401 o The first digit of the response code can only be 1 or 2: 1 = a 1402 positive result, 2 = a negative result. 1404 o The second digit of the response code indicates the category: 0 1405 = Protocol Syntax, 1 = Implementation Specific Business Rule, 2 1406 = Security, 3 = Server System. 1408 o The third and fourth digits of the response code indicate the 1409 individual message event within the category defines by the 1410 first two digits. 1412 The response codes are also categorized as to whether they are 1413 overall response codes that may only be returned in the 1414 "overallResult" data element in SPPF responses, or object level 1415 response codes that may only be returned in the "detailResult" 1416 element of the SPPF responses. 1418 +--------+--------------------------+-------------------------------+ 1419 | Result | Result Message | Overall or Object Level | 1420 | Code | | | 1421 +--------+--------------------------+-------------------------------+ 1422 | 1000 | Request Succeeded. | Overall Response Code | 1423 | | | | 1424 | 2000 | Request syntax invalid. | Overall Response Code | 1425 | | | | 1426 | 2001 | Request too large. | Overall Response Code | 1427 | | MaxSupported:[Maximum | | 1428 | | requests supported] | | 1429 | | | | 1430 | 2002 | Version not supported. | Overall Response Code | 1431 | | | | 1432 | 2100 | Command invalid. | Overall Response Code | 1433 | | | | 1434 | 2300 | System temporarily | Overall Response Code | 1435 | | unavailable. | | 1436 | | | | 1437 | 2301 | Unexpected internal | Overall Response Code | 1438 | | system or server error. | | 1439 | | | | 1440 | 2101 | Attribute value invalid. | Object Level Response Code | 1441 | | | | 1442 | | AttrName:[AttributeName] | | 1443 | | AttrVal:[AttributeValue] | | 1444 | | | | 1445 | 2102 | Object does not exist. | Object Level Response Code | 1446 | | AttrName:[AttributeName] | | 1447 | | AttrVal:[AttributeValue] | | 1448 | | | | 1449 | 2103 | Object status or | Object Level Response Code | 1450 | | ownership does not allow | | 1451 | | for operation. | | 1452 | | AttrName:[AttributeName] | | 1453 | | AttrVal:[AttributeValue] | | 1454 +--------+--------------------------+-------------------------------+ 1456 Table 1: Response Codes Numbering Scheme and Messages 1458 Response message for response code 2001 is "parameterized" with the 1459 following parameter: "[Maximum requests supported]". When the 1460 request is too large, this parameter MUST be used to indicate the 1461 maximum number of requests supported by the server in a single 1462 protocol operation. 1464 Each of the object level response messages are "parameterized" with 1465 the following parameters: "AttributeName" and "AttributeValue". 1467 For example, if an SPPF client sends a request to delete a 1468 Destination Group with a name "TestDG", and it does not already 1469 exist, then the error message returned should be: "Attribute value 1470 invalid. AttrName:dgName AttrVal:TestDG". 1472 The use of these parameters MUST adhere to the rules defined in 1473 "Response Message Types" section of the framework document. 1475 8. Protocol Operations 1477 Refer the "Framework Operations" section of the framework document 1478 for a description of all SPPF operations, and any necessary semantics 1479 that MUST be adhered to in order to conform with the SPPF 1480 specification. 1482 9. SPP Protocol over SOAP WSDL Definition 1484 The SPP Protocol over SOAP WSDL and data types are defined below. 1485 The WSDL design approach is commonly referred to as _Generic WSDL_. 1486 It is generic in the sense that there is not a specific WSDL 1487 operation defined for each object type that is supported by the SPPF 1488 protocol. There is a single WSDL structure for each type of SPPF 1489 operation. Each such WSDL structure contains exactly one input 1490 structure and one output structure that wraps any data elements that 1491 are part of the incoming request and the outgoing response 1492 respectively. The spppSOAPBinding in the WSDL defines the binding 1493 style as _document_ and the encoding as _literal_. It is this 1494 combination of _wrapped_ input and output data structures, _document_ 1495 binding style, and _literal_ encoding that characterize the Document 1496 Literal Wrapped style of WSDL specifications. 1498 Note: The following WSDL has been formatted (e.g., tabs, spaces) to 1499 meet I-D requirements. 1501 1502 1509 1510 1513 1514 1515 ---- Import base schema ---- 1516 1517 1518 1520 1521 1522 ---- Key type(s) extended 1523 from base schema. ---- 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1546 1547 1548 1549 1550 1552 1554 1555 1556 1557 1559 1560 1561 1562 1563 1564 1566 1567 1569 1571 1572 1573 1574 1575 1576 1577 1578 ---- Generic Request and 1579 Response Definitions ---- 1580 1581 1582 1583 1584 1585 1587 1589 1591 1592 1593 1594 1595 1596 1597 1599 1601 1603 1604 1605 1606 1607 1608 1609 1611 1613 1616 1617 1618 1619 1620 1621 1622 1624 1626 1629 1630 1631 1632 1633 1634 1635 1637 1640 1641 1642 1643 1644 1645 1646 1648 1650 1651 1652 1653 1655 1657 1658 1659 1660 1661 1662 1663 1664 1666 1667 1668 1669 1670 1671 1672 1674 1677 1679 1681 1684 1685 1686 1687 1688 1689 1690 1692 1694 1696 1699 1700 1701 1702 1703 1704 1705 1707 1709 1711 1714 1715 1716 1717 1718 1719 1720 1722 1724 1726 1729 1730 1731 1732 1733 1734 1735 1737 1739 1741 1744 1745 1746 1747 1748 1749 1750 1752 1754 1756 1757 1759 1761 1763 1765 1766 1767 1769 1770 1771 1772 1773 1775 1778 1779 1780 1781 1782 1783 1784 1786 1788 1789 1790 1791 1792 1793 ---- Operation Result Type 1794 Definitions ---- 1795 1796 1797 1798 1799 1800 1801 1802 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1818 1820 1821 1822 1823 1824 1825 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1997 1998 1999 2000 2001 2002 2003 2004 2005 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2022 Figure 2: WSDL 2024 10. SPP Protocol over SOAP Examples 2026 This section shows XML message exchange between two SIP Service 2027 Providers (SSP) and a registry. The messages in this section are 2028 valid XML instances that conform to the SPP Protocol over SOAP schema 2029 version within this document. This section relies on the XML data 2030 structures defined in the base SPPF specification 2031 [I-D.draft-ietf-drinks-spp-framework]. So refer to that document to 2032 understand XML object types embedded in these example messages. 2034 In this sample use case scenario, SSP1 and SSP2 provision resource 2035 data in the registry and use SPPF constructs to selectively share the 2036 SED groups. In the figure below, SSP2 has two ingress SBE instances 2037 that are associated with the public identities that SSP2 has the 2038 retail relationship with. Also, the two SBE instances for SSP1 are 2039 used to show how to use SPPF to associate route preferences for the 2040 destination ingress routes and exercise greater control on outbound 2041 traffic to the peer's ingress SBEs. 2043 ---------------+ +------------------ 2044 | | 2045 +------+ +------+ 2046 | sbe1 | | sbe2 | 2047 +------+ +------+ 2048 SSP1 | | SSP2 2049 +------+ +------+ 2050 | sbe3 | | sbe4 | 2051 +------+ +------+ 2052 iana-en:111 | | iana-en:222 2053 ---------------+ +------------------ 2054 | | 2055 | | 2056 | SPPF +------------------+ SPPF | 2057 +------->| Registry |<--------+ 2058 +------------------+ 2060 10.1. Add Destination Group 2062 SSP2 adds a destination group to the registry for use later. The 2063 SSP2 SPPF client sets a unique transaction identifier 'txn_1479' for 2064 tracking purposes. The name of the destination group is set to 2065 DEST_GRP_SSP2_1 2066 2067 2072 2073 2074 2075 2076 txn_1479 2077 2078 2079 iana-en:222 2080 iana-en:223 2081 DEST_GRP_SSP2_1 2082 2083 2084 2085 2087 The registry processes the request and return a favorable response 2088 confirming successful creation of the named destination group. Also, 2089 besides returning a unique server transaction identifier, Registry 2090 also returns the matching client transaction identifier from the 2091 request message back to the SPPF client. 2093 2094 2096 2097 2100 txn_1479 2101 tx_12345 2102 2103 1000 2104 Request Succeeded. 2105 2106 2107 2108 2110 10.2. Add SED Records 2112 SSP2 adds SED records in the form of ingress routes to the registry. 2114 2115 2120 2121 2122 2123 2124 txn_1479 2125 2126 2127 iana-en:222 2128 iana-en:223 2129 SED_SSP2_SBE2 2130 true 2131 10 2132 u 2133 E2U+sip 2134 2135 ^(.*)$ 2136 sip:\1@sbe2.ssp2.example.com 2137 2138 2139 2140 2141 2143 The registry returns a success response. 2145 2146 2148 2149 2152 txn_1479 2153 tx_12345 2154 2155 1000 2156 Request Succeeded. 2157 2158 2159 2160 2162 10.3. Add SED Records -- URIType 2164 SSP2 adds another SED record to the registry and makes use of URIType 2166 2167 2172 2173 2174 2175 txn_1479 2176 2177 2178 iana-en:222 2179 iana-en:223 2180 SED_SSP2_SBE4 2181 true 2182 ^(.*)$ 2183 sip:\1;npdi@sbe4.ssp2.example.com 2184 2185 2186 2187 2188 The registry returns a success response. 2190 2191 2192 2193 2196 txn_1479 2197 tx_12345 2198 2199 1000 2200 Request Succeeded. 2201 2202 2203 2204 2206 10.4. Add SED Group 2208 SSP2 creates the grouping of SED records (e.g. ingress routes) and 2209 chooses higher precedence for SED_SSP2_SBE2 by setting a lower number 2210 for the "priority" attribute, a protocol agnostic precedence 2211 indicator. 2213 2214 2219 2220 2221 2222 txn_1479 2223 2224 2225 iana-en:222 2226 iana-en:223 2227 SED_GRP_SSP2_1 2228 2229 2230 iana-en:222 2231 SED_SSP2_SBE2 2232 SedRec 2233 2234 100 2235 2236 DEST_GRP_SSP2_1 2237 true 2238 10 2239 2240 2241 2242 2244 To confirm successful processing of this request, registry returns a 2245 well-known result code '1000' to the SSP2 client. 2247 2248 2249 2250 2253 txn_1479 2254 tx_12345 2255 2256 1000 2257 Request Succeeded. 2258 2259 2260 2261 2263 10.5. Add Public Identity -- Successful COR claim 2265 SSP2 activates a TN public identity by associating it with a valid 2266 destination group. Further, SSP2 puts forth a claim that it is the 2267 carrier-of-record for the TN. 2269 2274 2275 2276 2277 txn_1479 2278 2279 2280 iana-en:222 2281 iana-en:223 2282 DEST_GRP_SSP2_1 2283 +12025556666 2284 2285 true 2286 2287 2288 2289 2290 2291 Assuming that the registry has access to TN authority data and it 2292 performs the required checks to verify that SSP2 is in fact the 2293 service provider of record for the given TN, the request is processed 2294 successfully. In the response message, the registry sets the value 2295 of to "true" in order to confirm SSP2 claim as the carrier of 2296 record and the reflects the time when the carrier of record 2297 claim is processed. 2299 2300 2303 2304 2307 txn_1479 2308 tx_12345 2309 2310 1000 2311 Request Succeeded. 2312 2313 2314 1000 2315 Request Succeeded. 2316 2317 iana-en:222 2318 iana-en:223 2319 2010-05-30T09:30:10Z 2320 DEST_GRP_SSP2_1 2321 +12025556666 2322 2323 true 2324 true 2325 2010-05-30T09:30:11Z 2326 2327 2328 2329 2330 2331 2333 10.6. Add LRN 2335 If another entity that SSP2 shares session establishment information 2336 (e.g. routes) with has access to Number Portability data, it may 2337 choose to perform route lookups by routing number. Therefore, SSP2 2338 associates a routing number to a destination group in order to 2339 facilitate ingress route discovery. 2341 2342 2347 2348 2349 2350 txn_1479 2351 2352 2353 iana-en:222 2354 iana-en:223 2355 DEST_GRP_SSP2_1 2356 2025550000 2357 2358 2359 2360 2362 Registry completes the request successfully and returns a favorable 2363 response to the SPPF client. 2365 2366 2368 2369 2372 txn_1479 2373 tx_12345 2374 2375 1000 2376 Request Succeeded. 2377 2378 2379 2380 2382 10.7. Add TN Range 2384 Next, SSP2 activates a block of ten thousand TNs and associate it to 2385 a destination group. 2387 2388 2393 2394 2395 2396 txn_1479 2397 2398 2399 iana-en:222 2400 iana-en:223 2401 DEST_GRP_SSP2_1 2402 2403 +12026660000 2404 +12026669999 2405 2406 2407 2408 2409 2410 Registry completes the request successfully and returns a favorable 2411 response. 2413 2414 2416 2417 2420 txn_1479 2421 tx_12345 2422 2423 1000 2424 Request Succeeded. 2425 2426 2427 2428 2430 10.8. Add TN Prefix 2432 Next, SSP2 activates a block of ten thousand TNs using the TNPType 2433 structure and identifying a TN prefix. 2435 2436 2441 2442 2443 2444 txn_1479 2445 2446 2447 iana-en:222 2448 iana-en:223 2449 DEST_GRP_SSP2_1 2450 +1202777 2451 2452 2454 2455 2457 Registry completes the request successfully and returns a favorable 2458 response. 2460 2461 2463 2464 2467 txn_1479 2468 tx_12345 2469 2470 1000 2471 Request Succeeded. 2472 2473 2474 2475 2477 10.9. Enable Peering -- SED Group Offer 2479 In order for SSP1 to complete session establishment for a destination 2480 TN where the target subscriber has a retail relationship with SSP2, 2481 it first requires an asynchronous bi-directional handshake to show 2482 mutual consent. To start the process, SSP2 initiates the peering 2483 handshake by offering SSP1 access to its SED group. 2485 2486 2491 2492 2493 2494 txn_1479 2495 2496 2497 iana-en:222 2498 iana-en:223 2499 2500 2501 iana-en:222 2502 SED_GRP_SSP2_1 2503 SedGrp 2504 2505 iana-en:111 2506 2507 offered 2508 2509 2006-05-04T18:13:51.0Z 2510 2511 2512 2513 2514 2516 Registry completes the request successfully and confirms that the 2517 SSP1 will now have the opportunity to weigh in on the offer and 2518 either accept or reject it. The registry may employ out-of-band 2519 notification mechanisms for quicker updates to SSP1 so they can act 2520 faster, though this topic is beyond the scope of this document. 2522 2523 2525 2526 2529 txn_1479 2530 tx_12345 2531 2532 1000 2533 Request Succeeded. 2534 2535 2536 2537 2539 10.10. Enable Peering -- SED Group Offer Accept 2541 SSP1 responds to the offer from SSP2 and agrees to have visibility to 2542 SSP2 session establishment information (e.g. ingress routes). 2544 2545 2548 2549 2550 2551 2552 txn_1479 2553 2554 2555 2556 iana-en:222 2557 SED_GRP_SSP2_1 2558 SedGrp 2559 2560 iana-en:111 2561 2562 2563 2564 2565 Registry confirms that the request has been processed successfully. 2566 From this point forward, if SSP1 looks up a public identity through 2567 the query resolution server, where the public identity is part of the 2568 destination group by way of "SED_GRP_SSP2_1" session establishment 2569 data association, SSP2 ingress SBE information will be shared with 2570 SSP1. 2572 2573 2575 2576 2579 txn_1479 2580 tx_12350 2581 2582 1000 2583 Request Succeeded. 2584 2585 2586 2587 2589 10.11. Add Egress Route 2591 SSP1 wants to prioritize all outbound traffic to the ingress route 2592 associated with the "SED_GRP_SSP2_1" SED Group record, through 2593 "sbe1.ssp1.example.com". 2595 2596 2601 2602 2603 2604 txn_1479 2605 2606 2607 iana-en:222 2608 iana-en:223 2609 EGR_RTE_01 2610 50 2611 2612 ^(.*@)(.*)$ 2613 \1\2?route=sbe1.ssp1.example.com 2614 2615 2616 iana-en:222 2617 SED_GRP_SSP2_1 2618 SedGrp 2619 2620 2621 2622 2623 2625 Since peering has already been established, the request to add the 2626 egress route has been successfully completed. 2628 2629 2631 2632 2635 txn_1479 2636 tx_12345 2637 2638 1000 2639 Request Succeeded. 2640 2641 2642 2643 2645 10.12. Remove Peering -- SED Group Offer Reject 2647 SSP1 had earlier accepted to have visibility to SSP2 session 2648 establishment data. SSP1 now decides to no longer maintain this 2649 visibility and hence rejects the SED Group Offer. 2651 2652 2655 2656 2657 2658 2659 txn_1479 2660 2661 2662 2663 iana-en:222 2664 SED_GRP_SSP2_1 2665 SedGrp 2666 2667 iana-en:111 2668 2669 2670 2671 2672 Registry confirms that the request has been processed successfully. 2673 From this point forward, if SSP1 looks up a public identity through 2674 the query resolution server, where the public identity is part of the 2675 destination group by way of "SED_GRP_SSP2_1" session establishment 2676 data association, SSP2 ingress SBE information will NOT be shared 2677 with SSP1 and hence SSP2 ingress SBE will NOT be returned in the 2678 query response. 2680 2681 2683 2684 2687 txn_1479 2688 tx_12350 2689 2690 1000 2691 Request Succeeded. 2692 2693 2694 2695 2697 10.13. Get Destination Group 2699 SSP2 uses the 'spppGetRequest' operation to tally the last 2700 provisioned record for destination group DEST_GRP_SSP2_1. 2702 2703 2707 2708 2709 2710 2711 2712 iana-en:222 2713 DEST_GRP_SSP2_1 2714 DestGrp 2715 2716 2717 2718 2720 Registry completes the request successfully and returns a favorable 2721 response. 2723 2724 2727 2728 2731 2732 1000 2733 success 2734 2735 2736 iana-en:222 2737 iana-en:223 2738 DEST_GRP_SSP2_1 2739 2740 2741 2742 2744 10.14. Get Public Identity 2746 SSP2 obtains the last provisioned record associated with a given TN. 2748 2749 2754 2755 2756 2757 2758 2759 iana-en:222 2760 2761 +12025556666 2762 TN 2763 2764 2765 2766 2767 2769 Registry completes the request successfully and returns a favorable 2770 response. 2772 2775 2776 2779 2780 1000 2781 success 2782 2783 2784 iana-en:222 2785 iana-en:223 2786 DEST_GRP_SSP2_1 2787 +12025556666 2788 2789 true 2790 true 2791 2010-05-30T09:30:10Z 2792 2793 2794 2795 2796 2798 10.15. Get SED Group Request 2800 SSP2 obtains the last provisioned record for the SED group 2801 SED_GRP_SSP2_1. 2803 2804 2808 2809 2810 2811 2812 2813 iana-en:222 2814 SED_GRP_SSP2_1 2815 SedGrp 2816 2817 2818 2819 2821 Registry completes the request successfully and returns a favorable 2822 response. 2824 2825 2828 2829 2832 2833 1000 2834 success 2835 2836 2837 iana-en:222 2838 iana-en:223 2839 SED_GRP_SSP2_1 2840 2841 2842 iana-en:222 2843 SED_SSP2_SBE2 2844 SedRec 2845 2846 100 2847 2848 2849 2850 iana-en:222 2851 SED_SSP2_SBE4 2852 SedRec 2853 2854 101 2855 2856 DEST_GRP_SSP2_1 2857 true 2858 10 2859 2860 2861 2862 2864 10.16. Get SED Group Offers Request 2866 SSP2 fetches the last provisioned SED group offer to the 2867 SSP1. 2869 2870 2873 2874 2875 2876 iana-en:111 2877 2878 2879 2881 Registry processes the request successfully and returns a favorable 2882 response. 2884 2885 2888 2889 2892 2893 1000 2894 success 2895 2896 2897 iana-en:222 2898 iana-en:223 2899 2901 2902 iana-en:222 2903 SED_GRP_SSP2_1 2904 SedGrp 2905 2906 iana-en:111 2907 2908 offered 2909 2910 2006-05-04T18:13:51.0Z 2911 2912 2913 2915 2916 2918 10.17. Get Egress Route 2920 SSP1 wants to verify the last provisioned record for the egress route 2921 called EGR_RTE_01. 2923 2924 2928 2929 2930 2931 2932 2933 iana-en:111 2934 EGR_RTE_01 2935 EgrRte 2936 2937 2938 2939 2941 Registry completes the request successfully and returns a favorable 2942 response. 2944 2945 2948 2949 2952 2953 1000 2954 success 2955 2956 2957 iana-en:222 2958 iana-en:223 2959 EGR_RTE_01 2960 50 2961 2962 ^(.*)$ 2963 sip:\1@sbe1.ssp1.example.com 2964 2965 2966 iana-en:222 2967 SED_GRP_SSP2_1 2968 SedRec 2969 2970 2971 2972 2973 2975 10.18. Delete Destination Group 2977 SSP2 initiates a request to delete the destination group 2978 DEST_GRP_SSP2_1. 2980 2981 2985 2986 2987 2988 2989 2990 iana-en:222 2991 DEST_GRP_SSP2_1 2992 DestGrp 2993 2994 2995 2996 2998 Registry completes the request successfully and returns a favorable 2999 response. 3001 3002 3004 3005 3008 tx_12354 3009 3010 1000 3011 Request Succeeded. 3012 3013 3014 3015 3017 10.19. Delete Public Identity 3019 SSP2 chooses to de-activate the TN and remove it from the registry. 3021 3022 3027 3028 3029 3030 3031 3032 iana-en:222 3033 DEST_GRP_SSP2_1 3034 3035 +12025556666 3036 TN 3037 3038 3039 3040 3041 3043 Registry completes the request successfully and returns a favorable 3044 response. 3046 3047 3049 3050 3053 tx_12354 3054 3055 1000 3056 Request Succeeded. 3057 3058 3059 3060 3062 10.20. Delete SED Group Request 3064 SSP2 removes the SED group called SED_GRP_SSP2_1. 3066 3067 3071 3072 3073 3074 3075 3076 iana-en:222 3077 SED_GRP_SSP2_1 3078 SedGrp 3079 3080 3081 3082 3084 Registry completes the request successfully and returns a favorable 3085 response. 3087 3088 3090 3091 3094 tx_12354 3095 3096 1000 3097 Request Succeeded. 3098 3099 3100 3101 3103 10.21. Delete SED Group Offers Request 3105 SSP2 no longer wants to share SED group SED_GRP_SSP2_1 with SSP1. 3107 3108 3112 3113 3114 3115 3116 3117 3118 iana-en:222 3119 SED_GRP_SSP2_1 3120 SedGrp 3121 3122 iana-en:111 3123 3124 3125 3126 3128 Registry completes the request successfully and returns a favorable 3129 response. Restoring this resource sharing will require a new SED 3130 group offer from SSP2 to SSP1 followed by a successful SED group 3131 accept request from SSP1. 3133 3134 3136 3137 3140 tx_12354 3141 3142 1000 3143 Request Succeeded. 3144 3145 3147 3148 3150 10.22. Delete Egress Route 3152 SSP1 decides to remove the egress route with the label EGR_RTE_01. 3154 3155 3159 3160 3161 3162 3163 3164 iana-en:111 3165 EGR_RTE_01 3166 EgrRte 3167 3168 3169 3170 3172 Registry completes the request successfully and returns a favorable 3173 response. 3175 3176 3178 3179 3182 tx_12354 3183 3184 1000 3185 Request Succeeded. 3186 3187 3188 3190 3192 10.23. Batch Request 3194 Following is an example of how some of the operations mentioned in 3195 previous sections MAY be performed by an SPPF client as a batch in 3196 one single SPP Protocol over SOAP request. 3198 In the sample request below SSP1 wants to accept a SED Group Offer 3199 from SSP3, add a Destination Group, add a NAPTR SED Record, add a SED 3200 Group, add a SED Group Offer, delete a previously provisioned TN type 3201 Public Identifier, delete a previously provisioned SED Group, and 3202 reject a SED Group Offer from SSP4. 3204 3205 3210 3211 3212 3213 txn_1467 3214 1 3216 3217 3218 iana-en:225 3219 SED_SSP3_SBE1_Offered 3220 SedGrp 3221 3222 iana-en:222 3223 3225 3226 iana-en:222 3227 iana-en:223 3228 DEST_GRP_SSP2_1 3229 3231 3232 iana-en:222 3233 iana-en:223 3234 SED_SSP2_SBE2 3235 10 3236 u 3237 E2U+sip 3238 3239 ^(.*)$ 3240 sip:\1@sbe2.ssp2.example.com 3241 3242 3244 3245 iana-en:222 3246 iana-en:223 3247 SED_GRP_SSP2_1 3248 3249 3250 iana-en:222 3251 SED_SSP2_SBE2 3252 SedRec 3253 3254 100 3255 3256 DEST_GRP_SSP2_1 3257 true 3258 10 3259 3261 3262 iana-en:222 3263 iana-en:223 3264 3265 3266 iana-en:222 3267 SED_GRP_SSP2_1 3268 SedGrp 3269 3270 iana-en:111 3271 3272 offered 3273 3274 2006-05-04T18:13:51.0Z 3275 3276 3278 3279 iana-en:222 3280 3281 3282 +12025556666 3283 TN 3284 3285 3287 3288 iana-en:222 3289 SED_GRP_SSP2_Previous 3290 SedGrp 3291 3293 3294 3295 iana-en:226 3296 SED_SSP4_SBE1_Offered 3297 SedGrp 3298 3299 iana-en:222 3300 3302 3303 3304 3306 Registry completes the request successfully and returns a favorable 3307 response. 3309 3310 3312 3313 3316 tx_12354 3317 3318 1000 3319 Request Succeeded. 3320 3321 3322 3323 3325 11. Security Considerations 3327 SPP Protocol over SOAP is used to query and update session peering 3328 data and addresses, so the ability to access this protocol should be 3329 limited to users and systems that are authorized to query and update 3330 this data. Because this data is sent in both directions, it may not 3331 be sufficient for just the client or user to be authenticated with 3332 the server. The identity of the server should also be authenticated 3333 by the client, which is often accomplished using the TLS certificate 3334 exchange and validation described in [RFC2818]. SPP Protocol over 3335 SOAP messages may include sensitive information, routing data, lists 3336 of resolvable addresses, etc. So when used in a production setting 3337 and across non-secure networks, SPP Protocol over SOAP should only be 3338 used over communications channels that provide strong encryption for 3339 data privacy. 3341 11.1. Integrity, Privacy, and Authentication 3343 The SPP Protocol over SOAP binding relies on an underlying secure 3344 transport for integrity and privacy. Such transports are expected to 3345 include TLS/HTTPS. In addition to the application level 3346 authentication imposed by an SPPF server, there are a number of 3347 options for authentication within the transport layer and the 3348 messaging envelope. These include TLS client certificates, HTTP 3349 Digest Access Authentication, and digital signatures within SOAP 3350 headers. 3352 At a minimum, all conforming SPP Protocol over SOAP implementations 3353 MUST support HTTPS. 3355 11.2. Vulnerabilities 3357 The above protocols may have various vulnerabilities, and these may 3358 be inherited by SPP Protocol over SOAP. SPP Protocol over SOAP 3359 itself may have vulnerabilities because an authorization model is not 3360 explicitly specified in the current specification. 3362 Sections 5 and 10.1 describe requirements for HTTPS support using 3363 TLS. Non-anonymous TLS servers can optionally request a certificate 3364 from a TLS client; that option is not a requirement for this 3365 protocol. This presents a denial of service risk in which 3366 unauthenticated clients can consume server CPU resources by creating 3367 TLS sessions. The risk is increased if the server supports client- 3368 initiated renegotiation. This risk can be mitigated by disabling 3369 client-initiated renegotiation on the server and by ensuring that 3370 other means (such as firewall access control lists) are used to 3371 restrict unauthenticated client access to servers. 3373 In conjunction with the above, it is important that SPP Protocol over 3374 SOAP implementations implement an authorization model that considers 3375 the source of each query or update request and determines whether it 3376 is reasonable to authorize that source to perform that specific query 3377 or update. 3379 11.3. Deployment Environment Specifics 3381 Some deployments of SPP Protocol over SOAP could choose to use 3382 transports without encryption. This presents vulnerabilities but 3383 could be selected for deployments involving closed networks or 3384 debugging scenarios. However, the vulnerabilities of such a 3385 deployment could be a lack of integrity and privacy of the data 3386 transported in this type of deployment. 3388 12. IANA Considerations 3390 This document uses URNs to describe XML namespaces and XML schemas 3391 conforming to a registry mechanism described in [RFC3688]. 3393 URN assignments requested are: urn:ietf:params:xml:ns:sppf:soap:1 3395 13. Acknowledgements 3397 This document is a result of various discussions held by the DRINKS 3398 design team, with contributions from the following individuals, in 3399 alphabetical order: Alexander Mayrhofer, David Schwartz, Deborah A 3400 Guyton, Jean-Francois Mule Kenneth Cartwright, Lisa Dusseault, Manjul 3401 Maharishi, Mickael Marrache, Otmar Lendl, Peter Saint-Andre, Richard 3402 Shockey, Samuel Melloul, Scott Hollenbeck, Sumanth Channabasappa, 3403 Syed Ali, and Vikas Bhatia . 3405 14. References 3407 14.1. Normative References 3409 [I-D.draft-ietf-drinks-spp-framework] 3410 Cartwright, K., Bhatia, V., Ali, S., and D. Schwartz, 3411 "Session Peering Provisioning Framework", 3412 draft-ietf-drinks-spp-framework-02 (work in progress), 3413 July 2012. 3415 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3416 Requirement Levels", BCP 14, RFC 2119, March 1997. 3418 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3419 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3420 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3422 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3423 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3424 Authentication: Basic and Digest Access Authentication", 3425 RFC 2617, June 1999. 3427 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3428 January 2004. 3430 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3431 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3433 [SOAPREF] Gudgin, M., Hadley, M., Moreau, J., and H. Nielsen, "SOAP 3434 Version 1.2 Part 1: Messaging Framework", W3C 3435 Recommendation REC-SOAP12-part1-20030624, June 2002. 3437 14.2. Informative References 3439 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3441 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 3442 October 2008. 3444 [W3C.REC-xml-20081126] 3445 Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E., 3446 and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth 3447 Edition)", World Wide Web Consortium Recommendation REC- 3448 xml-20081126, November 2008, 3449 . 3451 [WSDLREF] Christensen, E., Curbera, F., Meredith, G., and S. 3452 Weerawarana, "Web Services Description Language (WSDL) 3453 1.1", W3C Note NOTE-wsdl-20010315, March 2001. 3455 Authors' Addresses 3457 Kenneth Cartwright 3458 TNS 3459 1939 Roland Clarke Place 3460 Reston, VA 20191 3461 USA 3463 Email: kcartwright@tnsi.com 3465 Vikas Bhatia 3466 TNS 3467 1939 Roland Clarke Place 3468 Reston, VA 20191 3469 USA 3471 Email: vbhatia@tnsi.com 3473 Jean-Francois Mule 3474 CableLabs 3475 858 Coal Creek Circle 3476 Louisville, CO 80027 3477 USA 3479 Email: jfm@cablelabs.com 3481 Alexander Mayrhofer 3482 enum.at GmbH 3483 Karlsplatz 1/9 3484 Wien, A-1010 3485 Austria 3487 Email: alexander.mayrhofer@enum.at