idnits 2.17.1 draft-ietf-drinks-spp-protocol-over-soap-01.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 (March 12, 2012) is 4399 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-01 ** 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: September 13, 2012 March 12, 2012 7 Session Peering Provisioning (SPP) Protocol over SOAP 8 draft-ietf-drinks-spp-protocol-over-soap-01 10 Abstract 12 The Session Peering Provisioning Framework (SPPF) is an XML framework 13 that exists to enable the provisioning of session establishment data 14 into Session Data Registries or SIP Service Provider data stores. 15 Sending XML data structures over Simple Object Access Protocol (SOAP) 16 and HTTP(s) is a widely used, de-facto standard for messaging between 17 elements of provisioning systems. Therefore the combination of SOAP 18 and HTTP(s) as a transport protocol for SPPF is a natural fit. The 19 obvious benefits include leveraging existing industry expertise, 20 leveraging existing standards, and a higher probability that existing 21 provisioning systems can be more easily integrated with this 22 protocol. This document describes the specification for transporting 23 SPPF XML structures over SOAP and HTTP(s). 25 Status of this Memo 27 This Internet-Draft is submitted in full conformance with the 28 provisions of BCP 78 and BCP 79. 30 Internet-Drafts are working documents of the Internet Engineering 31 Task Force (IETF). Note that other groups may also distribute 32 working documents as Internet-Drafts. The list of current Internet- 33 Drafts is at http://datatracker.ietf.org/drafts/current/. 35 Internet-Drafts are draft documents valid for a maximum of six months 36 and may be updated, replaced, or obsoleted by other documents at any 37 time. It is inappropriate to use Internet-Drafts as reference 38 material or to cite them other than as "work in progress." 40 This Internet-Draft will expire on September 13, 2012. 42 Copyright Notice 44 Copyright (c) 2012 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 3. SOAP Features and Protocol Layering . . . . . . . . . . . . . 6 62 4. HTTP(s) Features and SPP Protocol over SOAP . . . . . . . . . 9 63 5. Authentication and Session Management . . . . . . . . . . . . 10 64 6. SPP Protocol SOAP Data Structures . . . . . . . . . . . . . . 11 65 6.1. Concrete Object Key Types . . . . . . . . . . . . . . . . 11 66 6.1.1. Generic Object Key . . . . . . . . . . . . . . . . . . 11 67 6.1.2. Public Identity Object Key . . . . . . . . . . . . . . 12 68 6.1.3. Route Group Offer Key . . . . . . . . . . . . . . . . 13 69 6.2. Operation Request and Response Structures . . . . . . . . 14 70 6.2.1. Add Operation Structure . . . . . . . . . . . . . . . 14 71 6.2.2. Delete Operation Structure . . . . . . . . . . . . . . 17 72 6.2.3. Accept Operation Structure . . . . . . . . . . . . . . 20 73 6.2.4. Reject Operation Structure . . . . . . . . . . . . . . 24 74 6.2.5. Batch Operation Structure . . . . . . . . . . . . . . 27 75 6.2.6. Get Operation Structure . . . . . . . . . . . . . . . 30 76 6.2.7. Get Route Group Offers Operation Structure . . . . . . 32 77 6.2.8. Generic Query Response . . . . . . . . . . . . . . . . 33 78 6.2.9. Get Server Details Operation Structure . . . . . . . . 34 79 6.3. Response Codes and Messages . . . . . . . . . . . . . . . 36 80 7. Protocol Operations . . . . . . . . . . . . . . . . . . . . . 39 81 8. SPP Protocol over SOAP WSDL Definition . . . . . . . . . . . . 40 82 9. SPP Protocol over SOAP Examples . . . . . . . . . . . . . . . 52 83 9.1. Add Destination Group . . . . . . . . . . . . . . . . . . 52 84 9.2. Add Route Records . . . . . . . . . . . . . . . . . . . . 54 85 9.3. Add Route Records -- URIRteRecType . . . . . . . . . . . . 55 86 9.4. Add Route Group . . . . . . . . . . . . . . . . . . . . . 56 87 9.5. Add Public Identity -- Successful COR claim . . . . . . . 58 88 9.6. Add LRN . . . . . . . . . . . . . . . . . . . . . . . . . 60 89 9.7. Add TN Range . . . . . . . . . . . . . . . . . . . . . . . 61 90 9.8. Add TN Prefix . . . . . . . . . . . . . . . . . . . . . . 62 91 9.9. Enable Peering -- Route Group Offer . . . . . . . . . . . 63 92 9.10. Enable Peering -- Route Group Offer Accept . . . . . . . . 65 93 9.11. Add Egress Route . . . . . . . . . . . . . . . . . . . . . 66 94 9.12. Remove Peering -- Route Group Offer Reject . . . . . . . . 68 95 9.13. Get Destination Group . . . . . . . . . . . . . . . . . . 69 96 9.14. Get Public Identity . . . . . . . . . . . . . . . . . . . 71 97 9.15. Get Route Group Request . . . . . . . . . . . . . . . . . 72 98 9.16. Get Route Group Offers Request . . . . . . . . . . . . . . 74 99 9.17. Get Egress Route . . . . . . . . . . . . . . . . . . . . . 76 100 9.18. Delete Destination Group . . . . . . . . . . . . . . . . . 77 101 9.19. Delete Public Identity . . . . . . . . . . . . . . . . . . 78 102 9.20. Delete Route Group Request . . . . . . . . . . . . . . . . 80 103 9.21. Delete Route Group Offers Request . . . . . . . . . . . . 81 104 9.22. Delete Egress Route . . . . . . . . . . . . . . . . . . . 82 105 9.23. Batch Request . . . . . . . . . . . . . . . . . . . . . . 83 106 10. Security Considerations . . . . . . . . . . . . . . . . . . . 86 107 10.1. Integrity, Privacy, and Authentication . . . . . . . . . . 86 108 10.2. Vulnerabilities . . . . . . . . . . . . . . . . . . . . . 86 109 10.3. Deployment Environment Specifics . . . . . . . . . . . . . 87 110 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 88 111 12. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 89 112 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 90 113 13.1. Normative References . . . . . . . . . . . . . . . . . . . 90 114 13.2. Informative References . . . . . . . . . . . . . . . . . . 90 115 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 91 117 1. Introduction 119 SPPF, defined in [I-D.draft-ietf-drinks-spp-framework], is best 120 supported by a transport and messaging infrastructure that is 121 connection oriented, request-response oriented, easily secured, 122 supports propagation through firewalls in a standard fashion, and 123 that is easily integrated into back-office systems. This is due to 124 the fact that the client side of SPPF is likely to be integrated with 125 organizations' operational support systems that facilitate 126 transactional provisioning of user addresses and their associated 127 session establishment data. While the server side of SPPF is likely 128 to reside in a separate organization's network, resulting the SPPF 129 provisioning transactions traversing the Internet as they are 130 propagated from the SPPF client to the SPPF server. Given the 131 current state of industry practice and technologies, SOAP and HTTP(s) 132 are well suited for this type of environment. This document 133 describes the specification for transporting SPPF XML structures over 134 SOAP and HTTP(s). 136 The specification in this document for transporting SPPF XML 137 structures over SOAP and HTTP(s) is primarily comprised of five 138 subjects: (1) a description of any applicable SOAP features, (2) any 139 applicable HTTP features, (3) security considerations, and perhaps 140 most importantly, (4) the Web Services Description Language (WSDL) 141 definition for SPP Protocol over SOAP, and (5) "transport" specific 142 XML schema type definitions 144 2. Terminology 146 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 147 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 148 document are to be interpreted as described in [RFC2119]. 150 3. SOAP Features and Protocol Layering 152 The list of SOAP features that are explicitly used and required for 153 SPP Protocol over SOAP are limited. Most SOAP features are not 154 necessary for SPPF. SPP Protocol over SOAP primarily uses SOAP 155 simply as a standard message envelope technology. The SOAP message 156 envelope is comprised of the SOAP header and body. As described in 157 the SOAP specifications, the SOAP header can contain optional, 158 application specific, information about the message. The SOAP body 159 contains the SPPF message itself, whose structure is defined by the 160 combination of one of the WSDL operations defined in this document 161 and the SPPF XML data structures defined in this document and the 162 SPPF document. SPPF does not rely on any data elements in the SOAP 163 header. All relevant data elements are defined in the SPPF XML 164 schema described in [I-D.draft-ietf-drinks-spp-framework] and the 165 SPPF WSDL types specification described in this document. 167 WSDL is a widely standardized and adopted technology for defining the 168 top-level structures of the messages that are transported within the 169 body of a SOAP message. The WSDL definition for the SPPF SOAP 170 messages is defined later in this document, which imports by 171 reference the XML data types contained in the SPPF schema. The IANA 172 registry where the SPPF schema resides is described in The IETF XML 173 Registry [RFC3688]. 175 There are multiple structural styles that SOAP WSDL allows. But the 176 best practice for this type of application is what is sometimes 177 referred to as the Document Literal Wrapped style of designing SOAP 178 WSDL. This style is generally regarded as an optimal approach that 179 enhances maintainability, comprehension, portability, and, to a 180 certain extent, performance. It is characterized by setting the 181 soapAction binding style as _document_, the soapAction encoding style 182 as _literal_, and then defining the SOAP messages to simply contain a 183 single data element that _wraps_ a data structure containing all the 184 required input or output data elements. The figure below illustrates 185 this high level technical structure as conceptual layers 3 through 6. 187 +-------------+ 188 (1) | Transport |Example: 189 | Protocol | TCP, TLS, BEEP, etc. 190 +-------------+ 191 | 192 V 193 +-------------+ 194 (2) | Message |Example: 195 | Envelope | HTTP, SOAP, None, etc. 196 +-------------+ 197 | 198 V 199 +--------------+ 200 +------| SOAP |-----+ 201 | (3) | Operation | | 202 Contains | +--------------+ | Contains 203 | Example: | 204 V submitAddRqst V 205 +--------------+ +-------------+ 206 |SOAP Request | |SOAP Response| 207 Example:| Message | (4) | Message | Example: 208 spppAdd | (Operation | | (Operation | spppAdd 209 RequestMsg | Input) | | Output) | ResponseMsg 210 +--------------+ +-------------+ 211 | | 212 Contains | | Contains 213 | | 214 V V 215 +---------------+ +---------------+ 216 Example:| Wrapped | (5) | Wrapped | Example: 217 spppAdd |Request Object | |Response Object| spppAdd 218 Request +---------------+ +---------------+ Response 219 | | 220 Contains | | Contains 221 | | 222 V V 223 +-------------+ +---------------+ 224 | SPPF | | SPPF | 225 |XML Types | (6) | XML Types | 226 +-------------+ +---------------+ 228 Figure 1: Layering and Technical Structure of the SPP Protocol over 229 SOAP Messages 231 The operations supported by SPP Protocol over SOAP are normatively 232 defined later in this document. Each SOAP operation defines a 233 request/input message and a response/output message. Each such 234 request and response message then contains a single object that wraps 235 the SPPF XML data types that comprise the inputs and the outputs, 236 respectively, of the SOAP operation. 238 SOAP faults are not used by the SPP Protocol over SOAP. All success 239 and error responses are specified in the "Response Codes and 240 Messages" section of this document. However, if a SOAP fault were to 241 occur, perhaps due to failures in the SOAP message handling layer of 242 a SOAP library, the client application should capture and handle the 243 fault. Specifics on how to handle such SOAP faults, if they should 244 occur, will be specific to the chosen SOAP implementation. 246 SOAP 1.2 [SOAPREF] or higher and WSDL 1.1 [WSDLREF] or higher SHOULD 247 be used. 249 SPPF is a request/reply framework that allows a client application to 250 submit provisioning data and query requests to a server. The SPPF 251 data structures are designed to be protocol agnostic. Concerns 252 regarding encryption, non-repudiation, and authentication are beyond 253 the scope of this document. For more details, please refer to the 254 "Transport Protocol Requirements" section in the framework document. 256 As illustrated in the previous diagram, SPPF can be viewed as a set 257 of layers that collectively define the structure of an SPPF request 258 and response. Layers 1 and 2 represent the transport, envelope, and 259 authentication technologies. This document defines layers 3, 4, 5, 260 and 6 below for SPP Protocol over SOAP. 262 1. Layer 1: The transport protocol layer represents the 263 communication mechanism between the client and server. SPPF can 264 be layered over any transport protocol that provides a set of 265 basic requirements defined in the Transport Protocol Requirements 266 section. But this document specifies the required mechanism. 268 2. Layer 2: The message envelope layer is optional, but can provide 269 features that are above the transport technology layer but below 270 the application messaging layer. Technologies such as HTTP and 271 SOAP are examples of messaging envelope technologies. This 272 document specifies the required envelope technology. 274 3. Layers 3,4,5,6: The operation and message layers provides an 275 envelope-independent and transport-independent wrapper for the 276 SPPF data model objects that are being acted on (created, 277 modified, queried). 279 4. HTTP(s) Features and SPP Protocol over SOAP 281 SOAP is not tied to HTTP(s), however, for reasons described in the 282 introduction, HTTP(s) is a good choice as the transport mechanism for 283 the SPP Protocol SOAP messages. HTTP 1.1 includes the "persistent 284 connection" feature, which allows multiple HTTP request/response 285 pairs to be transported across a single HTTP connection. This is an 286 important performance optimization feature, particularly when the 287 connections is an HTTPS connection where the relatively time 288 consuming SSL handshake has occurred. Persistent connections SHOULD 289 be used for the SPPF HTTP connections. 291 HTTP 1.1 [RFC2616] or higher SHOULD be used. 293 5. Authentication and Session Management 295 To achieve integrity and privacy, conforming SPP Protocol SOAP 296 Clients and Servers MUST support SOAP over HTTP over TLS [RFC5246] as 297 the secure transport mechanism. This combination of HTTP and TLS is 298 referred to as HTTPS. And to accomplish authentication, conforming 299 SOAP SPPF Clients and Servers MUST use HTTP Digest Authentication as 300 defined in [RFC2617]. As a result, the communication session is 301 established through the initial HTTP connection setup, the digest 302 authentication, and the TLS handshake. When the HTTP connection is 303 broken down, the communication session ends. 305 6. SPP Protocol SOAP Data Structures 307 SPP Protocol over SOAP uses a set of XML based data structures for 308 all the supported operations and any parameters that those operations 309 are applied to. As also mentioned earlier in this document, these 310 XML structures are envelope-independent and transport-independent. 311 Refer the "Protocol Operations" section of this document for a 312 description of all the operations that MUST be supported. 314 The following sections describe the definition all the XML data 315 structures. 317 6.1. Concrete Object Key Types 319 Certain operations in SPPF require an object key that uniquely 320 identifies the object(s) on which a given operation needs to be 321 performed. SPPF defines the XML structure of the any such object key 322 in an abstact manner and delegates the concrete representation to any 323 conforming transport protocol. The following sub-sections define the 324 various types of concrete object key types used in various operations 325 in SPP Protocol over SOAP: 327 6.1.1. Generic Object Key 329 Most objects in SPP Protocol over SOAP are uniquely identified by the 330 attributes in the generic object key (Refer "Generic Object Key Type" 331 section of the framework document for details). The concrete XML 332 representation of ObjKeyType is as below: 334 335 336 337 338 339 340 341 342 343 344 346 The ObjKeyType has the data elements as described below: 348 o rant: The identifier of the registrant organization that owns 349 the object. 351 o name: The character string that contains the name of the object. 353 o type: The enumeration value that represents the type of SPPF 354 object. For example, both a Destination Group and a Route Group 355 can have the same name "TestObj" and be associated with same 356 Registrant Id "iana-en:222". Hence, to uniquely identify the 357 object that represents a Destination Group with the name 358 "TestObj", the type "DestGrp" must be specified when using this 359 concrete ObjKeyType structure to identify the Destination Group 360 "TestObj". 362 The object types in SPP Protocol over SOAP that MUST adhere to the 363 above definition of generic object key are defined as an enumeration 364 in the XML data structure. The structure of the the enumeration is 365 as follows: 367 368 369 370 371 372 373 374 376 6.1.2. Public Identity Object Key 378 Public Identity type objects can further be of various sub-types like 379 a TN, RN, TN Prefix, URI, or a TN Range and cannot be cleanly 380 identified with the attributes in the generic ObjKeyType. The 381 definition of PubIdKeyType is as below: 383 384 385 386 387 388 389 390 392 394 396 397 398 399 400 402 The PubIdKeyType has the data elements as described below: 404 o rant: The identifier of the registrant organization that owns 405 the object. 407 o dgName: The name of the Destination Group that a Public 408 Identifier is member of. Note that this is an optional 409 attribute of the key as Public Identifiers may or may not be 410 provisioned as members of a Destination Group. 412 o number: An element of type NumberType (refer framework document) 413 that contains the value and type of a number . 415 o range: An element of type NumberRangeType (refer framework 416 document) that contains a range of numbers. 418 o uri: A value that represents a Public Identifier. 420 It is MUST that only one of the "number", "range", and "uri" elements 421 appears in a PubIdKeyType instance. 423 6.1.3. Route Group Offer Key 425 In addition to the attributes in the generic ObjKeyType, a Route 426 Group Offer object is uniquely identified by the organization ID of 427 the organization to whom an Route Group has been offered. The 428 definition of RteGrpOfferKeyType is as below: 430 431 432 433 434 435 436 437 438 439 441 The RteGrpOfferKeyType has the data elements as described below: 443 o rteGrpKey: Identifies the Route Group that was offered. 445 o offeredTo: The organization ID of the organization that was 446 offered the Route Group object identified by the rteGrpKey. 448 6.2. Operation Request and Response Structures 450 An SPPF client interacts with an SPPF server by using one of the 451 supported transport mechanisms to send one or more requests to the 452 server and receive corresponding replies from the server. The basic 453 set of operations that an SPPF client can submit to an SPPF server 454 and the semantics of those operations are defined in the "Framework 455 Operations" section of the framework document. The following sub- 456 sections describe the XML data structures that are used for each of 457 those types of operations for a SPP Protocol over SOAP 458 implementation. 460 6.2.1. Add Operation Structure 462 In order to add (or modify) an object in the registry, an authorized 463 entity can send the spppAddRequest to the registry. 465 An SPP Protocol over SOAP Add request is wrapped within the 466 element while an SPP Protocol over SOAP Add response 467 is wrapped within an element. The following sub- 468 sections describe the spppAddRequest and spppAddResponse elements. 469 Refer the "SPP Protocol over SOAP Examples" section of this document 470 for an example of Add operation on each type of SPPF object. 472 6.2.1.1. Add Request 474 An SPP Protocol over SOAP Add request definition is contained within 475 the generic element. 477 478 479 480 482 484 486 487 488 490 The data elements within the element are described 491 as follows: 493 o clientTransId: Zero or one client-generated transaction ID that, 494 within the context of the SPPF client, identifies this request. 495 This value can be used at the discretion of the SPPF client to 496 track, log or correlate requests and their responses. SPPF 497 server MUST echo back this value to the client in the 498 corresponding response to the incoming request. SPPF server 499 will not check this value for uniqueness. 501 o minorVer: Zero or one minor version identifier, indicating the 502 minor version of the SPPF API that the client is attempting to 503 use. This is used in conjunction with the major version 504 identifier in the XML namespace to identify the version of SPPF 505 that the client is using. If the element is not present, the 506 server assumes that the client is using the latest minor version 507 supported by the SPPF server for the given major version. The 508 versions supported by a given SPPF server can be retrieved by 509 the client using the SPPF server menu operation described later 510 in the document. 512 o obj: One or more elements of abstract type BasicObjType (defined 513 in the framework document). Each element contains all the 514 attributes of an SPPF object that that the client is requesting 515 the SPPF server to add. Refer the "Framework Data Model 516 Objects" section of the framework document for the XML structure 517 of all concrete types, for various SPPF objects, that extend 518 from abstract BasicObjType and hence are eligible to be passed 519 into this element. The elements are processed by the SPPF 520 server in the order in which they are included in the request. 521 With respect to handling of error conditions, it is a matter of 522 policy whether the objects are processed in a "stop and 523 rollback" fashion or in a "stop and commit" fashion. In the 524 "stop and rollback" scenario, the SPPF server would stop 525 processing BasicObjType elements in the request at the first 526 error and roll back any BasicObjType elements that had already 527 been processed for that add request. In the "stop and commit" 528 scenario the SPPF server would stop processing BasicObjType 529 elements in the request at the first error but commit any 530 BasicObjType elements that had already been processed for that 531 add request. 533 6.2.1.2. Add Response 535 An SPP Protocol over SOAP add response object is contained within the 536 generic element. This response structure is used 537 for all types of SPPF objects that are provisioned by the SPPF 538 client. 540 541 542 543 545 546 547 549 550 551 553 554 555 556 557 558 560 561 562 563 564 565 566 567 568 570 An contains the elements necessary for the SPPF 571 client to precisely determine the overall result of the request, and 572 if an error occurred, it provides information about the specific 573 object(s) that caused the error. 575 The data elements within the SPP Protocol over SOAP Add response are 576 described as follows: 578 o clientTransId: Zero or one client transaction ID. This value is 579 simply an echo of the client transaction ID that SPPF client 580 passed into the SPPF update request. When included in the 581 request, the SPPF server MUST return it in the corresponding 582 response message. 584 o serverTransId: Exactly one server transaction ID that identifies 585 this request for tracking purposes. This value MUST be unique 586 for a given SPPF server. 588 o overallResult: Exactly one response code and message pair that 589 explicitly identifies the result of the request. See the 590 Response Code section for further details. 592 o detailResult: An optional response code, response message, and 593 BasicObjType (as defined in the framework document) triplet. 594 This element will be present only if an object level error has 595 occurred. It indicates the error condition and the exact 596 request object that contributed to the error. The response code 597 will reflect the exact error. See the Response Code section for 598 further details. 600 6.2.2. Delete Operation Structure 602 In order to remove an object from the registry, an authorized entity 603 can send the spppDelRequest into the registry. An SPP Protocol over 604 SOAP Delete request is wrapped within the element 605 while a SPP Protocol over SOAP Delete response is wrapped within the 606 generic element. The following sub-sections 607 describe the spppDelRequest and spppDelResponse elements. Refer the 608 "SPP Protocol over SOAP Examples" section of this document for an 609 example of Delete operation on each type of SPPF object. 611 6.2.2.1. Delete Request 613 An SPP Protocol over SOAP Delete request definition is contained 614 within the generic element. 616 617 618 619 621 623 625 626 627 629 The data elements within the element are described 630 as follows: 632 o clientTransId: Zero or one client-generated transaction ID that, 633 within the context of the SPPF client, identifies this request. 634 This value can be used at the discretion of the SPPF client to 635 track, log or correlate requests and their responses. SPPF 636 server MUST echo back this value to the client in the 637 corresponding response to the incoming request. SPPF server 638 will not check this value for uniqueness. 640 o minorVer: Zero or one minor version identifier, indicating the 641 minor version of the SPPF API that the client is attempting to 642 use. This is used in conjunction with the major version 643 identifier in the XML namespace to identify the version of SPPF 644 that the client is using. If the element is not present, the 645 server assumes that the client is using the latest minor version 646 supported by the SPPF server for the given major version. The 647 versions supported by a given SPPF server can be retrieved by 648 the client using the SPPF server menu operation described later 649 in the document. 651 o objKey: One or more elements of abstract type ObjKeyType (as 652 defined in the framework document). Each element contains 653 attributes that uniquely identify the object that the client is 654 requesting the server to delete. Refer the "Concrete Object 655 Keys" section of this document for a description of all concrete 656 object key types, for various SPPF objects, which are eligible 657 to be passed into this element. The elements are processed by 658 the SPPF server in the order in which they are included in the 659 request. With respect to handling of error conditions, it is a 660 matter of policy whether the objects are processed in a "stop 661 and rollback" fashion or in a "stop and commit" fashion. In the 662 "stop and rollback" scenario, the SPPF server would stop 663 processing ObjKeyType elements in the request at the first error 664 and roll back any ObjKeyType elements that had already been 665 processed for that delete request. In the "stop and commit" 666 scenario the SPPF server would stop processing ObjKeyType 667 elements in the request at the first error but commit any 668 KeyParamType elements that had already been processed for that 669 delete request. 671 6.2.2.2. Delete Response 673 An SPP Protocol over SOAP delete response object is contained within 674 the generic element. This response structure is 675 used for a delete request on all types of SPPF objects that are 676 provisioned by the SPPF client. 678 679 680 681 683 684 685 687 688 689 691 692 693 694 695 696 698 699 700 701 702 703 704 705 706 708 An contains the elements necessary for the SPPF 709 client to precisely determine the overall result of the request, and 710 if an error occurred, it provides information about the specific 711 object key(s) that caused the error. 713 The data elements within the SPP Protocol over SOAP Delete response 714 are described as follows: 716 o clientTransId: Zero or one client transaction ID. This value is 717 simply an echo of the client transaction ID that SPPF client 718 passed into the SPPF update request. When included in the 719 request, the SPPF server MUST return it in the corresponding 720 response message. 722 o serverTransId: Exactly one server transaction ID that identifies 723 this request for tracking purposes. This value MUST be unique 724 for a given SPPF server. 726 o overallResult: Exactly one response code and message pair that 727 explicitly identifies the result of the request. See the 728 Response Code section for further details. 730 o detailResult: An optional response code, response message, and 731 ObjKeyType (as defined in the framework document) triplet. This 732 element will be present only if an specific object key level 733 error has occurred. It indicates the error condition and the 734 exact request object key that contributed to the error. The 735 response code will reflect the exact error. See the Response 736 Code section for further details. 738 6.2.3. Accept Operation Structure 740 In SPPF, a Route Group Offer can be accepted or rejected by, or on 741 behalf of, the registrant to whom the Route Group has been offered 742 (refer "Framework Data Model Objects" section of the framework 743 document for a description of the Route Group Offer object). The 744 Accept operation is used to accept such Route Group Offers by, or on 745 behalf of, the Registrant. The request structure for an SPP Protocol 746 over SOAP Accept operation is wrapped within the 747 element while an SPP Protocol over SOAP Accept response is wrapped 748 within the generic element. The following sub- 749 sections describe the spppAcceptRequest and spppAcceptResponse 750 elements. Refer the "SPP Protocol over SOAP Examples" section of 751 this document for an example of Accept operation on a Route Group 752 Offer. 754 6.2.3.1. Accept Request Structure 756 An SPP Protocol over SOAP Accept request definition is contained 757 within the generic element. 759 760 761 762 764 766 769 770 771 773 The data elements within the element are 774 described as follows: 776 o clientTransId: Zero or one client-generated transaction ID that, 777 within the context of the SPPF client, identifies this request. 778 This value can be used at the discretion of the SPPF client to 779 track, log or correlate requests and their responses. SPPF 780 server MUST echo back this value to the client in the 781 corresponding response to the incoming request. SPPF server 782 will not check this value for uniqueness. 784 o minorVer: Zero or one minor version identifier, indicating the 785 minor version of the SPPF API that the client is attempting to 786 use. This is used in conjunction with the major version 787 identifier in the XML namespace to identify the version of SPPF 788 that the client is using. If the element is not present, the 789 server assumes that the client is using the latest minor version 790 supported by the SPPF server for the given major version. The 791 versions supported by a given SPPF server can be retrieved by 792 the client using the SPPF server menu operation described later 793 in the document. 795 o rteGrpOfferKey: One or more elements of type RteGrpOfferKeyType 796 (as defined in this document). Each element contains attributes 797 that uniquely identify a Route Group Offer that the client is 798 requesting the server to accept. The elements are processed by 799 the SPPF server in the order in which they are included in the 800 request. With respect to handling of error conditions, it is a 801 matter of policy whether the objects are processed in a "stop 802 and rollback" fashion or in a "stop and commit" fashion. In the 803 "stop and rollback" scenario, the SPPF server would stop 804 processing RteGrpOfferKeyType elements in the request at the 805 first error and roll back any RteGrpOfferKeyType elements that 806 had already been processed for that accept request. In the 807 "stop and commit" scenario the SPPF server would stop processing 808 RteGrpOfferKeyType elements in the request at the first error 809 but commit any RteGrpOfferKeyType elements that had already been 810 processed for that accept request. 812 6.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 Route 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 847 849 An contains the elements necessary for the SPPF 850 client to precisely determine the overall result of the request, and 851 if an error occurred, it provides information about the specific 852 Route Group Offer key(s) that caused the error. 854 The data elements within the SPP Protocol over SOAP Accept response 855 are described as follows: 857 o clientTransId: Zero or one client transaction ID. This value is 858 simply an echo of the client transaction ID that SPPF client 859 passed into the SPPF update request. When included in the 860 request, the SPPF server MUST return it in the corresponding 861 response message. 863 o serverTransId: Exactly one server transaction ID that identifies 864 this request for tracking purposes. This value MUST be unique 865 for a given SPPF server. 867 o overallResult: Exactly one response code and message pair that 868 explicitly identifies the result of the request. See the 869 Response Code section for further details. 871 o detailResult: An optional response code, response message, and 872 RteGrpOfferKeyType (as defined in this document) triplet. This 873 element will be present only if any specific Route Group Offer 874 key level error has occurred. It indicates the error condition 875 and the exact request Route Group Offer key that contributed to 876 the error. The response code will reflect the exact error. See 877 the Response Code section for further details. 879 6.2.4. Reject Operation Structure 881 In SPPF, Route Group Offer can be accepted or rejected by, or on 882 behalf of, the registrant to whom the Route Group has been offered 883 (refer "Framework Data Model Objects" section of the framerwork 884 document for a description of the Route Group Offer object). The 885 Reject operation is used to reject such Route Group Offers by, or on 886 behalf of, the Registrant. The request structure for an SPP Protocol 887 over SOAP Reject operation is wrapped within the 888 element while an SPP Protocol over SOAP Reject response is wrapped 889 within the generic element. The following sub- 890 sections describe the spppRejectRequest and spppRejecResponse 891 elements. Refer the "SPP Protocol over SOAP Examples" section of 892 this document for an example of Reject operation on a Route Group 893 Offer. 895 6.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 rteGrpOfferKey: One or more elements of type RteGrpOfferKeyType 936 (as defined in this document). Each element contains attributes 937 that uniquely identify a Route 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, it is a 941 matter of policy whether the objects are processed in a "stop 942 and rollback" fashion or in a "stop and commit" fashion. In the 943 "stop and rollback" scenario, the SPPF server would stop 944 processing RteGrpOfferKeyType elements in the request at the 945 first error and roll back any RteGrpOfferKeyType elements that 946 had already been processed for that reject request. In the 947 "stop and commit" scenario the SPPF server would stop processing 948 RteGrpOfferKeyType elements in the request at the first error 949 but commit any RteGrpOfferKeyType elements that had already been 950 processed for that reject request. 952 6.2.4.2. Reject Response 954 An SPP Protocol over SOAP reject response structure is contained 955 within the generic element. This response 956 structure is used for an Reject request on a Route Group Offer. 958 959 960 961 963 964 965 968 969 970 972 973 974 975 976 977 979 980 981 982 983 984 985 986 987 989 An contains the elements necessary for the SPPF 990 client to precisely determine the overall result of the request, and 991 if an error occurred, it provides information about the specific 992 Route Group Offer key(s) that caused the error. 994 The data elements within the SPP Protocol over SOAP Reject response 995 are described as follows: 997 o clientTransId: Zero or one client transaction ID. This value is 998 simply an echo of the client transaction ID that SPPF client 999 passed into the SPPF update request. When included in the 1000 request, the SPPF server MUST return it in the corresponding 1001 response message. 1003 o serverTransId: Exactly one server transaction ID that identifies 1004 this request for tracking purposes. This value MUST be unique 1005 for a given SPPF server. 1007 o overallResult: Exactly one response code and message pair that 1008 explicitly identifies the result of the request. See the 1009 Response Code section for further details. 1011 o detailResult: An optional response code, response message, and 1012 RteGrpOfferKeyType (as defined in this document) triplet. This 1013 element will be present only if any specific Route Group Offer 1014 key level error has occurred. It indicates the error condition 1015 and the exact request Route Group Offer key that contributed to 1016 the error. The response code will reflect the exact error. See 1017 the Response Code section for further details. 1019 6.2.5. Batch Operation Structure 1021 An SPP Protocol over SOAP Batch request XML structure allows the SPPF 1022 client to send any of of Add, Del, Accept or Reject operations 1023 together in one single request. This gives an SPPF Client the 1024 flexibility to use one single request structure to perform more than 1025 operations (verbs). The batch request structure is wrapped within 1026 the element while a SPPF Batch response is wrapped 1027 within the element. This following sub-sections 1028 describe the spppBatchRequest and spppBatchResponse elements. Refer 1029 the "SPP Protocol over SOAP Examples" section of this document for an 1030 example of a batch operation. 1032 6.2.5.1. Batch Request Structure 1034 An SPP Protocol over SOAP Batch request definition is contained 1035 within the generic element. 1037 1038 1039 1040 1042 1044 1045 1046 1047 1049 1051 1052 1053 1054 1056 The data elements within the element are described 1057 as follows: 1059 o clientTransId: Zero or one client-generated transaction ID that, 1060 within the context of the SPPF client, identifies this request. 1061 This value can be used at the discretion of the SPPF client to 1062 track, log or correlate requests and their responses. SPPF 1063 server MUST echo back this value to the client in the 1064 corresponding response to the incoming request. SPPF server 1065 will not check this value for uniqueness. 1067 o minorVer: Zero or one minor version identifier, indicating the 1068 minor version of the SPPF API that the client is attempting to 1069 use. This is used in conjunction with the major version 1070 identifier in the XML namespace to identify the version of SPPF 1071 that the client is using. If the element is not present, the 1072 server assumes that the client is using the latest minor version 1073 supported by the SPPF server for the given major version. The 1074 versions supported by a given SPPF server can be retrieved by 1075 the client using the SPPF server menu operation described later 1076 in the document. 1078 o addObj: One or more elements of abstract type BasicObjType where 1079 each element identifies an object that needs to be added. 1081 o delObj: One or more elements of abstract type ObjKeyType where 1082 each element identifies a key for the object that needs to be 1083 deleted . 1085 o acceptRteGrpOffer: One or more elements of type 1086 RteGrpOfferKeyType where each element identifies a Route Group 1087 Offer that needs to be accepted. 1089 o rejectRteGrpOffer: One or more elements of type 1090 RteGrpOfferKeyType where each element identifies a Route Group 1091 Offer that needs to be rejected. 1093 With respect to handling of error conditions, it is a matter of 1094 policy whether the batch operation processed in a "stop and rollback" 1095 fashion or in a "stop and commit" fashion. In the "stop and 1096 rollback" scenario, the SPPF server would stop processing elements in 1097 the request at the first error and roll back any elements that had 1098 already been processed for that batch request. In the "stop and 1099 commit" scenario the SPPF server would stop processing elements in 1100 the request at the first error but commit any elements that had 1101 already been processed for that batch request. 1103 6.2.5.2. Batch Response 1105 An SPP Protocol over SOAP batch response structure is contained 1106 within the generic element. This response 1107 structure is used for an Batch request that contains many different 1108 types of SPPF operations. 1110 1111 1112 1113 1115 1116 1117 1118 1120 1122 1124 1126 1127 1128 1129 1131 An contains the elements necessary for an SPPF 1132 client to precisely determine the overall result of various 1133 operations in the request, and if an error occurred, it provides 1134 information about the specific objects or keys in the request that 1135 caused the error. 1137 The data elements within the SPP Protocol over SOAP Batch response 1138 are described as follows: 1140 o clientTransId: Zero or one client transaction ID. This value is 1141 simply an echo of the client transaction ID that SPPF client 1142 passed into the SPPF update request. When included in the 1143 request, the SPPF server MUST return it in the corresponding 1144 response message. 1146 o serverTransId: Exactly one server transaction ID that identifies 1147 this request for tracking purposes. This value MUST be unique 1148 for a given SPPF server. 1150 o overallResult: Exactly one response code and message pair that 1151 explicitly identifies the result of the request. See the 1152 Response Code section for further details. 1154 o addResult: One or more elements of type ObjResultCodeType where 1155 each element identifies the result code, result message and the 1156 specific object that the result relates to. 1158 o delResult: One or more elements of type ObjKeyResultCodeType 1159 where each element identifies the result code, result message 1160 and the specific object key that the result relates to. 1162 o acceptResult: One or more elements of type 1163 RteGrpOfferKeyResultCodeType where each element identifies the 1164 result code, result message and the specific Route Group Offer 1165 key that the result relates to. 1167 o rejectResult: One or more elements of type 1168 RteGrpOfferKeyResultCodeType where each element identifies the 1169 result code, result message and the specific Route Group Offer 1170 key that the result relates to. 1172 6.2.6. Get Operation Structure 1174 In order to query the details of an object from the Registry, an 1175 authorized entity can send the spppGetRequest to the registry with a 1176 GetRqstType XML data structure containing one or more object keys 1177 that uniquely identify the object whose details are being queried. 1178 The request strcuture for an SPP Protocol over SOAP Get operation is 1179 contained within the generic element while an SPP 1180 Protocol over SOAP Get response is wrapped within the generic 1181 element. The following sub-sections describe the 1182 spppGetRequest and spppGetResponse element. Refer the examples 1183 section for an example of SPP Protocol over SOAP Get operation on 1184 each type of SPPF object 1186 6.2.6.1. Get Request 1188 1189 1190 1191 1193 1196 1197 1198 1200 The data elements within the element are described 1201 as follows: 1203 o minorVer: Zero or one minor version identifier, indicating the 1204 minor version of the SPPF API that the client is attempting to 1205 use. This is used in conjunction with the major version 1206 identifier in the XML namespace to identify the version of SPPF 1207 that the client is using. If the element is not present, the 1208 server assumes that the client is using the latest minor version 1209 supported by the SPPF server for the given major version. The 1210 versions supported by a given SPPF server can be retrieved by 1211 the client using the SPPF server menu operation described later 1212 in the document. 1214 o objKey: One or more elements of abstract type ObjKeyType (as 1215 defined in the framework document). Each element contains 1216 attributes that uniquely identify the object that the client is 1217 requesting the server to query. Refer the "Concrete Object 1218 Keys" section of this document for a description of all concrete 1219 object key types, for various SPPF objects, which are eligible 1220 to be passed into this element. 1222 6.2.6.2. Get Response 1224 The spppGetResponse element is described later in section titled 1225 "Generic Query Response". 1227 6.2.7. Get Route Group Offers Operation Structure 1229 In addition to the ability to query the details of one or more Route 1230 Group offers using an a Route Group Offer key in the spppGetRequest, 1231 this operation also provides an additional, more flexible, structure 1232 to query for Route Group Offer objects. This additional structure is 1233 contained within the element while the 1234 response is wrapped within the generic element. 1235 The following sub-sections describe the getRteGrpOffersRequest and 1236 spppGetResponse elements. 1238 6.2.7.1. Get Route Group Offers Request 1240 Using the details passed into this structure, the server will attempt 1241 to find Route Group Offer objects that satisfy all the criteria 1242 passed into the request. If no criteria is passed in then the server 1243 will return the list of Route Group Offer objects that belongs to the 1244 registrant. If there are no matching Route Group Offers found then 1245 an empty result set will be returned. 1247 1248 1249 1250 1252 1254 1256 1258 1260 1261 1262 1264 The data elements within the element are 1265 described as follows: 1267 o minorVer: Zero or one minor version identifier, indicating the 1268 minor version of the SPPF API that the client is attempting to 1269 use. This is used in conjunction with the major version 1270 identifier in the XML namespace to identify the version of SPPF 1271 that the client is using. If the element is not present, the 1272 server assumes that the client is using the latest minor version 1273 supported by the SPPF server for the given major version. The 1274 versions supported by a given SPPF server can be retrieved by 1275 the client using the SPPF server menu operation described later 1276 in the document. 1278 o offeredBy: Zero or more organization IDs. Only offers that are 1279 offered to the organization IDs in this list should be included 1280 in the result set. The result set is also subject to other 1281 query criteria in the request. 1283 o offeredTo: Zero or more organization IDs. Only offers that are 1284 offered by the organization IDs in this list should be included 1285 in the result set. The result set is also subject to other 1286 query criteria in the request. 1288 o status: The status of the offer, offered or accepted. Only 1289 offers in the specified status should be included in the result 1290 set. If this element is not present then the status of the 1291 offer should not be considered in the query. The result set is 1292 also subject to other query criteria in the request. 1294 o rteGrpOfferKey: Zero or more Route Group Offer Keys. Only 1295 offers having one of these keys should be included in the result 1296 set. The result set is also subject to other query criteria in 1297 the request. 1299 6.2.7.2. Get Route Group Offers Response 1301 The spppGetResponse element is described later in section titled 1302 "Generic Query Response". 1304 6.2.8. Generic Query Response 1306 An SPP Protocol over SOAP query response object is contained within 1307 the generic element. 1309 1310 1311 1312 1314 1317 1318 1319 1321 An contains the elements necessary for the SPPF 1322 client to precisely determine the overall result of the query, and 1323 details of any SPPF objects that matched the criteria in the request. 1325 The data elements within the SPP Protocol over SOAP query response 1326 are described as follows: 1328 o overallResult: Exactly one response code and message pair that 1329 explicitly identifies the result of the request. See the 1330 Response Code section for further details. 1332 o resultObj: The set of zero or more objects that matched the 1333 query criteria. If no objects matched the query criteria then 1334 the result object(s) MUST be empty and the overallResult value 1335 MUST indicate success (if no matches are found for the query 1336 criteria, the response is considered a success). 1338 6.2.9. Get Server Details Operation Structure 1340 In order to query certain details of the SPPF server, like the SPPF 1341 server's status and the major/minor version supported by the server, 1342 the Server Details operation structure SHOULD be used. This 1343 structure is contained within the element 1344 while a SPPF server status response is wrapped within the 1345 element. This following sub-sections 1346 describe the spppServerStatusRequest and spppServerStatusResponse 1347 elements. 1349 6.2.9.1. Get Server Details Request 1350 1351 1352 1353 1355 1356 1357 1359 The data elements within the element are 1360 described as follows: 1362 o minorVer: Zero or one minor version identifier, indicating the 1363 minor version of the SPP Protocol over SOAP API that the client 1364 is attempting to use. This is used in conjunction with the 1365 major version identifier in the XML namespace to identify the 1366 version of SPP Protocol over SOAP that the client is using. If 1367 the element is not present, the server assumes that the client 1368 is using the latest minor version of SPP Protocol over SOAP 1369 supported by the SPPF server for the given major version. The 1370 versions of SPP Protocol over SOAP supported by a given SPPF 1371 server can be retrieved by the client using this same 1372 spppServerStatusRequest without passing in the minorVer element. 1374 6.2.9.2. Get Server Details Response 1376 An SPP Protocol over SOAP server details response structure is 1377 contained within the generic element. 1379 1380 1381 1382 1383 1384 1385 1386 1388 The data elements within the element are 1389 described as follows: 1391 o overallResult: Exactly one response code and message pair that 1392 explicitly identifies the result of the request. See the 1393 Response Code section for further details. 1395 o svcMenu: Exactly one element of type SvcMenuType which in turn 1396 contains the elements to return the server status and major/ 1397 minor version of the SPP Protocol over SOAP supported by the 1398 SPPF server (refer framework document for definition of 1399 SvcMenuType) . 1401 6.3. Response Codes and Messages 1403 This section contains the listing of response codes and their 1404 corresponding human-readable text. These response codes are in 1405 conformance with the response types defined in the section "Response 1406 Message Types" of the framework document. 1408 The response code numbering scheme generally adheres to the theory 1409 formalized in section 4.2.1 of [RFC5321]: 1411 o The first digit of the response code can only be 1 or 2: 1 = a 1412 positive result, 2 = a negative result. 1414 o The second digit of the response code indicates the category: 0 1415 = Protocol Syntax, 1 = Implementation Specific Business Rule, 2 1416 = Security, 3 = Server System. 1418 o The third and fourth digits of the response code indicate the 1419 individual message event within the category defines by the 1420 first two digits. 1422 The response codes are also categorized as to whether they are 1423 overall response codes that may only be returned in the 1424 "overallResult" data element in SPPF responses, or object level 1425 response codes that may only be returned in the "detailResult" 1426 element of the SPPF responses. 1428 +--------+--------------------------+-------------------------------+ 1429 | Result | Result Message | Overall or Object Level | 1430 | Code | | | 1431 +--------+--------------------------+-------------------------------+ 1432 | 1000 | Request Succeeded. | Overall Response Code | 1433 | | | | 1434 | 2000 | Request syntax invalid. | Overall Response Code | 1435 | | | | 1436 | 2001 | Request too large. | Overall Response Code | 1437 | | MaxSupported:[Maximum | | 1438 | | requests supported] | | 1439 | | | | 1440 | 2002 | Version not supported. | Overall Response Code | 1441 | | | | 1442 | 2100 | Command invalid. | Overall Response Code | 1443 | | | | 1444 | 2300 | System temporarily | Overall Response Code | 1445 | | unavailable. | | 1446 | | | | 1447 | 2301 | Unexpected internal | Overall Response Code | 1448 | | system or server error. | | 1449 | | | | 1450 | 2101 | Attribute value invalid. | Object Level Response Code | 1451 | | | | 1452 | | AttrName:[AttributeName] | | 1453 | | AttrVal:[AttributeValue] | | 1454 | | | | 1455 | 2102 | Object does not exist. | Object Level Response Code | 1456 | | AttrName:[AttributeName] | | 1457 | | AttrVal:[AttributeValue] | | 1458 | | | | 1459 | 2103 | Object status or | Object Level Response Code | 1460 | | ownership does not allow | | 1461 | | for operation. | | 1462 | | AttrName:[AttributeName] | | 1463 | | AttrVal:[AttributeValue] | | 1464 +--------+--------------------------+-------------------------------+ 1466 Table 1: Response Codes Numbering Scheme and Messages 1468 Response message for response code 2001 is "parameterized" with the 1469 following parameter: "[Maximum requests supported]". When the 1470 request is too large, this parameter MUST be used to indicate the 1471 maximum number of requests supported by the server in a single 1472 protocol operation. 1474 Each of the object level response messages are "parameterized" with 1475 the following parameters: "AttributeName" and "AttributeValue". 1477 For example, if an SPPF client sends a request to delete a 1478 Destination Group with a name "TestDG", and it does not already 1479 exist, then the error message returned should be: "Attribute value 1480 invalid. AttrName:dgName AttrVal:TestDG". 1482 The use of these parameters MUST adhere to the rules defined in 1483 "Response Message Types" section of the framework document. 1485 7. Protocol Operations 1487 Refer the "Framework Operations" section of the framework document 1488 for a description of all SPPF operations, and any necessary semantics 1489 that MUST be adhered to in order to conform with the SPPF 1490 specification. 1492 8. SPP Protocol over SOAP WSDL Definition 1494 The SPP Protocol over SOAP WSDL and data types are defined below. 1495 The WSDL design approach is commonly referred to as _Generic WSDL_. 1496 It is generic in the sense that there is not a specific WSDL 1497 operation defined for each object type that is supported by the SPPF 1498 protocol. There is a single WSDL structure for each type of SPPF 1499 operation. Each such WSDL structure contains exactly one input 1500 structure and one output structure that wraps any data elements that 1501 are part of the incoming request and the outgoing response 1502 respectively. The spppSOAPBinding in the WSDL defines the binding 1503 style as _document_ and the encoding as _literal_. It is this 1504 combination of _wrapped_ input and output data structures, _document_ 1505 binding style, and _literal_ encoding that characterize the Document 1506 Literal Wrapped style of WSDL specifications. 1508 Note: The following WSDL has been formatted (e.g., tabs, spaces) to 1509 meet I-D requirements. 1511 1512 1519 1520 1523 1524 1525 ---- Import base schema ---- 1526 1527 1528 1530 1531 1532 ---- Key type(s) extended 1533 from base schema. ---- 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1556 1557 1558 1559 1560 1562 1564 1565 1566 1567 1569 1570 1571 1572 1573 1574 1576 1577 1579 1581 1582 1583 1584 1585 1586 1587 1588 ---- Generic Request and 1589 Response Definitions ---- 1590 1591 1592 1593 1594 1595 1597 1599 1601 1602 1603 1604 1605 1606 1607 1609 1611 1613 1614 1615 1616 1617 1618 1619 1621 1623 1626 1627 1628 1629 1630 1631 1632 1634 1636 1639 1640 1641 1642 1643 1644 1645 1647 1650 1651 1652 1653 1654 1655 1656 1658 1660 1661 1662 1663 1665 1667 1668 1669 1670 1671 1672 1673 1674 1676 1677 1678 1679 1680 1681 1682 1684 1687 1689 1691 1694 1695 1696 1697 1698 1699 1700 1702 1704 1706 1709 1710 1711 1712 1713 1714 1715 1717 1719 1721 1724 1725 1726 1727 1728 1729 1730 1732 1734 1736 1739 1740 1741 1742 1743 1744 1745 1747 1749 1751 1754 1755 1756 1757 1758 1759 1760 1762 1764 1766 1767 1769 1771 1773 1775 1776 1777 1779 1780 1781 1782 1783 1785 1788 1789 1790 1791 1792 1793 1794 1796 1798 1799 1800 1801 1802 1803 ---- Operation Result Type 1804 Definitions ---- 1805 1806 1807 1808 1809 1810 1811 1812 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1828 1830 1831 1832 1833 1834 1835 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 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 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 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 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2007 2008 2009 2010 2011 2012 2013 2014 2015 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2032 Figure 2: WSDL 2034 9. SPP Protocol over SOAP Examples 2036 This section shows XML message exchange between two SIP Service 2037 Providers (SSP) and a registry. The messages in this section are 2038 valid XML instances that conform to the SPP Protocol over SOAP schema 2039 version within this document. This section relies on the XML data 2040 structures defined in the base SPPF specification 2041 [I-D.draft-ietf-drinks-spp-framework]. So refer to that document to 2042 understand XML object types embedded in these example messages. 2044 In this sample use case scenario, SSP1 and SSP2 provision resource 2045 data in the registry and use SPPF constructs to selectively share the 2046 route groups. In the figure below, SSP2 has two ingress SBE 2047 instances that are associated with the public identities that SSP2 2048 has the retail relationship with. Also, the two SBE instances for 2049 SSP1 are used to show how to use SPPF to associate route preferences 2050 for the destination ingress routes and exercise greater control on 2051 outbound traffic to the peer's ingress SBEs. 2053 ---------------+ +------------------ 2054 | | 2055 +------+ +------+ 2056 | sbe1 | | sbe2 | 2057 +------+ +------+ 2058 SSP1 | | SSP2 2059 +------+ +------+ 2060 | sbe3 | | sbe4 | 2061 +------+ +------+ 2062 iana-en:111 | | iana-en:222 2063 ---------------+ +------------------ 2064 | | 2065 | | 2066 | SPPF +------------------+ SPPF | 2067 +------->| Registry |<--------+ 2068 +------------------+ 2070 9.1. Add Destination Group 2072 SSP2 adds a destination group to the registry for use later. The 2073 SSP2 SPPF client sets a unique transaction identifier 'txn_1479' for 2074 tracking purposes. The name of the destination group is set to 2075 DEST_GRP_SSP2_1 2076 2077 2082 2083 2084 2085 2086 txn_1479 2087 2088 2089 iana-en:222 2090 iana-en:223 2091 DEST_GRP_SSP2_1 2092 2093 2094 2095 2097 The registry processes the request and return a favorable response 2098 confirming successful creation of the named destination group. Also, 2099 besides returning a unique server transaction identifier, Registry 2100 also returns the matching client transaction identifier from the 2101 request message back to the SPPF client. 2103 2104 2106 2107 2110 txn_1479 2111 tx_12345 2112 2113 1000 2114 Request Succeeded. 2115 2116 2117 2118 2120 9.2. Add Route Records 2122 SSP2 adds an ingress routes in the registry. 2124 2125 2130 2131 2132 2133 2134 txn_1479 2135 2136 2137 iana-en:222 2138 iana-en:223 2139 RTE_SSP2_SBE2 2140 true 2141 10 2142 u 2143 E2U+sip 2144 2145 ^(.*)$ 2146 sip:\1@sbe2.ssp2.example.com 2147 2148 2149 2150 2151 2153 The registry returns a success response. 2155 2156 2158 2159 2162 txn_1479 2163 tx_12345 2164 2165 1000 2166 Request Succeeded. 2167 2168 2169 2170 2172 9.3. Add Route Records -- URIRteRecType 2174 SSP2 adds another ingress routes in the registry and makes use of 2175 URIRteRecType 2177 2178 2183 2184 2185 2186 txn_1479 2187 2188 2189 iana-en:222 2190 iana-en:223 2191 RTE_SSP2_SBE4 2192 true 2193 ^(.*)$ 2194 sip:\1;npdi@sbe4.ssp2.example.com 2195 2196 2197 2198 2199 The registry returns a success response. 2201 2202 2203 2204 2207 txn_1479 2208 tx_12345 2209 2210 1000 2211 Request Succeeded. 2212 2213 2214 2215 2217 9.4. Add Route Group 2219 SSP2 creates the grouping of the ingress routes and chooses higher 2220 precedence for RTE_SSP2_SBE2 by setting a lower number for the 2221 "priority" attribute, a protocol agnostic precedence indicator. 2223 2224 2229 2230 2231 2232 txn_1479 2233 2234 2235 iana-en:222 2236 iana-en:223 2237 RTE_GRP_SSP2_1 2238 2239 2240 iana-en:222 2241 RTE_SSP2_SBE2 2242 RteRec 2243 2244 100 2245 2246 DEST_GRP_SSP2_1 2247 true 2248 10 2249 2250 2251 2252 2254 To confirm successful processing of this request, registry returns a 2255 well-known result code '1000' to the SSP2 client. 2257 2258 2259 2260 2263 txn_1479 2264 tx_12345 2265 2266 1000 2267 Request Succeeded. 2268 2269 2270 2271 2273 9.5. Add Public Identity -- Successful COR claim 2275 SSP2 activates a TN public identity by associating it with a valid 2276 destination group. Further, SSP2 puts forth a claim that it is the 2277 carrier-of-record for the TN. 2279 2284 2285 2286 2287 txn_1479 2288 2289 2290 iana-en:222 2291 iana-en:223 2292 DEST_GRP_SSP2_1 2293 +12025556666 2294 2295 true 2296 2297 2298 2299 2300 2301 Assuming that the registry has access to TN authority data and it 2302 performs the required checks to verify that SSP2 is in fact the 2303 service provider of record for the given TN, the request is processed 2304 successfully. In the response message, the registry sets the value 2305 of to "true" in order to confirm SSP2 claim as the carrier of 2306 record and the reflects the time when the carrier of record 2307 claim is processed. 2309 2310 2313 2314 2317 txn_1479 2318 tx_12345 2319 2320 1000 2321 Request Succeeded. 2322 2323 2324 1000 2325 Request Succeeded. 2326 2327 iana-en:222 2328 iana-en:223 2329 2010-05-30T09:30:10Z 2330 DEST_GRP_SSP2_1 2331 +12025556666 2332 2333 true 2334 true 2335 2010-05-30T09:30:11Z 2336 2337 2338 2339 2340 2341 2343 9.6. Add LRN 2345 If another entity that SSP2 shares the routes with has access to 2346 Number Portability data, it may choose to perform route lookups by 2347 routing number. Therefore, SSP2 associates a routing number to a 2348 destination group in order to facilitate ingress route discovery. 2350 2351 2356 2357 2358 2359 txn_1479 2360 2361 2362 iana-en:222 2363 iana-en:223 2364 DEST_GRP_SSP2_1 2365 2025550000 2366 2367 2368 2369 2371 Registry completes the request successfully and returns a favorable 2372 response to the SPPF client. 2374 2375 2377 2378 2381 txn_1479 2382 tx_12345 2383 2384 1000 2385 Request Succeeded. 2386 2387 2388 2389 2391 9.7. Add TN Range 2393 Next, SSP2 activates a block of ten thousand TNs and associate it to 2394 a destination group. 2396 2397 2402 2403 2404 2405 txn_1479 2406 2407 2408 iana-en:222 2409 iana-en:223 2410 DEST_GRP_SSP2_1 2411 2412 +12026660000 2413 +12026669999 2414 2415 2416 2417 2418 2419 Registry completes the request successfully and returns a favorable 2420 response. 2422 2423 2425 2426 2429 txn_1479 2430 tx_12345 2431 2432 1000 2433 Request Succeeded. 2434 2435 2436 2437 2439 9.8. Add TN Prefix 2441 Next, SSP2 activates a block of ten thousand TNs using the TNPType 2442 structure and identifying a TN prefix. 2444 2445 2450 2451 2452 2453 txn_1479 2454 2455 2456 iana-en:222 2457 iana-en:223 2458 DEST_GRP_SSP2_1 2459 +1202777 2460 2461 2463 2464 2466 Registry completes the request successfully and returns a favorable 2467 response. 2469 2470 2472 2473 2476 txn_1479 2477 tx_12345 2478 2479 1000 2480 Request Succeeded. 2481 2482 2483 2484 2486 9.9. Enable Peering -- Route Group Offer 2488 In order for SSP1 to complete session establishment for a destination 2489 TN where the target subscriber has a retail relationship with SSP2, 2490 it first requires an asynchronous bi-directional handshake to show 2491 mutual consent. To start the process, SSP2 initiates the peering 2492 handshake by offering SSP1 access to its route group. 2494 2495 2500 2501 2502 2503 txn_1479 2504 2505 2506 iana-en:222 2507 iana-en:223 2508 2509 2510 iana-en:222 2511 RTE_GRP_SSP2_1 2512 RteGrp 2513 2514 iana-en:111 2515 2516 offered 2517 2518 2006-05-04T18:13:51.0Z 2519 2520 2521 2522 2523 2525 Registry completes the request successfully and confirms that the 2526 SSP1 will now have the opportunity to weigh in on the offer and 2527 either accept or reject it. The registry may employ out-of-band 2528 notification mechanisms for quicker updates to SSP1 so they can act 2529 faster, though this topic is beyond the scope of this document. 2531 2532 2534 2535 2538 txn_1479 2539 tx_12345 2540 2541 1000 2542 Request Succeeded. 2543 2544 2545 2546 2548 9.10. Enable Peering -- Route Group Offer Accept 2550 SSP1 responds to the offer from SSP2 and agrees to have visibility to 2551 SSP2 ingress routes. 2553 2554 2557 2558 2559 2560 2561 txn_1479 2562 2563 2564 2565 iana-en:222 2566 RTE_GRP_SSP2_1 2567 RteGrp 2568 2569 iana-en:111 2570 2571 2572 2573 2574 Registry confirms that the request has been processed successfully. 2575 From this point forward, if SSP1 looks up a public identity through 2576 the query resolution server, where the public identity is part of the 2577 destination group by way of "RTE_GRP_SSP2_1" route association, SSP2 2578 ingress SBE information will be shared with SSP1. 2580 2581 2583 2584 2587 txn_1479 2588 tx_12350 2589 2590 1000 2591 Request Succeeded. 2592 2593 2594 2595 2597 9.11. Add Egress Route 2599 SSP1 wants to prioritize all outbound traffic to routes associated 2600 with "RTE_GRP_SSP2_1" route group through "sbe1.ssp1.example.com". 2602 2603 2608 2609 2610 2611 txn_1479 2612 2613 2614 iana-en:222 2615 iana-en:223 2616 EGR_RTE_01 2617 50 2618 2619 ^(.*@)(.*)$ 2620 \1\2?route=sbe1.ssp1.example.com 2621 2622 2623 iana-en:222 2624 SSP2_RTE_REC_3 2625 RteRec 2626 2627 2628 2629 2630 2632 Since peering has already been established, the request to add the 2633 egress route has been successfully completed. 2635 2636 2638 2639 2642 txn_1479 2643 tx_12345 2644 2645 1000 2646 Request Succeeded. 2647 2648 2649 2650 2652 9.12. Remove Peering -- Route Group Offer Reject 2654 SSP1 had earlier accepted to have visibility to SSP2 ingress routes. 2655 SSP1 now decides to no more maintain this visiblity and hence rejects 2656 the Route Group Offer. 2658 2659 2662 2663 2664 2665 2666 txn_1479 2667 2668 2669 2670 iana-en:222 2671 RTE_GRP_SSP2_1 2672 RteGrp 2673 2674 iana-en:111 2675 2676 2677 2678 2679 Registry confirms that the request has been processed successfully. 2680 From this point forward, if SSP1 looks up a public identity through 2681 the query resolution server, where the public identity is part of the 2682 destination group by way of "RTE_GRP_SSP2_1" route association, SSP2 2683 ingress SBE information will NOT be shared with SSP1 and hence SSP2 2684 ingress SBE will NOT be returned in the query response. 2686 2687 2689 2690 2693 txn_1479 2694 tx_12350 2695 2696 1000 2697 Request Succeeded. 2698 2699 2700 2701 2703 9.13. Get Destination Group 2705 SSP2 uses the 'spppGetRequest' operation to tally the last 2706 provisioned record for destination group DEST_GRP_SSP2_1. 2708 2709 2713 2714 2715 2716 2717 2718 iana-en:222 2719 DEST_GRP_SSP2_1 2720 DestGrp 2721 2722 2723 2724 2726 Registry completes the request successfully and returns a favorable 2727 response. 2729 2730 2733 2734 2737 2738 1000 2739 success 2740 2741 2742 iana-en:222 2743 iana-en:223 2744 DEST_GRP_SSP2_1 2745 2746 2747 2748 2750 9.14. Get Public Identity 2752 SSP2 obtains the last provisioned record associated with a given TN. 2754 2755 2760 2761 2762 2763 2764 2765 iana-en:222 2766 2767 +12025556666 2768 TN 2769 2770 2771 2772 2773 2775 Registry completes the request successfully and returns a favorable 2776 response. 2778 2781 2782 2785 2786 1000 2787 success 2788 2789 2790 iana-en:222 2791 iana-en:223 2792 DEST_GRP_SSP2_1 2793 +12025556666 2794 2795 true 2796 true 2797 2010-05-30T09:30:10Z 2798 2799 2800 2801 2802 2804 9.15. Get Route Group Request 2806 SSP2 obtains the last provisioned record for the route group 2807 RTE_GRP_SSP2_1. 2809 2810 2814 2815 2816 2817 2818 2819 iana-en:222 2820 RTE_GRP_SSP2_1 2821 RteGrp 2822 2823 2824 2825 2827 Registry completes the request successfully and returns a favorable 2828 response. 2830 2831 2834 2835 2838 2839 1000 2840 success 2841 2842 2843 iana-en:222 2844 iana-en:223 2845 RTE_GRP_SSP2_1 2846 2847 2848 iana-en:222 2849 RTE_SSP2_SBE2 2850 RteRec 2851 2852 100 2853 2854 2855 2856 iana-en:222 2857 RTE_SSP2_SBE4 2858 RteRec 2859 2860 101 2861 2862 DEST_GRP_SSP2_1 2863 true 2864 10 2865 2866 2867 2868 2870 9.16. Get Route Group Offers Request 2872 SSP2 fetches the last provisioned route group offer to the 2873 SSP1. 2875 2876 2879 2880 2881 2882 iana-en:111 2883 2884 2885 2887 Registry processes the request successfully and returns a favorable 2888 response. 2890 2891 2894 2895 2898 2899 1000 2900 success 2901 2902 2903 iana-en:222 2904 iana-en:223 2905 2907 2908 iana-en:222 2909 RTE_GRP_SSP2_1 2910 RteGrp 2911 2912 iana-en:111 2913 2914 offered 2915 2916 2006-05-04T18:13:51.0Z 2917 2918 2919 2921 2922 2924 9.17. Get Egress Route 2926 SSP1 wants to verify the last provisioned record for the egress route 2927 called EGR_RTE_01. 2929 2930 2934 2935 2936 2937 2938 2939 iana-en:111 2940 EGR_RTE_01 2941 EgrRte 2942 2943 2944 2945 2947 Registry completes the request successfully and returns a favorable 2948 response. 2950 2951 2954 2955 2958 2959 1000 2960 success 2961 2962 2963 iana-en:222 2964 iana-en:223 2965 EGR_RTE_01 2966 50 2967 2968 ^(.*)$ 2969 sip:\1@sbe1.ssp1.example.com 2970 2971 2972 iana-en:222 2973 RTE_GRP_SSP2_1 2974 RteRec 2975 2976 2977 2978 2979 2981 9.18. Delete Destination Group 2983 SSP2 initiates a request to delete the destination group 2984 DEST_GRP_SSP2_1. 2986 2987 2991 2992 2993 2994 2995 2996 iana-en:222 2997 DEST_GRP_SSP2_1 2998 DestGrp 2999 3000 3001 3002 3004 Registry completes the request successfully and returns a favorable 3005 response. 3007 3008 3010 3011 3014 tx_12354 3015 3016 1000 3017 Request Succeeded. 3018 3019 3020 3021 3023 9.19. Delete Public Identity 3025 SSP2 chooses to de-activate the TN and remove it from the registry. 3027 3028 3033 3034 3035 3036 3037 3038 iana-en:222 3039 DEST_GRP_SSP2_1 3040 3041 +12025556666 3042 TN 3043 3044 3045 3046 3047 3049 Registry completes the request successfully and returns a favorable 3050 response. 3052 3053 3055 3056 3059 tx_12354 3060 3061 1000 3062 Request Succeeded. 3063 3064 3065 3066 3068 9.20. Delete Route Group Request 3070 SSP2 removes the route group called RTE_GRP_SSP2_1. 3072 3073 3077 3078 3079 3080 3081 3082 iana-en:222 3083 RTE_GRP_SSP2_1 3084 RteGrp 3085 3086 3087 3088 3090 Registry completes the request successfully and returns a favorable 3091 response. 3093 3094 3096 3097 3100 tx_12354 3101 3102 1000 3103 Request Succeeded. 3104 3105 3106 3107 3109 9.21. Delete Route Group Offers Request 3111 SSP2 no longer wants to share route group RTE_GRP_SSP2_1 with SSP1. 3113 3114 3118 3119 3120 3121 3122 3123 3124 iana-en:222 3125 RTE_GRP_SSP2_1 3126 RteGrp 3127 3128 iana-en:111 3129 3130 3131 3132 3134 Registry completes the request successfully and returns a favorable 3135 response. Restoring this resource sharing will require a new route 3136 group offer from SSP2 to SSP1 followed by a successful route group 3137 accept request from SSP1. 3139 3140 3142 3143 3146 tx_12354 3147 3148 1000 3149 Request Succeeded. 3150 3151 3153 3154 3156 9.22. Delete Egress Route 3158 SSP1 decides to remove the egress route with the label EGR_RTE_01. 3160 3161 3165 3166 3167 3168 3169 3170 iana-en:111 3171 EGR_RTE_01 3172 EgrRte 3173 3174 3175 3176 3178 Registry completes the request successfully and returns a favorable 3179 response. 3181 3182 3184 3185 3188 tx_12354 3189 3190 1000 3191 Request Succeeded. 3192 3193 3194 3196 3198 9.23. Batch Request 3200 Following is an example of how some of the operations mentioned in 3201 previous sections MAY be performed by an SPPF client as a batch in 3202 one single SPP Protocol over SOAP request. 3204 In the sample request below SSP1 wants to accept a Route Group Offer 3205 from SSP3, add a Destination Group, add a NAPTR Route Rec, add a 3206 Route Group, add a Route Group Offer, delete a previously provisioned 3207 TN type Public Identifier, delete a previously provisioned Route 3208 Group, and reject a Route Group Offer from SSP4. 3210 3211 3216 3217 3218 3219 txn_1467 3220 1 3222 3223 3224 iana-en:225 3225 RTE_SSP3_SBE1_Offered 3226 RteGrp 3227 3228 iana-en:222 3229 3231 3232 iana-en:222 3233 iana-en:223 3234 DEST_GRP_SSP2_1 3235 3237 3238 iana-en:222 3239 iana-en:223 3240 RTE_SSP2_SBE2 3241 10 3242 u 3243 E2U+sip 3244 3245 ^(.*)$ 3246 sip:\1@sbe2.ssp2.example.com 3247 3248 3250 3251 iana-en:222 3252 iana-en:223 3253 RTE_GRP_SSP2_1 3254 3255 3256 iana-en:222 3257 RTE_SSP2_SBE2 3258 RteRec 3259 3260 100 3261 3262 DEST_GRP_SSP2_1 3263 true 3264 10 3265 3267 3268 iana-en:222 3269 iana-en:223 3270 3271 3272 iana-en:222 3273 RTE_GRP_SSP2_1 3274 RteGrp 3275 3276 iana-en:111 3277 3278 offered 3279 3280 2006-05-04T18:13:51.0Z 3281 3282 3284 3285 iana-en:222 3286 DEST_GRP_SSP2_Previous 3287 3288 +12025556666 3289 TN 3290 3291 3293 3294 iana-en:222 3295 RTE_GRP_SSP2_Previous 3296 RteGrp 3297 3299 3300 3301 iana-en:226 3302 RTE_SSP4_SBE1_Offered 3303 RteGrp 3304 3305 iana-en:222 3306 3308 3309 3310 3312 Registry completes the request successfully and returns a favorable 3313 response. 3315 3316 3318 3319 3322 tx_12354 3323 3324 1000 3325 Request Succeeded. 3326 3327 3328 3329 3331 10. Security Considerations 3333 SPP Protocol over SOAP is used to query and update session peering 3334 data and addresses, so the ability to access this protocol should be 3335 limited to users and systems that are authorized to query and update 3336 this data. Because this data is sent in both directions, it may not 3337 be sufficient for just the client or user to be authenticated with 3338 the server. The identity of the server should also be authenticated 3339 by the client, which is often accomplished using the TLS certificate 3340 exchange and validation described in [RFC2818]. SPP Protocol over 3341 SOAP messages may include sensitive information, routing data, lists 3342 of resolvable addresses, etc. So when used in a production setting 3343 and across non-secure networks, SPP Protocol over SOAP should only be 3344 used over communications channels that provide strong encryption for 3345 data privacy. 3347 10.1. Integrity, Privacy, and Authentication 3349 The SPP Protocol over SOAP binding relies on an underlying secure 3350 transport for integrity and privacy. Such transports are expected to 3351 include TLS/HTTPS. In addition to the application level 3352 authentication imposed by an SPPF server, there are a number of 3353 options for authentication within the transport layer and the 3354 messaging envelope. These include TLS client certificates, HTTP 3355 Digest Access Authentication, and digital signatures within SOAP 3356 headers. 3358 At a minimum, all conforming SPP Protocol over SOAP implementations 3359 MUST support HTTPS. 3361 10.2. Vulnerabilities 3363 The above protocols may have various vulnerabilities, and these may 3364 be inherited by SPP Protocol over SOAP. SPP Protocol over SOAP 3365 itself may have vulnerabilities because an authorization model is not 3366 explicitly specified in the current specification. 3368 Sections 5 and 10.1 describe requirements for HTTPS support using 3369 TLS. Non-anonymous TLS servers can optionally request a certificate 3370 from a TLS client; that option is not a requirement for this 3371 protocol. This presents a denial of service risk in which 3372 unauthenticated clients can consume server CPU resources by creating 3373 TLS sessions. The risk is increased if the server supports client- 3374 initiated renegotiation. This risk can be mitigated by disabling 3375 client-initiated renegotiation on the server and by ensuring that 3376 other means (such as firewall access control lists) are used to 3377 restrict unauthenticated client access to servers. 3379 In conjunction with the above, it is important that SPP Protocol over 3380 SOAP implementations implement an authorization model that considers 3381 the source of each query or update request and determines whether it 3382 is reasonable to authorize that source to perform that specific query 3383 or update. 3385 10.3. Deployment Environment Specifics 3387 Some deployments of SPP Protocol over SOAP could choose to use 3388 transports without encryption. This presents vulnerabilities but 3389 could be selected for deployments involving closed networks or 3390 debugging scenarios. However, the vulnerabilities of such a 3391 deployment could be a lack of integrity and privacy of the data 3392 transported in this type of deployment. 3394 11. IANA Considerations 3396 This document uses URNs to describe XML namespaces and XML schemas 3397 conforming to a registry mechanism described in [RFC3688]. 3399 URN assignments requested are: urn:ietf:params:xml:ns:sppf:soap:1 3401 12. Acknowledgements 3403 This document is a result of various discussions held by the DRINKS 3404 design team, which is comprised of the following individuals, in 3405 alphabetical order: Alexander Mayrhofer, David Schwartz, Deborah A 3406 Guyton, Jean-Francois Mule Kenneth Cartwright, Lisa Dusseault, Manjul 3407 Maharishi, Mickael Marrache, Otmar Lendl, Peter Saint-Andre, Richard 3408 Shockey, Samuel Melloul, Scott Hollenbeck, Sumanth Channabasappa, 3409 Syed Ali, and Vikas Bhatia . 3411 13. References 3413 13.1. Normative References 3415 [I-D.draft-ietf-drinks-spp-framework] 3416 Mule, J-F., Cartwright, K., Ali, S., Mayrhofer, A., and V. 3417 Bhatia, "Session Peering Provisioning Framework", 3418 draft-ietf-drinks-spp-framework-01 (work in progress), 3419 March 2012. 3421 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 3422 Requirement Levels", BCP 14, RFC 2119, March 1997. 3424 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., 3425 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext 3426 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. 3428 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 3429 Leach, P., Luotonen, A., and L. Stewart, "HTTP 3430 Authentication: Basic and Digest Access Authentication", 3431 RFC 2617, June 1999. 3433 [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, 3434 January 2004. 3436 [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security 3437 (TLS) Protocol Version 1.2", RFC 5246, August 2008. 3439 [SOAPREF] Gudgin, M., Hadley, M., Moreau, J., and H. Nielsen, "SOAP 3440 Version 1.2 Part 1: Messaging Framework", W3C 3441 Recommendation REC-SOAP12-part1-20030624, June 2002. 3443 13.2. Informative References 3445 [RFC2818] Rescorla, E., "HTTP Over TLS", RFC 2818, May 2000. 3447 [RFC5321] Klensin, J., "Simple Mail Transfer Protocol", RFC 5321, 3448 October 2008. 3450 [WSDLREF] Christensen, E., Curbera, F., Meredith, G., and S. 3451 Weerawarana, "Web Services Description Language (WSDL) 3452 1.1", W3C Note NOTE-wsdl-20010315, March 2001. 3454 Authors' Addresses 3456 Kenneth Cartwright 3457 TNS 3458 1939 Roland Clarke Place 3459 Reston, VA 20191 3460 USA 3462 Email: kcartwright@tnsi.com 3464 Vikas Bhatia 3465 TNS 3466 1939 Roland Clarke Place 3467 Reston, VA 20191 3468 USA 3470 Email: vbhatia@tnsi.com