idnits 2.17.1 draft-ietf-drinks-spp-protocol-over-soap-05.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 (October 21, 2013) is 3834 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) == Missing Reference: 'THISDOCUMENT' is mentioned on line 3365, but not defined == Outdated reference: A later version (-12) exists of draft-ietf-drinks-spp-framework-06 ** 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 (~~), 3 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: April 24, 2014 J-F. Mule 6 CableLabs 7 A. Mayrhofer 8 enum.at GmbH 9 October 21, 2013 11 Session Peering Provisioning (SPP) Protocol over SOAP 12 draft-ietf-drinks-spp-protocol-over-soap-05 14 Abstract 16 The Session Peering Provisioning Framework (SPPF) specifies the data 17 model and the overall structure to provision session establishment 18 data into Session Data Registries and SIP Service Provider data 19 stores. To utilize this framework one needs a transport protocol. 20 Given that Simple Object Access Protocol (SOAP) is currently widely 21 used for messaging between elements of such provisioning systems, 22 this document specifies the usage of SOAP (via HTTPS) as the 23 transport protocol for SPPF. The benefits include leveraging 24 prevalent expertise, and a higher probability that existing 25 provisioning systems will be able to easily migrate to using an SPPF 26 based protocol. 28 Status of This Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. 33 Internet-Drafts are working documents of the Internet Engineering 34 Task Force (IETF). Note that other groups may also distribute 35 working documents as Internet-Drafts. The list of current Internet- 36 Drafts is at http://datatracker.ietf.org/drafts/current/. 38 Internet-Drafts are draft documents valid for a maximum of six months 39 and may be updated, replaced, or obsoleted by other documents at any 40 time. It is inappropriate to use Internet-Drafts as reference 41 material or to cite them other than as "work in progress." 43 This Internet-Draft will expire on April 24, 2014. 45 Copyright Notice 47 Copyright (c) 2013 IETF Trust and the persons identified as the 48 document authors. All rights reserved. 50 This document is subject to BCP 78 and the IETF Trust's Legal 51 Provisions Relating to IETF Documents 52 (http://trustee.ietf.org/license-info) in effect on the date of 53 publication of this document. Please review these documents 54 carefully, as they describe your rights and restrictions with respect 55 to this document. Code Components extracted from this document must 56 include Simplified BSD License text as described in Section 4.e of 57 the Trust Legal Provisions and are provided without warranty as 58 described in the Simplified BSD License. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. SOAP Features and Protocol Layering . . . . . . . . . . . . . 4 65 4. HTTP(s) Features and SPP Protocol over SOAP . . . . . . . . . 6 66 5. Authentication, Integrity and Confidentiality . . . . . . . . 7 67 6. Language Identification . . . . . . . . . . . . . . . . . . . 7 68 7. SPP Protocol SOAP Data Structures . . . . . . . . . . . . . . 7 69 7.1. Concrete Object Key Types . . . . . . . . . . . . . . . . 7 70 7.1.1. Generic Object Key . . . . . . . . . . . . . . . . . 8 71 7.1.2. Public Identity Object Key . . . . . . . . . . . . . 9 72 7.1.3. SED Group Offer Key . . . . . . . . . . . . . . . . . 10 73 7.2. Operation Request and Response Structures . . . . . . . . 11 74 7.2.1. Add Operation Structure . . . . . . . . . . . . . . . 11 75 7.2.2. Delete Operation Structure . . . . . . . . . . . . . 14 76 7.2.3. Accept Operation Structure . . . . . . . . . . . . . 17 77 7.2.4. Reject Operation Structure . . . . . . . . . . . . . 20 78 7.2.5. Batch Operation Structure . . . . . . . . . . . . . . 23 79 7.2.6. Get Operation Structure . . . . . . . . . . . . . . . 26 80 7.2.7. Get SED Group Offers Operation Structure . . . . . . 27 81 7.2.8. Generic Query Response . . . . . . . . . . . . . . . 29 82 7.2.9. Get Server Details Operation Structure . . . . . . . 29 83 7.3. Response Codes and Messages . . . . . . . . . . . . . . . 31 84 8. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 33 85 9. SPP Protocol over SOAP WSDL Definition . . . . . . . . . . . 33 86 10. SPP Protocol over SOAP Examples . . . . . . . . . . . . . . . 44 87 10.1. Add Destination Group . . . . . . . . . . . . . . . . . 45 88 10.2. Add SED Records . . . . . . . . . . . . . . . . . . . . 46 89 10.3. Add SED Records -- URIType . . . . . . . . . . . . . . . 48 90 10.4. Add SED Group . . . . . . . . . . . . . . . . . . . . . 49 91 10.5. Add Public Identity -- Successful COR claim . . . . . . 50 92 10.6. Add LRN . . . . . . . . . . . . . . . . . . . . . . . . 51 93 10.7. Add TN Range . . . . . . . . . . . . . . . . . . . . . . 53 94 10.8. Add TN Prefix . . . . . . . . . . . . . . . . . . . . . 54 95 10.9. Enable Peering -- SED Group Offer . . . . . . . . . . . 55 96 10.10. Enable Peering -- SED Group Offer Accept . . . . . . . . 56 97 10.11. Add Egress Route . . . . . . . . . . . . . . . . . . . . 57 98 10.12. Remove Peering -- SED Group Offer Reject . . . . . . . . 59 99 10.13. Get Destination Group . . . . . . . . . . . . . . . . . 60 100 10.14. Get Public Identity . . . . . . . . . . . . . . . . . . 61 101 10.15. Get SED Group Request . . . . . . . . . . . . . . . . . 62 102 10.16. Get SED Group Offers Request . . . . . . . . . . . . . . 64 103 10.17. Get Egress Route . . . . . . . . . . . . . . . . . . . . 65 104 10.18. Delete Destination Group . . . . . . . . . . . . . . . . 66 105 10.19. Delete Public Identity . . . . . . . . . . . . . . . . . 67 106 10.20. Delete SED Group Request . . . . . . . . . . . . . . . . 69 107 10.21. Delete SED Group Offers Request . . . . . . . . . . . . 70 108 10.22. Delete Egress Route . . . . . . . . . . . . . . . . . . 71 109 10.23. Batch Request . . . . . . . . . . . . . . . . . . . . . 72 110 11. Security Considerations . . . . . . . . . . . . . . . . . . . 74 111 11.1. Vulnerabilities . . . . . . . . . . . . . . . . . . . . 75 112 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 113 13. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 75 114 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 115 14.1. Normative References . . . . . . . . . . . . . . . . . . 76 116 14.2. Informative References . . . . . . . . . . . . . . . . . 76 117 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 77 119 1. Introduction 121 SPPF, defined in [I-D.draft-ietf-drinks-spp-framework], is best 122 supported by a transport and messaging infrastructure that is 123 connection oriented, request-response oriented, easily secured, 124 supports propagation through firewalls in a standard fashion, and 125 that is easily integrated into back-office systems. This is due to 126 the fact that the client side of SPPF is likely to be integrated with 127 organizations' operational support systems that facilitate 128 transactional provisioning of user addresses and their associated 129 session establishment data. While the server side of SPPF is likely 130 to reside in a separate organization's network, resulting in the SPPF 131 provisioning transactions traversing the Internet as they are 132 propagated from the SPPF client to the SPPF server. Given the 133 current state of industry practice and technologies, SOAP and HTTP(S) 134 are well suited for this type of environment. This document 135 describes the specification for transporting SPPF XML structures over 136 SOAP and HTTP(S). 138 The specification in this document for transporting SPPF XML 139 structures over SOAP and HTTP(s) is primarily comprised of five 140 subjects: (1) a description of any applicable SOAP features, (2) any 141 applicable HTTP features, (3) security considerations, and perhaps 142 most importantly, (4) the Web Services Description Language (WSDL) 143 definition for SPP Protocol over SOAP, and (5) "transport" specific 144 XML Schema type definitions 146 2. Terminology 148 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 149 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 150 document are to be interpreted as described in [RFC2119]. 152 3. SOAP Features and Protocol Layering 154 The list of SOAP features that are explicitly used and required for 155 SPP Protocol over SOAP are limited. Most SOAP features are not 156 necessary for SPPF. SPP Protocol over SOAP primarily uses SOAP 157 simply as a standard message envelope technology. The SOAP message 158 envelope is comprised of the SOAP header and body. As described in 159 the SOAP specifications [SOAPREF], the SOAP header can contain 160 optional, application specific, information about the message. The 161 SOAP body contains the SPPF message itself, whose structure is 162 defined by the combination of one of the WSDL operations defined in 163 this document and the SPPF XML data structures defined in this 164 document and the SPPF document. SPPF does not rely on any data 165 elements in the SOAP header. All relevant data elements are defined 166 in the SPPF XML schema described in 167 [I-D.draft-ietf-drinks-spp-framework] and the SPPF WSDL types 168 specification described in this document and in 169 [I-D.draft-ietf-drinks-spp-framework]. 171 WSDL is a widely standardized and adopted technology for defining the 172 top-level structures of the messages that are transported within the 173 body of a SOAP message. The WSDL definition for the SPPF SOAP 174 messages is defined later in this document, which imports by 175 reference the XML data types contained in the SPPF schema. The IANA 176 registry where the SPPF schema resides is described in the IETF XML 177 Registry [RFC3688]. 179 There are multiple structural styles that WSDL allows. The best 180 practice for this type of application is what is sometimes referred 181 to as the "document/literal wrapped style". This style is generally 182 regarded as an optimal approach that enhances maintainability, 183 comprehension, portability, and, to a certain extent, performance. 184 It is characterized by setting the soapAction binding style as 185 "document", the soapAction encoding style as "literal", and then 186 defining the SOAP messages to simply contain a single data element 187 that "wraps" a data structure containing all the required input or 188 output data elements. The figure below illustrates this high level 189 technical structure as conceptual layers 3 through 6. 191 +-------------+ 192 (1) | Transport |Example: 193 | 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 Section 7.3 of this document. 245 However, if a SOAP fault were to occur, perhaps due to failures in 246 the SOAP message handling layer of a SOAP library, the client 247 application should capture and handle the fault. Specifics on how to 248 handle such SOAP faults, if they should occur, will be specific to 249 the chosen SOAP implementation. 251 This document RECOMMENDS SOAP 1.2 [SOAPREF] or higher, and WSDL 1.1 252 [WSDLREF] or higher. 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 259 Section 4 ("Transport Protocol Requirements") of 260 [I-D.draft-ietf-drinks-spp-framework]. 262 As illustrated in the previous diagram, SPPF can be viewed as a set 263 of layers that collectively define the structure of an SPPF request 264 and response. Layers 1 and 2 represent the transport, envelope, and 265 authentication technologies. This document defines layers 3, 4, 5, 266 and 6 for SPP Protocol over SOAP. 268 1. Layer 1: The transport protocol layer represents the 269 communication mechanism between the client and server. SPPF can 270 be layered over any transport protocol that provides a set of 271 basic requirements defined in Section 4 of 272 [I-D.draft-ietf-drinks-spp-framework]. 274 2. Layer 2: The message envelope layer is optional, but can provide 275 features that are above the transport technology layer but below 276 the application messaging layer. Technologies such as HTTP and 277 SOAP are examples of messaging envelope technologies. 279 3. Layers 3,4,5,6: The operation and message layers provide 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 While SOAP is not tied to HTTP(S), 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. 295 Implementations compliant with this document MUST use HTTP 1.1 296 [RFC2616] or higher. Also, implementations SHOULD use persistent 297 connections. 299 5. Authentication, Integrity and Confidentiality 301 To accomplish authentication, conforming SPP Protocol over SOAP 302 Clients and Servers MUST use HTTP Digest Authentication as defined in 303 [RFC2617]. 305 To achieve integrity and privacy, conforming SPP Protocol over SOAP 306 Clients and Servers MUST support Transport Layer Security (TLS) as 307 defined in [RFC5246] as the secure transport mechanism. 309 6. Language Identification 311 Section 9 of [I-D.draft-ietf-drinks-spp-framework] requires transport 312 protocols to provide a mechanism to transmit language tags together 313 with human-readable messages. When conforming SPP Protocol SOAP 314 servers use such tagging, the XML "lang" attribute 315 ([W3C.REC-xml-20081126], Section 2.12) MUST be used. Clients MAY use 316 the HTTP "Accept-Language" header field (see Section 14.4 of 317 [RFC2616]) in order to indicate their language preference. 319 7. SPP Protocol SOAP Data Structures 321 SPP Protocol over SOAP uses a set of XML based data structures for 322 all the supported operations and any parameters that those operations 323 are applied to. As also mentioned earlier in this document, these 324 XML structures are envelope-independent and transport-independent. 325 Refer the "Protocol Operations" (Section 8) of this document for a 326 description of all the operations that MUST be supported. 328 The following sections describe the definition all the XML data 329 structures. 331 7.1. Concrete Object Key Types 332 Certain operations in SPPF require an object key that uniquely 333 identifies the object(s) on which a given operation needs to be 334 performed. SPPF defines the XML structure of the any such object key 335 in an abstract manner and delegates the concrete representation to 336 any conforming transport protocol. The following sub-sections define 337 the various types of concrete object key types used in various 338 operations in SPP Protocol over SOAP. 340 7.1.1. Generic Object Key 342 Most objects in SPP Protocol over SOAP are uniquely identified by the 343 attributes in the generic object key (Refer Section 5.2.1 "Generic 344 Object Key Type" of [I-D.draft-ietf-drinks-spp-framework] for 345 details). The concrete XML representation of ObjKeyType is as below: 347 348 349 350 351 352 353 354 355 356 357 359 The ObjKeyType has the data elements as described below: 361 o rant: The identifier of the registrant organization that owns the 362 object. 364 o name: The character string that contains the name of the object. 366 o type: The enumeration value that represents the type of SPPF 367 object. For example, both a Destination Group and a SED Group can 368 have the same name "TestObj" and be associated with same 369 Registrant Id. Hence, to uniquely identify the object that 370 represents a Destination Group with the name "TestObj", the type 371 "DestGrp" must be specified when using this concrete ObjKeyType 372 structure to identify the Destination Group "TestObj". 374 The object types in SPP Protocol over SOAP MUST adhere to the above 375 definition of generic object key, and are defined as an enumeration 376 in the XML data structure as follows: 378 379 380 381 382 383 384 385 387 7.1.2. Public Identity Object Key 389 Public Identity type objects can further be of various sub-types like 390 a Telephone Number (TN), Routing Number (RN), TN Prefix, URI, or a TN 391 Range and cannot be cleanly identified with the attributes in the 392 generic ObjKeyType. The definition of PubIdKeyType is as below: 394 395 396 397 398 399 400 402 404 406 407 408 409 410 412 The PubIdKeyType has data elements, as described below: 414 o rant: The identifier of the registrant organization that owns the 415 object. 417 o number: An element of type NumberType (refer Section 12 of 418 [I-D.draft-ietf-drinks-spp-framework]) that contains the value and 419 type of a number . 421 o range: An element of type NumberRangeType (refer Section 12 of 422 [I-D.draft-ietf-drinks-spp-framework]) that contains a range of 423 numbers. 425 o uri: A value that represents a Public Identifier. 427 Any instance of PubIdKeyType MUST contain exactly one element from 428 the following set of elements: "number", "range", "uri". 430 7.1.3. SED Group Offer Key 432 In addition to the attributes in the generic ObjKeyType, a SED Group 433 Offer object is uniquely identified by the organization ID of the 434 organization to whom an SED Group has been offered. The definition 435 of SedGrpOfferKeyType is as below: 437 438 439 440 441 442 443 444 445 446 448 The SedGrpOfferKeyType has the data elements as described below: 450 o sedGrpKey: Identifies the SED Group that was offered. 452 o offeredTo: The organization ID of the organization that was 453 offered the SED Group object identified by the sedGrpKey. 455 7.2. Operation Request and Response Structures 457 An SPPF client interacts with an SPPF server by sending one or more 458 requests to the server, and by receiving corresponding responses from 459 the server. The basic set of operations that an SPPF client can 460 submit to an SPPF server and the semantics of those operations are 461 defined in Section 7 ("Framework Operations") of 462 [I-D.draft-ietf-drinks-spp-framework]. The following sub-sections 463 describe the XML data structures that are used for each of those 464 types of operations for a SPP Protocol over SOAP implementation. 466 7.2.1. Add Operation Structure 468 In order to add (or modify) an object in the registry, an authorized 469 entity can send the spppAddRequest to the registry. 471 An SPP Protocol over SOAP Add request is wrapped within the 472 element while an SPP Protocol over SOAP Add response 473 is wrapped within an element. The following sub- 474 sections describe the spppAddRequest and spppAddResponse elements. 475 Refer to Section 10 for an example of Add operation on each type of 476 SPPF object. 478 7.2.1.1. Add Request 480 An SPP Protocol over SOAP Add request definition is contained within 481 the generic element. 483 484 485 486 488 490 492 493 494 496 The data elements within the element are described 497 as follows: 499 o clientTransId: Zero or one client-generated transaction ID that, 500 within the context of the SPPF client, identifies this request. 501 This value can be used at the discretion of the SPPF client to 502 track, log or correlate requests and their responses. SPPF server 503 MUST echo back this value to the client in the corresponding 504 response to the incoming request. SPPF server will not check this 505 value for uniqueness. 507 o minorVer: Zero or one minor version identifier, indicating the 508 minor version of the SPPF API that the client is attempting to 509 use. This is used in conjunction with the major version 510 identifier in the XML namespace to identify the version of SPPF 511 that the client is using. If the element is not present, the 512 server assumes that the client is using the latest minor version 513 supported by the SPPF server for the given major version. The 514 versions supported by a given SPPF server can be retrieved by the 515 client using the "Get Server Details" operation described in 516 Section 7.2.9. 518 o obj: One or more elements of abstract type BasicObjType (defined 519 in [I-D.draft-ietf-drinks-spp-framework]). Each element contains 520 all the attributes of an SPPF object that that the client is 521 requesting the SPPF server to add. Refer to section 3.1 of 522 [I-D.draft-ietf-drinks-spp-framework] for the XML structure of all 523 concrete types, for various SPPF objects, that extend from 524 abstract BasicObjType and hence are eligible to be passed into 525 this element. The elements are processed by the SPPF server in 526 the order in which they are included in the request. With respect 527 to handling of error conditions, conforming SPPP SOAP servers MUST 528 stop processing BasicObjType elements in the request at the first 529 error, and roll back any BasicObjType elements that had already 530 been processed for that add request ("stop and rollback"). 532 7.2.1.2. Add Response 534 An SPP Protocol over SOAP add response object is contained within the 535 generic element. This response structure is used 536 for all types of SPPF objects that are provisioned by the SPPF 537 client. 539 540 541 542 544 545 546 548 549 550 552 553 554 555 556 557 559 560 561 562 563 564 565 566 567 569 An contains the elements necessary for the SPPF 570 client to precisely determine the overall result of the request, and 571 if an error occurred, it provides information about the specific 572 object(s) that caused the error. 574 The data elements within the SPP Protocol over SOAP Add response are 575 described as follows: 577 o clientTransId: Zero or one client transaction ID. This value is 578 simply an echo of the client transaction ID that SPPF client 579 passed into the SPPF update request. When included in the 580 request, the SPPF server MUST return it in the corresponding 581 response message. 583 o serverTransId: Exactly one server transaction ID that identifies 584 this request for tracking purposes. This value MUST be unique for 585 a given SPPF server. 587 o overallResult: Exactly one response code and message pair that 588 explicitly identifies the result of the request. See Section 7.3 589 for further details. 591 o detailResult: An optional response code, response message, and 592 BasicObjType (as defined in [I-D.draft-ietf-drinks-spp-framework]) 593 triplet. This element will be present only if an object level 594 error has occurred. It indicates the error condition and the 595 exact request object that contributed to the error. The response 596 code will reflect the exact error. See Section 7.3 for further 597 details. 599 7.2.2. Delete Operation Structure 601 In order to remove an object from the registry, an authorized entity 602 can send the spppDelRequest into the registry. An SPP Protocol over 603 SOAP Delete request is wrapped within the element 604 while a SPP Protocol over SOAP Delete response is wrapped within the 605 generic element. The following sub-sections 606 describe the spppDelRequest and spppDelResponse elements. Refer to 607 Section 10 for an example of Delete operation on each type of SPPF 608 object. 610 7.2.2.1. Delete Request 612 An SPP Protocol over SOAP Delete request definition is contained 613 within the generic element. 615 616 617 618 620 622 624 625 626 628 The data elements within the element are described 629 as follows: 631 o clientTransId: Zero or one client-generated transaction ID that, 632 within the context of the SPPF client, identifies this request. 633 This value can be used at the discretion of the SPPF client to 634 track, log or correlate requests and their responses. SPPF server 635 MUST echo back this value to the client in the corresponding 636 response to the incoming request. SPPF server will not check this 637 value for uniqueness. 639 o minorVer: Zero or one minor version identifier, indicating the 640 minor version of the SPPF API that the client is attempting to 641 use. This is used in conjunction with the major version 642 identifier in the XML namespace to identify the version of SPPF 643 that the client is using. If the element is not present, the 644 server assumes that the client is using the latest minor version 645 supported by the SPPF server for the given major version. The 646 versions supported by a given SPPF server can be retrieved by the 647 client using the Get Server Details Operation described in 648 Section 7.2.9. 650 o objKey: One or more elements of abstract type ObjKeyType (as 651 defined in [I-D.draft-ietf-drinks-spp-framework]). Each element 652 contains attributes that uniquely identify the object that the 653 client is requesting the server to delete. Refer to Section 7.1 654 for a description of all concrete object key types, for various 655 SPPF objects, which are eligible to be passed into this element. 656 The elements are processed by the SPPF server in the order in 657 which they are included in the request. With respect to handling 658 of error conditions, conforming SPPP SOAP servers MUST stop 659 processing ObjKeyType elements in the request at the first error, 660 and roll back any ObjKeyType elements that had already been 661 processed for that delete request ("stop and rollback"). 663 7.2.2.2. Delete Response 665 An SPP Protocol over SOAP delete response object is contained within 666 the generic element. This response structure is 667 used for a delete request on all types of SPPF objects that are 668 provisioned by the SPPF client. 670 671 672 673 675 676 677 679 680 682 684 685 686 687 688 689 691 692 693 694 695 696 697 698 699 701 An contains the elements necessary for the SPPF 702 client to precisely determine the overall result of the request, and 703 if an error occurred, it provides information about the specific 704 object key(s) that caused the error. 706 The data elements within the SPP Protocol over SOAP Delete response 707 are described as follows: 709 o clientTransId: Zero or one client transaction ID. This value is 710 simply an echo of the client transaction ID that SPPF client 711 passed into the SPPF update request. When included in the 712 request, the SPPF server MUST return it in the corresponding 713 response message. 715 o serverTransId: Exactly one server transaction ID that identifies 716 this request for tracking purposes. This value MUST be unique for 717 a given SPPF server. 719 o overallResult: Exactly one response code and message pair that 720 explicitly identifies the result of the request. See Section 7.3 721 for further details. 723 o detailResult: An optional response code, response message, and 724 ObjKeyType (as defined in [I-D.draft-ietf-drinks-spp-framework]) 725 triplet. This element will be present only if an specific object 726 key level error has occurred. It indicates the error condition 727 and the exact request object key that contributed to the error. 728 The response code will reflect the exact error. See Section 7.3 729 for further details. 731 7.2.3. Accept Operation Structure 733 In SPPF, a SED Group Offer can be accepted or rejected by, or on 734 behalf of, the registrant to whom the SED Group has been offered 735 (refer Section 3.1 of [I-D.draft-ietf-drinks-spp-framework] for a 736 description of the SED Group Offer object). The Accept operation is 737 used to accept such SED Group Offers by, or on behalf of, the 738 Registrant. The request structure for an SPP Protocol over SOAP 739 Accept operation is wrapped within the element 740 while an SPP Protocol over SOAP Accept response is wrapped within the 741 generic element. The following sub-sections 742 describe the spppAcceptRequest and spppAcceptResponse elements. 743 Refer to Section 10 for an example of Accept operation on a SED Group 744 Offer. 746 7.2.3.1. Accept Request Structure 748 An SPP Protocol over SOAP Accept request definition is contained 749 within the generic element. 751 752 753 754 756 758 761 762 763 765 The data elements within the element are 766 described as follows: 768 o clientTransId: Zero or one client-generated transaction ID that, 769 within the context of the SPPF client, identifies this request. 771 This value can be used at the discretion of the SPPF client to 772 track, log or correlate requests and their responses. SPPF server 773 MUST echo back this value to the client in the corresponding 774 response to the incoming request. SPPF server will not check this 775 value for uniqueness. 777 o minorVer: Zero or one minor version identifier, indicating the 778 minor version of the SPPF API that the client is attempting to 779 use. This is used in conjunction with the major version 780 identifier in the XML namespace to identify the version of SPPF 781 that the client is using. If the element is not present, the 782 server assumes that the client is using the latest minor version 783 supported by the SPPF server for the given major version. The 784 versions supported by a given SPPF server can be retrieved by the 785 client using the Get Server Details Operation described in 786 Section 7.2.9. 788 o sedGrpOfferKey: One or more elements of type SedGrpOfferKeyType 789 (as defined in this document). Each element contains attributes 790 that uniquely identify a SED Group Offer that the client is 791 requesting the server to accept. The elements are processed by 792 the SPPF server in the order in which they are included in the 793 request. With respect to handling of error conditions, conforming 794 SPPP SOAP servers MUST stop processing SedGrpOfferKeyType elements 795 in the request at the first error, and roll back any 796 SedGrpOfferKeyType elements that had already been processed for 797 that accept request ("stop and rollback"). 799 7.2.3.2. Accept Response 801 An SPP Protocol over SOAP accept response structure is contained 802 within the generic element. This response 803 structure is used for an Accept request on a SED Group Offer. 805 806 807 808 810 811 812 815 816 817 818 819 820 821 822 823 825 826 827 828 829 830 831 832 833 835 An contains the elements necessary for the SPPF 836 client to precisely determine the overall result of the request, and 837 if an error occurred, it provides information about the specific SED 838 Group Offer key(s) that caused the error. 840 The data elements within the SPP Protocol over SOAP Accept response 841 are described as follows: 843 o clientTransId: Zero or one client transaction ID. This value is 844 simply an echo of the client transaction ID that SPPF client 845 passed into the SPPF update request. When included in the 846 request, the SPPF server MUST return it in the corresponding 847 response message. 849 o serverTransId: Exactly one server transaction ID that identifies 850 this request for tracking purposes. This value MUST be unique for 851 a given SPPF server. 853 o overallResult: Exactly one response code and message pair that 854 explicitly identifies the result of the request. See Section 7.3 855 for further details. 857 o detailResult: An optional response code, response message, and 858 SedGrpOfferKeyType (as defined in this document) triplet. This 859 element will be present only if any specific SED Group Offer key 860 level error has occurred. It indicates the error condition and 861 the exact request SED Group Offer key that contributed to the 862 error. The response code will reflect the exact error. See 863 Section 7.3 for further details. 865 7.2.4. Reject Operation Structure 867 In SPPF, SED Group Offer can be accepted or rejected by, or on behalf 868 of, the registrant to whom the SED Group has been offered (refer 869 "Framework Data Model Objects" section of 870 [I-D.draft-ietf-drinks-spp-framework] for a description of the SED 871 Group Offer object). The Reject operation is used to reject such SED 872 Group Offers by, or on behalf of, the Registrant. The request 873 structure for an SPP Protocol over SOAP Reject operation is wrapped 874 within the element while an SPP Protocol over 875 SOAP Reject response is wrapped within the generic 876 element. The following sub-sections describe the 877 spppRejectRequest and spppRejecResponse elements. Refer to 878 Section 10 for an example of Reject operation on a SED Group Offer. 880 7.2.4.1. Reject Request 882 An SPP Protocol over SOAP Reject request definition is contained 883 within the generic element. 885 886 887 888 890 892 895 896 898 The data elements within the element are 899 described as follows: 901 o clientTransId: Zero or one client-generated transaction ID that, 902 within the context of the SPPF client, identifies this request. 903 This value can be used at the discretion of the SPPF client to 904 track, log or correlate requests and their responses. SPPF server 905 MUST echo back this value to the client in the corresponding 906 response to the incoming request. SPPF server will not check this 907 value for uniqueness. 909 o minorVer: Zero or one minor version identifier, indicating the 910 minor version of the SPPF API that the client is attempting to 911 use. This is used in conjunction with the major version 912 identifier in the XML namespace to identify the version of SPPF 913 that the client is using. If the element is not present, the 914 server assumes that the client is using the latest minor version 915 supported by the SPPF server for the given major version. The 916 versions supported by a given SPPF server can be retrieved by the 917 client using the Get Server Details Operation described in 918 Section 7.2.9. 920 o sedGrpOfferKey: One or more elements of type SedGrpOfferKeyType 921 (as defined in this document). Each element contains attributes 922 that uniquely identify a SED Group Offer that the client is 923 requesting the server to reject. The elements are processed by 924 the SPPF server in the order in which they are included in the 925 request. With respect to handling of error conditions, conforming 926 SPPF servers MUST stop processing SedGrpOfferKeyType elements in 927 the request at the first error, and roll back any 928 SedGrpOfferKeyType elements that had already been processed for 929 that reject request ("stop and rollback"). 931 7.2.4.2. Reject Response 933 An SPP Protocol over SOAP reject response structure is contained 934 within the generic element. This response 935 structure is used for an Reject request on a SED Group Offer. 937 938 939 940 942 943 944 947 949 950 952 953 954 955 956 957 959 960 961 962 963 964 965 966 967 969 An contains the elements necessary for the SPPF 970 client to precisely determine the overall result of the request, and 971 if an error occurred, it provides information about the specific SED 972 Group Offer key(s) that caused the error. 974 The data elements within the SPP Protocol over SOAP Reject response 975 are described as follows: 977 o clientTransId: Zero or one client transaction ID. This value is 978 simply an echo of the client transaction ID that SPPF client 979 passed into the SPPF update request. When included in the 980 request, the SPPF server MUST return it in the corresponding 981 response message. 983 o serverTransId: Exactly one server transaction ID that identifies 984 this request for tracking purposes. This value MUST be unique for 985 a given SPPF server. 987 o overallResult: Exactly one response code and message pair that 988 explicitly identifies the result of the request. See Section 7.3 989 for further details. 991 o detailResult: An optional response code, response message, and 992 SedGrpOfferKeyType (as defined in this document) triplet. This 993 element will be present only if any specific SED Group Offer key 994 level error has occurred. It indicates the error condition and 995 the exact request SED Group Offer key that contributed to the 996 error. The response code will reflect the exact error. See 997 Section 7.3 for further details. 999 7.2.5. Batch Operation Structure 1001 An SPP Protocol over SOAP Batch request XML structure allows the SPPF 1002 client to send any of of Add, Del, Accept or Reject operations 1003 together in one single request. This gives an SPPF Client the 1004 flexibility to use one single request structure to perform more than 1005 operations (verbs). The batch request structure is wrapped within 1006 the element while a SPPF Batch response is wrapped 1007 within the element. This following sub-sections 1008 describe the spppBatchRequest and spppBatchResponse elements. Refer 1009 to Section 10 for an example of a batch operation. 1011 7.2.5.1. Batch Request Structure 1013 An SPP Protocol over SOAP Batch request definition is contained 1014 within the generic element. 1016 1017 1018 1019 1021 1023 1024 1025 1026 1028 1030 1031 1032 1033 1035 The data elements within the element are described 1036 as follows: 1038 o clientTransId: Zero or one client-generated transaction ID that, 1039 within the context of the SPPF Client, identifies this request. 1040 This value can be used at the discretion of the SPPF client to 1041 track, log or correlate requests and their responses. SPPF Server 1042 MUST echo back this value to the Client in the corresponding 1043 response to the incoming request. SPPF Server will not check this 1044 value for uniqueness. 1046 o minorVer: Zero or one minor version identifier, indicating the 1047 minor version of the SPPF API that the client is attempting to 1048 use. This is used in conjunction with the major version 1049 identifier in the XML namespace to identify the version of SPPF 1050 that the client is using. If the element is not present, the 1051 server assumes that the client is using the latest minor version 1052 supported by the SPPF server for the given major version. The 1053 versions supported by a given SPPF server can be retrieved by the 1054 client using the Get Server Details Operation described in 1055 Section 7.2.9. 1057 o addObj: One or more elements of abstract type BasicObjType where 1058 each element identifies an object that needs to be added. 1060 o delObj: One or more elements of abstract type ObjKeyType where 1061 each element identifies a key for the object that needs to be 1062 deleted . 1064 o acceptSedGrpOffer: One or more elements of type SedGrpOfferKeyType 1065 where each element identifies a SED Group Offer that needs to be 1066 accepted. 1068 o rejectSedGrpOffer: One or more elements of type SedGrpOfferKeyType 1069 where each element identifies a SED Group Offer that needs to be 1070 rejected. 1072 With respect to handling of error conditions, conforming SPPP SOAP 1073 servers MUST stop processing elements in the request at the first 1074 error, and roll back any elements that had already been processed for 1075 that batch request ("stop and rollback"). 1077 7.2.5.2. Batch Response 1079 An SPP Protocol over SOAP batch response structure is contained 1080 within the generic element. This response 1081 structure is used for an Batch request that contains many different 1082 types of SPPF operations. 1084 1085 1086 1087 1089 1090 1091 1092 1094 1096 1098 1100 1101 1102 1103 1105 An contains the elements necessary for an SPPF 1106 client to precisely determine the overall result of various 1107 operations in the request, and if an error occurred, it provides 1108 information about the specific objects or keys in the request that 1109 caused the error. 1111 The data elements within the SPP Protocol over SOAP Batch response 1112 are described as follows: 1114 o clientTransId: Zero or one client transaction ID. This value is 1115 simply an echo of the client transaction ID that SPPF client 1116 passed into the SPPF update request. When included in the 1117 request, the SPPF server MUST return it in the corresponding 1118 response message. 1120 o serverTransId: Exactly one server transaction ID that identifies 1121 this request for tracking purposes. This value MUST be unique for 1122 a given SPPF server. 1124 o overallResult: Exactly one response code and message pair that 1125 explicitly identifies the result of the request. See Section 7.3 1126 for further details. 1128 o addResult: One or more elements of type ObjResultCodeType where 1129 each element identifies the result code, result message and the 1130 specific object that the result relates to. 1132 o delResult: One or more elements of type ObjKeyResultCodeType where 1133 each element identifies the result code, result message and the 1134 specific object key that the result relates to. 1136 o acceptResult: One or more elements of type 1137 SedGrpOfferKeyResultCodeType where each element identifies the 1138 result code, result message and the specific SED Group Offer key 1139 that the result relates to. 1141 o rejectResult: One or more elements of type 1142 SedGrpOfferKeyResultCodeType where each element identifies the 1143 result code, result message and the specific SED Group Offer key 1144 that the result relates to. 1146 7.2.6. Get Operation Structure 1148 In order to query the details of an object from the Registry, an 1149 authorized entity can send the spppGetRequest to the registry with a 1150 GetRqstType XML data structure containing one or more object keys 1151 that uniquely identify the object whose details are being queried. 1152 The request structure for an SPP Protocol over SOAP Get operation is 1153 contained within the generic element while an SPP 1154 Protocol over SOAP Get response is wrapped within the generic 1155 element. The following sub-sections describe the 1156 spppGetRequest and spppGetResponse element. Refer to Section 10 for 1157 an example of SPP Protocol over SOAP Get operation on each type of 1158 SPPF object 1160 7.2.6.1. Get Request 1162 1163 1164 1165 1167 1170 1171 1172 1174 The data elements within the element are described 1175 as follows: 1177 o minorVer: Zero or one minor version identifier, indicating the 1178 minor version of the SPPF API that the client is attempting to 1179 use. This is used in conjunction with the major version 1180 identifier in the XML namespace to identify the version of SPPF 1181 that the client is using. If the element is not present, the 1182 server assumes that the client is using the latest minor version 1183 supported by the SPPF server for the given major version. The 1184 versions supported by a given SPPF server can be retrieved by the 1185 client using the Get Server Details Operation described in 1186 Section 7.2.9. 1188 o objKey: One or more elements of abstract type ObjKeyType (as 1189 defined in [I-D.draft-ietf-drinks-spp-framework]). Each element 1190 contains attributes that uniquely identify the object that the 1191 client is requesting the server to query. Refer to Section 7.1 of 1192 this document for a description of all concrete object key types, 1193 for various SPPF objects, which are eligible to be passed into 1194 this element. 1196 7.2.6.2. Get Response 1198 The spppGetResponse element is described in Section 7.2.8. 1200 7.2.7. Get SED Group Offers Operation Structure 1202 In addition to the ability to query the details of one or more SED 1203 Group offers using an a SED Group Offer key in the spppGetRequest, 1204 this operation also provides an additional, more flexible, structure 1205 to query for SED Group Offer objects. This additional structure is 1206 contained within the element while the 1207 response is wrapped within the generic element. 1208 The following sub-sections describe the getSedGrpOffersRequest and 1209 spppGetResponse elements. 1211 7.2.7.1. Get SED Group Offers Request 1213 Using the details passed into this structure, the server will attempt 1214 to find SED Group Offer objects that satisfy all the criteria passed 1215 into the request. If no criteria is passed in then the SPPF Server 1216 will return the list of SED Group Offer objects that belongs to the 1217 registrant. If there are no matching SED Group Offers found then an 1218 empty result set will be returned. 1220 1221 1222 1223 1225 1227 1229 1231 1233 1234 1235 1237 The data elements within the element are 1238 described as follows: 1240 o minorVer: Zero or one minor version identifier, indicating the 1241 minor version of the SPPF API that the client is attempting to 1242 use. This is used in conjunction with the major version 1243 identifier in the XML namespace to identify the version of SPPF 1244 that the client is using. If the element is not present, the 1245 server assumes that the client is using the latest minor version 1246 supported by the SPPF server for the given major version. The 1247 versions supported by a given SPPF server can be retrieved by the 1248 client using the Get Server Details Operation described in 1249 Section 7.2.9. 1251 o offeredBy: Zero or more organization IDs. Only offers that are 1252 offered to the organization IDs in this list should be included in 1253 the result set. The result set is also subject to other query 1254 criteria in the request. 1256 o offeredTo: Zero or more organization IDs. Only offers that are 1257 offered by the organization IDs in this list should be included in 1258 the result set. The result set is also subject to other query 1259 criteria in the request. 1261 o status: The status of the offer, offered or accepted. Only offers 1262 in the specified status should be included in the result set. If 1263 this element is not present then the status of the offer should 1264 not be considered in the query. The result set is also subject to 1265 other query criteria in the request. 1267 o sedGrpOfferKey: Zero or more SED Group Offer Keys. Only offers 1268 having one of these keys should be included in the result set. 1269 The result set is also subject to other query criteria in the 1270 request. 1272 7.2.7.2. Get SED Group Offers Response 1274 The spppGetResponse element is described in Section 7.2.8. 1276 7.2.8. Generic Query Response 1278 An SPP Protocol over SOAP query response object is contained within 1279 the generic element. 1281 1282 1283 1284 1286 1289 1290 1291 1293 An contains the elements necessary for the SPPF 1294 client to precisely determine the overall result of the query, and 1295 details of any SPPF objects that matched the criteria in the request. 1297 The data elements within the SPP Protocol over SOAP query response 1298 are described as follows: 1300 o overallResult: Exactly one response code and message pair that 1301 explicitly identifies the result of the request. See Section 7.3 1302 for further details. 1304 o resultObj: The set of zero or more objects that matched the query 1305 criteria. If no objects matched the query criteria then the 1306 result object(s) MUST be empty and the overallResult value MUST 1307 indicate success (if no matches are found for the query criteria, 1308 the response is considered a success). 1310 7.2.9. Get Server Details Operation Structure 1311 In order to query certain details of the SPPF server, such as the 1312 SPPF server's status and the major/minor version supported by the 1313 server, the Server Details operation structure SHOULD be used. This 1314 structure is contained within the element 1315 whereas a SPPF server status response is wrapped within the 1316 element. The following sub-sections 1317 describe the spppServerStatusRequest and spppServerStatusResponse 1318 elements. 1320 7.2.9.1. Get Server Details Request 1322 1323 1324 1325 1327 1328 1329 1331 The data elements within the element are 1332 described as follows: 1334 o minorVer: Zero or one minor version identifier, indicating the 1335 minor version of the SPP Protocol over SOAP API that the client is 1336 attempting to use. This is used in conjunction with the major 1337 version identifier in the XML namespace to identify the version of 1338 SPP Protocol over SOAP that the client is using. If the element 1339 is not present, the server assumes that the client is using the 1340 latest minor version of SPP Protocol over SOAP supported by the 1341 SPPF server for the given major version. The versions of SPP 1342 Protocol over SOAP supported by a given SPPF server can be 1343 retrieved by the client using this same spppServerStatusRequest 1344 without passing in the minorVer element. 1346 7.2.9.2. Get Server Details Response 1348 An SPP Protocol over SOAP server details response structure is 1349 contained within the generic element. 1351 1352 1353 1354 1355 1356 1357 1358 1360 The data elements within the element are 1361 described as follows: 1363 o overallResult: Exactly one response code and message pair that 1364 explicitly identifies the result of the request. See Section 7.3 1365 for further details. 1367 o svcMenu: Exactly one element of type SvcMenuType which in turn 1368 contains the elements to return the server status, the major and 1369 minor versions of the SPP Protocol over SOAP supported by the SPPF 1370 server (refer Section 12 of [I-D.draft-ietf-drinks-spp-framework] 1371 for definition of SvcMenuType). 1373 7.3. Response Codes and Messages 1375 This section contains the listing of response codes and their 1376 corresponding human-readable text. These response codes are in 1377 conformance with the response types defined in Section 5.3 of 1378 [I-D.draft-ietf-drinks-spp-framework]. 1380 The response code numbering scheme generally adheres to the theory 1381 formalized in section 4.2.1 of [RFC5321]: 1383 o The first digit of the response code can only be 1 or 2: 1 = a 1384 positive result, 2 = a negative result. 1386 o The second digit of the response code indicates the category: 0 = 1387 Protocol Syntax, 1 = Implementation Specific Business Rule, 2 = 1388 Security, 3 = Server System. 1390 o The third and fourth digits of the response code indicate the 1391 individual message event within the category defines by the first 1392 two digits. 1394 The response codes are also categorized as to whether they are 1395 overall response codes that may only be returned in the 1396 "overallResult" data element in SPPF responses, or object level 1397 response codes that may only be returned in the "detailResult" 1398 element of the SPPF responses. 1400 +----------+------------------------------------------+-------------+ 1401 | Result | Result Message | Overall or | 1402 | Code | | Object | 1403 | | | Level | 1404 +----------+------------------------------------------+-------------+ 1405 | 1000 | Request Succeeded. | Overall | 1406 | | | Response | 1407 | | | Code | 1408 | | | | 1409 | 2000 | Request syntax invalid. | Overall | 1410 | | | Response | 1411 | | | Code | 1412 | | | | 1413 | 2001 | Request too large. MaxSupported:[Maximum | Overall | 1414 | | requests supported] | Response | 1415 | | | Code | 1416 | | | | 1417 | 2002 | Version not supported. | Overall | 1418 | | | Response | 1419 | | | Code | 1420 | | | | 1421 | 2100 | Command invalid. | Overall | 1422 | | | Response | 1423 | | | Code | 1424 | | | | 1425 | 2300 | System temporarily unavailable. | Overall | 1426 | | | Response | 1427 | | | Code | 1428 | | | | 1429 | 2301 | Unexpected internal system or server | Overall | 1430 | | error. | Response | 1431 | | | Code | 1432 | | | | 1433 | 2101 | Attribute value invalid. | Object | 1434 | | AttrName:[AttributeName] | Level | 1435 | | AttrVal:[AttributeValue] | Response | 1436 | | | Code | 1437 | | | | 1438 | 2102 | Object does not exist. | Object | 1439 | | AttrName:[AttributeName] | Level | 1440 | | AttrVal:[AttributeValue] | Response | 1441 | | | Code | 1442 | | | | 1443 | 2103 | Object status or ownership does not | Object | 1444 | | allow for operation. | Level | 1445 | | AttrName:[AttributeName] | Response | 1446 | | AttrVal:[AttributeValue] | Code | 1447 +----------+------------------------------------------+-------------+ 1448 Table 1: Response Codes Numbering Scheme and Messages 1450 Response message for response code 2001 is "parameterized" with the 1451 following parameter: "[Maximum requests supported]". When the 1452 request is too large, this parameter MUST be used to indicate the 1453 maximum number of requests supported by the server in a single 1454 protocol operation. 1456 Each of the object level response messages are "parameterized" with 1457 the following parameters: "AttributeName" and "AttributeValue". 1459 For example, if an SPPF client sends a request to delete a 1460 Destination Group with a name "TestDG", and it does not already 1461 exist, then the error message returned should be: "Attribute value 1462 invalid. AttrName:dgName AttrVal:TestDG". 1464 The use of these parameters MUST adhere to the rules defined in 1465 Section 5.3 of [I-D.draft-ietf-drinks-spp-framework]. 1467 8. Protocol Operations 1469 Refer to Section 7 of [I-D.draft-ietf-drinks-spp-framework] for a 1470 description of all SPPF operations, and any necessary semantics that 1471 MUST be adhered to in order to conform with SPPF. 1473 9. SPP Protocol over SOAP WSDL Definition 1475 The SPP Protocol over SOAP WSDL and data types are defined below. 1476 The WSDL design approach is commonly referred to as "Generic WSDL". 1477 It is generic in the sense that there is not a specific WSDL 1478 operation defined for each object type that is supported by the SPPF 1479 protocol. There is a single WSDL structure for each type of SPPF 1480 operation. Each such WSDL structure contains exactly one input 1481 structure and one output structure that wraps any data elements that 1482 are part of the incoming request and the outgoing response 1483 respectively. The spppSOAPBinding in the WSDL defines the binding 1484 style as "document" and the encoding as "literal". It is this 1485 combination of "wrapped" input and output data structures, "document" 1486 binding style, and "literal" encoding that characterize the Document 1487 Literal Wrapped style of WSDL specifications. 1489 Notes: The following WSDL has been formatted (e.g. tabs, spaces) to 1490 meet IETF document requirements. Deployments MUST replace 1491 "REPLACE_WITH_ACTUAL_URL" in the WSDL below with the URI of the SPPF 1492 Server instance. 1494 1495 1502 1503 1506 1507 1508 ---- Import base schema ---- 1509 1510 1511 1513 1514 1515 ---- Key type(s) extended 1516 from base schema. ---- 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1539 1540 1541 1542 1543 1545 1547 1548 1549 1550 1552 1553 1554 1555 1556 1557 1558 1560 1562 1563 1564 1565 1566 1568 1569 1570 ---- Generic Request and 1571 Response Definitions ---- 1572 1573 1574 1575 1576 1577 1579 1581 1583 1584 1585 1586 1587 1588 1589 1591 1593 1595 1596 1597 1598 1599 1600 1601 1603 1605 1608 1609 1610 1611 1612 1613 1614 1616 1618 1621 1622 1623 1624 1625 1626 1627 1629 1632 1633 1634 1635 1636 1637 1638 1640 1642 1643 1644 1645 1647 1649 1650 1651 1652 1653 1654 1655 1656 1658 1659 1660 1661 1662 1663 1664 1666 1669 1671 1673 1676 1677 1678 1679 1680 1681 1682 1684 1686 1688 1691 1692 1693 1694 1695 1696 1697 1699 1701 1703 1706 1707 1708 1709 1710 1711 1712 1714 1716 1718 1721 1722 1723 1724 1725 1726 1727 1729 1731 1733 1737 1738 1739 1740 1741 1742 1743 1745 1747 1749 1750 1752 1754 1756 1758 1759 1760 1761 1762 1763 1764 1765 1767 1770 1771 1772 1773 1774 1775 1776 1778 1780 1781 1782 1783 1784 1785 ---- Operation Result Type 1786 Definitions ---- 1787 1788 1789 1790 1791 1792 1793 1794 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1811 1812 1813 1814 1815 1816 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1834 1835 1836 1837 1838 1839 1840 1841 1843 1844 1845 1846 1847 1848 1849 1850 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 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1931 1932 1933 1934 1935 1936 1937 1938 1939 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 1988 1989 1990 1991 1992 1993 1994 1995 1996 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2013 Figure 2: WSDL 2015 10. SPP Protocol over SOAP Examples 2017 This section shows XML message exchange between two SIP Service 2018 Providers (SSP) and a registry. The messages in this section are 2019 valid XML instances that conform to the SPP Protocol over SOAP schema 2020 version within this document. This section also relies on the XML 2021 data structures defined in the SPPF specification 2022 [I-D.draft-ietf-drinks-spp-framework]. Which should also be 2023 referenced to understand XML object types embedded in these example 2024 messages. 2026 In this sample use case scenario, SSP1 and SSP2 provision resource 2027 data in the registry and use SPPF constructs to selectively share the 2028 SED groups. In the figure below, SSP2 has two ingress SBE instances 2029 that are associated with the public identities that SSP2 has the 2030 retail relationship with. Also, the two Session Border Element 2031 instances for SSP1 are used to show how to use SPPF to associate 2032 route preferences for the destination ingress routes and exercise 2033 greater control on outbound traffic to the peer's ingress SBEs. 2035 ---------------+ +------------------ 2036 | | 2037 +------+ +------+ 2038 | sbe1 | | sbe2 | 2039 +------+ +------+ 2040 SSP1 | | SSP2 2041 +------+ +------+ 2042 | sbe3 | | sbe4 | 2043 +------+ +------+ 2044 iana-en:111 | | iana-en:222 2045 ---------------+ +------------------ 2046 | | 2047 | | 2048 | SPPF +------------------+ SPPF | 2049 +------->| Registry |<--------+ 2050 +------------------+ 2052 10.1. Add Destination Group 2054 SSP2 adds a destination group to the registry for use later. The 2055 SSP2 SPPF client sets a unique transaction identifier 'txn_1479' for 2056 tracking purposes. The name of the destination group is set to 2057 DEST_GRP_SSP2_1 2059 2060 2065 2066 2067 2068 2069 txn_1479 2070 2071 2072 iana-en:222 2073 iana-en:223 2074 DEST_GRP_SSP2_1 2075 2076 2077 2078 2080 The registry processes the request and return a favorable response 2081 confirming successful creation of the named destination group. Also, 2082 besides returning a unique server transaction identifier, Registry 2083 also returns the matching client transaction identifier from the 2084 request message back to the SPPF client. 2086 2087 2089 2090 2093 txn_1479 2094 tx_12345 2095 2096 1000 2097 Request Succeeded. 2098 2099 2100 2101 2103 10.2. Add SED Records 2105 SSP2 adds SED records in the form of ingress routes to the registry. 2107 2108 2113 2114 2115 2116 2117 txn_1479 2118 2119 2120 iana-en:222 2121 iana-en:223 2122 SED_SSP2_SBE2 2123 true 2124 10 2125 u 2126 E2U+sip 2127 2128 ^(.*)$ 2129 sip:\1@sbe2.ssp2.example.com 2130 2131 2132 2133 2134 2136 The registry returns a success response. 2138 2139 2141 2142 2145 txn_1479 2146 tx_12345 2147 2148 1000 2149 Request Succeeded. 2150 2151 2152 2153 2155 10.3. Add SED Records -- URIType 2157 SSP2 adds another SED record to the registry and makes use of URIType 2159 2160 2165 2166 2167 2168 txn_1479 2169 2170 2171 iana-en:222 2172 iana-en:223 2173 SED_SSP2_SBE4 2174 true 2175 ^(.*)$ 2176 sip:\1;npdi@sbe4.ssp2.example.com 2177 2178 2179 2180 2182 The registry returns a success response. 2184 2185 2186 2187 2190 txn_1479 2191 tx_12345 2192 2193 1000 2194 Request Succeeded. 2195 2196 2197 2198 2200 10.4. Add SED Group 2202 SSP2 creates the grouping of SED records (e.g. ingress routes) and 2203 chooses higher precedence for SED_SSP2_SBE2 by setting a lower number 2204 for the "priority" attribute, a protocol agnostic precedence 2205 indicator. 2207 2208 2213 2214 2215 2216 txn_1479 2217 2218 2219 iana-en:222 2220 iana-en:223 2221 SED_GRP_SSP2_1 2222 2223 2224 iana-en:222 2225 SED_SSP2_SBE2 2226 SedRec 2227 2228 100 2229 2230 DEST_GRP_SSP2_1 2231 true 2232 10 2233 2234 2235 2236 2238 To confirm successful processing of this request, registry returns a 2239 well-known result code '1000' to the SSP2 client. 2241 2242 2243 2244 2247 txn_1479 2248 tx_12345 2249 2250 1000 2251 Request Succeeded. 2252 2253 2254 2255 2257 10.5. Add Public Identity -- Successful COR claim 2259 SSP2 activates a TN public identity by associating it with a valid 2260 destination group. Further, SSP2 puts forth a claim that it is the 2261 carrier-of-record for the TN. 2263 2268 2269 2270 2271 txn_1479 2272 2273 2274 iana-en:222 2275 iana-en:223 2276 DEST_GRP_SSP2_1 2277 +12025556666 2278 2279 true 2280 2281 2282 2283 2284 2285 Assuming that the registry has access to TN authority data and it 2286 performs the required checks to verify that SSP2 is in fact the 2287 service provider of record for the given TN, the request is processed 2288 successfully. In the response message, the registry sets the value 2289 of to "true" in order to confirm SSP2 claim as the carrier of 2290 record and the reflects the time when the carrier of record 2291 claim is processed. 2293 2294 2297 2298 2301 txn_1479 2302 tx_12345 2303 2304 1000 2305 Request Succeeded. 2306 2307 2308 1000 2309 Request Succeeded. 2310 2311 iana-en:222 2312 iana-en:223 2313 2010-05-30T09:30:10Z 2314 DEST_GRP_SSP2_1 2315 +12025556666 2316 2317 true 2318 true 2319 2010-05-30T09:30:11Z 2320 2321 2322 2323 2324 2325 2327 10.6. Add LRN 2328 If another entity that SSP2 shares session establishment information 2329 (e.g. routes) with has access to Number Portability data, it may 2330 choose to perform route lookups by routing number. Therefore, SSP2 2331 associates a routing number to a destination group in order to 2332 facilitate ingress route discovery. 2334 2335 2340 2341 2342 2343 txn_1479 2344 2345 2346 iana-en:222 2347 iana-en:223 2348 DEST_GRP_SSP2_1 2349 2025550000 2350 2351 2352 2353 2355 Registry completes the request successfully and returns a favorable 2356 response to the SPPF client. 2358 2359 2361 2362 2365 txn_1479 2366 tx_12345 2367 2368 1000 2369 Request Succeeded. 2370 2371 2373 2374 2376 10.7. Add TN Range 2378 Next, SSP2 activates a block of ten thousand TNs and associate it to 2379 a destination group. 2381 2382 2387 2388 2389 2390 txn_1479 2391 2392 2393 iana-en:222 2394 iana-en:223 2395 DEST_GRP_SSP2_1 2396 2397 +12026660000 2398 +12026669999 2399 2400 2401 2402 2403 2405 Registry completes the request successfully and returns a favorable 2406 response. 2408 2409 2411 2412 2415 txn_1479 2416 tx_12345 2417 2418 1000 2419 Request Succeeded. 2420 2421 2422 2423 2425 10.8. Add TN Prefix 2427 Next, SSP2 activates a block of ten thousand TNs using the TNPType 2428 structure and identifying a TN prefix. 2430 2431 2436 2437 2438 2439 txn_1479 2440 2441 2442 iana-en:222 2443 iana-en:223 2444 DEST_GRP_SSP2_1 2445 +1202777 2446 2447 2448 2449 2451 Registry completes the request successfully and returns a favorable 2452 response. 2454 2455 2457 2458 2461 txn_1479 2462 tx_12345 2463 2464 1000 2465 Request Succeeded. 2466 2467 2468 2469 2471 10.9. Enable Peering -- SED Group Offer 2473 In order for SSP1 to complete session establishment for a destination 2474 TN where the target subscriber has a retail relationship with SSP2, 2475 it first requires an asynchronous bi-directional handshake to show 2476 mutual consent. To start the process, SSP2 initiates the peering 2477 handshake by offering SSP1 access to its SED group. 2479 2480 2485 2486 2487 2488 txn_1479 2489 2490 2491 iana-en:222 2492 iana-en:223 2493 2494 2495 iana-en:222 2496 SED_GRP_SSP2_1 2497 SedGrp 2498 2499 iana-en:111 2500 2501 offered 2502 2503 2006-05-04T18:13:51.0Z 2504 2505 2506 2507 2508 2510 Registry completes the request successfully and confirms that the 2511 SSP1 will now have the opportunity to weigh in on the offer and 2512 either accept or reject it. The registry may employ out-of-band 2513 notification mechanisms for quicker updates to SSP1 so they can act 2514 faster, though this topic is beyond the scope of this document. 2516 2517 2519 2520 2523 txn_1479 2524 tx_12345 2525 2526 1000 2527 Request Succeeded. 2528 2529 2530 2531 2533 10.10. Enable Peering -- SED Group Offer Accept 2535 SSP1 responds to the offer from SSP2 and agrees to have visibility to 2536 SSP2 session establishment information (e.g. ingress routes). 2538 2539 2542 2543 2544 2545 2546 txn_1479 2547 2548 2549 2550 iana-en:222 2551 SED_GRP_SSP2_1 2552 SedGrp 2553 2554 iana-en:111 2555 2556 2557 2558 2560 Registry confirms that the request has been processed successfully. 2561 From this point forward, if SSP1 looks up a public identity through 2562 the query resolution server, where the public identity is part of the 2563 destination group by way of "SED_GRP_SSP2_1" session establishment 2564 data association, SSP2 ingress SBE information will be shared with 2565 SSP1. 2567 2568 2570 2571 2574 txn_1479 2575 tx_12350 2576 2577 1000 2578 Request Succeeded. 2579 2580 2581 2582 2584 10.11. Add Egress Route 2585 SSP1 wants to prioritize all outbound traffic to the ingress route 2586 associated with the "SED_GRP_SSP2_1" SED Group record, through 2587 "sbe1.ssp1.example.com". 2589 2590 2595 2596 2597 2598 txn_1479 2599 2600 2601 iana-en:222 2602 iana-en:223 2603 EGR_RTE_01 2604 50 2605 2606 ^(.*@)(.*)$ 2607 \1\2?route=sbe1.ssp1.example.com 2608 2609 2610 iana-en:222 2611 SED_GRP_SSP2_1 2612 SedGrp 2613 2614 2615 2616 2617 2619 Since peering has already been established, the request to add the 2620 egress route has been successfully completed. 2622 2623 2625 2626 2629 txn_1479 2630 tx_12345 2631 2632 1000 2633 Request Succeeded. 2634 2635 2636 2637 2639 10.12. Remove Peering -- SED Group Offer Reject 2641 SSP1 had earlier accepted to have visibility to SSP2 session 2642 establishment data. SSP1 now decides to no longer maintain this 2643 visibility and hence rejects the SED Group Offer. 2645 2646 2649 2650 2651 2652 2653 txn_1479 2654 2655 2656 2657 iana-en:222 2658 SED_GRP_SSP2_1 2659 SedGrp 2660 2661 iana-en:111 2662 2663 2664 2665 2667 Registry confirms that the request has been processed successfully. 2668 From this point forward, if SSP1 looks up a public identity through 2669 the query resolution server, where the public identity is part of the 2670 destination group by way of "SED_GRP_SSP2_1" session establishment 2671 data association, SSP2 ingress SBE information will not be shared 2672 with SSP1 and hence SSP2 ingress SBE will not be returned in the 2673 query response. 2675 2676 2678 2679 2682 txn_1479 2683 tx_12350 2684 2685 1000 2686 Request Succeeded. 2687 2688 2689 2690 2692 10.13. Get Destination Group 2694 SSP2 uses the 'spppGetRequest' operation to tally the last 2695 provisioned record for destination group DEST_GRP_SSP2_1. 2697 2698 2702 2703 2704 2705 2706 2707 iana-en:222 2708 DEST_GRP_SSP2_1 2709 DestGrp 2710 2711 2712 2713 2714 Registry completes the request successfully and returns a favorable 2715 response. 2717 2718 2721 2722 2725 2726 1000 2727 success 2728 2729 2730 iana-en:222 2731 iana-en:223 2732 2012-10-22T09:30:10Z 2733 DEST_GRP_SSP2_1 2734 2735 2736 2737 2739 10.14. Get Public Identity 2741 SSP2 obtains the last provisioned record associated with a given TN. 2743 2744 2749 2750 2751 2752 2753 2754 iana-en:222 2755 2756 +12025556666 2757 TN 2759 2760 2761 2762 2763 2765 Registry completes the request successfully and returns a favorable 2766 response. 2768 2771 2772 2775 2776 1000 2777 success 2778 2779 2780 iana-en:222 2781 iana-en:223 2782 2012-10-22T09:30:10Z 2783 DEST_GRP_SSP2_1 2784 +12025556666 2785 2786 true 2787 true 2788 2010-05-30T09:30:10Z 2789 2790 2791 2792 2793 2795 10.15. Get SED Group Request 2797 SSP2 obtains the last provisioned record for the SED group 2798 SED_GRP_SSP2_1. 2800 2801 2805 2806 2807 2808 2809 2810 iana-en:222 2811 SED_GRP_SSP2_1 2812 SedGrp 2813 2814 2815 2816 2818 Registry completes the request successfully and returns a favorable 2819 response. 2821 2822 2825 2826 2829 2830 1000 2831 success 2832 2833 2834 iana-en:222 2835 iana-en:223 2836 2012-10-22T09:30:10Z 2837 SED_GRP_SSP2_1 2838 2839 2840 iana-en:222 2841 SED_SSP2_SBE2 2842 SedRec 2843 2844 100 2845 2846 2847 2848 iana-en:222 2849 SED_SSP2_SBE4 2850 SedRec 2851 2852 101 2853 2854 DEST_GRP_SSP2_1 2855 true 2856 10 2857 2858 2859 2860 2862 10.16. Get SED Group Offers Request 2864 SSP2 fetches the last provisioned SED group offer to the 2865 SSP1. 2867 2868 2871 2872 2873 2874 iana-en:111 2875 2876 2877 2879 Registry processes the request successfully and returns a favorable 2880 response. 2882 2883 2886 2887 2890 2891 1000 2892 success 2893 2894 2895 iana-en:222 2896 iana-en:223 2897 2012-10-22T09:30:10Z 2898 2900 2901 iana-en:222 2902 SED_GRP_SSP2_1 2903 SedGrp 2904 2905 iana-en:111 2906 2907 offered 2908 2909 2006-05-04T18:13:51.0Z 2910 2911 2912 2913 2914 2916 10.17. Get Egress Route 2918 SSP1 wants to verify the last provisioned record for the egress route 2919 called EGR_RTE_01. 2921 2922 2926 2927 2928 2929 2930 2931 iana-en:111 2932 EGR_RTE_01 2933 EgrRte 2934 2935 2936 2937 2939 Registry completes the request successfully and returns a favorable 2940 response. 2942 2943 2946 2947 2950 2951 1000 2952 success 2953 2954 2955 iana-en:222 2956 iana-en:223 2957 2012-10-22T09:30:10Z 2958 EGR_RTE_01 2959 50 2960 2961 ^(.*)$ 2962 sip:\1@sbe1.ssp1.example.com 2963 2964 2965 iana-en:222 2966 SED_GRP_SSP2_1 2967 SedRec 2968 2969 2970 2971 2972 2974 10.18. Delete Destination Group 2975 SSP2 initiates a request to delete the destination group 2976 DEST_GRP_SSP2_1. 2978 2979 2983 2984 2985 2986 2987 2988 iana-en:222 2989 DEST_GRP_SSP2_1 2990 DestGrp 2991 2992 2993 2994 2996 Registry completes the request successfully and returns a favorable 2997 response. 2999 3000 3002 3003 3006 tx_12354 3007 3008 1000 3009 Request Succeeded. 3010 3011 3012 3013 3015 10.19. Delete Public Identity 3016 SSP2 chooses to de-activate the TN and remove it from the registry. 3018 3019 3024 3025 3026 3027 3028 3029 iana-en:222 3030 3031 +12025556666 3032 TN 3033 3034 3035 3036 3037 3039 Registry completes the request successfully and returns a favorable 3040 response. 3042 3043 3045 3046 3049 tx_12354 3050 3051 1000 3052 Request Succeeded. 3053 3054 3055 3056 3058 10.20. Delete SED Group Request 3060 SSP2 removes the SED group called SED_GRP_SSP2_1. 3062 3063 3067 3068 3069 3070 3071 3072 iana-en:222 3073 SED_GRP_SSP2_1 3074 SedGrp 3075 3076 3077 3078 3080 Registry completes the request successfully and returns a favorable 3081 response. 3083 3084 3086 3087 3090 tx_12354 3091 3092 1000 3093 Request Succeeded. 3094 3095 3096 3097 3099 10.21. Delete SED Group Offers Request 3101 SSP2 no longer wants to share SED group SED_GRP_SSP2_1 with SSP1. 3103 3104 3108 3109 3110 3111 3112 3113 3114 iana-en:222 3115 SED_GRP_SSP2_1 3116 SedGrp 3117 3118 iana-en:111 3119 3120 3121 3122 3124 Registry completes the request successfully and returns a favorable 3125 response. Restoring this resource sharing will require a new SED 3126 group offer from SSP2 to SSP1 followed by a successful SED group 3127 accept request from SSP1. 3129 3130 3132 3133 3136 tx_12354 3137 3138 1000 3139 Request Succeeded. 3140 3141 3142 3144 3146 10.22. Delete Egress Route 3148 SSP1 decides to remove the egress route with the label EGR_RTE_01. 3150 3151 3155 3156 3157 3158 3159 3160 iana-en:111 3161 EGR_RTE_01 3162 EgrRte 3163 3164 3165 3166 3168 Registry completes the request successfully and returns a favorable 3169 response. 3171 3172 3174 3175 3178 tx_12354 3179 3180 1000 3181 Request Succeeded. 3182 3183 3184 3185 3187 10.23. Batch Request 3189 Following is an example of how some of the operations mentioned in 3190 previous sections MAY be performed by an SPPF client as a batch in 3191 one single SPP Protocol over SOAP request. 3193 In the sample request below SSP1 wants to accept a SED Group Offer 3194 from SSP3, add a Destination Group, add a NAPTR SED Record, add a SED 3195 Group, add a SED Group Offer, delete a previously provisioned TN type 3196 Public Identifier, delete a previously provisioned SED Group, and 3197 reject a SED Group Offer from SSP4. 3199 3200 3205 3206 3207 3208 txn_1467 3209 1 3211 3212 3213 iana-en:225 3214 SED_SSP3_SBE1_Offered 3215 SedGrp 3216 3217 iana-en:222 3218 3220 3221 iana-en:222 3222 iana-en:223 3223 DEST_GRP_SSP2_1 3224 3226 3227 iana-en:222 3228 iana-en:223 3229 SED_SSP2_SBE2 3230 10 3231 u 3232 E2U+sip 3233 3234 ^(.*)$ 3235 sip:\1@sbe2.ssp2.example.com 3236 3237 3239 3240 iana-en:222 3241 iana-en:223 3242 SED_GRP_SSP2_1 3243 3244 3245 iana-en:222 3246 SED_SSP2_SBE2 3247 SedRec 3248 3249 100 3250 3251 DEST_GRP_SSP2_1 3252 true 3253 10 3254 3256 3257 iana-en:222 3258 iana-en:223 3259 3260 3261 iana-en:222 3262 SED_GRP_SSP2_1 3263 SedGrp 3264 3265 iana-en:111 3266 3267 offered 3268 3269 2006-05-04T18:13:51.0Z 3270 3271 3273 3274 iana-en:222 3275 3276 +12025556666 3277 TN 3278 3279 3281 3282 iana-en:222 3283 SED_GRP_SSP2_Previous 3284 SedGrp 3285 3287 3288 3289 iana-en:226 3290 SED_SSP4_SBE1_Offered 3291 SedGrp 3292 3293 iana-en:222 3294 3296 3297 3298 3300 Registry completes the request successfully and returns a favorable 3301 response. 3303 3304 3306 3307 3310 tx_12354 3311 3312 1000 3313 Request Succeeded. 3314 3315 3316 3317 3319 11. Security Considerations 3321 SPP Protocol over SOAP is used to query and update session peering 3322 data and addresses, so the ability to access this protocol should be 3323 limited to users and systems that are authorized to query and update 3324 this data. Because this data is sent in both directions, it may not 3325 be sufficient for just the client or user to be authenticated with 3326 the server. The identity of the server should also be authenticated 3327 by the client, which is often accomplished using the TLS certificate 3328 exchange and validation described in [RFC2818]. 3330 11.1. Vulnerabilities 3332 Section 5 describes the use of HTTP and TLS as the underlying 3333 transport protocols for SPP Protocol over SOAP. These underlying 3334 protocols may have various vulnerabilities, and these may be 3335 inherited by SPP Protocol over SOAP. SPP Protocol over SOAP itself 3336 may have vulnerabilities because an authorization model is not 3337 explicitly specified in this document. 3339 During a TLS handshake, TLS servers can optionally request a 3340 certificate from a TLS client; that option is not a requirement for 3341 this protocol. This presents a denial of service risk in which 3342 unauthenticated clients can consume server CPU resources by creating 3343 TLS sessions. The risk is increased if the server supports client- 3344 initiated renegotiation. This risk can be mitigated by disabling 3345 client-initiated renegotiation on the server and by ensuring that 3346 other means (such as firewall access control lists) are used to 3347 restrict unauthenticated client access to servers. 3349 In conjunction with the above, it is important that SPP Protocol over 3350 SOAP implementations implement an authorization model that considers 3351 the source of each query or update request and determines whether it 3352 is reasonable to authorize that source to perform that specific query 3353 or update. 3355 12. IANA Considerations 3357 This document uses URNs to describe XML Namespaces and XML Schemas. 3358 According to [RFC3688], IANA is requested to perform the following 3359 URN assignment: 3361 URN: urn:ietf:params:xml:ns:sppf:soap:1 3363 Registrant Contact: IESG 3365 XML: See Section 9 of [THISDOCUMENT] 3367 13. Acknowledgements 3369 This document is a result of various discussions held with the IETF 3370 DRINKS working group, specifically the protocol design team, with 3371 contributions from the following individuals, in alphabetical order: 3372 Alexander Mayrhofer, David Schwartz, Deborah A Guyton, Jean-Francois 3373 Mule Kenneth Cartwright, Lisa Dusseault, Manjul Maharishi, Mickael 3374 Marrache, Otmar Lendl, Peter Saint-Andre, Richard Shockey, Samuel 3375 Melloul, Scott Hollenbeck, Sumanth Channabasappa, Syed Ali, and Vikas 3376 Bhatia . 3378 14. References 3380 14.1. Normative References 3382 [I-D.draft-ietf-drinks-spp-framework] 3383 Cartwright, K., Bhatia, V., Ali, S., and D. Schwartz, 3384 "Session Peering Provisioning Framework ", draft-ietf- 3385 drinks-spp-framework-06 (work in progress), October 2013. 3387 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3388 Requirement Levels", BCP 14, RFC 2119, March 1997. 3390 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3391 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3392 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3394 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3395 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3396 Authentication: Basic and Digest Access Authentication", 3397 RFC 2617, June 1999. 3399 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3400 January 2004. 3402 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3403 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3405 [SOAPREF] Gudgin, M., Hadley, M., Moreau, J., and H. Nielsen, "SOAP 3406 Version 1.2 Part 1: Messaging Framework", W3C 3407 Recommendation REC-SOAP12-part1-20030624, June 2002. 3409 14.2. Informative References 3411 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3413 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 3414 October 2008. 3416 [W3C.REC-xml-20081126] 3417 Sperberg-McQueen, C., Yergeau, F., Bray, T., Maler, E., 3418 and J. Paoli, "Extensible Markup Language (XML) 1.0 (Fifth 3419 Edition)", World Wide Web Consortium Recommendation REC- 3420 xml-20081126, November 2008, 3421 . 3423 [WSDLREF] Christensen, E., Curbera, F., Meredith, G., and S. 3424 Weerawarana, "Web Services Description Language (WSDL) 3425 1.1", W3C Note NOTE-wsdl-20010315, March 2001. 3427 Authors' Addresses 3429 Kenneth Cartwright 3430 TNS 3431 1939 Roland Clarke Place 3432 Reston, VA 20191 3433 USA 3435 Email: kcartwright@tnsi.com 3437 Vikas Bhatia 3438 TNS 3439 1939 Roland Clarke Place 3440 Reston, VA 20191 3441 USA 3443 Email: vbhatia@tnsi.com 3445 Jean-Francois Mule 3446 CableLabs 3447 858 Coal Creek Circle 3448 Louisville, CO 80027 3449 USA 3451 Email: jfm@cablelabs.com 3453 Alexander Mayrhofer 3454 enum.at GmbH 3455 Karlsplatz 1/9 3456 Wien A-1010 3457 Austria 3459 Email: alexander.mayrhofer@enum.at