idnits 2.17.1 draft-mule-peppermint-espp-protocol-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 20. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 4941. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 4952. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 4959. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 4965. 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 : ---------------------------------------------------------------------------- == There are 11 instances of lines with non-RFC2606-compliant FQDNs in the document. -- The document has examples using IPv4 documentation addresses according to RFC6890, but does not use any IPv6 documentation addresses. Maybe there should be IPv6 examples, too? Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 1281 has weird spacing: '...service regx ...' == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: In cases where the server determines the transaction ID to be correct, there are two general categories of errors: system errors and business errors. In the event a system error occurs (e.g., disk space has been exhausted) the ESPP Server MUST return the appropriate error message (System Unavailable Error or Authentication Error) and the ESPP Client SHOULD suspend real-time updates to the server for some period of time configured by the SIP Service Provider, and then resume after that time has elapsed. In this case the ESPP Client MUST not update the transaction ID as transaction IDs are only consumed/updated by the client on successful responses to a given API request or when a file based update is successfully generated by the client. In the event a business error occurs (e.g., a data element fails the regular expression validation), the ESPP Server MUST return the appropriate error code for the given error and operation. In response to this type of error response the client MUST, again, not consume that transaction ID, because the transaction did not complete successfully. The client MUST suspend real-time protocol communication with that ESPP Server and generate an internal alarm. Manual intervention is required to analyze and rectify the erroneous data that caused the error and then re-enable real-time protocol communication with the ESPP Server. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (July 14, 2008) is 5765 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: 'RFC 3761' is mentioned on line 2063, but not defined ** Obsolete undefined reference: RFC 3761 (Obsoleted by RFC 6116, RFC 6117) ** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615, RFC 7616, RFC 7617) ** Obsolete normative reference: RFC 2821 (Obsoleted by RFC 5321) ** Obsolete normative reference: RFC 3761 (Obsoleted by RFC 6116, RFC 6117) -- Possible downref: Non-RFC (?) normative reference: ref. 'SOAP' -- Possible downref: Non-RFC (?) normative reference: ref. 'WSDL' -- Possible downref: Non-RFC (?) normative reference: ref. 'XML' == Outdated reference: A later version (-17) exists of draft-ietf-speermint-terminology-16 Summary: 5 errors (**), 0 flaws (~~), 6 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Drinks Working Group K. Cartwright 3 Internet-Draft VeriSign 4 Intended status: Standards Track S. Dimig 5 Expires: January 15, 2009 Tekelec 6 M. Teodoro 7 NeuStar 8 J-F. Mule 9 CableLabs 10 July 14, 2008 12 A Provisioning Protocol for ENUM-SIP Addressing Servers 13 draft-mule-peppermint-espp-protocol-02 15 Status of this Memo 17 By submitting this Internet-Draft, each author represents that any 18 applicable patent or other IPR claims of which he or she is aware 19 have been or will be disclosed, and any of which he or she becomes 20 aware will be disclosed, in accordance with Section 6 of BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF), its areas, and its working groups. Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 This Internet-Draft will expire on January 15, 2009. 40 Abstract 42 This document defines a provisioning protocol for ENUM-SIP addressing 43 servers. 44 An ENUM-SIP addressing server is a host that acts as Lookup Function 45 in session peering to determine the target domain of a given SIP 46 request and it may also act as a Location Routing Function to develop 47 the location of the SIP signaling entity in that target domain. 48 This protocol allows SIP service providers to provision and manage 49 session establishment data used by SIP network elements to route SIP 50 sessions to the target destinations which may be served by the SIP 51 service provider's own internal network or by a session peering 52 partner. The data provisioned into an ENUM-SIP addressing server is 53 queried by SIP entities using ENUM or SIP. 55 This version of the protocol integrates comments received on the IETF 56 peppermint and drinks mailing lists before July 2008. This document 57 is an Internet-Draft and the protocol it describes is subject to 58 technical changes that may make this version incompatible with future 59 versions defined in Internet-Drafts. It is expected that the authors 60 will continue to update this protocol based on the drinks working 61 group requirements on the session establishment data. 63 Table of Contents 65 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 4 66 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 67 3. Protocol Requirements . . . . . . . . . . . . . . . . . . . . 7 68 4. Protocol Definition . . . . . . . . . . . . . . . . . . . . . 11 69 4.1. Logical Structure - Data Model . . . . . . . . . . . . . 11 70 4.2. Technical Structure - SOAP/XML Type Hierarchy . . . . . . 15 71 4.3. Overview of Protocol Operations . . . . . . . . . . . . . 16 72 4.3.1. Deployment Scenario and ESPP Provisioning . . . . . . 17 73 4.3.2. Deployment Scenario and Resolution . . . . . . . . . 33 74 4.3.3. Generic Examples . . . . . . . . . . . . . . . . . . 35 75 4.4. Protocol Specification . . . . . . . . . . . . . . . . . 35 76 4.4.1. General Protocol Concepts . . . . . . . . . . . . . . 36 77 4.4.2. Protocol Operation Descriptions . . . . . . . . . . . 43 78 5. File-based ESPP provisioning protocol . . . . . . . . . . . . 86 79 5.1. Overview of the File-based Provisioning Operations . . . 86 80 5.2. File Structure . . . . . . . . . . . . . . . . . . . . . 86 81 6. Response Codes and Messages . . . . . . . . . . . . . . . . . 89 82 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 91 83 8. Formal API Definition . . . . . . . . . . . . . . . . . . . . 92 84 8.1. WSDL Specification . . . . . . . . . . . . . . . . . . . 92 85 8.2. XSD Types Specification . . . . . . . . . . . . . . . . . 103 86 9. Security Considerations . . . . . . . . . . . . . . . . . . . 116 87 10. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 117 88 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 118 89 11.1. Normative References . . . . . . . . . . . . . . . . . . 118 90 11.2. Informative References . . . . . . . . . . . . . . . . . 118 91 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 120 92 Intellectual Property and Copyright Statements . . . . . . . . . 121 94 1. Introduction 96 This document defines a provisioning protocol for ENUM-SIP addressing 97 servers. It allows SIP service providers to provision data related 98 their SIP route management. The data is used by ENUM-SIP addressing 99 servers to return part of the session establishment data to SIP 100 network elements so that they can route SIP sessions to the proper 101 target destinations. 103 An ENUM-SIP addressing server is a session routing server that 104 implements a Lookup Function and may also implement a Location 105 Routing Function as defined in [I-D.ietf-speermint-terminology]. An 106 ENUM-SIP addressing server typically takes a user address that can be 107 used to establish a SIP session as the input to the lookup query (SIP 108 address of record, a telephone number or any type of public user 109 addresses). It resolves the address into one or more Uniform 110 Resource Identifiers (URIs) based on various rules and routing logic. 111 Optionally, it may also develop the responses to include information 112 on how to route the SIP session to the requesting entity. 113 The data provisioned into an ENUM-SIP addressing server is queried by 114 SIP entities using protocols such as ENUM [RFC3761] or Session 115 Establishment Protocol (SIP) [RFC3261]. While the protocols used to 116 query the provisioned data may impose limitations on the data 117 modeling, they are considered out of scope of this document. 119 The use cases and protocol requirements for the ENUM-SIP Server 120 Provisioning Protocol (ESPP) are described in 121 [I-D.espp-requirements]. For reference, the original version of this 122 protocol is published as a CableLabs specification, the PacketCable 123 ENUM Server Provisioning Specification ([CableLabs-ESPP]). A number 124 of vendors have client and server implementations of this original 125 protocol and three interoperability testing events have been 126 conducted to date. 128 This document is organized as follows: 130 o Section 3 describes the protocol's functional entities and 131 provides a pointer to the use cases and protocol requirements 132 maintained in a separate document, 134 o Section 4 and Section 5 define the real-time and filed-based 135 operations of the ESPP provisioning protocol including the data 136 model (Section 4.1), the SOAP/XML Type Hierarchy (Section 4.2), 137 and an overview of the protocol operations by walking through a 138 real-life deployment scenario showing examples of ESPP 139 operations and how the provisioned data can be used to resolve 140 ENUM or SIP queries,(Section 4.3), 142 o Section 8 provides the complete normative WSDL and XSD 143 definitions of the protocol. 145 2. Terminology 147 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 148 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 149 document are to be interpreted as described in [RFC2119]. 151 This document also reuses the SIP terminology defined in [RFC3261]. 152 The Lookup Function (LUF), Location Routing Functions (LRF) and other 153 session peering terms are defined [I-D.ietf-speermint-terminology]. 155 3. Protocol Requirements 157 The ENUM Server Provisioning Protocol (ESPP) allows a SIP Service 158 Provider (SSP) to receive session establishment-related data from 159 various sources: its internal back-office systems for intra-domain 160 routes, a session peer or a federation registry. A source of 161 provisioning data is logically represented by an ESPP provisioning 162 client (ESPP Client). The SIP Service Provider's addressing server 163 receives this provisioning data via a functional entity called an 164 ESPP Server. This data is then used by the server's Lookup and 165 Location routing Functions to return session establishment data to 166 querying entities. 168 The data sent by an ESPP Client to an ESPP Server follows a formal 169 data structure based on the data model defined in Section 4.1. The 170 data elements include parameters such as a peer's target addresses 171 grouped by destination groups and the Signaling path Border Elements 172 to reach those telephone numbers. 174 This specification defines the protocol interfaces between a 175 provisioning client (ESPP Client) and a provisioning server function 176 of an ENUM-SIP addressing server (ESPP Server), as shown on Figure 1. 178 SIP SSP +-------------+ 179 Intra-Domain | | 180 Network | Back Office | 181 | | Server | 182 +-------|+-----------+|-+ 183 ||ESPP Client|| | 184 |+-----------+| | 185 +-------------+ | 186 | +-------------+ 187 Peer +-------------+ | | ENUM-SIP | 188 Bi-lateral | | | | Addressing | 189 Agreement | Resolution | | | Server | 190 | | Server | | | | 191 +-------|+-----------+| | ESPP |+-----------+| 192 ||ESPP Client|+-+------+|ESPP Server|| 193 |+-----------+| | |+-----------+| 194 +-------------+ | |+-----------+| 195 | || Data || 196 Peer +-------------+ | ||Repository || 197 Federation | Other Data | | |+-----------+| 198 Network | Sources | | |+-----------+| * +-----------+ 199 | |+-----------+|-+ || LUF - LRF ||+----+ SIP Entity| 200 +-------||ESPP Client|| |+-----------+| +-----------+ 201 |+-----------+| |+-----------+| 202 +-------------+ || ENUM - SIP|| 203 |+-----------+| 204 +-------------+ 206 ENUM Server Provisioning Protocol Reference Architecture 208 Figure 1 210 To claim compliance with this specification, an ESPP Client and an 211 ESPP Server MUST conform to the real-time and file-based provisioning 212 protocol requirements defined in Section 4, Section 5 and Section 8 213 of this document. The protocols used by SIP entities and various 214 network elements to query the addressing server are typically ENUM or 215 SIP; they are out of scope of this specification and are denoted with 216 an asterisk (*) in Figure 1. 218 The guiding design principal behind ESPP is the ability to support a 219 large session addressing space whose size is of the same order of 220 magnitude as the Public Switched Telephone Network (PSTN). 221 Optimizing bandwidth and storage usage is a key characteristic. 223 The logical data structure implemented by ESPP allows for a more 224 natural modeling of relationships between the entities that comprise 225 the logical topology. Telephone numbers and other types of public 226 user identities are grouped in logical or geographical areas and 227 associated with routes that describe how traffic traverses the nodes 228 of the topology. The process begins by arranging a plurality of 229 telephone numbers and nodes connected by a plurality of routes. Each 230 telephone number, number range or public user identity is assigned to 231 a destination group. Through a route assignment each node is 232 associated with one or more destination groups. For example, a SIP 233 Service Provider could first create destination groups for the New 234 York metropolitan area, assigning the telephone numbers of New York 235 subscribers into that destination group. The SIP Service Provider 236 then defines the call servers that provide digital voice services for 237 New Yorkers and the border elements that connect the New York 238 metropolitan area to peering networks. Finally, through the 239 definition of intra-SSP and inter-SSP routes, that SIP Service 240 Provider completes the establishment of session peering data by 241 associating nodes with destination groups. 243 Figure 2 illustrates the link between logical destination groups and 244 telephone numbers and the associated routes. 246 Destination Groups: 247 +----------------------------------------+ 248 |Destination Group Name| TN or TN Ranges | 249 +----------------------+-----------------+ 250 |Manhattan |212-203-0000 -> | 251 | |212-203-9999 | ,--. 252 |Bronx |347-876-1000 -> | / \ 253 | |347-876-1999 | / \ 254 |Queens |347-354-6000 -> | ( Bronx ) 255 | |347-354-6999 | \ / 256 +----------------------------------------+ ,-----. \ / 257 Routes: / \ `-' 258 +------------------------------------+ / \ 259 |Route Name|Nodes |Dest. Groups | (Manhattan) ,. 260 +----------+---------+---------------+ ,-. / / \ 261 |118th Ave |NYC-SBE-1|Manhattan/Bronx|-->(SBE) / / \ 262 |60 Hudson |NYC-SBE-2|Queens |-+ `-'--------' (Queens) 263 +----------+--------++---------------+ | ,+. / 264 +-------------->(SBE) / 265 Nodes: `-''- 266 +-------------------------------+ 267 |Node Name| Host/Domain Name | 268 +---------+---------------------+ 269 |NYC-SBE-1|sbe-1.nyc.example.com| 270 |NYC-SBE-2|sbe-2.nyc.example.com| 271 +---------+---------------------+ 273 Example of ESPP Destination Groups and Routes 275 Figure 2 277 A number of design considerations and requirements (transport, data 278 model, security, etc.) can be found in [I-D.espp-requirements]. 280 4. Protocol Definition 282 This section first introduces the structure of the data model and the 283 overall technical structure that provide the information framework to 284 which ESPP adheres. An overview of the protocol operations is then 285 provided with a typical deployment scenario. This section concludes 286 with the definition of the operations and data elements that comprise 287 ESPP. 289 4.1. Logical Structure - Data Model 291 The data model illustrated and described in Figure 3 defines the 292 logical objects and the relationships between these objects that the 293 ESPP protocol supports. ESPP defines the protocol operations through 294 which an ESPP Client populates an ENUM-SIP addressing server with 295 these logical objects. Various clients may use the protocol for 296 populating the server's data. ESPP Clients may include, for example, 297 a back-office system, a federation registry or another ENUM-SIP 298 addressing server. 300 A key requirement of ESPP is the ability to support an addressing 301 space of the same magnitude as the PSTN. To achieve the above, the 302 data model needs to be designed such that it optimizes bandwidth and 303 storage. The data model needs to support distribution of addressing 304 information in a manner that affords the implementations the 305 opportunity to maximize storage and minimize transport overhead. One 306 way to achieve this is not relying exclusively on distribution of 307 redundant NAPTR records. The use of a direct association between 308 NAPTRs and telephone numbers should be restricted to service 309 scenarios where there is a need to communicate subscriber-specific 310 service attributes. This is because the NAPTRs carry a large amount 311 of redundant data when many telephone numbers resolve into a URI 312 where the host part is the same Internet address. 314 As illustrated in the figure below, the logical structure that 315 underlies ESPP is designed around a simplified version of the logical 316 entities that comprise session peering data. This logical structure 317 provides a consistent terminology and design to the constructs that 318 make up the protocol. 320 +----------------+ 321 A Route is associated with |NAPTR: | 322 +----------------+ zero or more SBE NAPTRs. |id,enterpriseId,| 323 | |--------------------------->|order,pref, | 324 |Route: | NAPTRs associated with |flags,svcs,regx,| 325 |id,enterpriseId,| Routes are not User or TN |repl,extension | 326 |routeName, | specific. The user portion +----------------+ 327 |isLnService, | of the regex will be "\\1". 328 |sbeNAPTRs, | +----------------+ 329 |extension | |Egress Route: | 330 | |<---------------------------|id,enterpriseId,| 331 +----------------+ An EgressRoute is |routeIds,pref, | 332 ^ associated with zero or |svcs, | 333 A Destination | more Routes. |regxRewriteRule,| 334 Group is | |extension | 335 associated | +----------------+ 336 with 1 or more | 337 Routes | 338 +----------------+ 339 |Destination | 340 |Group: | 341 |id,enterpriseId,| 342 +--->|DestGroupName, |<---+ 343 | |routeIds, | | 344 | |extension | | 345 | +----------------+ | 346 |An RN is |A TNRange is |A Public 347 |associated |associated |Identify is 348 |with only 1 |with only 1 |associated 349 |Destination |Destination |with zero or 350 |Group. |Group. |1 Destination Group. 351 | | | 352 +--------------++--------------++--------------+ +--------------+ 353 |RN: ||TNRange: ||Public | |NAPTR: | 354 |id, ||id, ||Identity: | |id, | 355 |enterpriseId, ||enterpriseId, ||id, | |enterpriseId, | 356 |rn, ||tnRangeStart, ||enterpriseId, |-->|order,pref, | 357 |destGroupId, ||tnRangeEnd, ||pubIdentity, | |flags,svcs, | 358 |extension ||destGroupId, ||priIdentity, | |regx,repl, | 359 | ||extension ||destGroupId, | |extension | 360 | || ||extension | | | 361 +--------------++--------------++--------------+ +--------------+ 362 | 363 A Public Identity | Multiple Public 364 is associated with | Identities can 365 zero or 1 Private | be associated 366 Identity | with 1 Private 367 | Identity 368 | 369 | 370 | 371 | 372 | 373 V 374 +----------------+ 375 |Private | 376 |Identity: | 377 |id, | 378 |enterpriseId, | 379 |privateIdentity,| 380 |extension | 381 +----------------+ 383 Logical Structure of ESPP Objects 385 Figure 3 387 The objects that comprise the logical domain model can be described 388 as follows: 390 Public Identity (PubId): 391 A string of numbers or characters that serves as a public 392 identity. A Public Identity may be a telephone number, an email 393 address, or other identity as deemed appropriate. The Public 394 Identity object may be associated with a Destination Group which 395 serves as a logical grouping of public identities and indirectly 396 defines the signaling path used to Route to that Public Identity. 397 A Public Identity may optionally be associated with zero or more 398 individual NAPTRs. This ability for a Public Identity to be 399 directly associated with a set of NAPTRs, as opposed to being 400 associated with a Destination Group, supports the use cases where 401 the NAPTR may contain data specifically tailored to an individual 402 Public Identity. A Public Identity may, optionally, be associated 403 with zero or one Private Identity. 405 Private Identity (PvtId): 406 A string of numbers or characters that serves to associate, or 407 group together, a set of related Public Identities. A Private 408 Identity may, for example, represent a user who has more than one 409 Public Identity instances. When a resolution request for a public 410 identity arrives at an addressing server, the addressing server 411 may locate the Public Identity that matches the queried public 412 identity, discover the Private Identity associated with that 413 Public Identity, and then gather and return all the NAPTRs 414 directly or indirectly (via a Destination Group) associated with 415 the Public Identities that are associated with that Private 416 Identity. 418 Route: 419 A set of related Signaling path Border Elements (SBEs). SBEs are 420 generally ingress or egress points within, or at the edge of, a 421 SIP service provider's network. A Route object is associated with 422 zero or more SBEs. An SBE's properties are housed within the 423 constructs of a NAPTR object modeled after a DNS NAPTR Record. At 424 runtime (i.e., during the resolution of a SIP or ENUM query to an 425 addressing server), the SBEs associated with the route to the 426 Destination Group of a public identity will be returned as part of 427 the NAPTR response. In case of multiple SBEs, the ENUM response 428 will have multiple NAPTR records, each referring to a particular 429 SBE. This indirection between a Public Identity and its ENUM 430 NAPTRs allows the modification of signaling path border elements 431 without having to modify a large number of NAPTRs. 433 Egress Route: 434 Optional rules for re-writing (modifying) the regular expressions 435 housed in the NAPTRs associated with a Route. This is primarily 436 used by the addressing server to dynamically add a SIP Route 437 header as part of a SIP resolution, and to dynamically indicate 438 into a NAPTR's regular expression what SIP Route to use. This 439 allows a NAPTR to define the local egress SBE or the remote 440 ingress SBE of a signaling path. 442 Destination Group: 443 A collection of zero or more Public Identities, Telephone Number 444 ranges (TNRanges), and Routing Numbers (RNs) that are related by 445 virtue of their common signaling path and a set of zero or more 446 Route relationships. The grouping of Public Identities, TNRanges, 447 and RNs into related groups and the indirect association of these 448 groups to their signaling path elements significantly enhances the 449 manageability of routing data for a large number of Public 450 Identities. This allows the addressing server to apply routing 451 changes to a set of Public Identities, TNRanges, and RNs without 452 having to make changes to each individual Public Identities, 453 TNRange, or RN. 455 Routing Number (RN): 456 A routing number prefixed for a routing purpose (as defined in the 457 ITU-T Recommendation e.164). The length of a routing number may 458 vary from country to country. The RN is sometimes called a prefix 459 as it can symbolize a global telephone number prefix. The RN can 460 indeed represent the first digits of a number block handled by an 461 SSP to which the session should be routed. In some countries, the 462 RN value contains one or more digits not used as first digits in 463 the national numbering plan to indicate a ported number (e.g. in 464 North American where the RN is used for Local Number Portability). 465 In the rest of this document, we use the RN as a synonym of 466 prefix. An RN is associated with a Destination Group. 468 TNRange: 469 An object that represents a range of telephone numbers. The 470 TNRange object must be associated with a Destination Group which 471 indirectly defines the signaling path to reach the TNs in that 472 range. 474 Enterprise ID: 475 The enterprise ID data element that resides within each object 476 type and uniquely identifies an operational entity within an ESPP 477 Server. The operational entity is responsible for, or owns, that 478 object from a business perspective. This does not identify the 479 software entity that provisioned the object, which is the purpose 480 of the client ID. Refer to Section 4.4.1.7 for more details. 482 ID: 483 Each object is uniquely identifiable using its object ID. An 484 object ID is guaranteed to be unique within an ESPP Server and 485 ESPP Client, regardless of the number of ESPP Clients populating 486 objects into a given ESPP Server. Refer to Section 4.4.1.7 for 487 more details. 489 NAPTR: 490 The data structure used to house the properties of signaling path 491 border elements, and any other information appropriately held 492 within the data structures offered by a NAPTR. 494 4.2. Technical Structure - SOAP/XML Type Hierarchy 496 In addition to employing the logical structure described in the 497 previous section, ESPP also employs a consistent overall technical 498 structure. This technical structure is typically referred to as the 499 "Document Literal Wrapped" style of designing SOAP based APIs. This 500 style is generally regarded as an optimal approach that enhances 501 maintainability, comprehension, portability, and, to a certain 502 extent, performance. Figure 4 illustrates this high level technical 503 structure. 505 +-----------+ 506 +------| SOAP |------+ 507 | | Operation | | 508 Contains | +-----------+ | Contains 509 | | 510 V V 511 +------------+ +-------------+ 512 |SOAP Request| |SOAP Response| 513 Example:| Message | | Message |Example: 514 addRtesRqstMsg| (Operation | | (Operation |cmnRspnsMsg 515 | Input) | | Output) | 516 +------------+ +-------------+ 517 | | 518 Contains | | Contains 519 | | 520 V V 521 +--------------+ +---------------+ 522 Example:| Wrapped | | Wrapped |Example: 523 addRtesRqst|Request Object| |Response Object|cmnRspns 524 +--------------+ +---------------+ 525 | | 526 | | 527 | | 528 V V 529 +--------------+ +---------------+ 530 Example:| ESPP | | ESPP |Example: 531 RteType| Object Types | | Object Types |BasicRspnsType 532 +--------------+ +---------------+ 534 Technical Structure of the ESPP Protocol 536 Figure 4 538 The SOAP operations supported by ESPP (e.g., addRtes) are normatively 539 defined in Section 8. Each SOAP operation defines a request/input 540 message and a response/output message. Each request and response 541 message then contains a single object that wraps the data elements 542 that comprise the inputs and the outputs, respectively, of the 543 operation. 545 Section 4.4.2 of this document defines how each operation utilizes 546 this technical structure and the logical structure defined in the 547 previous section. 549 4.3. Overview of Protocol Operations 551 This section provides an overview of ESPP and its protocol operations 552 by describing a usage scenario and examples. It is divided into two 553 sub-sections. The first sub-section defines a usage scenario and 554 provides a set of example ESPP request messages that apply to the 555 scenario. The second sub-section provides examples of a generic set 556 of ESPP request/response pairs, one for each protocol operation. 558 4.3.1. Deployment Scenario and ESPP Provisioning 560 A typical deployment scenario for ESPP involves multiple SIP Service 561 Providers wanting to exchange multimedia traffic including Voice over 562 IP (VoIP) calls and Instant Messaging (IM) sessions. Each service 563 provider first advertises the public user identities (e.g., telephone 564 numbers and instant messaging addresses) it serves on its network 565 along with the routes to its peers. Note that the process by which a 566 SIP service provider exchanges data such as an instant messaging 567 address may be subject to end-user privacy and a subscriber-triggered 568 authorization step may be required. 570 Various models can be chosen by SSPs to determine if a target address 571 is served by a peer. In one model, for each session initiation, an 572 out-of-network query could be made to each peer individually, or to a 573 federation entity representing the peers. In another model, an SSP 574 who has deployed ENUM-SIP addressing servers for session routing may 575 prefer in-network queries to its addressing servers to resolve target 576 addresses. In this second case, the service provider's addressing 577 server could be provisioned with peer data: this is the purpose of 578 the ESPP protocol. Both models can also co-exist: in some cases and 579 depending on the SSP policy, the resolution of certain types of 580 addresses may require an out-of-network query. 582 The remaining of this section assumes that SSPs have deployed ENUM- 583 SIP addressing servers and prefer in-network queries. A deployment 584 scenario is described in details covering both the provisioning 585 activities using ESPP and the query resolutions to resolve target 586 addresses using ENUM or SIP. We first introduce the actors of the 587 scenario (SIP Service Providers or enterprises participating in 588 multimedia session exchanges), and then expand on the ESPP operations 589 for the provisioning of peers, Session Establishment Data (SED), and 590 the public identities or Address of Records to which session may be 591 established. 593 4.3.1.1. Actors 595 4.3.1.1.1. Enterprises Description 597 Three SIP service Providers have agreed to exchange Voice over IP 598 traffic and Instant Messages via their IP networks: 600 o GlobalSSP: 602 GlobalSSP is a large SIP service provider with service footprints in 603 Boston and Arizona and several SIP servers capable of processing VoIP 604 traffic. The SIP servers are logically linked to several Signaling 605 path Border Elements (SBEs) that hide the topology of the SIP service 606 provider's network while providing specific access points for other 607 peers. GlobalSSP does also control its egress routes by choosing the 608 SBE that egress calls to a particular peer. 610 Each Call Management Server (CMS) is also associated with one or more 611 Routing Number(s) (RN) due to local number portability support. The 612 telephone numbers served by GlobalSSP are distributed among the CMS 613 servers as well as the PSTN switches. 615 o MidwestSSP: 617 MidwestSSP operates a network similar to GlobalSSP with services in 618 the Chicago area (subscriber base only located in one state). Two 619 Call Management Servers and only one SBE are deployed. 621 o NewYorkSSP: 623 NewYorkSSP offers services in the region of New York City including 624 voice and IM. Four SBEs have been deployed for voice, one SBE for 625 IM. IM subscribers are known by a public identity. 627 SIP service providers take advantage of ESPP to provision session 628 establishment data. They agreed to use a common Registry function 629 with a Registrar component that implements the client-side of the 630 ESPP protocol. Note that ESPP also supports a deployment model where 631 each SIP service provider has bilateral relationships with a number 632 of peers and use ESPP directly with each peer. 634 Each SIP service provider is connected to the Registrar and 635 implements an instance of the ENUM SIP addressing server (ESPP 636 Server) for the server-side of the protocol. Note that GlobalSSP is 637 connected to the Registrar from one of their Destination Group that 638 distributes data to the Boston Destination Group. 640 Each SIP service provider is allocated an identifier or Enterprise 641 ID: 643 +---------------+---------------------------+ 644 | SSP | Enterprise ID | 645 +---------------+---------------------------+ 646 | GlobalSSP | 76543 | 647 | | | 648 | NewYorkSSP | 76544 | 649 | | | 650 | MidwestSSP | 76545 | 651 +---------------+---------------------------+ 653 Table 1: Example SSP and Enterprise ID 655 After these three SSPs have successfully exchanged session 656 establishment data (SED) for some time, a new SSP called NewSSP wants 657 to exchange calls and IM with the other three. To facilitate the 658 process of getting the data from all three SIP service providers in a 659 limited amount of time, the NewSSP server will receive a complete 660 copy of the data the SSPs wish to share with NewSSP using a bulk 661 file. 663 +---------------+---------------------------+ 664 | SSP | Enterprise ID | 665 +---------------+---------------------------+ 666 | NewSSP | 76546 | 667 +---------------+---------------------------+ 669 Table 2: Example NewSSP and Enterprise ID 671 In this scenario, each SIP Service Provider operates an ESPP Server 672 that houses the ESPP Server's SED and end point data from an ESPP 673 Client (a Registrar or a Registry). The ESPP Client initiates 674 connections and, using the supported ESPP operations, pushes data 675 down to the ESPP Servers. SED and end point objects are stored in 676 the ESPP Server. 678 Each ESPP Server receives the data its SSP is allowed to access and 679 each addressing server has a "unique" view of its peer's data. Note 680 that a SIP Service Provider may also choose to store internal or 681 private routes using ESPP. For example, the data for routing 682 sessions out of the SSP's network is different from the data used to 683 route sessions within the SSP's own Destination Groups. 685 4.3.1.1.2. Enterprises: ESPP Provisioning Operations 687 As these partner relationships are established, each SSP sends SED 688 data to its peers via the ESPP Client(s). In order to identify the 689 peer the SED data belong to, an Enterprise ID is provided along with 690 the list of Destination Groups, SBEs, etc. 692 ESPP is an XML SOAP protocol. An ESPP Client uses the ESPP 693 protocol's addEntr operation to create these enterprises in the ESPP 694 Server for each participating SSP. To do so, it sends a request to 695 create three enterprise identifiers (eId) at an ESPP Server. This 696 operation is sent to the ESPP Server operated by the three SIP 697 Service Providers, MidwestSSP, GlobalSSP, and NewYorkSSP. 699 700 701 702 703 704 7845601 705 1000000 706 1 707 708 76543 709 76544 710 76545 711 712 713 715 Figure 5 717 For brevity and to improve the readability of examples, the basicRqst 718 element of the SOAP message will be omitted from the remaining 719 examples. With the exception of the transId element incrementing 720 upward, the content of the basicRqst element is identical for all 721 examples in this section. 723 The enterprise ID for NewSSP is added later. At that time, the 724 central registry via its ESPP Client uses the addEntr operation to 725 add the NewSSP's enterprise ID to the ESPP Servers of the peers 726 NewSSP wishes to exchange traffic with. 728 729 730 731 732 [snip] 733 76546 734 735 736 737 Figure 6 739 The addEntr operation is an infrequent occurrence; it is used when 740 new enterprises agree to exchange traffic. 742 4.3.1.2. Session Establishment Data 744 4.3.1.2.1. Description of Session Establishment Data 746 As part of establishing their traffic exchange policies, each SSP 747 defines its points of session interconnect for their destination 748 groups, which may or may not vary for each peering partner. This 749 information is part of the data required to establish a session and 750 is called session establishment data (SED). As described in the 751 introductory sections of this document, SED in ESPP includes Routes, 752 SBEs, and Destination Groups. SED is usually provisioned once for 753 each SIP Service Provider with occasional subsequent updates as 754 interconnect points are added or changed. It is provisioned 755 independently from the provisioning of the elements contained in 756 Destination Groups (TNs, TN Ranges, RNs, and IM IDs). This allows 757 the rare process of provisioning SED to be distinctly separate from 758 the continuous process of adding subscribers. The destination groups 759 supported by each SIP Service Provider are illustrated in Figure 7 760 below. 762 +----------------+ +----------------+ 763 | Chicago |_________________| Boston | 764 |Dest. Group (1)| |Dest. Group (3) | 765 +----------------+_ +----------------+ 766 | `-. .-' | 767 | `. .-' | 768 | `-..' | 769 | .-'`-. | 770 | .-' `. | 771 +----------------+.-' `-.+----------------+ 772 | Flagstaff |_________________| New York | 773 |Dest. Group (2) | |Dest. Group (4) | 774 +----------------+ +----------------+ 776 Sample Scenario and Destination Groups 778 Figure 7 780 The three initial SIP Service Providers offer voice and IM services. 781 GlobalSSP has defined two Destination Groups and MidwestSSP and 782 NewYorkSSP have each defined one Destination Group. Each Destination 783 Group is reachable via a Route associated with a set of SBEs. 785 Figure 8 below further illustrates the details of the relationship 786 between the Flagstaff and New York destination groups operated by the 787 GlobalSSP and NewYorkSSP respectively. The examples in this section 788 focus on the relationship between GlobalSSP's Flagstaff destination 789 group and the NewYorkSSP's New York destination group. 791 FlagStaff 792 Destination Group 793 SBE-10 SBE-40 794 ,-----. ,-. Route 3 --> ,-. ,-----. 795 ,-' (SBE)______________________(SBE)-' `-. 796 / `-' `-' \ 797 / \ <-- Route 300 / \ 798 ; : ; : 799 | | | | 800 : ; : ; 801 \ ,-. Route 4 --> ,+. / 802 \ (SBE)_____________________(SBE) / 803 `-. ,-'-' `-'`-. ,-' 804 `-----' SBE-11 <-- Route 304 SBE-41 `-----' 805 New York 806 Destination 807 Group 809 Sample Scenario - Destination Groups and SBEs 811 Figure 8 813 Each Route illustrated above is further defined in the Route table 814 (Table 3 below) to contain one or more SBEs that serve as the ingress 815 points for that Route. 817 +-------------+-----------------------------------------------------+ 818 | Routes | SBE NAPTRs | 819 +-------------+-----------------------------------------------------+ 820 | RTFlag-NYC1 | Order = 10, Pref=10, Svcs=E2U+SIP, Regx = | 821 | Ingress | "!^.*$!sip:\\1@sbe40-newyork.newyorkssp.example1.co | 822 | route to | m!" | 823 | reach the | | 824 | New York | | 825 | Destination | | 826 | Group from | | 827 | Flagstaff. | | 828 | | | 829 | | | 830 | | | 831 | RTFlag-NYC2 | Order= 10, Pref=10, Svcs= E2U+IM, Regx = | 832 | Ingress | "!^.*$!im:\\1@sbe41-newyork.newyorkssp.example1.com | 833 | route to | !" | 834 | reach the | | 835 | New York | | 836 | Destination | | 837 | Group from | | 838 | Flagstaff. | | 839 | | | 840 | | | 841 | | | 842 | RTNYC-Flag1 | Order= 10, Pref=10, Svcs= E2U+SIP, Regx = | 843 | Ingress | "!^.*$!sip:\\1@sbe10-globalssp.example2.com!" | 844 | route to | | 845 | reach the | | 846 | Flagstaff | | 847 | Destination | | 848 | Group from | | 849 | New York. | | 850 | | | 851 | | | 852 | | | 853 | RTNYC-Flag2 | Order = 10, Pref=10, Svcs= E2U+IM, Regx = | 854 | Ingress | "!^.*$!im:\\1@sbe11-globalssp.example2.com!" | 855 | route to | | 856 | reach the | | 857 | Flagstaff | | 858 | Destination | | 859 | Group from | | 860 | New York. | | 861 +-------------+-----------------------------------------------------+ 863 Table 3: Examples of Routes to SBEs Associations 865 The Routes defined above can then be associated with the destination 866 groups that they support. This allocation is laid out in the Table 4 867 below. 869 +-------------+-------------+------------+------------+-------------+ 870 | Destination | GlobalSSP | GlobalSSP | MidwestSSP | NewYorkSSP | 871 | Groups | Flagstaff | Boston | Chicago | New York | 872 +-------------+-------------+------------+------------+-------------+ 873 | GlobalSSP | | RTFlag-Bos | RTFlag-Chi | RTFlag-NYC1 | 874 | Flagstaff | | | | RTFlag-NYC2 | 875 | | | | | | 876 | | | | | | 877 | | | | | | 878 | GlobalSSP | RTBos-Flag | | RTFlag-Chi | RTBos-NYC | 879 | Boston | | | | | 880 | | | | | | 881 | | | | | | 882 | | | | | | 883 | MidwestSSP | RTChi-Flag | RTChic-Bos | | RTChi-NYC | 884 | Chicago | | | | | 885 | | | | | | 886 | | | | | | 887 | | | | | | 888 | NewYorkSSP | RTNYC-Flag1 | RTNYC-Bos | RTNYC-Chi | | 889 | NewYork | RTNYC-Flag2 | | | | 890 | | | | | | 891 | | | | | | 892 +-------------+-------------+------------+------------+-------------+ 894 Table 4: Example of Destination Groups to Routes Associations 896 4.3.1.2.2. ESPP Provisioning of Session Establishment Data 898 The Route, SBE, and Destination Group data is provisioned in the 899 appropriate ESPP Server of each participating SIP Service Provider 900 using the addRtes, addDestGroups, and addNAPTRs operations supported 901 by the ESPP protocol. An optional approach is to combine some of the 902 operations into a single ESPP request using the batchUpdate 903 operation. The following example SOAP/XML messages provision the 904 Routes, SBE NAPTRs, and Destination Groups for the example above. 906 Using the batchUpdate operation, the ESPP Client provisions the 907 Global SSPs Flagstaff SBE NAPTRs, Routes, and Destination Groups in 908 the NewYorkSSP's ESPP Server. 910 911 912 913 914 [snip] 915 916 917 918 7845601000012345610 919 76543 920 10 921 10 922 u 923 E2U+SIP 924 !^.*$!sip:\\1@sbe10-globalssp.example2.com! 925 926 927 7845601000012345611 928 76543 929 10 930 10 931 u 932 E2U+IM 933 !^.*$!im:\\1@sbe11-globalssp.example2.com! 934 935 936 7845601000012345620 937 76543 938 RTNYC-Flag1 939 7845601000012345610 940 true 941 942 943 7845601000012345621 944 76543 945 RTNYC-Flag2 946 7845601000012345611 947 true 948 949 950 7845601000012345630 951 76543 952 FlagstaffDG 953 7845601000012345620 954 7845601000012345621 955 956 957 958 959 960 Figure 9 962 Using the alternative approach of a single ESPP operation for each 963 object type (as opposed to the batchUpdate operation), the ESPP 964 Client provisions the NewYorkSSP's NAPTRs, Routes, and Destination 965 Groups in the GlobalSSP's ESPP Server. 967 Provision the New York SSP's New York NAPTRs in the Global SSPs 968 Flagstaff SBEs ESPP Server. 970 971 972 973 974 [snip] 975 976 7845601000012345612 977 76544 978 10 979 10 980 u 981 E2U+SIP 982 !^.*$!sip:\\1@sbe40-newyork.newyorkssp.example1.com! 983 984 985 7845601000012345613 986 76544 987 10 988 10 989 u 990 E2U+IM 991 !^.*$!im:\\1@sbe41-newyork.newyorkssp.example1.com! 992 993 994 995 997 Figure 10 999 The ESPP Client provisions the New York SSP's New York Routes in the 1000 Global SSP's ESPP Server. 1002 1003 1004 1005 1006 [snip] 1007 1008 7845601000012345622 1009 76544 1010 RTFlag-NYC1 1011 7845601000012345612 1012 true 1013 1014 1015 7845601000012345623 1016 76544 1017 RTFlag-NYC2 1018 7845601000012345613 1019 true 1020 1021 1022 1023 1025 Figure 11 1027 The ESPP Client provisions the New York SSP's New York Destination 1028 Groups in the Global SSP's ESPP Server. 1030 1031 1032 1033 1034 [snip] 1035 1036 7845601000012345631 1037 76544 1038 NewYorkDG 1039 7845601000012345622 1040 7845601000012345623 1041 1042 1043 1044 1046 Figure 12 1048 4.3.1.3. Public Identities, TN Ranges, and RNs 1050 4.3.1.3.1. Description of Identities, TN Ranges, and RNs 1052 With the enterprises and SED data in place, SSPs have established the 1053 Destination Groups they wish to exchange traffic to. Public 1054 identities such as telephone numbers (TN), ranges of TNs, RNs, IM 1055 identifiers can now be provisioned into Destination Groups. This 1056 scenario illustrates the provisioning of TNs, TN Ranges and RNs for 1057 voice traffic exchanges, as well as the provisioning of TNs and IM 1058 identifiers for IM service. 1060 A group of friends wishes to take advantage of their voice and IM 1061 services by having their calls within the group always use the most 1062 efficient technology. These friends are spread out between Boston, 1063 New York, Chicago and Phoenix and across three SSPs. Their public 1064 identities (TNs and IM IDs) are defined below. To simplify the 1065 scenario, the delivery of Instant Messages uses the same SBEs as the 1066 voice traffic. As messaging grows, there may be a need to separate 1067 the SBEs into voice and data portals which would create new SBE NAPTR 1068 records and, optionally, new Routes. Note that this is a technical 1069 example for the purpose of illustrating a protocol specification; 1070 end-user privacy considerations must apply. 1072 +--------+-------------+-------------+------------+-----------------+ 1073 | Subscr | Number | Destination | SSP | IM Identity | 1074 | iber | | Group | | | 1075 +--------+-------------+-------------+------------+-----------------+ 1076 | Pat | 928-774-555 | FlagstaffDG | GlobalSSP | imPat@globalssp | 1077 | | 5 | | | .example2.com | 1078 | | | | | | 1079 | Ashley | 312-746-555 | ChicagoDG | MidwestSSP | imAshley@midwes | 1080 | | 5 | | | tssp.example3.c | 1081 | | | | | om | 1082 | | | | | | 1083 | Vince | 718-330-555 | NewYorkDG | NewYorkSSP | imVince@newyork | 1084 | | 5 | | | ssp.example1.co | 1085 | | | | | m | 1086 | | | | | | 1087 | Carl | 617-414-555 | BostonDG | GlobalSSP | imCarl@globalss | 1088 | | 5 | | | p.example2.com | 1089 +--------+-------------+-------------+------------+-----------------+ 1091 Table 5 1093 These four subscribers have authorized their friends to see their 1094 public identities. The SSPs have also defined TN Ranges associated 1095 with the new VoIP services as shown below. 1097 +-------------------------+--------------------+--------------------+ 1098 | Destination Group | TN Range | | 1099 | Name/ID | | | 1100 +-------------------------+--------------------+--------------------+ 1101 | FlagstaffDG | 928-774-5000 | 928-774-5999 | 1102 | | | | 1103 | ChicagoDG | 312-746-5500 | 312-746-5600 | 1104 | | | | 1105 | NewYorkDG | 718-330-5250 | 718-330-5590 | 1106 | | | | 1107 | | 718-330-4000 | 718-330-4999 | 1108 | | | | 1109 | BostonDG | 617-414-5555 | 617-414-5560 | 1110 +-------------------------+--------------------+--------------------+ 1112 Table 6 1114 To support number portability in some countries, Routing Numbers 1115 (RNs) have identified each of the CMSes within the network. Although 1116 there may be an RN associated with each CMS, we show only the 1117 relevant sub-set applicable to this example: 1119 +---------------------+---------------------+-----------------------+ 1120 | Proxy | Destination Group | RN | 1121 +---------------------+---------------------+-----------------------+ 1122 | Proxy-center | FlagstaffDG | 928-774-1000 | 1123 | | | | 1124 | Proxy-lakestreet | ChicagoDG | 312-746-1000 | 1125 | | | | 1126 | Proxy-bronx | NewYorkDG | 718-330-1000 | 1127 | | | | 1128 | Proxy-fenway | BostonDG | 617-414-1000 | 1129 +---------------------+---------------------+-----------------------+ 1131 Table 7 1133 4.3.1.3.2. ESPP Provisioning of TNs, RNs, and identities 1135 The Public Identity, TN Range and RN data can then be provisioned in 1136 the appropriate ESPP Server of each SSP using the addPvtIds, 1137 addPubIds, addTNRs, and addRNs operations supported by the ESPP 1138 protocol. An optional approach is to combine some of the operations 1139 into a single request using the batchUpdate operation. The following 1140 example SOAP/XML messages provision the data described above. 1142 Using the batchUpdate operation, the ESPP Client provisions four 1143 GlobalSSP elements in the Flagstaff destination group. This command 1144 is sent to the NewYorkSSP's ESPP Server and to any other applicable 1145 peer servers. 1147 1148 1149 1150 1151 [snip] 1152 1153 1154 1155 7845601000012345650 1156 76544 1157 patsPrivateIdentifier 1158 1159 1160 7845601000012345640 1161 76543 1162 9287745555 1163 7845601000012345630 1164 7845601000012345650 1165 1166 1167 7845601000012345641 1168 76543 1169 imPat@globalssp.example2.com 1170 E2U+IM 1171 7845601000012345630 1172 7845601000012345650 1173 1174 1175 7845601000012345642 1176 76543 1177 9287745000 1178 9287745999 1179 7845601000012345630 1180 1181 1182 7845601000012345643 1183 76543 1184 9287741000 1185 7845601000012345630 1186 1187 1188 1189 1190 1192 Figure 13 1194 Using the batchUpdate operation, the ESPP Client provisions four 1195 NewYorkSSP elements in the New York destination group. This command 1196 is sent to the GlobalSSP's ESPP Server (and to any other applicable 1197 servers). 1199 1200 1201 1202 1203 [snip] 1204 1205 1206 1207 7845601000012345651 1208 76544 1209 vincesPrivateIdentifier 1210 1211 1212 7845601000012345644 1213 76544 1214 7183305555 1215 7845601000012345631 1216 7845601000012345651 1217 1218 1219 7845601000012345645 1220 76544 1221 imVince@newyorkssp.example1.com 1222 E2U+IM 1223 7845601000012345631 1224 7845601000012345651 1226 1227 1228 7845601000012345646 1229 76544 1230 7183305250 1231 7183305590 1232 7845601000012345631 1233 1234 1235 7845601000012345647 1236 76544 1237 7183301000 1238 7845601000012345631 1239 1240 1241 1242 1243 1245 Figure 14 1247 4.3.2. Deployment Scenario and Resolution 1249 4.3.2.1. Initiating an Outgoing Call 1251 Initiating a call from Pat to Vince, the CMS hosting Pat launches an 1252 ENUM query to the GlobalSSP addressing server. The addressing server 1253 takes the E.164 address and examines the Public Identities to see if 1254 the specific number is set in the server. 1256 Vince's number is found in the New York Destination Group. This 1257 Destination Group is associated with the Routes RTFlag-NYC1 and 1258 RTFlag-NYC2 that link Flagstaff with New York City. Each of these 1259 Routes has a single SBE NAPTR record. The addressing server would 1260 respond to the CMS with both NAPTR records. The CMS then attempts to 1261 complete the call to the NewYorkSSP by sending the call setup to the 1262 address(es) found in the NAPTR record. The detailed steps involved 1263 in this process are: 1265 1. The CMS normalizes the TN to an e.164 format and queries the 1266 GlobalSSP ESPP Server, which results in the following response: 1268 $ORIGIN 5.5.5.5.0.3.3.8.1.7.1.ssp-example. 1269 NAPTR 10 100 "u" "E2U+SIP" "!^.*$ 1270 !sip:\\1@sbe40-newyorkssp.newyorkssp.example1.com!". 1271 NAPTR 10 101 "u" "E2U+IM" "!^.*$ 1272 !im:imvince@sbe41-newyorkssp.newyorkssp.example1.com!". 1274 Figure 15 1276 2. Assuming that the CMS is interested in the SIP service, as it is 1277 initiating a telephone call, the CMS now executes a NAPTR query to 1278 the DNS server for "sbe40-newyorkssp.example1.com" resulting in: 1280 sbe40-newyorkssp.example1.com. 1281 order pref flgs service regx replacement 1282 IN NAPTR 100 50 "s" "SIP+D2U" "" _sip._udp.sbe40-newyorkssp 1283 .newyorkssp.example1.com 1285 Figure 16 1287 3. The CMS now sends a DNS SRV query for _sip._udp.sbe40-newyorkssp. 1288 newyorkssp.example1.com which results in: 1290 $ORIGIN _sip._udp.sbe40-newyorkssp.newyorkssp.example1.com. 1291 (Some content not included for clarity purposes.) 1292 IN SRV 0 1 5060 sbe40-newyorkssp.example1.com 1294 ;; ANSWER SECTION 1295 sbe40-newyorkssp.newyorkssp.example1.com A 192.0.2.17 1296 sbe40-newyorkssp.newyorkssp.example1.com A 192.0.2.18 1298 Figure 17 1300 4. Now the CMS applies the regular expression rules to the NAPTR 1301 obtained in step 1 and places the result into the SIP Request URI: 1303 INVITE sip:17183305555@sbe40-newyorkssp.newyorkssp.example1.com 1304 SIP/2.0 1305 (Other SIP INVITE content not included for clarity purposes.) 1307 Figure 18 1309 5. CMS sends the SIP INVITE to Vince via the SBE with associated 1310 IPv4 address 192.0.2.17 to port 5060 using UDP as the transport 1311 protocol. 1313 4.3.2.2. Receiving an Incoming Call 1315 Taking the call scenario described above, once the call request 1316 arrives in NewYorkSSP's network the SBE within NewYorkSSP queries its 1317 own ESPP Server and finds a match for Mary's number in the TN Range 1318 records (718-330-5250 to 718-330-5590). The NewYorkSSP ESPP Server 1319 has been provisioned with intra-domain routes so that the SBE can 1320 locate the proper CMS. The NewYorkSSP ESPP Server contains the New 1321 York Destination Group that is associated with a intra-domain Route 1322 that is not shared with the other SSPs. This allows the internal 1323 routing topology of an SSP to remain private to the SSP. There is 1324 only one route for this range of phone numbers with only one NAPTR 1325 record. The data used to resolve the query looks like: 1327 TN Range: 718-330-5250 to 718-330-5590 1328 Destination Group: New York 1329 Route: RTNYC-Private 1330 NAPTR 10 101 "u" "E2U+SIP" "!^.*$ 1331 !sip:\\1@cms-bronx.newyorkssp.example1.com!" . 1333 Figure 19 1335 4.3.2.2.1. Query using the Routing Number 1337 If the number has been ported, there are a number of cases where the 1338 query may also contain a Routing Number. The Routing Number is a 1339 reference number for one or more telephone switches where previously 1340 the first 6 digits of the phone number clearly identified the switch. 1342 Once the call request arrives in NewYorkSSP's network the SBE within 1343 NewYorkSSP queries its own ESPP Server and finds a match for the RN 1344 or prefix (718-330-1000) in the New York Destination Group. The rest 1345 of the routing lookup is similar to what is described for the 1346 telephone number above. 1348 RN: 718-330-1000 1349 Destination Group: New York 1350 Route: RTNYC-Private 1351 NAPTR 10 101 "u" "E2U+SIP" "!^.*$ 1352 !sip:\\1@cms-bronx.newyorkssp.example1.com!" . 1354 Figure 20 1356 4.3.2.2.2. Growth of the SIP Service Provider Group 1358 When NewSSP is ready to exchange traffic, their ESPP Server receives 1359 a batch download the latest data from all its peers via the 1360 Registrar. The Registrar takes an image of the current data that 1361 each peer has allowed NewSSP to view and performs a secure file 1362 transfer to the NewSSP addressing server. Following the download, 1363 the NewSSP ESPP Server connects to the Registrar and begin processing 1364 real-time updates to ensure that any changes made since creating the 1365 batch download files are made in the addressing server. 1367 4.3.3. Generic Examples 1369 Additional examples are available in Appendix I of [CableLabs-ESPP]. 1371 4.4. Protocol Specification 1373 This section describes the general concepts that apply to the 1374 protocol's operations. It also describes each individual protocol 1375 operation, its input and output objects, and its functional 1376 characteristics. The complete normative specification of the 1377 protocol (the WSDL and XSD definitions) can be found in Section 8, 1378 Formal API Definition, in this document. Note that if any 1379 specification conflicts exist between this section and Section 8, the 1380 normative definitions contained in Section 8 take precedence. 1382 The protocol utilizes SOAP 1.1 [SOAP], WSDL1.1 [WSDL], and XML 1.0 1383 [XML]. 1385 4.4.1. General Protocol Concepts 1387 The following sub-sections describe the object structures and 1388 concepts that are applicable to many of the protocol operations 1390 4.4.1.1. Basic Request Object 1392 All ESPP operations that may potentially modify persistent protocol 1393 objects require a BasicRqst object to be passed in, in addition to 1394 other object types that are specific to each operation. The basic 1395 request object contains a client ID, a transaction ID, the minor 1396 version of the protocol, and an optional extension element. Each of 1397 the values is described in the subsequent sub-sections. 1399 1400 1401 1402 1403 1404 1405 1406 1408 1409 1410 1412 1413 1414 1416 4.4.1.2. Basic Query Object 1418 All ESPP "get" operations require a BasicQueryRqst object to be 1419 passed in, in addition to other object types that are specific to 1420 each get operation. The basic query object contains a client ID, the 1421 minor version of the protocol, and an optional extension element. 1422 Each of the values is described in the subsequent sub-sections. 1423 Notice that no transaction ID is necessary for query operations. 1425 1426 1427 1428 1429 1430 1431 1433 4.4.1.3. Authentication 1435 For each ESPP connection, the ESPP Client and ESPP Server MUST use 1436 HTTP Digest based authentication as defined in [RFC2617]. The HTTP 1437 Digest authentication SHOULD be performed once per connection. To 1438 further support authentication and operational activities, such as 1439 auditing, each ESPP operation requires a client ID as input. 1441 4.4.1.4. Transaction ID 1443 Each ESPP Client maintains a transaction ID counter for each ESPP 1444 Server that it is configured to update. Similarly, each ESPP Server 1445 maintains the transaction ID for each ESPP Client from which it 1446 receives updates. These transaction IDs are maintained in persistent 1447 storage on both client and server. The protocol data element that 1448 contains the transaction ID for each operation is declared as 1449 follows: 1451 1452 1453 1454 1456 A transaction ID is sent with each update request to an ESPP Server. 1457 The transaction ID MUST be present in a protocol request operation 1458 whose purpose is to modify data within an ESPP Server. The ESPP 1459 Client and ESPP Server must implement the transaction ID as a 64-bit 1460 value. The initial value for the transaction ID on the ESPP Client 1461 MUST either be chosen randomly, start at zero, or be configured by 1462 the SIP Service Provider before protocol processing or bootstrap file 1463 generation begins. 1465 When generating an API-based update request or a file based 1466 batchFileUpdateRqst request destined for an ESPP Server, the ESPP 1467 Client MUST use the current transaction ID for the target server, 1468 which is one increment greater than the previous successful 1469 transaction ID (or the first transaction ID in the counter if this is 1470 the first request generated for the given ESPP Client/server pair). 1471 After successfully generating a batchFileUpdateRqst structure or 1472 after receiving a successful response from an API base request, the 1473 client increments the transaction ID for that server by one. When 1474 the 'isFullResync' flag is set in the batchFileUpdateRqst, the ESPP 1475 Server MUST set the transaction ID for that client to the value 1476 received in the batchFileUpdateRqst. 1478 When receiving a transaction ID in a request, the ESPP Server 1479 compares it to its current transaction ID value. If the transaction 1480 ID from the client is one greater than the transaction ID from the 1481 server, the request is processed normally. If the request succeeds 1482 on the server, the ESPP Server MUST update its transaction ID to be 1483 the one received from the client. Once all database changes have 1484 been synchronized to persistent storage, the server MUST respond with 1485 a successful result code. When the client receives the response from 1486 the server indicating that the request has succeeded, the client MUST 1487 increment its transaction ID by one. 1489 If the server receives a request from a client with a transaction ID 1490 that is the same as server's current transaction ID for that client, 1491 the server compares the content of the request received from the 1492 client to the content of the request most recently received from that 1493 client. If the content is identical, this indicates that the client 1494 failed to receive the response to the previous transaction. The 1495 client is assumed to be retrying that transaction that the server has 1496 already successfully processed. In this event the server SHOULD NOT 1497 modify its database. The ESPP Server MUST simply return the 1498 identical response that it returned in response to the clients first 1499 attempt to process the request/response. 1501 In the case that the transaction ID is the same but the request 1502 content is different, or the transaction ID from the client is 1503 different but is not one greater than the transaction ID for that 1504 client on the server, the server and client are out of sync. In this 1505 event, the ESPP Server SHOULD return the appropriate error code 1506 (Transaction ID out of sequence). The ESPP Client MUST automatically 1507 suspend protocol updates to that server and raise a critical alarm. 1508 Manual intervention is likely required at this point to analyze and 1509 clear the error, perhaps by initiating a full re-synchronization of 1510 the client's data store, and then re-enabling real-time protocol 1511 communication to that ESPP Server. 1513 In cases where the server determines the transaction ID to be 1514 correct, there are two general categories of errors: system errors 1515 and business errors. In the event a system error occurs (e.g., disk 1516 space has been exhausted) the ESPP Server MUST return the appropriate 1517 error message (System Unavailable Error or Authentication Error) and 1518 the ESPP Client SHOULD suspend real-time updates to the server for 1519 some period of time configured by the SIP Service Provider, and then 1520 resume after that time has elapsed. In this case the ESPP Client 1521 MUST not update the transaction ID as transaction IDs are only 1522 consumed/updated by the client on successful responses to a given API 1523 request or when a file based update is successfully generated by the 1524 client. In the event a business error occurs (e.g., a data element 1525 fails the regular expression validation), the ESPP Server MUST return 1526 the appropriate error code for the given error and operation. In 1527 response to this type of error response the client MUST, again, not 1528 consume that transaction ID, because the transaction did not complete 1529 successfully. The client MUST suspend real-time protocol 1530 communication with that ESPP Server and generate an internal alarm. 1531 Manual intervention is required to analyze and rectify the erroneous 1532 data that caused the error and then re-enable real-time protocol 1533 communication with the ESPP Server. 1535 4.4.1.5. Version Identification 1537 The version of the ESPP protocol in use is defined by the combination 1538 of the major version ID embedded in the namespace of the XSD and the 1539 minor version ID that is passed in with each request as an element of 1540 the BasicRqstType object. 1542 A major version ID will change when a change is made to the protocol 1543 that is not backward compatible. The minor version ID may change 1544 when a change is made to the protocol that is backward compatible. 1545 The version ID passed in by the ESPP Client MUST indicate the version 1546 that the client supports; it SHOULD be the version that the client 1547 believes that the ESPP Server supports. When a message arrives at 1548 the server, the server MUST evaluate the version indicator passed in 1549 by the ESPP Client and it MUST return the appropriate error code and 1550 message if the version is not one that is supported by the server. 1551 Refer to the list of response codes for the appropriate code to 1552 return in this circumstance. 1554 4.4.1.6. Basic Response Object 1556 The request/input object type is distinct for each operation. 1557 However, most operations of the ESPP protocol return the same 1558 response/output object type, CmnRspnsMsg. In keeping with the 1559 Document Literal Wrapped design approach described in the 1560 introductory sections, the WSDL declaration of this response message 1561 is declared as follows: 1563 1564 1565 1567 1568 1569 1570 1571 1572 1573 1575 The resCode element is a response code and the resMsg is the 1576 corresponding response message. The BasicRspnsType may also be 1577 extended using the ext element. Each of these elements is further 1578 described in subsequent sections. 1580 4.4.1.7. Object ID and Enterprise ID 1582 As described in the Logical Structure section of this document, each 1583 object instance in ESPP has a unique identifier, its oId, and the 1584 identifier os its "owning" operational entity, its eId. These two 1585 data elements are defined as follows: 1587 1588 1589 1591 1592 1593 1595 These two fields are further defined as follows: 1597 o oId: 1598 Each object is uniquely identifiable using its object ID. An 1599 object ID is guaranteed to be unique within an ESPP Server and 1600 ESPP Client, regardless of the number of ESPP Clients populating 1601 objects into a given ESPP Server. An ESPP Client MUST create 1602 and assign the Object IDs it provisions. This approach has 1603 significant performance advantages. The management of the 1604 unique name space for ESPP object IDs and the approach for 1605 creation and assignment of object IDs is defined as follows: 1607 * ESPP Clients and Servers MUST implement the oId attribute as 1608 an unsigned 64-bit value, unsigned long. Unsigned longs 1609 support up to 20 digits, but refer to the data validation 1610 appendix of this document where the maximum allowable value 1611 of an unsigned long is documented. 1613 * The 8 most significant digits of the object ID MUST contain a 1614 client ID that is guaranteed to be globally unique within an 1615 ESPP federation. This client ID MUST be right justified in 1616 this 8 digit field, leaving any unused most significant 1617 digits empty. The client ID MUST be the combination of two 1618 parts, a 1 to 6 digit organization ID and a 2 digit suffix. 1619 The organization ID portion of the client ID MUST be a number 1620 acquired from the IANA Private Enterprise Number (PEN) 1621 registry, http://www.iana.org/assignments/enterprise-numbers. 1622 The 2 digit suffix MUST be used to further uniquely identify 1623 an ESPP Client software within the organization represented 1624 by the organization ID. The 2 digit suffix is necessary in 1625 cases where more than one ESPP Client, within the same ESPP 1626 federation, are from the same organization and therefore 1627 would have the same organization ID. The suffix MUST be 1628 within the range of 00 and 99, inclusive. Prior to 1629 introducing an ESPP Client into an ESPP federation, the 1630 organization that operates that ESPP Client acquires an 1631 organization ID, adds an appropriate 2 digit suffix. The 1632 resulting client ID will then be used to formulate the object 1633 Ids for the ESPP objects created by that client software. 1635 * The remaining, right hand, 12 digits of the object ID MUST 1636 contain an object ID that is guaranteed to be unique within 1637 the client identified by the client ID. 1639 * As an example, a valid object ID would be 123401000012345678. 1640 In this example, 1234 is the organization ID of the 1641 organization that manages the ESPP Client implementation, 01 1642 is the client ID suffix, and 000012345678 is the object ID 1643 that is unique within that ESPP client. Notice that the two 1644 most significant digit fields are not used and are not 1645 necessary in this example. The result is an object ID that 1646 is unique within the ESPP federation. 1648 o eId: 1649 The enterprise ID data element that resides as a data element 1650 within each ESPP object uniquely identifies an operational 1651 entity within an ESPP federation that is responsible for, or 1652 owns, that object from a business perspective. This is distinct 1653 from the client ID, which identifies the piece of software that 1654 performs the mechanics of provisioning an ESPP object within an 1655 ESPP client. The globally unique name space for the assignment 1656 of an enterprise ID is the IANA Private Enterprise Number (PEN) 1657 registry, http://www.iana.org/assignments/enterprise-numbers. 1658 Prior to contributing its addresses and routing information to 1659 an ESPP federation an enterprise acquires a PEN, which will then 1660 reside in the eId field of each ESPP object that and ESPP Client 1661 provisions on behalf of that enterprise. 1663 The ESPP Client and ESPP Server MUST implement the oId attribute as 1664 an unsigned 64-bit value. 1666 4.4.1.8. Response Codes and Messages 1668 The response to each protocol operation includes exactly one response 1669 code and response message. The response codes that each operation is 1670 permitted to return are listed in each sub-section that describes 1671 each operation. And the consolidated list of response codes and 1672 messages are listed in the "Response Codes and Messages" section of 1673 this document. 1675 All real-time API operations of the ESPP protocols MUST be atomic, 1676 all aspects of the operation will fail or all will succeed. An 1677 operation should never result in a "partial success". As a result, 1678 the response code returned by any given operation call indicates 1679 whether the operation succeeded or failed. Each failure reason has a 1680 unique failure response code and message, and only one may be 1681 returned in response to any given operation call. The protocol 1682 object that houses the response code and message is called 1683 BasicRspnsType. 1685 4.4.1.9. Extensibility 1687 Extensibility allows a given ESPP Client or ESPP Server to supplement 1688 ESPP messages with additional object or data elements that may be 1689 appropriate for a given ESPP deployment or operational scenario. 1690 ESPP is implicitly and explicitly extensible. Implicit extensibility 1691 is supported by the fact that XSD and WSDL definitions may be 1692 extended without breaking backward compatibility. New WSDL 1693 operations can be added and new XSD data types can be added without 1694 breaking backward compatibility. Explicit extensibility is supported 1695 through the use of the XSD "any" type. Each object type definition 1696 in ESPP contains an additional attribute called "ext", which is of 1697 type ExtAnyType, which contains one or more an XSD "any" elements. 1698 Furthermore, the BasicRqstType and BasicRspnsType also contain an 1699 "ext" element to allow the addition of objects of any type to be 1700 added to the request and response objects that are used for each ESPP 1701 operation. And ESPP Server may dynamically evaluate the version ID 1702 of any given request and choose to accept or return these optional 1703 attributes from or to an ESPP Client. 1705 1706 1707 1708 1709 1711 4.4.2. Protocol Operation Descriptions 1713 The following sub-sections describe each individual protocol 1714 operation in detail, its input and output objects, and its functional 1715 characteristics. 1717 4.4.2.1. Operation Name: addRtes 1719 As described in the introductory sections, a Route represents a 1720 collection of session-level peering points named Signaling path 1721 Border Elements (SBEs). Routes are linked to Destination Groups to 1722 establish the link between a set of public identities and their SBEs. 1723 It is this indirect linking of public identities to SBEs that 1724 significantly improves the scalability and manageability of the 1725 peering data. Additions and changes to session-level peering points 1726 are reduced to a single data distribution operation of a Route or 1727 Destination Group in an addressing server, rather than millions of 1728 data distribution updates to public identity records that 1729 individually contain their peering point data. 1731 The addRtes operation creates or overwrites one or more Routes in the 1732 addressing server. If a Route with the given Route ID does not 1733 exist, then the ESPP Server MUST create the route. If a Route with 1734 the given Route ID does exist, then the ESPP Server MUST replace the 1735 current properties of the Route with the properties passed into the 1736 addRtes operation. If a Route with the given ID does exist, but was 1737 created by a client other than the one calling the addRtes operation 1738 then the ESPP Server SHOULD reject the request with the appropriate 1739 error code, 2106. 1741 In keeping with the Document Literal Wrapped design approach 1742 described in the introductory sections, the WSDL declaration of the 1743 operation is as follows: 1745 1746 1747 1748 1750 1751 1752 1754 1755 1756 1758 Inputs to the operation are wrapped in the addRtesRqst object, which 1759 is declared as follows: 1761 1762 1763 1764 1765 1767 1768 1769 1771 As with all update operations, the basicRqst data element is a 1772 required input. Refer to Section 4.4.1, General Protocol Concepts, 1773 for a detailed description of this data element. One or more RteType 1774 objects are also required. Any limitation on the maximum number of 1775 routes that may be passed into a call to the addRtes operation is a 1776 policy decision and is not limited by the protocol. 1778 The RteType object structure is declared as follows: 1780 1781 1782 1783 1784 1785 1787 1788 1789 1790 1792 The RteType object is comprised of the following data elements: 1794 o oid: Exactly one object ID to uniquely identify the object 1795 instance. This identifier is also an input to the delRtes, 1796 getRtes, and addDestGroups operations to identify a given route. 1798 o eid: Exactly one enterprise ID that uniquely identifies the 1799 operational entity within the call routing community that is 1800 responsible for, or "owns" this object. 1802 o RteName: Exactly one human readable name of the Route. 1804 o SBENaptrId: Zero or more NAPTR IDs. 1806 o IsInSvc: Toggle-able boolean value that sets the Route in 1807 service or out of service. The ESPP Server MUST NOT include the 1808 NAPTR record(s) associated with an out-of-service route in the 1809 response to a resolution request for a telephone number that is 1810 associated with the Route that contains that border element. 1812 o Ext: Point of extensibility described in Section 4.4.1.9. 1814 Table 8 defines the result codes and messages that the addRtes 1815 operation SHOULD return. 1817 +--------+----------------------------------------------------------+ 1818 | Result | Text | 1819 | Code | | 1820 +--------+----------------------------------------------------------+ 1821 | 1000 | Request Succeeded. | 1822 | | | 1823 | 2001 | Request syntax invalid. | 1824 | | | 1825 | 2002 | Request too large. | 1826 | | | 1827 | 2003 | Version not supported. | 1828 | | | 1829 | 2301 | System temporarily unavailable. | 1830 | | | 1831 | 2103 | Transaction ID out of sequence: [transaction ID | 1832 | | received]:[ transaction ID expected]. | 1833 | | | 1834 | 2104 | Attribute value invalid: [attribute name]:[attribute | 1835 | | value]:[objectType-objectId]. | 1836 | | | 1837 | 2106 | Object status or ownership does not allow for request: | 1838 | | [request name]:[ attributeName]:[objectType-objectId]. | 1839 +--------+----------------------------------------------------------+ 1841 Table 8: addRtes Operation Result Codes and Messages 1843 4.4.2.2. Operation Name: addDestGroups 1845 As described in the introductory sections, a Destination Group 1846 represents a collection of public identities that are linked to a set 1847 of Routes. Routes are linked to Destination Groups to establish the 1848 link between a set of public identities and their session-level 1849 peering points. The addDestGroups operation creates or overwrites 1850 one or more Destination Groups in the addressing server. If a 1851 destination group with the given destination group ID does not exist, 1852 then the ESPP Server MUST create the destination group. If a 1853 destination group with the given identity does exist, then the ESPP 1854 Server MUST replace the current properties of that destination group 1855 with the properties passed into the addDestGroups operation. If a 1856 destination group with the given ID does exist, but was created by a 1857 client other than the one calling the addDestGroups operation then 1858 the ESPP Server SHOULD reject the request with the appropriate error 1859 code, 2106. 1861 In keeping with the Document Literal Wrapped design approach 1862 described in the introductory sections, the WSDL declaration of the 1863 operation is as follows: 1865 1866 1867 1868 1870 1871 1872 1874 1875 1876 1878 Inputs to the operation are wrapped in the addDestGroupsRqst object, 1879 which is declared as follows: 1881 1882 1883 1884 1885 1887 1888 1889 1891 As with all update operations, the basicRqst data element is a 1892 required input. Refer to Section 4.4.1, General Protocol Concepts, 1893 for a detailed description of this data element. Also required is 1894 one or more DestGroupType objects. Any limitation on the maximum 1895 number of destination groups that may be passed into a call to the 1896 addDestGroups operation is a policy decision and is not limited by 1897 the protocol. 1899 The DestGroup object structure is declared as follows: 1901 1902 1903 1904 1905 1906 1908 1910 1911 1913 The data elements of the DestGroupType are described as follows: 1915 o oId: Exactly one object ID that provides the identity of the 1916 object. This identifier is also an input to other operations 1917 that must refer to a Destination Group, such as delDestGroups, 1918 getDestGroups, and addPubIds operations to identify a given 1919 destination group. 1921 o Eid: Exactly one enterprise ID that uniquely identifies the 1922 operational entity within the call routing community that is 1923 responsible for, or "owns" this object. 1925 o destGroupName: Exactly one human readable name of the 1926 destination group. 1928 o RteID: The identity of zero or more routes that the Public 1929 Identities, RNs, and TN Ranges in this destination group can be 1930 routed through. 1932 o Ext: Point of extensibility described in Section 4.4.1.9. 1934 The ESPP Server MUST reject any addDestGroups operation call that 1935 attempts to create a destination group with a route ID that does not 1936 exist within the context of the addressing server. 1938 Table 9 defines the result codes and messages that the addDestGroups 1939 operation SHOULD return. 1941 +--------+----------------------------------------------------------+ 1942 | Result | Text | 1943 | Code | | 1944 +--------+----------------------------------------------------------+ 1945 | 1000 | Request Succeeded. | 1946 | | | 1947 | 2001 | Request syntax invalid. | 1948 | | | 1949 | 2002 | Request too large. | 1950 | | | 1951 | 2003 | Version not supported. | 1952 | | | 1953 | 2301 | System temporarily unavailable. | 1954 | | | 1955 | 2103 | Transaction ID out of sequence: [transaction ID | 1956 | | received]:[ transaction ID expected]. | 1957 | | | 1958 | 2104 | Attribute value invalid: [attribute name]:[attribute | 1959 | | value]:[objectType-objectId]. | 1960 | | | 1961 | 2105 | Object does not exist: [attribute name]:[ | 1962 | | objectType-objectId]. | 1963 | | | 1964 | 2106 | Object status or ownership does not allow for request: | 1965 | | [request name]:[ attributeName]:[objectType-objectId]. | 1966 +--------+----------------------------------------------------------+ 1968 Table 9: addDestGroups Operation Result Codes and Messages 1970 4.4.2.3. Operation Name: addPubIds 1972 As described in the introductory sections, a Public Identity object 1973 represents a public addressable identity (such as a telephone number, 1974 email address, or some other addressable string). It is linked to 1975 SBEs and NAPTRs (indirectly via a Destination Group ID), and, 1976 alternatively, to directly associated NAPTRs. The ESPP protocol 1977 allows a Public Identity to have a relationship to a Destination 1978 Group and/or a set of NAPTRs. 1980 A Public Identity may also be associated with a Private Identity 1981 object. The addPubIds operation creates or overwrites one or more 1982 PubId objects in the addressing server. If a PubId object with the 1983 same object ID does not exist within the context of the addressing 1984 server, then the ESPP Server MUST create the PubId object. If such 1985 an object does exist within the context of the addressing server, 1986 then the ESPP Server MUST replace the current properties of that 1987 object with the values passed into the addPubIds operation. If a 1988 Public Identity with the given ID does exist, but was created by a 1989 client other than the one calling the addPubIds operation then the 1990 ESPP Server SHOULD reject the request with the appropriate error 1991 code, 2106. 1993 In keeping with the Document Literal Wrapped design approach 1994 described in the introductory sections, the WSDL declaration of the 1995 operation is as follows: 1997 1998 1999 2000 2002 2003 2004 2006 2007 2008 2010 Inputs to the operation are wrapped in the addPubIdsRqst object, 2011 which is declared as follows: 2013 2014 2015 2016 2017 2019 2020 2021 2023 As with all update operations, the basicRqst data element is a 2024 required input. Refer to the Section 4.4.1, General Protocol 2025 Concepts, for a detailed description of this data element. Also 2026 required is one or more PubIdType objects. Any limitation on the 2027 maximum number of Public Identities that may be passed into a call to 2028 the addPubIds operation is a policy decision and is not limited by 2029 the protocol. 2031 The PubIdType object structure is declared as follows: 2033 2034 2035 2036 2037 2038 2039 2040 2042 2043 2044 2045 2047 The PubIdType is comprised of the following data elements: 2049 o oId: Exactly one object ID that provides the identity of the 2050 object. 2052 o Eid: Exactly one enterprise ID that uniquely identifies the 2053 operational entity within the call routing community that is 2054 responsible for or "owns" this object. 2056 o PubId: Exactly one public identity that is a resolvable identity 2057 within the context of the addressing server. This identity may, 2058 for example, be a TN, an email address, or some other resolvable 2059 identity. 2061 o Svcs: Exactly one ENUM service type associated with the public 2062 identity. This field's value must be of the form specified in 2063 [RFC 3761] (e.g., E2U+pstn:sip+sip). The allowable values are a 2064 matter of policy and not limited by this protocol. 2066 o dgId: Zero or one object ID that identifies the Destination 2067 Group this public identity object instance resides within. The 2068 Destination Group's relationship to one or more Routes can then 2069 define the peering points of Public Identities. The ESPP Server 2070 MUST reject, with the appropriate error response code, an 2071 attempt to create a public identity object containing a 2072 Destination Group ID that does not exist within the appropriate 2073 context of the addressing server. 2075 o NAPTR: Zero or more NAPTRs. NAPTR objects directly associated 2076 with a public identity can be a lower level, more data 2077 distribution intensive approach to associating a telephone 2078 number with its peering points. 2080 o PvtId: Zero or one object ID that optionally identified a 2081 private identity to which this public identity is associated. 2082 This provides the ability to create a "related" set of public 2083 identities. The ESPP Server MUST return an error response if 2084 the Private Identity object identified by this PvtId does not 2085 exist within the context of the addressing server. 2087 o Ext: Point of extensibility described in Section 4.4.1.9. 2089 The ESPP protocol does not specifically disallow the creation of 2090 Public Identities that have no associated NAPTRs and no associated 2091 Destination Group. 2093 Table 10 defines the result codes and messages that the addPubIds 2094 operation SHOULD return. 2096 +--------+----------------------------------------------------------+ 2097 | Result | Text | 2098 | Code | | 2099 +--------+----------------------------------------------------------+ 2100 | 1000 | Request Succeeded. | 2101 | | | 2102 | 2001 | Request syntax invalid. | 2103 | | | 2104 | 2002 | Request too large. | 2105 | | | 2106 | 2003 | Version not supported. | 2107 | | | 2108 | 2301 | System temporarily unavailable. | 2109 | | | 2110 | 2103 | Transaction ID out of sequence: [transaction ID | 2111 | | received]:[ transaction ID expected]. | 2112 | | | 2113 | 2104 | Attribute value invalid: [attribute name]:[attribute | 2114 | | value]:[objectType-objectId]. | 2115 | | | 2116 | 2105 | Object does not exist: [attribute name]:[ | 2117 | | objectType-objectId]. | 2118 | | | 2119 | 2106 | Object status or ownership does not allow for request: | 2120 | | [request name]:[ attributeName]:[objectType-objectId]. | 2121 +--------+----------------------------------------------------------+ 2123 Table 10: addPubIds Operation Result Codes and Messages 2125 4.4.2.4. Operation Name: addPvtIds 2127 As described in the introductory sections, a Private Identity object 2128 represents a string of numbers or characters that serves to 2129 associate, or group together, a set of related Public Identities. 2130 The addPvtIds operation creates or overwrites one or more PvtId 2131 objects in the addressing server. If a PvtId object with the same 2132 object ID does not exist within the context of the addressing server, 2133 then the ESPP Server MUST create the PvtId object. If such an object 2134 does exist within the context of the addressing server, then the ESPP 2135 Server MUST replace the current properties of that object with the 2136 values passed into the operation. If a Private Identity with the 2137 given ID does exist, but was created by a client other than the one 2138 calling the addPvtIds operation then the ESPP Server SHOULD reject 2139 the request with the appropriate error code, 2106. 2141 In keeping with the Document Literal Wrapped design approach 2142 described in the introductory sections, the WSDL declaration of the 2143 operation is as follows: 2145 2146 2147 2148 2150 2151 2152 2154 2155 2156 2158 Inputs to the operation are wrapped in the addPvtIdsRqst object, 2159 which is declared as follows: 2161 2162 2163 2164 2165 2166 2167 2169 2171 As with all update operations, the basicRqst data element is a 2172 required input. Refer to the Section 4.4.1, General Protocol 2173 Concepts, for a detailed description of this data element. Also 2174 required is one or more PubIdType objects. Any limitation on the 2175 maximum number of Public Identities that may be passed into a call to 2176 the addPubIds operation is a policy decision and is not limited by 2177 the protocol. 2179 The PvtIdType object structure is declared as follows: 2181 2182 2183 2184 2185 2186 2187 2188 2190 The PvtIdType is comprised of the following data elements: 2192 o oId: Exactly one object ID that provides the identity of the 2193 object. 2195 o Eid: Exactly one enterprise ID that uniquely identifies the 2196 operational entity within the call routing community that is 2197 responsible for or "owns" this object. 2199 o PvtId: Exactly one private identity that serves to associate, or 2200 group together, a set of related Public Identities. 2202 o Ext: Point of extensibility described in Section 4.4.1.9. 2204 Table 11 defines the result codes and messages that the addPvtIds 2205 operation SHOULD return. 2207 +--------+----------------------------------------------------------+ 2208 | Result | Text | 2209 | Code | | 2210 +--------+----------------------------------------------------------+ 2211 | 1000 | Request Succeeded. | 2212 | | | 2213 | 2001 | Request syntax invalid. | 2214 | | | 2215 | 2002 | Request too large. | 2216 | | | 2217 | 2003 | Version not supported. | 2218 | | | 2219 | 2301 | System temporarily unavailable. | 2220 | | | 2221 | 2103 | Transaction ID out of sequence: [transaction ID | 2222 | | received]:[ transaction ID expected]. | 2223 | | | 2224 | 2104 | Attribute value invalid: [attribute name]:[attribute | 2225 | | value]:[objectType-objectId]. | 2226 | | | 2227 | 2105 | Object does not exist: [attribute name]:[ | 2228 | | objectType-objectId]. | 2229 | | | 2230 | 2106 | Object status or ownership does not allow for request: | 2231 | | [request name]:[ attributeName]:[objectType-objectId]. | 2232 +--------+----------------------------------------------------------+ 2234 Table 11: addPvtIds Operation Result Codes and Messages 2236 4.4.2.5. Operation Name: addRNs 2238 As described in the introductory sections, an RN object represents a 2239 routing number and its indirect relationship to one or more SBEs (via 2240 a Destination Group ID). 2242 The addRNs operation creates or overwrites one or more RN objects in 2243 the addressing server. If an RN object with the same object ID does 2244 not exist within the context of the addressing server, then the ESPP 2245 Server MUST create the RN object. If an RN object with the same 2246 object ID does exist within the context of the addressing server, 2247 then the ESPP Server MUST replace the current properties of that RN 2248 with the properties passed into the addRNs operation. If an RN with 2249 the given ID does exist, but was created by a client other than the 2250 one calling the addRN operation then the ESPP Server SHOULD reject 2251 the request with the appropriate error code, 2106. 2253 In keeping with the Document Literal Wrapped design approach 2254 described in the introductory sections, the WSDL declaration of the 2255 operation is as follows: 2257 2258 2259 2260 2262 2263 2264 2266 2267 2268 2270 Inputs to the operation are wrapped in the addRNsRqst object, which 2271 is declared as follows: 2273 2274 2275 2276 2277 2278 2279 2280 2282 As with all update operations, the basicRqst data element is a 2283 required input. Refer to the Section 4.4.1 General Protocol Concepts 2284 for a detailed description of this data element. Also required is 2285 one or more RNType objects. Any limitation on the maximum number of 2286 RNs that may be passed into a call to the addRNs operation is a 2287 policy decision and is not limited by the protocol. 2289 The RN object structure is declared as follows: 2291 2292 2293 2294 2295 2296 2297 2298 2299 2301 RNType is comprised of the following data elements: 2303 o oid: Exactly one object ID that provides the identity of the 2304 object. This identifier is also an input to the delRNs, getRNs 2305 operations to identify a given RN 2307 o eid: Exactly one enterprise ID that uniquely identifies the 2308 operational entity within the call routing community that is 2309 responsible for or "owns" this object 2311 o RN: One local routing number 2313 o dgId: Exactly one object ID that identifies the Destination 2314 Group in which this RN resides. The Destination Group's 2315 relationship to one or more Routes can then define the RNs 2316 peering points. The ESPP Server MUST reject, with the 2317 appropriate error response code, an attempt to create an RN 2318 object containing a Destination Group ID that does not exist 2319 within the appropriate context of the addressing server 2321 o Ext: Point of extensibility described in Section 4.4.1.9 of this 2322 document 2324 Table 12 defines the result codes and messages that the addRNs 2325 operation SHOULD return. 2327 +--------+----------------------------------------------------------+ 2328 | Result | Text | 2329 | Code | | 2330 +--------+----------------------------------------------------------+ 2331 | 1000 | Request Succeeded. | 2332 | | | 2333 | 2001 | Request syntax invalid. | 2334 | | | 2335 | 2002 | Request too large. | 2336 | | | 2337 | 2003 | Version not supported. | 2338 | | | 2339 | 2301 | System temporarily unavailable. | 2340 | | | 2341 | 2103 | Transaction ID out of sequence: [transaction ID | 2342 | | received]:[ transaction ID expected]. | 2343 | | | 2344 | 2104 | Attribute value invalid: [attribute name]:[attribute | 2345 | | value]:[objectType-objectId]. | 2346 | | | 2347 | 2105 | Object does not exist: [attribute name]:[ | 2348 | | objectType-objectId]. | 2349 | | | 2350 | 2106 | Object status or ownership does not allow for request: | 2351 | | [request name]:[ attributeName]:[objectType-objectId]. | 2352 +--------+----------------------------------------------------------+ 2354 Table 12: addRNs Operation Result Codes and Messages 2356 4.4.2.6. Operation Name: addTNRs 2358 As described in the introductory sections, a TNRType is a range of 2359 telephone numbers which are provisioned as a group, reducing the 2360 number of objects that must be independently provisioned and managed. 2361 This object contains the indirect relationship to a set of peering 2362 point NAPTRs (via a Destination Group ID). The addTNRs operation 2363 creates or overwrites one or more TNR objects in the addressing 2364 server. If a TNR object with the same object ID does not exist 2365 within the context of the addressing server, then the ESPP Server 2366 MUST create the TNR object. If such an object does exist within the 2367 context of the addressing server, then the ESPP Server MUST replace 2368 the current properties of that object with the values passed into the 2369 addTNRanges operation. If a TNRange with the given ID does exist, 2370 but was created by a client other than the one calling the addTNRs 2371 operation then the ESPP Server SHOULD reject the request with the 2372 appropriate error code, 2106. 2374 In keeping with the Document Literal Wrapped design approach 2375 described in the introductory sections, the WSDL declaration of the 2376 operation is as follows: 2378 2379 2380 2381 2383 2384 2385 2387 2388 2389 2391 Inputs to the operation are wrapped in the addTNRsRqst object, which 2392 is declared as follows: 2394 2395 2396 2397 2398 2399 2400 2401 2403 As with all update operations, the basicRqst data element is a 2404 required input. Refer to the Section 4.4.1, General Protocol 2405 Concepts, for a detailed description of this data element. Also 2406 required is one or more TNRType objects. Any limitation on the 2407 maximum number of TNRs that may be passed into a call to the 2408 operation is a policy decision and is not limited by the protocol. 2410 The TNRType object structure is declared as follows: 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2423 TNRType is comprised of the following data elements: 2425 o oId: Exactly one object ID that provides the identity of the 2426 object. 2428 o Eid: Exactly one enterprise ID that uniquely identifies the 2429 operational entity within the call routing community that is 2430 responsible for or "owns" this object. 2432 o TNRStrt: A required element that represents either the telephone 2433 number being added or the first telephone number in a continuous 2434 range of telephone numbers being added. 2436 o TNREnd: An optional element that represents the last telephone 2437 number in a continuous range of telephone numbers being added. 2438 The ESPP Server MUST validate that the range is a valid range of 2439 continuous numbers (e.g., that the tnREnd is greater than the 2440 tnRStrt). If not, then the ESPP Server MUST return the 2441 appropriate error code to the ESPP Client. 2443 o dgId: Exactly one object ID that identifies the Destination 2444 Group this TN Range object instance resides within. The 2445 Destination Group's relationship to one or more Routes can then 2446 define the telephone numbers' peering points. The ESPP Server 2447 MUST reject, with the appropriate error response code, an 2448 attempt to create a TNR object containing a Destination Group ID 2449 that does not exist within the appropriate context of the 2450 addressing server. 2452 o Ext: Point of extensibility described in Section 4.4.1.9 of this 2453 document. 2455 Table 13 defines the result codes and messages that the addTNRs 2456 operation SHOULD return 2457 +--------+----------------------------------------------------------+ 2458 | Result | Text | 2459 | Code | | 2460 +--------+----------------------------------------------------------+ 2461 | 1000 | Request Succeeded. | 2462 | | | 2463 | 2001 | Request syntax invalid. | 2464 | | | 2465 | 2002 | Request too large. | 2466 | | | 2467 | 2003 | Version not supported. | 2468 | | | 2469 | 2301 | System temporarily unavailable. | 2470 | | | 2471 | 2103 | Transaction ID out of sequence: [transaction ID | 2472 | | received]:[ transaction ID expected]. | 2473 | | | 2474 | 2104 | Attribute value invalid: [attribute name]:[attribute | 2475 | | value]:[objectType-objectId]. | 2476 | | | 2477 | 2105 | Object does not exist: [attribute name]:[ | 2478 | | objectType-objectId]. | 2479 | | | 2480 | 2106 | Object status or ownership does not allow for request: | 2481 | | [request name]:[ attributeName]:[objectType-objectId]. | 2482 +--------+----------------------------------------------------------+ 2484 Table 13: addTNRs Operation Result Codes and Messages 2486 4.4.2.7. Operation Name: addNAPTRs 2488 As described in the introductory sections, a NAPTR object represents 2489 a peering point for routing and/or other data. NAPTRs are associated 2490 to Routes and TNs. The addNAPTRs operation creates or overwrites one 2491 or more NAPTR objects in the addressing server. If a NAPTR object 2492 with the same object ID does not exist within the context of the 2493 addressing server, then the ESPP Server MUST create the NAPTR object. 2494 If a NAPTR object with the same object ID does exist within the 2495 context of the addressing server, then the ESPP Server MUST replace 2496 the current properties of that NAPTR with the properties passed into 2497 the addNAPTRs operation. If a NAPTR with the given ID does exist, 2498 but was created by a client other than the one calling the addNAPTRs 2499 operation then the ESPP Server SHOULD reject the request with the 2500 appropriate error code, 2106. 2502 In keeping with the Document Literal Wrapped design approach 2503 described in the introductory sections, the WSDL declaration of the 2504 operation is as follows: 2506 2507 2508 2509 2511 2512 2513 2515 2516 2517 2519 Inputs to the operation are wrapped in the addNAPTRsRqst object, 2520 which is declared as follows: 2522 2523 2524 2525 2526 2527 2528 2529 2531 As with all update operations, the basicRqst data element is a 2532 required input. Refer to the Section 4.4.1 General Protocol Concepts 2533 for a detailed description of this data element. Also required is 2534 one or more NAPTRType objects. Any limitation on the maximum number 2535 of NAPTRs that may be passed into a call to the addNAPTRs operation 2536 is a policy decision and is not limited by the protocol. 2538 A NAPTR object is declared as follows: 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2553 2555 The NAPTRType object is comprised of the data elements that are 2556 necessary for a NAPTR that represents a peering port within the 2557 Route. Each data element is described as follows: 2559 o oId: Exactly one object ID to uniquely identify the object 2560 instance. This identifier is also an input to the delNAPTRs, 2561 getNAPTRs, and addRtes operations to identify a given NAPTR. 2563 o Eid: Exactly one enterprise ID that uniquely identifies the 2564 operational entity within the call routing community that is 2565 responsible for or "owns" this object. 2567 o Order: Relative order value in an ENUM NAPTR. 2569 o Pref: Relative preference value in an ENUM NAPTR. 2571 o Svcs: ENUM service(s) that are served by the SBE. This field's 2572 value must be of the form specified in RFC 3761 (e.g., E2U+ 2573 pstn:sip+sip). The allowable values are a matter of policy and 2574 not limited by this protocol. 2576 o Regex: NAPTR's regular expression field. If this is not 2577 included then the Repl field must be included. 2579 o Repl: NAPTR replacement field, should only be provided if the 2580 Regex field is not provided, otherwise it will be ignored by the 2581 addressing server. 2583 o Ext: Point of extensibility described in Section 4.4.1.9 of this 2584 document. 2586 Table 14 defines the result codes and messages that the addNAPTRs 2587 operation SHOULD return. 2589 +--------+----------------------------------------------------------+ 2590 | Result | Text | 2591 | Code | | 2592 +--------+----------------------------------------------------------+ 2593 | 1000 | Request Succeeded. | 2594 | | | 2595 | 2001 | Request syntax invalid. | 2596 | | | 2597 | 2002 | Request too large. | 2598 | | | 2599 | 2003 | Version not supported. | 2600 | | | 2601 | 2301 | System temporarily unavailable. | 2602 | | | 2603 | 2103 | Transaction ID out of sequence: [transaction ID | 2604 | | received]:[ transaction ID expected]. | 2605 | | | 2606 | 2104 | Attribute value invalid: [attribute name]:[attribute | 2607 | | value]:[objectType-objectId]. | 2608 | | | 2609 | 2106 | Object status or ownership does not allow for request: | 2610 | | [request name]:[ attributeName]:[objectType-objectId]. | 2611 +--------+----------------------------------------------------------+ 2613 Table 14: addNAPTRs Operation Result Codes and Messages 2615 4.4.2.8. Operation Name: addEgrRtes 2617 As described in the introductory sections, an Egress Route houses a 2618 rule that can be used for re-writing (modifying) the regular 2619 expressions housed in the NAPTRs associated with a Route object. The 2620 addEgrRtes operation creates or overwrites one or more Egress Route 2621 objects in the addressing server. If an Egress Route object with the 2622 same object ID does not exist within the context of the addressing 2623 server, then the ESPP Server MUST create the Egress route object. If 2624 an Egress Route object with the same object ID does exist within the 2625 context of the addressing server, then the ESPP Server MUST replace 2626 the current properties of that Egress Route with the properties 2627 passed into the addEgrRtes operation. If an Egress Routes with the 2628 given ID does exist, but was created by a client other than the one 2629 calling the addEgrRtes operation then the ESPP Server SHOULD reject 2630 the request with the appropriate error code, 2106. 2632 In keeping with the Document Literal Wrapped design approach 2633 described in the introductory sections, the WSDL declaration of the 2634 operation is as follows: 2636 2637 2638 2639 2641 2642 2643 2645 2646 2647 2649 Inputs to the operation are wrapped in the addEgrRtesRqst object, 2650 which is declared as follows: 2652 2653 2654 2655 2656 2658 2659 2660 2662 As with all update operations, the basicRqst data element is a 2663 required input. Refer to the Section 4.4.1 General Protocol Concepts 2664 for a detailed description of this data element. Also required is 2665 one or more EgrRteType objects. Any limitation on the maximum number 2666 of Egress Routes that may be passed into a call to the addEgrRtes 2667 operation is a policy decision and is not limited by the protocol. 2669 An Egress Route object is declared as follows: 2671 2672 2673 2674 2675 2677 2678 2679 2680 2682 2683 2685 The EgrRteType object is comprised of the data elements that are 2686 necessary to for a an Egress Route. Each data element is described 2687 as follows: 2689 o oId: Exactly one object ID to uniquely identify the object 2690 instance. This identifier is also an input to the delEgrRtes 2691 and getEgrRtes operations to identify a given Egress Route. 2693 o Eid: Exactly one enterprise ID that uniquely identifies the 2694 operational entity within the call routing community that is 2695 responsible for or "own" this object. 2697 o Order: Relative order value in an ENUM NAPTR. 2699 o RteId: Zero or more Routes to which this Egress Route applies. 2700 The ESPP Server MUST reject, with the appropriate error response 2701 code, an attempt to create an Egress Route object containing a 2702 Route ID that does not exist within the appropriate context of 2703 the addressing server. 2705 o Pref: Relative preference value of the Egress Route with respect 2706 to other Egress Routes associated with the same Route object. 2708 o Svcs: ENUM service(s) to which this Egress Route's 2709 regxRewriteRule should be applied. This field's value must be 2710 of the form specified in RFC 3761 (e.g., E2U+pstn:sip+sip). 2712 o RegexRewriteRule: A regular expression that is applied to the 2713 Regx field of a NAPTR. 2715 o Ext: Point of extensibility described in Section 4.4.1.9 of this 2716 document. 2718 Table 15 defines the result codes and messages that the addEgrRtes 2719 operation SHOULD return. 2721 +--------+----------------------------------------------------------+ 2722 | Result | Text | 2723 | Code | | 2724 +--------+----------------------------------------------------------+ 2725 | 1000 | Request Succeeded. | 2726 | | | 2727 | 2001 | Request syntax invalid. | 2728 | | | 2729 | 2002 | Request too large. | 2730 | | | 2731 | 2003 | Version not supported. | 2732 | | | 2733 | 2301 | System temporarily unavailable. | 2734 | | | 2735 | 2103 | Transaction ID out of sequence: [transaction ID | 2736 | | received]:[ transaction ID expected]. | 2737 | | | 2738 | 2104 | Attribute value invalid: [attribute name]:[attribute | 2739 | | value]:[objectType-objectId]. | 2740 | | | 2741 | 2105 | Object does not exist: [attribute name]:[ | 2742 | | objectType-objectId]. | 2743 | | | 2744 | 2106 | Object status or ownership does not allow for request: | 2745 | | [request name]:[ attributeName]:[objectType-objectId]. | 2746 +--------+----------------------------------------------------------+ 2748 Table 15: addEgrRtes Operation Result Codes and Messages 2750 4.4.2.9. Delete Operations 2752 This sub-section defines the delete operations (i.e. delRtes, 2753 delDestGroups, delPubIds, delPvtIds, delTNRs, delRNs, delNAPTRs, 2754 delEgrRtes). All delete operations are of the same design and the 2755 delRtes operation is used here for illustration. The delete 2756 operations delete one or more existing objects from the addressing 2757 server. If an object of the indicated type with the given ID exists, 2758 then the operation must delete that object. If such an object does 2759 not exist, then the ESPP Server MUST return the appropriate error 2760 response code. If an object with the given ID does exist, but was 2761 created by a client other than the one calling the delete operation 2762 then the ESPP Server SHOULD reject the request with the appropriate 2763 error code, 2106. The delete operations delete one or more existing 2764 objects from an addressing server. If all the indicated objects, 2765 with the given ID(s) exist, then the ESPP Server MUST delete those 2766 objects and return a response code of 1000. If one or more of the 2767 objects do not exist then the ESPP Server MUST return a response code 2768 of 1001, i.e., the ESPP Server will not regard this as an error 2769 condition. If the ESPP server returns a response code of 1001 the 2770 ESPP server SHOULD log the objectIDs of non-existent objects that 2771 were requested to be deleted and the ESPP Client that requested the 2772 deletion. If one or more of the objects with the given IDs does 2773 exist but was created by a client other than the one calling the 2774 delete operation then the ESPP Server SHOULD reject the request with 2775 an error code of 2106. 2777 In keeping with the Document Literal Wrapped design approach 2778 described in the introductory sections, the WSDL declaration of the 2779 operation is as: 2781 2782 2783 2784 2786 2787 2788 2790 Inputs to the operation are wrapped in the delRtesRqst object, which 2791 is declared as follows: 2793 2794 2795 2796 2798 2800 2801 2802 2804 As with all update operations, the basicRqst data element is a 2805 required input. Refer to the Section 4.4.1 General Protocol Concepts 2806 for a detailed description of this data element. Also required is 2807 one or more object IDs that identify the objects that the addressing 2808 server is to delete. Any limitation on the maximum number object IDs 2809 that may be passed into this operation is a policy decision and not 2810 limited by the protocol. It is the responsibility of the ESPP Server 2811 to maintain referential integrity when an object is deleted. The 2812 following rules apply to the delete operations: 2814 It is the responsibility of the ESPP Server to maintain referential 2815 integrity when an object is deleted. The following rules apply to 2816 the delete operations: 2818 o With the exception of cascading Destination Group deletions 2819 described below, an ESPP Server SHOULD NOT allow an object created 2820 by a client having a given client ID to be deleted by a client 2821 having a different client ID. 2823 o The ESPP Server MUST delete all RNs and TNRanges within a 2824 Destination Group that is being deleted, even if those RNs or 2825 TNRanges were created by another ESPP client ID. The ESPP Server 2826 MUST delete all Public Identity instances within a Destination 2827 Group, but only if a Public Identity instance is not directly 2828 associated with one or more NAPTR objects. As with RNs and 2829 TNRanges, Destination Groups and Public Identities MUST be deleted 2830 even if they were created by another ESPP client ID. 2832 o When an object is deleted within an ESPP Server, the ESPP Server 2833 must automatically remove any references to that object that may 2834 exist within objects created by any client IDs within that ESPP 2835 Server. For example, if a Route object "ABC" that was created by 2836 Client ID "123" is referred to by Egress Route "GHI" that was 2837 created by client ID "678", then when Route "ABC" is deleted by 2838 client "123" the ESPP Server MUST also automatically remove the 2839 reference to Route "ABC" from Egress Route "GHI", or any other 2840 Egress Routes. This rule applies to the relationships between 2841 Routes and Destination Groups, Egress Routes and Routes, Routes 2842 and NAPTRs, Public Identities and Private Identities, and Public 2843 Identities and NAPTRs. 2845 Table 16 defines the result codes and messages that these delete 2846 operations SHOULD return. 2848 +--------+----------------------------------------------------------+ 2849 | Result | Text | 2850 | Code | | 2851 +--------+----------------------------------------------------------+ 2852 | 1000 | Request Succeeded. | 2853 | | | 2854 | 1001 | Request Succeeded. Deleted object(s) did not exist. | 2855 | | | 2856 | 2001 | Request syntax invalid. | 2857 | | | 2858 | 2002 | Request too large. | 2859 | | | 2860 | 2003 | Version not supported. | 2861 | | | 2862 | 2301 | System temporarily unavailable. | 2863 | | | 2864 | 2103 | Transaction ID out of sequence: [transaction ID | 2865 | | received]:[ transaction ID expected]. | 2866 | | | 2867 | 2104 | Attribute value invalid: [attribute name]:[attribute | 2868 | | value]:[objectType-objectId]. | 2869 | | | 2870 | 2105 | Object does not exist: [attribute name]:[ | 2871 | | objectType-objectId]. | 2872 | | | 2873 | 2106 | Object status or ownership does not allow for request: | 2874 | | [request name]:[ attributeName]:[objectType-objectId]. | 2875 +--------+----------------------------------------------------------+ 2877 Table 16: delRtes, delDestGroups, delPubIds, delPvtIds, delTNRs, 2878 delRNs, delNAPTRs, delEgrRtes Operation Result Codes and Messages 2880 4.4.2.10. Get Operations 2882 This sub-section defines the get, or query, operations (i.e. getRtes, 2883 getDestGroups, getPubIds, getPvtIds, getTNRs, getRNs, getNAPTRs, 2884 getEgrRtes). All get operations are of the same design and the 2885 getRtes operation is used here for illustration. If an object of the 2886 indicated type with the given ID exists, then the ESPP Server MUST 2887 return that object. If such an object does not exist, the ESPP 2888 Server MUST NOT return an object. An empty result set MUST NOT 2889 result in an error code response. 2891 In keeping with the Document Literal Wrapped design approach 2892 described in the introductory sections, the WSDL declaration of the 2893 getRtes operation is as follows: 2895 2896 2897 2898 2900 2901 2902 2904 2905 2906 2908 Inputs to the operation are wrapped in the getRtesRqst object, which 2909 is declared as follows: 2911 2912 2913 2914 2916 2918 2920 2921 2922 2924 2925 2926 2927 2928 2930 2931 2933 The required input is one BasicQueryType object and one or more 2934 object IDs that the addressing server is to return and/or one or more 2935 enterprise IDs for which the addressing server should return all 2936 objects of the given type. The list of object IDs and enterprise IDs 2937 MUST be considered "or" criteria, find objects of the given type that 2938 have these object IDs or that belong to the given enterprise IDs. 2939 Stated another way, the addressing server is to return the objects 2940 that have any of the given object IDs and return the objects that 2941 have any of the given enterprise IDs. Any limitation on the maximum 2942 number of objects that may be passed into or returned by this 2943 operation is a policy decision and not limited by the protocol. 2944 Notice that the get operations are the only operations that do not 2945 accept a BasicRqstType object as input. Rather, a BasicQueryType 2946 object is required. This results from the fact that passing a 2947 transaction ID into a get operation is not necessary and would be 2948 inefficient. The BasicQueryType object only contains the mandatory 2949 version identifier and the optional extensibility element. 2951 Results of the operation are wrapped in the getRtesRspns object, 2952 which is declared as follows: 2954 2955 2956 2957 2959 2961 2962 2963 2965 The response includes the standard BasicRspnsType object and zero or 2966 more RteType objects, one for each object ID that matches a Route in 2967 the addressing server. 2969 Table 17 defines the result codes and messages that these get 2970 operations SHOULD return. 2972 +--------+----------------------------------------------------------+ 2973 | Result | Text | 2974 | Code | | 2975 +--------+----------------------------------------------------------+ 2976 | 1000 | Request Succeeded. | 2977 | | | 2978 | 2001 | Request syntax invalid. | 2979 | | | 2980 | 2002 | Request too large. | 2981 | | | 2982 | 2003 | Version not supported. | 2983 | | | 2984 | 2301 | System temporarily unavailable. | 2985 | | | 2986 | 2104 | Attribute value invalid: [attribute name]:[attribute | 2987 | | value]:[objectType-objectId]. | 2988 +--------+----------------------------------------------------------+ 2990 Table 17: getRtes, getDestGroups, getPubIds, getPvtIds, getTNRs, 2991 getRNs, getNAPTRs, getEgrRtes Operation Result Codes and Messages 2993 4.4.2.11. Operation Name: addEntr 2995 Prior to attempting to add an object under a given an enterprise ID 2996 to an ESPP Server, the ESPP Client MUST create that enterprise ID in 2997 that ESPP Server using the addEntr operation. 2999 The addEntr operation creates an enterprise ID in the addressing 3000 server. If an enterprise ID value of an addEntr operation does not 3001 exist, the ESPP Server MUST create the enterprise ID. If an 3002 enterprise ID value of an addEntr operation already exists, the ESPP 3003 Server MUST return a success response. 3005 In keeping with the Document Literal Wrapped design approach 3006 described in the introductory sections, the WSDL declaration of the 3007 operation is as follows: 3009 3010 3011 3012 3014 3015 3016 3017 Inputs to the operation are wrapped in the addEntrRqst object, which 3018 is declared as follows: 3020 3021 3022 3023 3025 3026 3027 3028 3030 As with all update operations, the basicRqst data element is a 3031 required input. Refer to Section 4.4.1, for a detailed description 3032 of this data element. Also required is one enterprise ID. 3034 Table 18 defines the result codes and messages that the addEntr 3035 operation SHOULD return. 3037 +--------+----------------------------------------------------------+ 3038 | Result | Text | 3039 | Code | | 3040 +--------+----------------------------------------------------------+ 3041 | 1000 | Request Succeeded. | 3042 | | | 3043 | 2001 | Request syntax invalid. | 3044 | | | 3045 | 2002 | Request too large. | 3046 | | | 3047 | 2003 | Version not supported. | 3048 | | | 3049 | 2301 | System temporarily unavailable. | 3050 | | | 3051 | 2103 | Transaction ID out of sequence: [transaction ID | 3052 | | received]:[ transaction ID expected]. | 3053 | | | 3054 | 2104 | Attribute value invalid: [attribute name]:[attribute | 3055 | | value]:[objectType-objectId]. | 3056 +--------+----------------------------------------------------------+ 3058 Table 18: addEntr Operation Result Codes and Messages 3060 4.4.2.12. Operation Name: modEntr 3062 Modification of an enterprise ID by one ESPP Client must not impact 3063 objects created by another ESPP Client. In other words only objects 3064 created by the client modifying the enterprise ID MUST be moved to 3065 the new enterprise ID as part of processing the modEntr operation. 3066 Any objects created by a different ESPP Client must remain in their 3067 existing enterprise ID. 3069 The modEntr operation modifies an existing enterprise ID in the 3070 addressing server. If the "old" enterprise ID being modified does 3071 exist then the ESPP Server MUST replace the current enterprise ID 3072 with the "new" enterprise ID. If the "old" enterprise ID does not 3073 exist then the ESPP Server MUST return the appropriate error code. 3075 In keeping with the Document Literal Wrapped design approach 3076 described in the introductory sections, the WSDL declaration of the 3077 operation is as follows: 3079 3080 3081 3082 3084 3085 3086 3088 Inputs to the operation are wrapped in the modEntrRqst object, which 3089 is declared as follows: 3091 3092 3093 3094 3096 3097 3098 3099 3100 3101 As with all update operations, the basicRqst data element is a 3102 required input. Refer to Section 4.4.1, for a detailed description 3103 of this data element. Also required is one "new" enterprise ID and 3104 one "old" enterprise ID. 3106 Table 19 defines the result codes and messages that the modEntr 3107 operation SHOULD return. 3109 +--------+----------------------------------------------------------+ 3110 | Result | Text | 3111 | Code | | 3112 +--------+----------------------------------------------------------+ 3113 | 1000 | Request Succeeded. | 3114 | | | 3115 | 2001 | Request syntax invalid. | 3116 | | | 3117 | 2002 | Request too large. | 3118 | | | 3119 | 2003 | Version not supported. | 3120 | | | 3121 | 2301 | System temporarily unavailable. | 3122 | | | 3123 | 2103 | Transaction ID out of sequence: [transaction ID | 3124 | | received]:[ transaction ID expected]. | 3125 | | | 3126 | 2104 | Attribute value invalid: [attribute name]:[attribute | 3127 | | value]:[objectType-objectId]. | 3128 +--------+----------------------------------------------------------+ 3130 Table 19: modEntr Operation Result Codes and Messages 3132 4.4.2.13. Operation Name: delEntr 3134 The delEntr operation deletes the enterprise ID and all objects from 3135 an addressing server that have the given enterprise ID and that were 3136 created by the client that is deleting the enterprise ID. If the 3137 enterprise ID does not exist in the addressing server, then the ESPP 3138 Server MUST return the response code 1001, i.e., the ESPP Server will 3139 not regard this as an error condition. If the ESPP server returns a 3140 response code of 1001 the ESPP server SHOULD log the non-existent 3141 enterpriseID and the ESPP Client that requested the deletion. If the 3142 enterprise ID did exist and the operation was successful then the 3143 ESPP Server MUST return the response code 1000. 3145 Deletion of an enterprise ID by one ESPP Client MUST NOT impact 3146 objects created by another ESPP Client. In other words only objects 3147 created by the client deleting the enterprise ID MUST be deleted. 3148 Any objects created by a different ESPP Client MUST NOT be deleted 3149 and MUST remain in their existing enterprise ID. 3151 In keeping with the Document Literal Wrapped design approach 3152 described in the introductory sections, the WSDL declaration of the 3153 operation is as follows: 3155 3156 3157 3158 3160 3161 3162 3164 Inputs to the operation are wrapped in the delEntrRqst object, which 3165 is declared as follows: 3167 3168 3169 3170 3172 3173 3174 3175 3177 As with all update operations, the basicRqst data element is a 3178 required input. Refer to Section 4.4.1, for a detailed description 3179 of this data element. Also required is one enterprise ID. 3181 Table 20 defines the result codes and messages that the delEntr 3182 operation SHOULD return. 3184 +--------+----------------------------------------------------------+ 3185 | Result | Text | 3186 | Code | | 3187 +--------+----------------------------------------------------------+ 3188 | 1000 | Request Succeeded. | 3189 | | | 3190 | 1001 | Request Succeeded. Deleted object(s) did not exist. | 3191 | | | 3192 | 2001 | Request syntax invalid. | 3193 | | | 3194 | 2002 | Request too large. | 3195 | | | 3196 | 2003 | Version not supported. | 3197 | | | 3198 | 2301 | System temporarily unavailable. | 3199 | | | 3200 | 2103 | Transaction ID out of sequence: [transaction ID | 3201 | | received]:[ transaction ID expected]. | 3202 | | | 3203 | 2104 | Attribute value invalid: [attribute name]:[attribute | 3204 | | value]:[objectType-objectId]. | 3205 +--------+----------------------------------------------------------+ 3207 Table 20: delEntr Operation Result Codes and Messages 3209 4.4.2.14. Operation Name: batchUpdate 3211 The batchUpdate operation is a single operation, with a single 3212 transaction ID that may contain one or more of update actions. This 3213 approach can significantly speed processing time under some 3214 circumstances by effectively allowing multiple operations to be 3215 transmitted and performed under a single transaction ID, and a single 3216 connection. 3218 In keeping with the Document Literal Wrapped design approach 3219 described in the introductory sections, the WSDL declaration of the 3220 operation is as follows: 3222 3223 3224 3225 3227 3228 3229 3231 3232 3233 3235 Inputs to the operation are wrapped in the batchUpdateRqst object, 3236 which is declared as follows: 3238 3239 3240 3241 3243 3245 3246 3247 3249 3250 3251 3253 3254 3256 3257 3258 3260 3262 3264 3266 3269 3271 3273 3275 3277 3279 3281 3283 3285 3287 3289 3291 3293 3295 3297 3298 3299 3301 3303 3304 3305 3306 3307 3309 The BatchUpdateType object can contain one or more BatchOpType 3310 objects. The structure is nested here to allow multiple 3311 BatchUpdateType objects to be included in any order that is 3312 appropriate to achieve the desired end goal of the batch operation. 3313 More specifically, this structure works around the strict ordering 3314 rules imposed on the XSD "sequence" data structure, allowing adds and 3315 dels to occur in any order. The ESPP Server MUST process the sub- 3316 elements of the batchUpdate and the op elements in the order in which 3317 they appear in the batchUpdateRqst element. 3319 The ESPP Server MUST return the appropriate response code when the 3320 operation is successfully completed, i.e., 1000 or 1001. If one or 3321 more of the objects do not exist then the ESPP Server MUST return a 3322 response code of 1001, i.e., the ESPP Server will not regard this as 3323 an error condition. If the ESPP server returns a response code of 3324 1001 the ESPP server SHOULD log the objectIDs of non-existent objects 3325 that were requested to be deleted and the ESPP Client that requested 3326 the deletion. 3328 Upon encountering the first error condition, the ESPP Server MUST 3329 stop processing and return the appropriate error response code, 3330 rolling back any changes that may have been made for the current 3331 request. 3333 As with all update operations, the basicRqst data element is a 3334 required input. Refer to Section 4.4.1, for a detailed description 3335 of this data element. Each of the remaining elements are simply zero 3336 or more instances of the top level data structures that are wrapped 3337 in each of the other update operations described in previous 3338 sections. 3340 Table 21 defines the result codes and messages that the batchUpdate 3341 operation SHOULD return. 3343 +--------+----------------------------------------------------------+ 3344 | Result | Text | 3345 | Code | | 3346 +--------+----------------------------------------------------------+ 3347 | 1000 | Request Succeeded. | 3348 | | | 3349 | 1001 | Request Succeeded. Deleted object(s) did not exist. | 3350 | | | 3351 | 2001 | Request syntax invalid. | 3352 | | | 3353 | 2002 | Request too large. | 3354 | | | 3355 | 2003 | Version not supported. | 3356 | | | 3357 | 2301 | System temporarily unavailable. | 3358 | | | 3359 | 2103 | Transaction ID out of sequence: [transaction ID | 3360 | | received]:[ transaction ID expected]. | 3361 | | | 3362 | 2104 | Attribute value invalid: [attribute name]:[attribute | 3363 | | value]:[objectType-objectId]. | 3364 | | | 3365 | 2105 | Object does not exist: [attribute name]:[ | 3366 | | objectType-objectId]. | 3367 | | | 3368 | 2106 | Object status or ownership does not allow for request: | 3369 | | [request name]:[ attributeName]:[objectType-objectId]. | 3370 +--------+----------------------------------------------------------+ 3372 Table 21: batchUpdate Operation Result Codes and Messages 3374 4.4.2.15. Operation Name: getSvcMenu 3376 The getSvcMenu operation returns a list of operations supported by 3377 the ESPP Server and the protocol versions supported by the ESPP 3378 Server. The list of operations is comprised of a list or URNs, one 3379 for each supported operation. This feature can be used by ESPP 3380 Clients to dynamically discover which operations and versions are 3381 supported by the ESPP Servers. 3383 In keeping with the Document Literal Wrapped design approach 3384 described in the introductory sections, the WSDL declaration of the 3385 operation is as follows: 3387 3388 3389 3390 3392 3393 3394 3396 3397 3398 3400 Inputs to the operation are wrapped in the getSvcMenuRqst object, 3401 which is declared as follows: 3403 3404 3405 3406 3408 3409 3410 3412 The required input is one BasicQueryType and the results of the 3413 operation are wrapped in the getRtesRspns object, which is declared 3414 as follows: 3416 3417 3418 3419 3421 3423 3424 3425 3427 3428 3429 3431 3433 3435 3436 3438 The response includes the standard BasicRspnsType object and one 3439 SvcMenyType objects. The SvcMenuType contains the following 3440 elements: 3442 o MajMinVersion: One or more version identifiers in dotted notation, 3443 where each version identifier represents a fully qualified version 3444 identifier that is supported by the ESPP Server. 3446 o ObjUri: One or more URI(s) where each URI identifies one ESPP 3447 operation that is supported by the ESPP Server. URIs take the 3448 following form: urn:example.com:TBD-api-1.0:est:addRtesRqst 3450 o ExtUri: One or more URI(s) where each URI identifies an operation 3451 that is not part of the formal ESPP specification but is supported 3452 by the ESPP Server. This may arise where an ESPP Server has added 3453 non-standard operations to its ESPP implementation. 3455 Table 22 defines the result codes and messages that the getSvcMenu 3456 operation SHOULD return. 3458 +--------+----------------------------------------------------------+ 3459 | Result | Text | 3460 | Code | | 3461 +--------+----------------------------------------------------------+ 3462 | 1000 | Request Succeeded. | 3463 | | | 3464 | 2001 | Request syntax invalid. | 3465 | | | 3466 | 2301 | System temporarily unavailable. | 3467 | | | 3468 | 2104 | Attribute value invalid: [attribute name]:[attribute | 3469 | | value]:[objectType-objectId]. | 3470 +--------+----------------------------------------------------------+ 3472 Table 22: getSvcMenu Operation Result Codes and Messages 3474 5. File-based ESPP provisioning protocol 3476 To further support the high data distribution requirements of the 3477 target reference architecture, the ESPP specification defines a file 3478 based operational scheme. Some aspects of this scheme are policy 3479 driven and are, therefore, outside the scope of this document. The 3480 file-based provisioning protocol requirements defined in this section 3481 MUST be supported by an ESPP Client and an ESPP Server to claim 3482 compliance with this specification. They must be used in the 3483 following manner to support file base data distribution. 3485 5.1. Overview of the File-based Provisioning Operations 3487 Under certain circumstances, such as bootstrapping a new ENUM-SIP 3488 addressing server with its initial data set, or establishing a new 3489 session peering relationship between two peers, it may be advisable 3490 to distribute peering data in the form of a file. To accomplish 3491 this, the ESPP Client MUST have the ability to, on command, generate 3492 a set of files containing all the session establishment data residing 3493 within the ESPP Client view for a given session peering partner. 3494 Similarly, the ESPP Server MUST support the ability to read, parse, 3495 and load the content of that file into the appropriate context of the 3496 ENUM-SIP addressing server. The process of retrieving that file from 3497 the ESPP Client (acting as a file server) and then delivering the 3498 file to the proper location on the ENUM-SIP addressing server is a 3499 matter of policy and procedure and it is not specified in this 3500 document. The process of suspending real-time provisioning 3501 operations (non-file-based) during this file-based provisioning 3502 process is also a matter of policy and procedure. 3504 5.2. File Structure 3506 An ESPP compliant distribution file MUST be comprised of exactly one 3507 batchUpdateFileRqst element which contains one 3508 BatchUpdateFilePropsType object and one or more BatchUpdateType 3509 objects, which is described in a previous section of this document. 3510 This approach is taken to simplify the implementation effort for this 3511 feature as the ESPP Client and the ESPP Server have the ability to 3512 process the data structures that comprise the batchUpdateFileRqst. 3513 To ensure data consistency, the ESPP Client must generate batch files 3514 using the same transaction identifier sequence as the real time 3515 protocol. It is therefore necessary to disable real-time propagation 3516 while the file-based provisioning process is active. 3518 3519 3520 3521 3522 3524 3526 3527 3528 3530 The BatchUpdateFilePropsType is the file header that specifies some 3531 basic information about where and when the batch update file(s) were 3532 generated. A given batch update may span multiple files, with the 3533 BatchUpdateFilePropsType object in each file. 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3546 o clientId - The integer that identifies the ESPP Client that 3547 generated the batch file(s). 3549 o serverId - A string that identifies the ESPP Server for which 3550 the batch file(s) were generated. 3552 o isFullResync - Indicates if this sequence of files is a full 3553 refresh of all the data that should reside within an addressing 3554 server. If not, then the file sequence represents an 3555 incremental update. The addressing server MUST properly apply 3556 the data based on the value of this attribute. This may entail 3557 dropping the current data in the addressing server. 3559 o creationTimestamp - The creation timestamp for the batch load 3560 file sequence MUST follow the format defined by the dateTime 3561 datatype of XML Schema Part 2 and MUST contain the time zone 3562 information. For example, a valid format can be represented as 3563 YYYY-MM-DDTHH:MM:SS('+'|'-')hh':'mm). 3565 o sequenceNumber - The sequence number for this batch file within 3566 the batch update. An ESPP Client may generate multiple batch 3567 files that, as a set, represent the entire batch update. The 3568 sequenceNumber is a sequential number, starting with 1 and 3569 incremented by 1 for each subsequent file. 3571 o isEndOfSequence - A boolean value indicating whether or not this 3572 is that last file in the sequence of files that comprise the 3573 batch update. 3575 The ESPP Server SHOULD log error codes that correspond to the codes 3576 used in the real time protocol as defined in Section 4.4.1.8. 3578 6. Response Codes and Messages 3580 This section contains the consolidated listing of the response codes 3581 and their corresponding messages. 3583 The response code numbering scheme generally adheres to the theory 3584 formalized in section 4.2.1 of [RFC2821]: 3586 o The first digit of the response code can only be 1 or 2: 1 = a 3587 positive result, 2 = a negative result. 3589 o The second digit of the response code indicates the category: 0 3590 = Protocol Syntax, 1 = Implementation Specific Business Rule, 2 3591 = Security, 3 = Server System. 3593 o The third and fourth digits of the response code indicate the 3594 individual message event within the category defines by the 3595 first two digits. 3597 +--------+----------------------------------------------------------+ 3598 | Result | Text | 3599 | Code | | 3600 +--------+----------------------------------------------------------+ 3601 | 1000 | Request Succeeded. | 3602 | | | 3603 | 1001 | Request Succeeded. Deleted object(s) did not exist. | 3604 | | | 3605 | 2001 | Request syntax invalid. | 3606 | | | 3607 | 2002 | Request too large. | 3608 | | | 3609 | 2003 | Version not supported. | 3610 | | | 3611 | | | 3612 | | | 3613 | 2301 | System temporarily unavailable. | 3614 | | | 3615 | 2103 | Transaction ID out of sequence: [transaction ID | 3616 | | received]:[ transaction ID expected]. | 3617 | | | 3618 | 2104 | Attribute value invalid: [attribute name]:[attribute | 3619 | | value]:[objectType-objectId]. | 3620 | | | 3621 | 2105 | Object does not exist: [attribute name]:[ | 3622 | | objectType-objectId]. | 3623 | | | 3624 | 2106 | Object status or ownership does not allow for request: | 3625 | | [request name]:[ attributeName]:[objectType-objectId]. | 3626 | 2301 | Unexpected internal system or server error. | 3627 +--------+----------------------------------------------------------+ 3629 Table 23: Response Codes Numbering Scheme and Messages 3631 Some response messages are "parameterized" with one or more of the 3632 following parameters: "attribute name", "attribute value", 3633 "objectType-objectId", and "operation name". 3635 The use of these parameters MUST adhere to the following rules: 3637 o All parameters within a response message are mandatory and MUST 3638 be present. Parameters within a response message MUST NOT be 3639 left empty. 3641 o Any value provided for the "attribute name" parameter MUST be an 3642 exact element name of the protocol data element that the 3643 response message is referring to. For example, allowable values 3644 for "attribute name" are "tnRStrt", "rteName", etc. 3646 o Any value provided for the "request name" parameter MUST be an 3647 exact request object name that the response message is referring 3648 to. For example, an allowable value for "request object name" 3649 is "delRtesRqst". 3651 o The value for "attribute value" MUST be the value of the data 3652 element to which the preceding "attribute name" refers. 3654 o Result codes 2104 and 2105 MUST NOT be used interchangeably. 3655 Response code 2105 SHOULD be returned when the data element(s) 3656 used to uniquely identify a pre-existing object do not exist. 3657 If the data elements used to uniquely identify an object are 3658 malformed, then response code 2104 SHOULD be returned. 3660 o Result code 2104 SHOULD be used whenever an element value does 3661 not adhere to data validation rules. It MUST be used for 3662 circumstances where an optional data element was expected but 3663 not received. 3665 7. IANA Considerations 3667 Should there be interest in working on a protocol like ESPP in IETF, 3668 a formal IANA consideration section should be drafted with proper 3669 registrations for the protocol namespace(s), versions, etc. 3671 8. Formal API Definition 3673 Note that the formal API definition is currently provided as defined 3674 in the PacketCable specifications for the XML namespace and protocol 3675 versioning conventions. 3677 8.1. WSDL Specification 3679 3685 3686 3691 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3934 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4208 8.2. XSD Types Specification 4210 4211 4215 4216 4217 -------- Object Type Definitions ---------------- 4218 4219 4220 4221 4222 4223 4224 4225 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4352 4354 4356 4358 4360 4362 4364 4366 4368 4370 4372 4374 4376 4378 4380 4382 4384 4386 4387 4388 4389 4390 4391 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4412 4415 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 ----------- Wrapped Rqst Message Definitions ----- 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4453 4455 4456 4457 4458 4459 4460 4461 4462 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4481 4483 4484 4485 4486 4487 4488 4489 4490 4492 4493 4494 4495 4496 4497 4498 4499 4501 4502 4503 4504 4505 4506 4507 4508 4510 4511 4512 4513 4514 4515 4516 4517 4519 4520 4521 4522 4523 4524 4525 4526 4528 4529 4530 4531 4532 4533 4534 4535 4538 4539 4540 4541 4542 4543 4544 4545 4547 4548 4549 4550 4551 4552 4553 4554 4556 4557 4558 4559 4560 4561 4562 4563 4565 4566 4567 4568 4569 4570 4571 4572 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4625 4626 4627 4628 4629 4630 4631 4632 4633 4635 4636 4637 4638 4639 4640 4641 4643 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4662 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 ----- Wrapped Rspns Message Definitions ---------------- 4703 4704 4705 4706 4707 4708 4710 4711 4712 4713 4714 4715 4716 4717 4719 4720 4721 4722 4723 4724 4725 4726 4728 4729 4730 4731 4732 4733 4734 4735 4737 4738 4739 4740 4741 4742 4743 4744 4746 4747 4748 4749 4750 4751 4752 4753 4755 4756 4757 4758 4759 4760 4761 4762 4764 4765 4766 4767 4768 4769 4770 4771 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4791 4792 4793 4794 4795 9. Security Considerations 4797 This document specifies a new provisioning protocol. 4799 Provisioning data and other configuration information in scope of 4800 ESPP include public identities, telephone number ranges, RNs, 4801 signaling path border elements, NAPTRs and Egress Routes. This 4802 information is sensitive and its transmission in the clear and 4803 without integrity checking leaves servers exposed to eavesdropping 4804 attacks. Compliant implementations must therefore satisfy the 4805 requirements defined in Section 4.4.1.3. 4807 If the object values for the Public Identity, Route, Destination 4808 Group, RN, SBE, MAPTRs are set maliciously, it may result in sessions 4809 being misrouted and service disruption. It may also result in an 4810 over-allocation of signaling resources in an attempt to create denial 4811 of service attacks (all routes of all destination groups directed 4812 towards a particular SBE). 4814 Additional security considerations must also apply given the 4815 provisioning data exchanged within and between Trust Domains as 4816 defined in [RFC3325]. 4818 An initial set of security requirements that must be met by compliant 4819 ESPP Clients and ESPP Servers is defined in [I-D.espp-requirements]. 4821 10. Acknowledgments 4823 This document is based on the work of participants in the CableLabs 4824 PacketCable ENUM Server vendor focus team. 4826 The authors wish to thank the following participants for their 4827 contributions and comments: 4828 Jack Burton, Paul Natale, Costas Gavrilidis, Matt Cannon, Ken 4829 Cartwright, Kevin Johns, James Brister, Ted Lemon, Vivian Neou, Mark 4830 McBride, Tim Cody, Sean Leach, Gene Lew, Rich Shockey, Mark Teodoro, 4831 Robby Benedyk, Steve Dimig, , Ajay Gupta, Sean Kent, Tom Kershaw, 4832 Manjul Maharishi, Yasir Saleem, Sanjeev Chauhan, Gaurav Sharma, Vikas 4833 Sarawat, Daryl Malas, Sumanth Channabasappa, Otmar Lendl and Penn 4834 Pfautz. 4836 11. References 4838 11.1. Normative References 4840 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 4841 Requirement Levels", BCP 14, RFC 2119, March 1997. 4843 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., 4844 Leach, P., Luotonen, A., and L. Stewart, "HTTP 4845 Authentication: Basic and Digest Access Authentication", 4846 RFC 2617, June 1999. 4848 [RFC2821] Klensin, J., "Simple Mail Transfer Protocol", RFC 2821, 4849 April 2001. 4851 [RFC3761] Faltstrom, P. and M. Mealling, "The E.164 to Uniform 4852 Resource Identifiers (URI) Dynamic Delegation Discovery 4853 System (DDDS) Application (ENUM)", RFC 3761, April 2004. 4855 [SOAP] W3C, "W3C Recommendation, SOAP Version 1.1", May 2000. 4857 [WSDL] W3C, "W3C Recommendation, Web Services Description 4858 Language (WSDL) Version 1.1", March 2001. 4860 [XML] W3C, "W3C Recommendation, Extensible Markup Language (XML) 4861 1.0", August 2006. 4863 11.2. Informative References 4865 [CableLabs-ESPP] 4866 CableLabs, "PacketCable ENUM Server Provisioning 4867 Specification, PKT-SP-ENUM-PROV-I01-080215", CableLabs Spe 4868 cification http://www.cablelabs.com/specifications/ 4869 PKT-SP-ENUM-PROV-I01-080215.pdf, February 2008. 4871 [I-D.espp-requirements] 4872 Creighton, T. and J-F. Mule, "ENUM-SIP Server Provisioning 4873 Protocol (ESPP)", 4874 draft-mule-peppermint-espp-requirements-01.txt (work in 4875 progress), July 2008. 4877 [I-D.ietf-speermint-terminology] 4878 Malas, D. and D. Meyer, "SPEERMINT Terminology", 4879 draft-ietf-speermint-terminology-16 (work in progress), 4880 February 2008. 4882 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston, 4883 A., Peterson, J., Sparks, R., Handley, M., and E. 4885 Schooler, "SIP: Session Initiation Protocol", RFC 3261, 4886 June 2002. 4888 [RFC3325] Jennings, C., Peterson, J., and M. Watson, "Private 4889 Extensions to the Session Initiation Protocol (SIP) for 4890 Asserted Identity within Trusted Networks", RFC 3325, 4891 November 2002. 4893 Authors' Addresses 4895 Kenneth Cartwright 4896 VeriSign 4897 21355 Ridgetop Circle 4898 Dulles, VA 20166 4899 USA 4901 Email: kcartwright@verisign.com 4903 Stephen M. Dimig 4904 Tekelec 4905 5200 Paramount Parkway 4906 Morrisville, NC 27560 4907 USA 4909 Email: stephen.dimig@tekelec.com 4911 Mark Teodoro 4912 NeuStar 4913 46000 Center Oak Plaza 4914 Sterling, VA 20166 4915 USA 4917 Email: mark.teodoro@neustar.com 4919 Jean-Francois Mule 4920 CableLabs 4921 858 Coal Creek Circle 4922 Louisville, CO 80027 4923 USA 4925 Email: jfm@cablelabs.com 4927 Full Copyright Statement 4929 Copyright (C) The IETF Trust (2008). 4931 This document is subject to the rights, licenses and restrictions 4932 contained in BCP 78, and except as set forth therein, the authors 4933 retain all their rights. 4935 This document and the information contained herein are provided on an 4936 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 4937 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 4938 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 4939 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 4940 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 4941 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 4943 Intellectual Property 4945 The IETF takes no position regarding the validity or scope of any 4946 Intellectual Property Rights or other rights that might be claimed to 4947 pertain to the implementation or use of the technology described in 4948 this document or the extent to which any license under such rights 4949 might or might not be available; nor does it represent that it has 4950 made any independent effort to identify any such rights. Information 4951 on the procedures with respect to rights in RFC documents can be 4952 found in BCP 78 and BCP 79. 4954 Copies of IPR disclosures made to the IETF Secretariat and any 4955 assurances of licenses to be made available, or the result of an 4956 attempt made to obtain a general license or permission for the use of 4957 such proprietary rights by implementers or users of this 4958 specification can be obtained from the IETF on-line IPR repository at 4959 http://www.ietf.org/ipr. 4961 The IETF invites any interested party to bring to its attention any 4962 copyrights, patents or patent applications, or other proprietary 4963 rights that may cover technology that may be required to implement 4964 this standard. Please address the information to the IETF at 4965 ietf-ipr@ietf.org.