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.