idnits 2.17.1
draft-jennings-vipr-vap-02.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
-- The document date (March 5, 2012) is 4427 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)
** Obsolete normative reference: RFC 5389 (Obsoleted by RFC 8489)
** Obsolete normative reference: RFC 2617 (Obsoleted by RFC 7235, RFC 7615,
RFC 7616, RFC 7617)
** Downref: Normative reference to an Informational RFC: RFC 2104
** Obsolete normative reference: RFC 2616 (Obsoleted by RFC 7230, RFC 7231,
RFC 7232, RFC 7233, RFC 7234, RFC 7235)
Summary: 4 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 vipr C. Jennings
3 Internet-Draft Cisco
4 Intended status: Standards Track J. Rosenberg
5 Expires: September 6, 2012 jdrosen.net
6 M. Petit-Huguenin
7 Stonyfish
8 March 5, 2012
10 Verification Involving PSTN Reachability: The ViPR Access Protocol (VAP)
11 draft-jennings-vipr-vap-02
13 Abstract
15 Verification Involving PSTN Reachability (ViPR) is a technique for
16 inter-domain SIP federation. ViPR hybridizes the PSTN, P2P networks,
17 and SIP, and in doing so, addresses the phone number routing and VoIP
18 spam problems that have been a barrier to federation. The ViPR
19 architecture uses a server, the ViPR server, which performs P2P and
20 validation services on behalf of call agents, which acts as clients
21 to the server. Such an architecture requires a client/server
22 protocol between call agents and the ViPR server. That protocol,
23 defined here, is called the ViPR Access Protocol (VAP).
25 Legal
27 This documents and the information contained therein are provided on
28 an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
29 REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE
30 IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL
31 WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
32 WARRANTY THAT THE USE OF THE INFORMATION THEREIN WILL NOT INFRINGE
33 ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
34 FOR A PARTICULAR PURPOSE.
36 Status of this Memo
38 This Internet-Draft is submitted in full conformance with the
39 provisions of BCP 78 and BCP 79.
41 Internet-Drafts are working documents of the Internet Engineering
42 Task Force (IETF). Note that other groups may also distribute
43 working documents as Internet-Drafts. The list of current Internet-
44 Drafts is at http://datatracker.ietf.org/drafts/current/.
46 Internet-Drafts are draft documents valid for a maximum of six months
47 and may be updated, replaced, or obsoleted by other documents at any
48 time. It is inappropriate to use Internet-Drafts as reference
49 material or to cite them other than as "work in progress."
51 This Internet-Draft will expire on September 6, 2012.
53 Copyright Notice
55 Copyright (c) 2012 IETF Trust and the persons identified as the
56 document authors. All rights reserved.
58 This document is subject to BCP 78 and the IETF Trust's Legal
59 Provisions Relating to IETF Documents
60 (http://trustee.ietf.org/license-info) in effect on the date of
61 publication of this document. Please review these documents
62 carefully, as they describe your rights and restrictions with respect
63 to this document. Code Components extracted from this document must
64 include Simplified BSD License text as described in Section 4.e of
65 the Trust Legal Provisions and are provided without warranty as
66 described in the Simplified BSD License.
68 Table of Contents
70 1. Introduction to ViPR . . . . . . . . . . . . . . . . . . . . . 5
71 2. Overview of VAP . . . . . . . . . . . . . . . . . . . . . . . 5
72 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7
73 4. VAP Message Structure . . . . . . . . . . . . . . . . . . . . 8
74 5. VAP Transactions . . . . . . . . . . . . . . . . . . . . . . . 10
75 5.1. Transport and Connection Management . . . . . . . . . . . 11
76 5.2. Requestor Procedures . . . . . . . . . . . . . . . . . . . 11
77 5.2.1. Generating Requests . . . . . . . . . . . . . . . . . 12
78 5.2.2. Receiving Responses . . . . . . . . . . . . . . . . . 12
79 5.3. Responder Behaviors . . . . . . . . . . . . . . . . . . . 13
80 5.3.1. Receiving Requests . . . . . . . . . . . . . . . . . 13
81 5.3.2. Sending Responses . . . . . . . . . . . . . . . . . . 14
82 6. State Model . . . . . . . . . . . . . . . . . . . . . . . . . 14
83 7. Protocol Versioning . . . . . . . . . . . . . . . . . . . . . 17
84 8. ViPR Client Procedures . . . . . . . . . . . . . . . . . . . . 18
85 8.1. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 18
86 8.2. Registration . . . . . . . . . . . . . . . . . . . . . . . 18
87 8.3. Unregistering . . . . . . . . . . . . . . . . . . . . . . 20
88 8.4. Publishing Services . . . . . . . . . . . . . . . . . . . 20
89 8.4.1. VService . . . . . . . . . . . . . . . . . . . . . . 21
90 8.4.2. ViPR Number Service . . . . . . . . . . . . . . . . . 23
91 8.5. Updating the VService . . . . . . . . . . . . . . . . . . 24
92 8.6. Uploading VCRs . . . . . . . . . . . . . . . . . . . . . . 25
93 8.7. Subscribing to Number Service . . . . . . . . . . . . . . 25
94 8.8. Unsubscribing to Services . . . . . . . . . . . . . . . . 26
95 8.9. Receiving Notify . . . . . . . . . . . . . . . . . . . . . 27
96 8.10. Receiving PublishRevoke . . . . . . . . . . . . . . . . . 27
97 9. ViPR Server Procedures . . . . . . . . . . . . . . . . . . . . 27
98 9.1. Connection Establishment . . . . . . . . . . . . . . . . . 28
99 9.2. Registration . . . . . . . . . . . . . . . . . . . . . . . 28
100 9.3. Unregistration . . . . . . . . . . . . . . . . . . . . . . 29
101 9.4. Publication . . . . . . . . . . . . . . . . . . . . . . . 29
102 9.4.1. VService . . . . . . . . . . . . . . . . . . . . . . 29
103 9.4.2. ViPR Number Service . . . . . . . . . . . . . . . . . 31
104 9.5. Unpublish . . . . . . . . . . . . . . . . . . . . . . . . 33
105 9.6. Subscribe . . . . . . . . . . . . . . . . . . . . . . . . 33
106 9.7. Unsubscribe . . . . . . . . . . . . . . . . . . . . . . . 34
107 9.8. UploadVCR . . . . . . . . . . . . . . . . . . . . . . . . 34
108 9.8.1. Originating . . . . . . . . . . . . . . . . . . . . . 35
109 9.8.2. Terminating . . . . . . . . . . . . . . . . . . . . . 36
110 9.9. Sending Notify . . . . . . . . . . . . . . . . . . . . . . 36
111 9.10. Sending PublishRevoke . . . . . . . . . . . . . . . . . . 37
112 10. Syntax Details . . . . . . . . . . . . . . . . . . . . . . . . 37
113 10.1. XML Schema for VService . . . . . . . . . . . . . . . . . 37
114 10.2. XML Schema for ValInfo . . . . . . . . . . . . . . . . . . 39
115 10.3. VAP Attributes . . . . . . . . . . . . . . . . . . . . . . 39
116 10.3.1. USERNAME . . . . . . . . . . . . . . . . . . . . . . 40
117 10.3.2. REALM . . . . . . . . . . . . . . . . . . . . . . . . 40
118 10.3.3. MESSAGE-INTEGRITY . . . . . . . . . . . . . . . . . . 41
119 10.3.4. ERROR-CODE . . . . . . . . . . . . . . . . . . . . . 41
120 10.3.5. Client-Name . . . . . . . . . . . . . . . . . . . . . 43
121 10.3.6. Client-Handle . . . . . . . . . . . . . . . . . . . . 43
122 10.3.7. Protocol-Version . . . . . . . . . . . . . . . . . . 43
123 10.3.8. Client-Label . . . . . . . . . . . . . . . . . . . . 43
124 10.3.9. Keepalive . . . . . . . . . . . . . . . . . . . . . . 44
125 10.3.10. ServiceIdentity . . . . . . . . . . . . . . . . . . . 44
126 10.3.11. ServiceVersion . . . . . . . . . . . . . . . . . . . 44
127 10.3.12. ServiceContent . . . . . . . . . . . . . . . . . . . 44
128 10.3.13. SubscriptionID . . . . . . . . . . . . . . . . . . . 45
129 10.3.14. CallDirection . . . . . . . . . . . . . . . . . . . . 45
130 10.3.15. StartTime . . . . . . . . . . . . . . . . . . . . . . 45
131 10.3.16. StopTime Attribute . . . . . . . . . . . . . . . . . 45
132 10.3.17. CallingNum Attribute . . . . . . . . . . . . . . . . 45
133 10.3.18. CalledNum Attribute . . . . . . . . . . . . . . . . . 46
134 10.3.19. Quota Attribute . . . . . . . . . . . . . . . . . . . 46
135 10.3.20. DHTLifetime Attribute . . . . . . . . . . . . . . . . 47
136 11. Security Considerations . . . . . . . . . . . . . . . . . . . 47
137 11.1. Outsider Attacks . . . . . . . . . . . . . . . . . . . . . 47
138 11.2. Insider Attacks . . . . . . . . . . . . . . . . . . . . . 47
139 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 47
140 13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 47
141 13.1. Normative References . . . . . . . . . . . . . . . . . . . 47
142 13.2. Informative References . . . . . . . . . . . . . . . . . . 48
143 Appendix A. Release notes . . . . . . . . . . . . . . . . . . . . 48
144 A.1. Modifications between rosenberg-03 and rosenberg-02 . . . 48
145 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 49
147 1. Introduction to ViPR
149 [VIPR-OVERVIEW] introduces a new technology, called Verification
150 Involving PSTN Reachability (ViPR), which enables VoIP federation
151 between domains, over the Internet. ViPR is a hybrid technology that
152 combines together the PSTN, P2P networks, and SIP. In doing so, it
153 addresses the phone number routing problem and anti-spam problems
154 that have been the most significant barriers to widespread deployment
155 of SIP inter-domain federation.
157 It is assumed that readers of this document have read and understood
158 [VIPR-OVERVIEW].
160 One of the key protocols used in ViPR is the ViPR Access Protocol
161 (VAP). VAP connects call agents, such as phones, SBCs and IP PBXs,
162 to a ViPR server. This document defines the VAP protocol in detail.
164 2. Overview of VAP
166 A high level view on the ViPR architecture is shown in Figure 1.
167 This architecture is discussed in more detail in [VIPR-OVERVIEW].
169 +-+ +-+
170 | | | | +------+
171 | | +-----| |---|Enroll|
172 | | | | | +------+
173 |I| | |I|
174 |n| +-----+ |n|
175 VAP |t| | ViPR| |t|
176 +----------|r|---|Srvr |--|e|-----------------
177 | |a| | | |r| P2P-Validation
178 | |n| +-----+ |n|
179 | |e| |e|
180 | |t| |t|
181 +-----+ SIP | | +-----+ | |
182 | CA |-------|F|---| |--|F| ---------------
183 +-----+ |i| | | |i| SIP/TLS
184 . |r| | . | |r|
185 SIP/ . |e| | | |e|
186 MGCP/ . |w| | BE | |w|
187 TDM . |a| | | |a|
188 . |l| | | |l|
189 +-----+ |l| | | |l|
190 | UA |-------| |---| |--| |-----------------
191 +-----+ | | +-----+ | | SRTP
192 | | | |
193 +-+ +-+
194 | |
195 +--------------------+-----------------+
196 |
197 Single administrative domain
199 Figure 1: Architecture
201 A key component of this architecture is the ViPR server. The ViPR
202 server is responsible for connecting to the P2P network, publishing
203 phone numbers into that network, performing validation, and learning
204 new routes. The ViPR server performs those functions on behalf of
205 one or more call agents. This requires a protocol to run between the
206 call agents and the ViPR server. This protocol is called VAP - the
207 ViPR Access Protocol.
209 VAP is a client-server protocol that runs between the call agent and
210 the ViPR server. VAP is a simple, binary based, request/response
211 protocol. It utilizes the same syntactic structure and transaction
212 state machinery as STUN [RFC5389], but otherwise is totally distinct
213 from it. VAP clients initiate TCP/TLS connections towards the ViPR
214 server. The ViPR server never opens connections towards the call
215 agent. This allows the ViPR servers to run on the public side of
216 NATs and firewalls.
218 Once the connections are established, the call agent sends a Register
219 message to the ViPR server. This register message primarily provides
220 authentication and connects the client to the ViPR server. VAP
221 provides several messages for different purposes:
222 o Publish: The Publish message informs the ViPR server of service
223 information. There are two types of Publishes supported in ViPR.
224 The first is the ViPR Service (VService). This informs the ViPR
225 server of the SIP URIs on the call agent and black and white lists
226 used by the ViPR server to block validations. The ViPR server
227 stores that information locally and uses it during the validation
228 process, as described above. The second Publish is the ViPR
229 Number Service. The ViPR server, upon receiving this message,
230 performs a Store operation into the DHT.
231 o UploadVCR: This message comes in two flavors - an originating and
232 terminating message. An originating UploadVCR comes from a call
233 agent upon completion of a non-ViPR call to the PSTN. A
234 terminating UploadVCR comes from an agent upon completion of a
235 call received FROM the PSTN. The ViPR server behavior for both
236 messages is very different. For originating UploadVCR, the ViPR
237 server will store these, and at a random time later, query the DHT
238 for the called number and attempt validation against the ViPR
239 servers that are found. For a terminating UploadVCR, the ViPR
240 server will store these, awaiting receipt of a validation against
241 them.
242 o Subscribe: Call agents can subscribe for information from the
243 ViPR server. There is one service that call agent can subscribe
244 for: Number Service. When a new number is validated, the ViPR
245 server will send a Notify to the call agent, containing the
246 validated number, the ticket, and a set of SIP trunk URIs.
247 o Notify: The ViPR server sends this message to the call agent when
248 it has an event to report for a particular subscription.
250 The VAP protocol provides authentication by including an integrity
251 object in each message. This integrity message is the hash of the
252 contents of the message and a shared secret between the ViPR server
253 and the client. VAP can also be run over TLS, which enhances
254 security further.
256 3. Terminology
258 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
259 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
260 document are to be interpreted as described in [RFC2119].
262 4. VAP Message Structure
264 VAP messages follow the syntax and structure of Session Traversal
265 Utilities for NAT (STUN) [RFC5389]. It also shares the same
266 transaction model as STUN. However, aside from its common syntax and
267 transaction model, STUN and VAP are unrelated.
269 VAP messages are encoded in binary using network-oriented format
270 (most significant byte or octet first, also commonly known as big-
271 endian). The transmission order is described in detail in Appendix B
272 of RFC791 [RFC0791]. Unless otherwise noted, numeric constants are
273 in decimal (base 10).
275 All VAP messages MUST start with a 20-byte header followed by zero or
276 more Attributes. The VAP header contains a VAP message type, message
277 length, magic cookie and transaction ID.
279 0 1 2 3
280 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
281 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
282 |0 0| VAP Message Type | Message Length |
283 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
284 | Magic Cookie |
285 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
286 | |
287 | Transaction ID (96 bits) |
288 | |
289 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
291 Figure 2: Format of VAP Message Header
293 The most significant two bits of every VAP message MUST be zeroes.
295 The message type defines the message class (request, success
296 response, failure response) and the message method (the primary
297 function) of the VAP message. Although there are four message
298 classes, there is only one type of transaction in VAP: request/
299 response transactions (which consist of a request message and a
300 response message). Response classes are split into error and success
301 responses to aid in quickly processing the VAP message.
303 The message type field is decomposed further into the following
304 structure:
306 0 1
307 2 3 4 5 6 7 8 9 0 1 2 3 4 5
309 +--+--+-+-+-+-+-+-+-+-+-+-+-+-+
310 |M |M |M|M|M|C|M|M|M|C|M|M|M|M|
311 |11|10|9|8|7|1|6|5|4|0|3|2|1|0|
312 +--+--+-+-+-+-+-+-+-+-+-+-+-+-+
314 Figure 3: Format of VAP Message Type Field
316 Here the bits in the message type field are shown as most-significant
317 (M11) through least-significant (M0). M11 through M0 represent a 12-
318 bit encoding of the method. C1 and C0 represent a 2 bit encoding of
319 the class. A class of 0b00 is a Request, a class of 0b10 is a
320 success response, and a class of 0b11 is an error response. The
321 method and class are orthogonal, so that for each method, a request,
322 success response, error response and indication are defined for that
323 method.
325 The magic cookie field MUST contain the fixed value 0x41666679 in
326 network byte order (note that this is a different value than STUN).
328 The transaction ID is a 96 bit identifier, used to uniquely identify
329 VAP transactions. For request/response transactions, the transaction
330 ID is chosen by the VAP client for the request and echoed by the
331 server in the response. The transaction ID MUST be uniformly and
332 randomly chosen from the interval 0 .. 2**96-1, and SHOULD be
333 cryptographically random. The client MUST choose a new transaction
334 ID for new transactions. Success and error responses MUST carry the
335 same transaction ID as their corresponding request.
337 The message length MUST contain the size, in bytes, of the message
338 not including the 20 byte VAP header. Since all VAP attributes are
339 padded to a multiple of four bytes, the last two bits of this field
340 are always zero.
342 Following the VAP fixed portion of the header are zero or more
343 attributes. Each attribute is TLV (type-length-value) encoded. The
344 details of the attributes themselves is given in Section 10.3.
346 The methods defined in VAP, and their corresponding method values,
347 are:
349 Method Value
350 ------ ------
351 Register 0x001
352 Unregister 0x002
353 Publish 0x004
354 Unpublish 0x005
355 PublishRevoke 0x006
356 Subscribe 0x007
357 Unsubscribe 0x008
358 Notify 0x00a
359 UploadVCR 0x00b
361 Figure 4: VAP Methods
363 After the VAP header are zero or more attributes. Each attribute is
364 TLV encoded, with a 16 bit type, 16 bit length, and variable value.
365 Each attribute MUST end on a 32 bit boundary:
367 0 1 2 3
368 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
369 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
370 | Type | Length |
371 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
372 | Value .... |
373 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
375 Figure 5: VAP Attributes
377 The Length refers to the length of the actual useful content of the
378 Value portion of the attribute, measured in bytes. Since VAP aligns
379 attributes on 32 bit boundaries, attributes whose content is not a
380 multiple of 4 bytes are padded with 1, 2 or 3 bytes of padding so
381 that they are a multiple of 4 bytes. Such padding is only needed
382 with attributes that take freeform strings, such as USERNAME. For
383 attributes that contain more structured data, the attributes are
384 constructed to align on 32 bit boundaries. The value in the Length
385 field refers to the length of the Value part of the attribute prior
386 to padding - i.e., the useful content. Consequently, when parsing
387 messages, implementations will need to round up the Length field to
388 the nearest multiple of four in order to find the start of the next
389 attribute.
391 5. VAP Transactions
393 This section describes the general behavior of VAP transactions,
394 regardless of the method.
396 5.1. Transport and Connection Management
398 VAP runs only over TCP. UDP is not supported. As a consequence,
399 transactions are simple. For each transaction, the client sends a
400 single request, and the server sends a response.
402 VAP can also be run over TLS. The server MUST implement TLS, and the
403 client SHOULD utilize it. The TLS_RSA_WITH_AES_128_CBC_SHA
404 ciphersuite MUST be implemented. The client MUST verify that the
405 server certificate matches a configured value associated with the
406 ViPR server that is to be used. The server MUST accept any
407 certificate from the client. Client authentication is performed
408 using a simple digest technique.
410 Reliability of VAP over TCP and TLS-over-TCP is handled by TCP
411 itself, and there are no retransmissions at the VAP protocol level.
412 However, for a request/response transaction, if the client has not
413 received a response by Ti seconds after it sent the SYN to establish
414 the connection, it considers the transaction to have timed out. Ti
415 SHOULD be configurable and SHOULD have a default of 39.5s.
417 In addition, if the client is unable to establish the TCP connection,
418 or the TCP connection is reset or fails before a response is
419 received, any request/response transaction in progress is considered
420 to have failed.
422 The client MAY send multiple transactions over a single TCP (or TLS-
423 over-TCP) connection, and it MAY send another request before
424 receiving a response to the previous. The client SHOULD keep the
425 connection open until it
426 o has no further VAP requests to send over that connection, and;
427 o has no outstanding subscriptions
429 At the server end, the server SHOULD keep the connection open, and
430 let the client close it, unless the server has determined that the
431 connection has timed out (for example, due to the client
432 disconnecting from the network). The server SHOULD NOT close a
433 connection if a request was received over that connection for which a
434 response was not sent. A server MUST NOT ever open a connection back
435 towards the client in order to send a response. Servers SHOULD
436 follow best practices regarding connection management in cases of
437 overload.
439 5.2. Requestor Procedures
441 Though VAP is a client/server protocol, the ViPR server can
442 asynchronously send requests towards the client call agent. As such,
443 this section defines transaction rules in terms of the requestor (the
444 entity sending the request) and the responder (the entity receiving
445 the request).
447 5.2.1. Generating Requests
449 The requestor MUST construct a request message based on the syntax in
450 Section 4. The message class MUST be a request. The method depends
451 on the method of the request.
453 The requestor MUST add a MESSAGE-INTEGRITY, REALM and USERNAME
454 attribute to the request message. The USERNAME contains a string
455 which is the provisioned username identifying the client to the VAP
456 server. The REALM attribute MUST have the value of "ViPR". The
457 MESSAGE-INTEGRITY is computed as described in Section 10.3.3. That
458 computation relies on a 16-byte key. The 16-byte key for MESSAGE-
459 INTEGRITY HMAC is formed by taking the MD5 hash of the result of
460 concatenating the following five fields: (1) The username, with any
461 quotes and trailing nulls removed, (2) A single colon, (3) The realm,
462 with any quotes and trailing nulls removed, (4) A single colon, and
463 (5) The password, with any trailing nulls removed. Note that the
464 password itself never appears in the message.
466 This format for the key was chosen so as to enable a common
467 authentication database for SIP, which uses digest authentication as
468 defined in RFC 2617 [RFC2617].
470 The request will contain other attributes depending on the method.
472 5.2.2. Receiving Responses
474 All responses MUST first be authenticated by the requestor.
475 Authentication is performed by first comparing the Transaction ID of
476 the response to an outstanding request. If there is no match, the
477 requestor MUST discard the response. Then the requestor SHOULD check
478 the response for a MESSAGE-INTEGRITY attribute. If not present, it
479 MUST discard the response, except for error responses with response
480 codes 431 and 436. If MESSAGE-INTEGRITY is present, the requestor
481 computes the HMAC over the response. The key that is used MUST be
482 same as used to compute the MESSAGE-INTEGRITY attribute in the
483 request.
485 If the computed HMAC matches the one from the response, processing
486 continues. If the response was discarded, in cases where the failure
487 is due to an implementation error, this will cause timeout of the
488 transaction.
490 If the response is an Error Response, the requestor checks the
491 response code from the ERROR-CODE attribute of the response. For a
492 400 (Bad Request) response code, the requestor SHOULD generate an
493 alarm (a notification here refers to some kind of indication, sent to
494 the administrator of the system, indicating an error condition.
495 Notification mechanisms include SNMP alarms, logs, syslog, and so on,
496 and are a matter of local implementation) containing the reason
497 phrase.
499 For a 431 (Integrity Check Failure) response code, this is typically
500 caused by a mis-provisioning of the password. The requestor SHOULD
501 generate an alarm and SHOULD NOT retry.
503 If the requestor receives a 436 (Unknown Username) response, it means
504 that the username it provided in the request is unknown. This is
505 typically due to a provisioning error, a consequence of a mismatched
506 username. The requestor SHOULD generate an alarm.
508 The requestor MUST ignore any attributes from the response whose
509 attribute type were not understood by the requestor.
511 5.3. Responder Behaviors
513 5.3.1. Receiving Requests
515 A responder will receive requests on an existing TCP connection,
516 either one initiated by the client, or the one accepted by the ViPR
517 server.
519 If a responder cannot process a request because the request does not
520 meet the syntactic requirements necessary for the processing
521 described below, the responder SHOULD reject the request with an
522 error response and include an ERROR-CODE attribute with a response
523 code of 400 (Bad Request). If the request is so malformed that a
524 response cannot be generated, the request is just dropped. Error
525 codes for specific failures are not provided, since these failures
526 would not be seen in a functionally correct system. The protocol
527 only provides error codes for errors that can arise due to
528 misconfiguration or network error. Note, however, that a responder
529 SHOULD NOT verify that a requestor has generated the request in full
530 compliance to this specification; it should only validate what it
531 needs to perform the processing described for handling the request.
533 First, the responder authenticates the request. The request will
534 contain a USERNAME, REALM, and MESSAGE-INTEGRITY attribute. If the
535 USERNAME is unknown, the responder generates an error response with
536 an ERROR-CODE attribute with a response code of 436 (Unknown
537 Username). The response MUST include the REALM, but MUST omit the
538 MESSAGE-INTEGRITY attribute.
540 The responder computes the HMAC over the request. If the computed
541 HMAC differs from the one from the MESSAGE-INTEGRITY attribute in the
542 request, the responder MUST generate an error response with an ERROR-
543 CODE attribute with a response code of 431 (Integrity Check Failure).
544 This response MUST include a REALM but MUST omit the MESSAGE-
545 INTEGRITY attribute.
547 The responder MUST ignore any attributes from the request whose
548 attribute type were not understood by the responder.
550 5.3.2. Sending Responses
552 To construct the response the responder follows the message structure
553 described in Section 4. The message type MUST indicate either a
554 success response or error response class and MUST indicate the same
555 method as the request. The responder MUST copy the transaction ID
556 from the request to the response.
558 The attributes that get added to the response depend on the type of
559 response.
561 When sending an error response, the server MUST add an ERROR-CODE
562 attribute containing the error code. The reason phrase is not fixed,
563 but SHOULD be something suitable for the error code.
565 All responses except for an error response with ERROR-CODE of 431 and
566 436 will contain a MESSAGE-INTEGRITY attribute. All responses will
567 contain a REALM attribute. The computation of the message integrity
568 is based on the same username value present in the request (along
569 with its corresponding password); however the response SHOULD NOT
570 contain the USERNAME attribute.
572 All responses MUST be sent on the same TCP connection on which the
573 request was received. If this connection has closed, the responder
574 MUST NOT open a new connection in order to try to send the response.
575 The transaction is considered failed in this case.
577 6. State Model
579 The state model for VAP is shown in Figure Figure 6. This state is
580 built up as a consequence of the primary messages which build state
581 on the ViPR server: Register, Publish, UploadVCR and Subscribe.
583 +-------+
584 |Handle |
585 +-------+
586 ^1 1 +----+
587 |1 +-------->|DHT |
588 +-------+ n+--------+ n | +----+
589 |Client |<-------|Instance|<------+ |
590 +-------+ +--------+ | | 1 +----------+
591 | | | | +------>|BlackWhite|
592 | | | | | +----------+
593 Vn | +-------------+
594 +------------+ | | | 1 +---------+
595 |Subscription| V | VService |---->|NumCount |
596 +------------+ +-----+ +-------------+ +---------+
597 |route| |1 |
598 +-----+ | | 1 +--------+
599 | +------->|domain |
600 |1 +--------+
601 +----------+
602 |VServiceID|
603 +----------+
604 |1 |1
605 | |
606 Vn Vn
607 +--------+ +--------+
608 |OrigVCR | |TermVCR |
609 +--------+ +--------+
611 Figure 6: VAP State Model
613 It is important to understand that the ViPR client publishes two
614 unique sets of information to the ViPR server:
616 1. The set of numbers that are reachable by the client through a
617 particular ViPR service,
619 2. The set of ViPR services
621 Both of these are uploaded from the client to the ViPR server using a
622 VAP Publish operation. The ViPR clients have the concept of a "ViPR
623 Service" (not to be confused with ViPR server). A ViPR service is a
624 unique instance of ViPR processing in a call agent - and is
625 associated with a specific DHT, specific routes, specific domain,
626 specific set of numbers to use, and specific set of policies
627 governing operation. When a client publishes a number, it is always
628 associated with a specific ViPR service, or VService. Multiple
629 clients can publish the same VServices, and they will differ only in
630 the routes associated with that VService, as each client will have
631 its own route to reach the same VService.
633 The ViPR server actively tracks the association of clients,
634 VServices, routes, DHTs, BlackWhite lists, and VServiceIDs. Number
635 publications and VService publications are differentiated from each
636 other by different serviceID values in attributes in the Publish
637 request. To be thoroughly confusing, this serviceID is not the same
638 as a VServiceID. ServiceID refers to whether something is a VService
639 publication or number publication, and is an enumerated value,
640 whereas a VServiceID is an instance ID for a particular VService.
641 The ViPR server only actually stores the VService publications; when
642 receiving a Publish for a number service, the corresponding data is
643 written directly to the DHT and then forgotten by the ViPR server.
644 The ViPR server doesn't take any responsibility for removing the
645 state or for keeping it fresh. All of this is the responsibility of
646 the ViPR client. Consequently, VAP itself is not responsible for
647 maintaining this information.
649 Firstly, when a client connects, it will Register to the ViPR server.
650 That creates an instance of the client object, which is assigned a
651 unique handle that identifies it. The client object is one of the
652 key pieces of state (ViPR service being the other). All subsequent
653 messaging from the client includes that Client-Handle, allowing the
654 ViPR server to immediately determine the client associated with the
655 messaging.
657 The client can issue subscriptions for services over its connection
658 to the ViPR server. The ViPR server remembers the set of
659 subscriptions from that client.
661 The VService publication builds the next large block of state. When
662 a VService publication is received from a client, the ViPR server
663 creates the VService object if it didn't have one yet for that
664 VServiceID. Each distinct instance of a VService publication gets
665 linked to it, and each distinct instance is, in turn, associated with
666 one or more routes. Each route has a SIP URI, but the internal
667 structure of the route is opaque to the ViPR server. It parses no
668 deeper than the route element itself; the contents are not parsed,
669 examined or checked by the ViPR server. This allows for future
670 extensibility on how call routing is done. The VService itself has a
671 numberCount, domain, BlackWhite list and DHT, all of which are
672 learned from the VService publication. The VServiceID is 1-1
673 associated with each VService.
675 Finally, each UploadVCR, whether it is originating or terminating,
676 contains a VServiceID as well. This binds it to a particular
677 VService. It is important to note that, the linkage from VCRs to
678 VServices is indirect, through the VServiceID. This allows a
679 temporary outage to break all client connections, which will delete
680 the VService objects, but keep the VCRs and the VServiceIDs. When
681 the clients reconnect, the VServices are rebuilt, along with their
682 IDs, and once again can be linked to the VCRs.
684 When the VAP connection terminates, the client object and
685 subscription state from the corresponding client is destroyed. Any
686 instances of a VService from that client are destroyed. If there are
687 no longer any instances of the VService left, the VService itself is
688 destroyed. The VCRs are not affected by the termination of a
689 connection from a client.
691 When the client TCP connection breaks or keepalives cease to be sent,
692 the ViPR server will remove the registration, subscription and
693 VServiceID to SIP trunk/DHT mappings. Similarly, on the client side,
694 if the TCP connection breaks, the client must create a new TCP
695 connection, register without a handle, subscribe and performs its
696 VService publications.
698 The VAP state above is, in addition, utterly and completely
699 orthogonal to the state of the DHT itself. That state is driven
700 through number service publications, which cause storage operations
701 into the DHT.
703 7. Protocol Versioning
705 Each version of VAP has a major and minor version number. This
706 specification describes major version 1, minor version 0. It is
707 anticipated that the protocol may require updating in the future.
709 If an update can be done such that an older client will work with a
710 newer server, and an older server with a newer client, this MUST be
711 done using an increase in the minor version number within the major
712 version. This would typically include bug fixes and minor
713 extensions. If a protocol change is such that it cannot be
714 understood by previous servers and clients, this MUST be done using
715 an increase in the major version number of the protocol.
717 This specification further requires that, in addition to the most
718 recent version of the protocol they understand, a client MUST
719 understand the previous major version number. For example, a client
720 supporting version 2.1 would also need to support version 1.0.
722 The protocol version number is included in client register messages,
723 and negotiation as part of that exchange.
725 This allows for a graceful upgrade procedure. When a new version of
726 the protocol is to be rolled out, the clients are upgraded first,
727 each in turn. When they are upgraded, they'll come back, but during
728 registration, notices that the servers only support a previous major
729 version. The clients thus switch to the previous version of the
730 protocol. Once all of the clients are updated, the servers can be
731 updated. When the clients connect to them, they will utilize the
732 newest version of the protocol.
734 8. ViPR Client Procedures
736 8.1. Discovery
738 VAP provides no discovery mechanism. The client must be provisioned
739 with the domain names and/or IP addresses and ports of its ViPR
740 servers. Typically, a client will be provisioned with two servers -
741 a primary and a backup.
743 8.2. Registration
745 Once a TCP connection is established, the client MUST perform a
746 registration. This applies to all TCP connections held by the client
747 for purposes of high availability.
749 The client constructs a Register request based on the basic client
750 procedures in Section 5.2. In addition, the client MUST include the
751 Client-Name attribute. This field is used strictly for debugging
752 purposes and indicates the name of the client to the server.
754 If the client is registering for the first time towards this ViPR
755 server, the registration MUST omit the Client-Handle attribute.
757 If the client is registering for the first time towards this ViPR
758 server (and thus there was not Client-Handle attribute), the client
759 MUST include a Protocol-Version attribute in the request. This
760 includes the major and minor version number of the most recent
761 version of the protocol supported by the client. For purposes of
762 extensibility, in addition to their current version of the client
763 protocol, a client MUST support the previous major version as well.
765 The client MUST include the Client-Label attribute in the request.
766 However, it is not used and its contents are arbitrary.
768 Once constructed, the client sends the Register request to the ViPR
769 server. The response is processed using the general techniques in
770 Section 5.2. Assuming a success response is ultimately received, it
771 indicates that the client has successfully registered. This response
772 will contain a Client-Handle attribute. The client MUST retain this
773 handle and store it for the lifetime of the clients connection to the
774 server. The response will also contain the Keepalive attribute,
775 which tells the client how often it needs to keepalive its
776 registration to the server.
778 If the response to the initial Register request (one without a
779 Client-Handle) is an error response with an ERROR-CODE attribute with
780 a response code of 478, it means that the server does not support the
781 major protocol version signaled by the client. The client MUST
782 extract the Protocol-Version attribute from the error response. This
783 attribute indicates the major and minor versions supported by the
784 server. Based on the principles in Section 7, the client will be
785 able to support a version of the protocol that has a major protocol
786 version matching the one in the Protocol-Version attribute of the
787 error response. The client MUST switch to this version of the
788 protocol, and then MUST generate a new Register request (without a
789 Client-Handle), indicating a Protocol-Version equal to the new, lower
790 version of the protocol.
792 If the response to the initial Register request (one without a
793 Client-Handle) is an error response with an ERROR-CODE attribute with
794 a response code of 477, it means that the server believes that the
795 client has already registered on this connection. There has been a
796 state synchronization error. The client SHOULD generate an alarm,
797 and then tear down the TCP connection. It MUST open a new TCP
798 connection, and then generate a fresh Register request (without a
799 Client-Handle) over that connection.
801 If the Register message was for an existing connection (and thus a
802 keepalive), and thus included the Client-Handle attribute in the
803 request, but the response was a Register Error response with an
804 ERROR-RESPONSE with a response code of 471, the client MUST consider
805 this a failure of the connection. It SHOULD attempt a new connection
806 and a new Register, but without a Client-Handle.
808 During an initial Register (one that omits Client-Handle), the client
809 MUST NOT generate any subsequent requests until that Register
810 transaction completes.
812 If the TCP connection fails, the client needs to reconnect and create
813 a new registration without the handle, and furthermore, resubscribe
814 and republish as needed. In other words, on the client side, the
815 lifetime of the handle is equal to the lifetime of the TCP
816 connection. The server also holds onto the handle as long as the
817 connection is active. However, it will also watch for refreshes of
818 registrations, and if it doesn't see one fast enough, remove the
819 client registration, the handle, and state received from that client,
820 as well.
822 8.3. Unregistering
824 A Client that wishes to terminate its connection gracefully does so
825 using the Unregister request. This request is first constructed as
826 described in Section 5.2. Once constructed, the client MUST add the
827 Client-Handle attribute to the request, and send it to the ViPR
828 server.
830 If the response was an error response and was of type 400, it means
831 that the client did not construct the request properly. The client
832 MUST NOT retry unless it changes the content or set of attributes in
833 the request to match the requirements defined here.
835 If the response was an error response with an ERROR-RESPONSE
836 attribute with a response code of 471, the client MUST consider this
837 a failure of the connection. It indicates a synchronization error
838 between client and server. The client SHOULD generate an alarm.
840 If the response was an error response and was of type 474, it means
841 that the client sent an Unregister request on a TCP connection but
842 had not yet registered. If the client had registered, there has been
843 some kind of synchronization error. The client SHOULD generate an
844 alarm.
846 In all cases, success or error responses, the client MUST consider
847 all subscriptions to this server terminated, and consider all
848 published VServices to this server as unpublished. The client MUST
849 terminate the TCP connection after the response has been received.
851 8.4. Publishing Services
853 Publish requests inform the ViPR server of information from the
854 client. There are two types, VService publications and number
855 publications. These differ in the value of the ServiceIdentity
856 attribute.
858 All publications contain a ServiceContent attribute which contains an
859 XML element that defines the service. The schema for the
860 ServiceContent element depends on whether the publication is a
861 VService or number publication.
863 The Publish request MUST contain a ServiceVersion attribute. This
864 attribute is a version number that increments by at least one every
865 time a particular service (identified by a unique VService, instance,
866 service ID and sub-service ID value) changes in any way. If the
867 service data different from the previous published value, the
868 ServiceVersion attribute MUST increase. If the service data is the
869 same as the previous published value, the ServiceVersion SHOULD stay
870 the same, but MAY increase. Consequently, increasing version numbers
871 are not a guarantee that there was a change; only that lack of
872 increasing version number is a guarantee that there was no change.
874 If a client loses track of the previous version number of the service
875 (due, for example, to a restart), it MUST choose a new instance ID
876 and then it can reset the ServiceVersion.
878 Finally, the Publish Request MUST contain a ServiceContent attribute.
879 This attribute contains the actual service data. Its actual
880 structure and syntax are a function of the service and sub-service.
882 If the response was an error response and was of type 472, it means
883 that the client didn't increment the sequence number. More likely,
884 it indicates that the client has inadvertently forgotten the version
885 number of the service and gotten out of sync with the server. The
886 client SHOULD choose a new instance ID for this service, withdraw the
887 old one, and publish the new one.
889 If the response was an error response and was of type 474, it means
890 that the client sent a Publish request on a TCP connection but had
891 not yet registered. If the client hadn't registered, it MUST now do
892 so. If it had registered, there has been some kind of
893 synchronization error. The client SHOULD generate an alarm. Then,
894 it MUST generate a new register (without the Client-Handle), flushing
895 all subscriptions.
897 If the response was an error response and was of type 400, it means
898 that the client did not construct the request properly. The client
899 MUST NOT retry unless it changes the content or set of attributes in
900 the request to match the requirements defined here.
902 If the response was a success, the publication has been accepted.
904 8.4.1. VService
906 The VService indicates the critical information for the VService
907 identified by the VService ID. Typically, a call agent will run on
908 many servers, each of which is listening for SIP traffic on a
909 specific IP address and port. Each such IP address and port forms a
910 particular instance of the VService, and represents an alternative
911 SIP destination for receiving incoming calls. The instance ID is a
912 unique identifier, within the scope of the VServiceID, which
913 identifies that call agent server.
915 The additional information placed into the VService publication will
916 not vary amongst different instances. That information is:
918 o The DHT that the client wishes its numbers to be published into
919 for this VService. This must always be the name of the public
920 ViPR DHT, which is "Quetzalcoatl".
921 o The domain name associated with this VService, e.g., example.com.
922 This domain name is used by the ViPR server at the end of the
923 validation process.
924 o The set of routes which can be used to reach a SIP server on the
925 call agent instance. Each route contains a SIP URI, in addition
926 to extensions to allow for future advanced routing. This
927 parameter of the VService data is instance specific.
928 o a black/white list of domains. These are used by the ViPR server
929 during the validation protocol. The white list contains the set
930 of domains that this domain wishes to only federate with. The
931 black list contains the list of domains that this domain does not
932 wish to federate with.
933 o A count of the number of phone numbers being published for this
934 VService. This is used for quota management on the ViPR server.
936 Note that the VService does not contain phone numbers. VService
937 information is not stored into the DHT by the ViPR server. It is
938 stored locally on the ViPR server and used to support the validation
939 protocol.
941 Section 10.1 defines the XML schema for the object included in the
942 Publish request.
944 The SIP URI is constructed as follows:
946 1. The scheme MUST be sip.
947 2. The user part MUST be an identifier which is unique to this agent
948 and is identical for all instances of that call agent. For
949 example, if a call agent consists of two servers for purposes
950 availability, and either can be used, the user part will be
951 identical in the SIP URI published by each server.
952 3. The domain part MUST be the domain associated with this call
953 agent, and MUST match certificates that the domain can obtain.
954 4. There MUST be a port and it MUST be the port on which incoming
955 SIP invites can be received.
956 5. There MUST be an maddr URI parameter, and it MUST contain the IP
957 address or hostname of the instance of the call agent server.
958 6. The transport URI parameter MUST be present and MUST be TCP.
960 There will be one or more URI per each instance of the call agent.
961 The IP address in the URI MUST be a publicly reachable one. If the
962 call agent is to be reached through a border element, the IP address
963 and port on the border element MUST be used here.
965 The use of the IP address in the maddr parameter allows the system to
966 operate without DNS support.
968 An example document for a VService on the public DHT is:
970
971
975
976 Quetzalcoatl
977 3670
978 example.com
979
980 example.com
981 foo.edu
982
983
984
985 sip:17ahhs7zpaksux6z5==@example.com:2371;maddr=1.2.3.4;transport=tcp
986
987
988
989
991 Figure 7: Example ServiceContent
993 The ViPR client SHOULD publish each ViPR trunk service to both its
994 primary and backup ViPR server, for purposes of HA.
996 8.4.2. ViPR Number Service
998 The ViPR number service is used to publish the numbers that are
999 associated with the VService. It is published as a separate service
1000 due to the differing state requirements associated with the numbers.
1001 For the VService, the ViPR server stores the information and does not
1002 actually publish it into the DHT. For ViPR number service, the ViPR
1003 server immediately writes the data into the DHT and doesn't actually
1004 store it locally. The ViPR server does not refresh the data in the
1005 DHT on its own, nor does it withdraw the data from the DHT when the
1006 client disconnects. The ViPR client is responsible for refreshing
1007 the data in the DHT by periodically refreshing each of its numbers in
1008 each DHT. The numbers in the DHT have a configurable expiration.
1009 Consequently, the ViPR client has to refresh the data prior to the
1010 expiration. There is no way in VAP to remove a number from the DHT;
1011 it is merely left to expire.
1013 The ViPR client SHOULD publish each service to both its primary and
1014 backup ViPR server, for purposes of HA. Next, the client constructs
1015 a ViPR number service advertisement. Unlike VService advertisements,
1016 which utilize an XML object in the ServiceContent attribute, number
1017 services utilize only VAP attributes. The Publish message will
1018 contain a ServiceIdentity attribute and a CalledNum attribute. The
1019 VServiceID of the ServiceIdentity attribute indicates the VService
1020 for this number, and is used by the ViPR server to determine which
1021 DHT to publish into. The CalledNum attribute contains the number to
1022 be published into the DHT. The ServiceVersion attribute is not
1023 present.
1025 8.5. Updating the VService
1027 A client can change the VService information at any time. Typically,
1028 changes in the black or white list will require an updated VService
1029 publication, as will changes in the set of servers listening for
1030 incoming SIP traffic.
1032 To update a VService, the client modifies its service description,
1033 and creates a new Publish request. This request is first formed as
1034 described in Section 4. This request MUST contain the
1035 ServiceIdentity attribute, identifying the service to be modified.
1036 The request MUST also contain the ServiceContent attributes,
1037 containing the relevant information for the service.
1039 The request MUST contain a ServiceVersion attribute. That version
1040 number MUST be at least one higher than the version number in the
1041 previous publication for the same service (as identified by service
1042 ID, subservice ID and instance).
1044 If the response was an error response and was of type 472, it means
1045 that the client didn't increment the sequence number. More likely,
1046 it indicates that the client has inadvertently forgotten the version
1047 number of the service and gotten out of sync with the server. The
1048 client SHOULD choose a new instance ID for this service, unregister,
1049 reconnect, re-register, and republish.
1051 If the response was an error response and was of type 474, it means
1052 that the client sent a Publish request on a TCP connection but had
1053 not yet registered. If the client hadn't registered, it MUST now do
1054 so. If it had registered, there has been some kind of
1055 synchronization error. The client SHOULD generate an alarm. Then,
1056 it MUST generate a new register (without the Client-Handle).
1058 If the response was an error response and was of type 400, it means
1059 that the client did not construct the request properly. The client
1060 MUST NOT retry unless it changes the content or set of attributes in
1061 the request to match the requirements defined here.
1063 If a client is no longer capable of receiving SIP requests at the URI
1064 it previously published, it should remove its VService by sending an
1065 Unpublish request.
1067 8.6. Uploading VCRs
1069 When the call agent initiates or receives a call that goes towards
1070 the PSTN, whether it be through a PSTN gateway or through a SIP trunk
1071 to a service provider, the call agent MUST send an UploadVCR request
1072 to its primary server ViPR server. It SHOULD send its terminating
1073 UploadVCRs to its secondary ViPR server, and SHOULD NOT send its
1074 originating UploadVCRs to its secondary. The UploadVCR request is
1075 first constructed like any other VAP request. This means it will
1076 contain the USERNAME, REALM, and MESSAGE-INTEGRITY attributes.
1078 In addition, it MUST contain a CallingNum, CalledNum, StartTime and
1079 StopTime attribute. The CallDirection attribute is set as described
1080 in Section 10.3.14.
1082 The UploadVCR request MUST contain a ServiceIdentity attribute. The
1083 serviceID is 100, the subservice ID is 3 (ViPR number service) and
1084 the VService ID must identify the VService for which this UploadVCR
1085 is associated. The instance is arbitrary and are ignored by the ViPR
1086 server.
1088 If the response was an error response and was of type 474, it means
1089 that the client sent a UploadVCR request on a TCP connection but had
1090 not yet registered and had not yet sent a VService publication with a
1091 VServiceID matching that of the UploadVCR. If the client hadn't
1092 registered and published a matching VService, it MUST now do so. If
1093 it had, there has been some kind of synchronization error. The
1094 client SHOULD generate an alarm. Then, it MUST disconnect, generate
1095 a new register (without the Client-Handle) and a new VService
1096 publication.
1098 If the response was an error response and was of type 400, it means
1099 that the client did not construct the request properly. The client
1100 MUST NOT retry unless it changes the content or set of attributes in
1101 the request to match the requirements defined here.
1103 8.7. Subscribing to Number Service
1105 In order to learn about validated numbers, a ViPR client MUST
1106 subscribe for the ViPR Number Service. The client should subscribe
1107 to just its primary ViPR server.
1109 To create a subscription, the client creates a Subscribe request.
1110 The request is formed as described in Section 4. It MUST NOT be sent
1111 if the client has not previously generated a successful Register
1112 request on this connection.
1114 Each initial Subscribe request MUST omit the SubscriptionID
1115 attribute; that attribute is only used when withdrawing a
1116 subscription. The client MUST include a ServiceIdentity attribute in
1117 the request. The service ID MUST be 101, the subserviceID MUST be 3,
1118 the VServiceID MUST be the VServiceID for the VService from which
1119 learned numbers are desired, and the instance value MUST be all ones.
1120 This will cause the client to receive notifications upon validated
1121 numbers learned as a consequence of an UploadVCR for that VService.
1123 8.8. Unsubscribing to Services
1125 A client MAY terminate a subscription at any time. To do that, it
1126 sends an Unsubscribe request. This request MUST contain the
1127 SubscriptionID attribute identifying the subscription to be
1128 terminated. Note that this unsubscription will affect only the
1129 subscription identified by the subscription ID. Other subscriptions
1130 will continue to be in effect.
1132 The client MAY generate additional Unsubscribe requests while the
1133 transactions for previous Subscribe, Publish or Unpublish requests
1134 are in progress. By definition a client can only Unsubscribe a
1135 subscription for which it had already received a successful response
1136 to a Subscribe request that created the subscription.
1138 If the response was an error response and was of type 474, it means
1139 that the client sent a Subscribe request on a TCP connection but had
1140 not yet registered. If the client hadn't registered, it MUST now do
1141 so. If it had registered, there has been some kind of
1142 synchronization error. The client SHOULD generate an alarm. Then,
1143 it MUST generate a new register (without the Client-Handle).
1145 If the response was an error response and was of type 476, it means
1146 that the client sent an Unsubscribe request for a subscription which
1147 does not exist. The client SHOULD generate an alarm, since a
1148 synchronization error has occurred. It should however proceed as if
1149 the withdrawal was successful.
1151 If the response was an error response and was of type 400, it means
1152 that the client did not construct the request properly. The client
1153 MUST NOT retry unless it changes the content or set of attributes in
1154 the request to match the requirements defined here.
1156 8.9. Receiving Notify
1158 The ViPR server will generate a Notify request when a new number and
1159 route are learned. It will send this Notify request to all clients
1160 which have subscribed to the corresponding VService.
1162 Once the client has received a successful response to its Subscribe
1163 request, the client MUST be prepared to receive Notify requests on
1164 the TCP connection to its ViPR server. When the client receives a
1165 Notify request, it searches for the SubscriptionID attribute in the
1166 request. This informs the client of the subscription that this
1167 notification is associated with. If this subscriptionID is known to
1168 the client, it proceeds. Otherwise, it MUST generate a Notify error
1169 response with a 476 response code in an ERROR-RESPONSE attribute.
1170 When this occurs, there has been a synchronization error between the
1171 client and server in the set of valid subscriptions. This event
1172 SHOULD be alarmed, and the contents of the Notify not used.
1174 The Notify request will contain a ServiceIdentity attribute and a
1175 ServiceContent attribute, in addition to the standard authentication
1176 attributes and the SubscriptionID attribute. The ViPR client must
1177 verify that the ServiceIdentity has service 100, subservice 3. It
1178 looks at the instance value, and checks that the topmost 64 bits of
1179 the instance contain a VServiceID that matches one for which the ViPR
1180 client is currently interested in learning about. The ViPR client
1181 then extracts the contents of the ServiceContent attribute. This
1182 will be an XML object, formatted as described below.
1184 The client SHOULD store the phone number, SIP URI and Ticket. When
1185 receiving a future call to that phone number, it SHOULD send a SIP
1186 INVITE request to the SIP URI and include the ticket in an X-Cisco-
1187 ViPR-Ticket header field.
1189 8.10. Receiving PublishRevoke
1191 The PublishRevoke method is defined only for the VService, not for
1192 the Number Service. The ViPR server will send a PublishRevoke for a
1193 VService if the corresponding DHT is no longer available. The
1194 request will contain the ServiceIdentity attribute, which indicates
1195 the specific VService and instance that are being withdrawn. If
1196 these correspond to a known VService, the client should consider that
1197 service deactivated, and periodically try to republish it.
1199 9. ViPR Server Procedures
1200 9.1. Connection Establishment
1202 The ViPR server MUST be prepared to receive incoming TCP or TLS
1203 connections on a configure port. Whether or not TCP or TLS is used,
1204 is a configured property of that port.
1206 9.2. Registration
1208 The purpose of registrations is to create VAP client objects, which
1209 represent a VAP connection and contain the state described in
1210 Section 6, and then link those with a TCP connection. Each VAP
1211 connection can be considered a client object, linked to one and only
1212 one TCP connection at a time.
1214 The first request that the server will receive over the TCP
1215 connection will be a Register request. This request is first
1216 processed as described in Section 5.3. Assuming those procedures
1217 succeed, the server checks for the Client-Handle attribute in the
1218 Register request. If present, the server checks if it currently has
1219 a client state object with that handle. If the client object was
1220 already bound to another TCP connection, that other TCP connection
1221 MUST be closed by the server, and then the new TCP connection MUST be
1222 bound to the client object.
1224 If the Register request had a Client-Handle attribute, but there were
1225 no client objects with that handle, the server MUST generate an error
1226 response and MUST include an ERROR-CODE attribute with a response
1227 code of 471. This is due to a state synchronization error between
1228 the client and server. The server SHOULD generate an alarm.
1230 If the Register did not have a Client-Handle attribute, it is a
1231 request to create a client object. The server examines the Protocol-
1232 Version attribute from the request. If the major version indicated
1233 in the attribute is higher than the version supported by the server,
1234 the server MUST reject the Register request with an error response
1235 and include an ERROR-CODE attribute with a response code of 478.
1236 That error response MUST include a Protocol-Version attribute that
1237 contains the major and minor protocol versions supported by the
1238 server.
1240 Next, the server MUST create a new client object, and allocate a new
1241 Client-Handle for it. The Client-Handle MUST be unique amongst all
1242 other Client-Handles known to this server, across all clients that
1243 are connected to it.
1245 If the registration succeeds, the server sends a success response.
1246 This response MUST include the Client-Handle attribute containing the
1247 handle created by the server. The response MUST include a Keepalive
1248 attribute, indicating the time in milliseconds that the server will
1249 need to see traffic from the client in order to continue to maintain
1250 the client object.
1252 9.3. Unregistration
1254 The client can gracefully disconnect by using an Unregister request.
1256 If the server receives an Unregister request on a TCP connection, it
1257 first looks for the client object bound to that connection. If there
1258 is no client object bound to it, it means that the client has sent an
1259 Unregister request prior to registering, or there has been some kind
1260 of synchronization error. The server MUST respond with an error
1261 response, and MUST include an ERROR-CODE attribute with a response
1262 code of 474.
1264 Otherwise, if the client object is known to the server, it MUST
1265 generate a success response. Once it does, the server MUST destroy
1266 the client, its associated subscriptions, and published VService
1267 instances. It then sets a timer equal to thirty seconds. If the
1268 client has not closed the TCP connection bound to this client object,
1269 the server MUST close the TCP connection.
1271 If, as a consequence of the deletion of those VService instances,
1272 there are no longer any instances left for a VService, that VService
1273 and its associated data (BlackWhite, DHT, numberCount) are removed.
1275 Note that unregistration does not ever remove VCRs.
1277 9.4. Publication
1279 Behavior depends on whether the publication is for the VService or
1280 the ViPR number service.
1282 The ViPR server extracts the ServiceIdentity attribute. If the value
1283 is not one of the following:
1285 1. ServiceID is 101 and SubserviceID is 3.
1286 2. ServiceID is 101 and SubserviceID is 4
1288 the ViPR server sends a 400 response.
1290 9.4.1. VService
1292 If the Publish request is for service 100, sub-service 4, it
1293 indicates that this was for the VService. The ViPR server first
1294 looks for the client object bound to that connection. If there is no
1295 client object bound to it, it means that the client has sent a
1296 Publish request prior to registering, or there has been some kind of
1297 synchronization error. The server MUST respond with an error
1298 response, and MUST include an ERROR-CODE attribute with a response
1299 code of 474.
1301 The ViPR server extracts the contents of the ServiceContent
1302 attribute. This will be an XML object structured as defined in
1303 Section 10.1. It also extracts the VServiceID and Instance values
1304 from the ServiceIdentity attribute.
1306 First, the ViPR server checks if it has any VService objects with the
1307 VServiceID from the publish.
1309 o If it does, it replaces the BlackWhite, numberCount, domain, and
1310 DHTName parameters of that VService with the ones from the
1311 publish. Next, it checks to see if the instance is currently an
1312 instance associated with that VService:
1313 o
1314 * If it is, the route elements for that instance are replaced
1315 with the route values from the publish.
1316 * If it is not, a new instance object is created, associated with
1317 the client and the VService, and is linked with the route
1318 values from the publish.
1319 o If it does not, it creates a new VService object, and associates
1320 it with the values of the BlackWhite, numberCount, domain, and
1321 DHTName parameters of the VService. Next, it creates a new
1322 instance, associates it with the VService, The route values from
1323 the publish are associated with that instance.
1325 ViPR server sends a Publish success response. The ViPR server looks
1326 for all other ViPR services in the same DHT as the one from this
1327 Publish, it sums up their numberCounts, and includes that value in
1328 the "current" field of the Quota attribute in the Publish response.
1329 Since there is a limit on the count of the numbers that can be
1330 published into the DHT, this mechanism allows the ViPR server to
1331 inform the clients about the total usage across all clients of this
1332 ViPR server. Note further, that since the ViPR server itself does
1333 not have local memory of the numbers it stored into the DHT, the ViPR
1334 server cannot determine how many numbers have been placed into the
1335 DHT for a particular VService. That information is known only to the
1336 client. That is why the client informs the ViPR server of how many
1337 numbers it has published as part of the VService publication.
1339 The ViPR server places its configured per-DHT limit for that DHT into
1340 the "limit" field in the Quota attribute in the Publish response.
1341 This tells the clients the maximum count of phone numbers which can
1342 be published.
1344 The ViPR server includes a DHTLifetime attribute in the response.
1345 This attribute indicates the amount of time that data will remain in
1346 the DHT prior to be expunged. This is a configured property of the
1347 DHT.
1349 9.4.2. ViPR Number Service
1351 If the server receives a Publish request for service 100, sub-service
1352 3, it indicates that this was for the ViPR Number Service. The ViPR
1353 server first looks for the client object bound to that connection.
1354 If there is no client object bound to it, it means that the client
1355 has sent a Publish request prior to registering, or there has been
1356 some kind of synchronization error. The ViPR server MUST respond
1357 with an error response, and MUST include an ERROR-CODE attribute with
1358 a response code of 474. The ViPR server extracts the VServiceID from
1359 the ServiceIdentity attribute. It checks that, for that VServiceID,
1360 there is a VService object currently being stored. If not, the ViPR
1361 server MUST respond with an error response, and MUST include an
1362 ERROR-CODE attribute with a response code of 474.
1364 Next, the ViPR server extracts the number from the CalledNum
1365 attribute. The ViPR server extracts the DHT from the VService object
1366 associated with the VServiceID from the Publish. For the number, the
1367 ViPR server takes the number and treats it as an ASCII string, called
1368 the suffix seed.
1370 Next, the ViPR server generates two additional strings. The first is
1371 formed by taking the suffix seed, and prepending the string "COPY1".
1372 The second is formed by taking the suffix seed and prepending the
1373 string "COPY2".
1375 Each of the three values is passed through the SHA-1 hash function,
1376 producing 160 bits. The least significant 128 bits of this are
1377 taken. Those 128 bits, for each of the three values, form the
1378 Resource-ID against which a STORE is to be performed. Three separate
1379 stores are performed in order to provide security in the DHT. Each
1380 store operation writes an object into the DHT whose value is a
1381 dictionary (or map) entry.
1383 Conceptually:
1385 Store(Resource-ID, object)
1387 Where Resource-ID is the 128 bit Resource-ID computed above. The
1388 stored object is a dictionary entry which has a key and a value:
1390 Object = {key,value}
1391 Here, the key is formed by taking the peerID of the storing node in
1392 hex format, without the "0x", appending a "+", followed by the
1393 VServiceID in hex format, without the "0x". For example, if a peer
1394 with peerID 0x8e60f5fab753037f64ab6c53947fd532 receives a Publish
1395 with a VServiceID of 0x7eeb6a7036478351, the resulting key is:
1397 8e60f5fab753037f64ab6c53947fd532+7eeb6a7036478351
1399 Both parts of this key are important. Using the peerID of the node
1400 performing the store basically segments the keyspace of the
1401 dictionary so that no two peers ever store using the same key.
1402 Indeed, the responsible node will verify the signature over the
1403 stored data and check the peerID against the value of the key, to
1404 make sure that a conflict does not take place. The usage of the
1405 VService allows for a single ViPR server to service multiple call
1406 agents, and to ensure that numbers published by one call agent (using
1407 one VServiceID) do not clobber or step on numbers published by
1408 another call agent (using a different VServiceID). The responsible
1409 node does not verify or check the VServiceID.
1411 In this version of the protocol, only one of the three stored objects
1412 is read. Three are stored to allow an enhancement in the future,
1413 which will read all three and use a simple voting algorithm to handle
1414 inconsistencies in the results. In this way, if a malicious node
1415 returns no result or fakes the result, as long as the remaining two
1416 results are retrieved, the validation process can continue. This
1417 means that the compromise of a single node has, with only extremely
1418 low probability (order Log(N)/N where N is the number of nodes in the
1419 ring) of being able to disrupt validation against a number.
1421 The value of the dictionary entry is a sequence of TLV attributes,
1422 with the same format used by VAP. In this case, it is a single
1423 attribute, the peerID attribute. This attribute is populated with
1424 the peerID of the ViPR server in the DHT into which the STORE is
1425 being performed. The reason for using the TLV construct is to
1426 provide extensibility in the contents of the DHT. In the future, if
1427 needed, new ViPR nodes can add additional data, each with a specific
1428 attribute type. Older nodes will ignore any unknown attributes and
1429 go right for the peerID attribute, while newer ones can process the
1430 new and old attributes.
1432 The Store operations are paced into the DHT at a fixed rate. The
1433 ViPR server maintains a queue. This queue is filled with store
1434 requests. The ViPR server services that queue at a fixed,
1435 provisioned rate, the Store Rate Limit. When serviced, the next
1436 Store operation in the queue is serviced. Because transactions from
1437 clients are pipelined, there can only be as many Store operations in
1438 the queue as there are simultaneously connected clients, times three
1439 (three Stores per Publish, one Publish at a timer per client). The
1440 Publish is then responded to with a success response. Note that, a
1441 success response is not sent until all three Store operations have
1442 been performed. If there is a failure due to inability to store into
1443 the DHT, the server returns a 481 error response. Note that a ViPR
1444 server cannot disambiguate the first Publish for a service and an
1445 updated Publish. It performs identical processing for each.
1447 Note further that, the DHT itself will replicate each of the three
1448 stored values, producing a total of nine copies of each number into
1449 the DHT.
1451 9.5. Unpublish
1453 The ViPR client can only Unpublish for the VService.
1455 The ViPR server extracts the VServiceID and instance from the
1456 ServiceIdentity in the Unpublish. It checks to see if there is an
1457 instance with that ID associated with the VService with that
1458 VServiceID. If there is, it removes the instance object and its
1459 associated SIPURI. If, as a consequence, there are no longer any
1460 instances associated with the VService, it deletes the VService
1461 object and its associated attributes.
1463 9.6. Subscribe
1465 If the server receives a Subscribe request on a connection, it first
1466 looks for the client object bound to that connection. If there is no
1467 client object bound to it, it means that the client has sent a
1468 Subscribe request prior to registering, or there has been some kind
1469 of synchronization error. The server MUST respond with an error
1470 response, and MUST include an ERROR-CODE attribute with a response
1471 code of 474.
1473 The ViPR server checks that the ServiceIdentity from the request. If
1474 verifies that the ServiceID is 101 and the SubServiceID is 3. Any
1475 other combination causes the server to return a 400 response. The
1476 subscription is to the VServiceID identified in the ServiceIdentity
1477 attribute.
1479 If the ServiceIdentity is valid, the server MUST create a new
1480 subscription object. It MUST allocate a SubscriptionID for this
1481 subscription. This ID MUST be unique across all SubscriptionIDs
1482 associated with this client. The subscription MUST be linked with
1483 the client object. It is not permitted for there to be multiple
1484 subscriptions from a client with identical VServices since each
1485 subscription is for a unique service/subservice/VServiceID/instance,
1486 the ViPR server can hash these to get a 32 bit SubscriptionID, or
1487 assign them sequentially and store the associations.
1489 The ViPR server then checks the VServiceID from the ServiceIdentity
1490 attribute. The ViPR server adds a subscription object to the client
1491 object, and associates it with a SubscriptionID and the VServiceID
1492 which is being watched.
1494 The server then generates a success response to the Subscribe
1495 request. It MUST include the SubscriptionID attribute in the
1496 response, identifying this subscription.
1498 9.7. Unsubscribe
1500 If the server receives an Unsubscribe request on a connection, it
1501 first looks for the client object bound to that connection. If there
1502 is no client object bound to it, it means that the client has sent an
1503 Unsubscribe request prior to registering, or there has been some kind
1504 of synchronization error. The server MUST respond with an error
1505 response, and MUST include an ERROR-CODE attribute with a response
1506 code of 474.
1508 Next, the server extracts the SubscriptionID attribute from the
1509 request. If it contains a SubscriptionID not known to the server,
1510 there has been a synchronization error. The server MUST reject the
1511 Unsubscribe request with an error response and MUST include an ERROR-
1512 CODE attribute with a value of 476.
1514 Assuming the SubscriptionID is known, the server MUST remove the
1515 subscription object from the client object, and destroy it. The
1516 server will therefore no longer send notifications associated with
1517 this subscription. The server MUST respond to the Unsubscribe
1518 request with a success response.
1520 9.8. UploadVCR
1522 The ViPR server first processes the request like any other VAP
1523 request, specifically it will perform the message integrity check and
1524 follow associated procedures.
1526 If the UploadVCR was received on a TCP connection but the client had
1527 not yet registered over that connection, it is an error and the ViPR
1528 server returns a 474. If the client had registered, but the
1529 VServiceID from the ServiceIdentity doesn't match a known VService,
1530 the UploadVCR is rejected with a 474.
1532 Otherwise, the ViPR server extracts the CallDirection, StartTime,
1533 StopTime, CallingNum and CalledNum attributes, and stores them.
1534 Further processing depends on whether it was an originating or
1535 terminating UploadVCR.
1537 9.8.1. Originating
1539 Once stored, the ViPR server starts timer Tv. Tv is selected as a
1540 random number, in seconds, starting from 30 and ending at the maximum
1541 validation time, which is a configured parameter of the ViPR Server
1542 for the DHT associated with the VService. The validation request -
1543 which includes the VCR - is stored until that timer fires. The
1544 validation request includes the details from the UploadVCR (calling,
1545 called numbers, start and stop time), along with the VService
1546 associated with the UploadVCR.
1548 When the timer fires, the ViPR server examines the called party
1549 number. This number will be a plus followed by N digits. Using this
1550 number, it forms a lookup key K. K is equal to the least significant
1551 128 bits of the SHA1 hash of the called party number in string form,
1552 including the + sign. Next, the ViPR server extracts VService
1553 associated with the VCR. It checks to see if this VService is
1554 currently being published. If so, it performs a lookup into the DHT
1555 using key K. Each DHT node has a queue on read transactions. These
1556 lookups are queued because the node has, per-DHT, a limit on the rate
1557 at which it will perform read requests.
1559 Once the lookup request comes to the top of the queue and it can be
1560 serviced, the resulting fetch will be a result, a no-match, or a
1561 timeout. If there is a no-match or timeout, ViPR server processing
1562 is complete.
1564 If there is a result, the ViPR server will now have all of the
1565 dictionary entries associated with the Resource-ID. Each dictionary
1566 entry is a key and a value. The key is the concatenation of a peerID
1567 and VServiceID, and the value is a set of TLV attributes. The ViPR
1568 server parses each dictionary entry as a sequence of TLV attributes,
1569 and extracts the first TLV value whose type is peerID (type 0x2008).
1570 From this, the ViPR server obtains a set of {peerID, VServiceID}s.
1572 The ViPR server SHOULD perform validation, using the validation
1573 protocol [VIPR-PVP]. A ViPR server MAY use any algorithm of its
1574 choosing to determine whether a number should be validated once, many
1575 times, or not at all. When the ViPR server is satisfied that a
1576 number has been sufficiently validated, it SHOULD send a Notify.
1577 Furthermore, during validation, the ViPR server SHOULD compare the
1578 domain of the learned number with the blacklist for the VService
1579 associated with the matching VCR. If the domain is on the blacklist
1580 or not on the whitelist, a Notify SHOULD NOT be sent.
1582 If a Notify is to be sent as a consequence of a validation success,
1583 the ViPR server looks to see if there is currently a subscription
1584 from a client whose VServiceID matches the one from the VCR that
1585 triggered the validation that is causing the notification. For each
1586 matching one, it sends a Notify message. The ServiceContent in the
1587 Notify contains a ValInfo XML containing the SIPURI and ticket
1588 learned from the validation. It also contains the full E.164 number
1589 of the called number which validated.
1591 9.8.2. Terminating
1593 When the ViPR server receives a terminating UploadVCR, it stores the
1594 information, awaiting the receipt of a validation query. This
1595 information MUST be stored for a minimum whose value is a configured
1596 property of the DHT.
1598 9.9. Sending Notify
1600 The ViPR server MUST NOT send a Notify until it had already sent a
1601 response to the Subscribe message that created the subscription, for
1602 which the Notify is being sent.
1604 When a Notify is to be sent, it must contain the SubscriptionID
1605 attribute associated with the subscription on which the notification
1606 is being sent. This will differ for each client that is subscribed.
1608 The Notify MUST contain the ServiceIdentity attribute, containing
1609 service 100, subservice 3, a VServiceID for the VService on which the
1610 number was learned, and an instance ID whose instance is all ones.
1611 The content of the ServiceContent attribute is an XML document, which
1612 is the scrubbed document from the ValExchange response. An example
1613 document is:
1615
1616
1618 +17325552496
1619 7hasd88a7sd6a6d7989xkk8g7a6sdq78ekaz
1620
1621
1622 sip:17ahhs$7zpaksux6z5==@example.com:2371;maddr=1.2.3.4
1623
1624
1625
1626
1627 sip:17ahhs$7zpaksux6z5==@example.com:2371;maddr=1.2.3.5
1628
1629
1630
1632 Figure 8: Example Notify XML
1634 9.10. Sending PublishRevoke
1636 The ViPR server is only permitted to PublishRevoke the VService; it
1637 cannot withdraw Number Service publications. It should PublishRevoke
1638 published VServices when the corresponding DHT is no longer
1639 available. If this should happen, the ViPR server sends a
1640 PublishRevoke for each VService that was published which utilized the
1641 DHT which is no longer available. That PublishRevoke MUST include a
1642 ServiceIdentity attribute indicating the VServiceID and instanceID of
1643 the PublishRevoke service. Furthermore, it SHOULD include a
1644 ServiceContent attribute with the corresponding service description;
1645 this is used strictly for diagnostic purposes and is not needed by
1646 the client. Once sent, the ViPR server removes that instance of that
1647 VServiceID from its internal state.
1649 10. Syntax Details
1651 10.1. XML Schema for VService
1653 This document is included in publications for the ViPR service. Note
1654 its target namespace.
1656
1658
1662
1663
1664
1665
1666
1667
1668
1669
1670
1672
1673
1676
1679
1680
1681
1684
1685
1688
1689
1690
1691
1692
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1706
1708
1709
1711
1713 Figure 9: VService XML Schema
1715 10.2. XML Schema for ValInfo
1717 This document is passed from the terminating ViPR server to the
1718 originating, containing the ticket, routes and number which was
1719 validated. The originating ViPR server verifies this and passes it
1720 to the client in VService notifications.
1722
1723
1725
1726
1727
1728
1730
1732
1734
1735
1736
1737
1738
1739
1740
1742
1744
1745
1746
1748 Figure 10: ValInfo XML Schema
1750 10.3. VAP Attributes
1752 This section enumerates the attributes used by VAP. The attribute
1753 names and corresponding types are:
1755 Attribute Name Type
1756 -------------- ----
1757 USERNAME 0x0006
1758 MESSAGE-INTEGRITY 0x0008
1759 REALM 0x0014
1760 ERROR-CODE 0x0009
1761 Client-Name 0x1001
1762 Client-Handle 0x1002
1763 Protocol-Version 0x1003
1764 Client-Label 0x1005
1765 Keepalive 0x1006
1766 ServiceIdentity 0x1007
1767 ServiceVersion 0x100b
1768 ServiceContent 0x100c
1769 SubscriptionID 0x100e
1770 CallDirection 0x2001
1771 StartTime 0x2002
1772 StopTime 0x2003
1773 CallingNum 0x2004
1774 CalledNum 0x2005
1775 peerID 0x2008
1776 Quota 0x200a
1777 DHTLifetime 0x200b
1779 Figure 11: VAP Attributes
1781 10.3.1. USERNAME
1783 The USERNAME attribute is used for authentication. It identifies the
1784 shared secret used in the message integrity check. Consequently, the
1785 USERNAME MUST be included in any request that contains the MESSAGE-
1786 INTEGRITY attribute.
1788 The value of USERNAME is a variable length opaque value of UTF-8
1789 characters. Note that, as described above, if the USERNAME is not a
1790 multiple of four bytes it is padded for encoding into the VAP
1791 message, in which case the attribute length represents the length of
1792 the USERNAME prior to padding.
1794 10.3.2. REALM
1796 The REALM attribute is present in requests and responses. It
1797 contains text which meets the grammar for "realm" as described in RFC
1798 3261 [RFC3261], and will thus contain a quoted string (including the
1799 quotes).
1801 The value of this attribute MUST always be "ViPR".
1803 10.3.3. MESSAGE-INTEGRITY
1805 The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [RFC2104] of
1806 the message. The MESSAGE-INTEGRITY attribute can be present in any
1807 message type. Since it uses the SHA1 hash, the HMAC will be 20
1808 bytes. The text used as input to HMAC is the message, including the
1809 header, up to and including the attribute preceding the MESSAGE-
1810 INTEGRITY attribute. That text is then padded with zeroes so as to
1811 be a multiple of 64 bytes. The MESSAGE-INTEGRITY attribute MUST be
1812 the last attribute in the message.
1814 The 16-byte key for MESSAGE-INTEGRITY HMAC is formed by taking the
1815 MD5 hash of the result of concatenating the following five fields:
1816 (1) The username, with any quotes and trailing nulls removed, (2) A
1817 single colon, (3) The realm, with any quotes and trailing nulls
1818 removed, (4) A single colon, and (5) The password, with any trailing
1819 nulls removed. Note that the password itself never appears in the
1820 message.
1822 Since the hash is computed over the entire message, it includes the
1823 length field from the message header. This length indicates the
1824 length of the entire message, including the MESSAGE-INTEGRITY
1825 attribute itself. Consequently, the MESSAGE-INTEGRITY attribute MUST
1826 be inserted into the message as the last attribute (with dummy
1827 content) prior to the computation of the integrity check. Once the
1828 computation is performed, the value of the attribute can be filled
1829 in. This ensures the length has the correct value when the hash is
1830 performed.
1832 10.3.4. ERROR-CODE
1834 The ERROR-CODE attribute is present in error responses. It is a
1835 numeric value in the range of 100 to 699 plus a textual reason phrase
1836 encoded in UTF-8, and is consistent in its code assignments and
1837 semantics with [RFC3261] and [RFC2616]. The reason phrase is meant
1838 for user consumption (typically freeform fields in alarms and logs),
1839 and can be anything appropriate for the response code. Recommended
1840 reason phrases for the defined response codes are presented below.
1842 To facilitate processing, the class of the error code (the hundreds
1843 digit) is encoded separately from the rest of the code.
1845 0 1 2 3
1846 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
1847 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1848 | 0 |Class| Number |
1849 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1850 | Reason Phrase (variable) ..
1851 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1853 Figure 12: ERROR-CODE Syntax
1855 The class represents the hundreds digit of the response code. The
1856 value MUST be between 1 and 6. The number represents the response
1857 code modulo 100, and its value MUST be between 0 and 99.
1859 If the reason phrase has a length that is not a multiple of four
1860 bytes, it is padded for encoding into the message, in which case the
1861 attribute length represents the length of the entire ERROR-CODE
1862 attribute (including the reason phrase) prior to padding.
1864 The following response codes, along with their recommended reason
1865 phrases (in brackets) are defined at this time:
1867 400 (Bad Request): The request was malformed. The requestor should
1868 not retry the request without modification from the previous
1869 attempt.
1870 431 (Integrity Check Failure): The request contained a MESSAGE-
1871 INTEGRITY attribute, but the HMAC failed verification. This could
1872 be a sign of a potential attack, or misconfiguration of the
1873 password .
1874 436 (Unknown Username): The username was not known. This was likely
1875 due to a misconfiguration.
1876 471 (Bad Client Handle): The client handle provided in the Register
1877 request is not known.
1878 472 (Version Number Too Low): The client published a service whose
1879 version was lower than the currently held one by the server.
1880 474 (Unregistered): The client tried an operation, such as publish
1881 or subscribe, but it has not yet registered.
1882 476 (Unknown Subscription): The referenced subscription does not
1883 exist.
1884 477 (Already Registered): The client tried an initial Register
1885 request, but it is already registered.
1886 478 (Unsupported Protocol Version): The server does not support the
1887 protocol version requested by the client.
1888 481 (Publication Failed): The publication was attempted but could
1889 not be performed due to an error reaching the DHT. The client
1890 should try again.
1892 10.3.5. Client-Name
1894 The Client-Name attribute is included the Register request. It
1895 contains a textual description, in UTF-8, of the software being used
1896 by the client, including manufacturer and version number. The
1897 attribute has no impact on operation of the protocol, and serves only
1898 as a tool for diagnostic and debugging purposes. The value of
1899 Client-Name is variable length. If the value of Client-Name is not a
1900 multiple of four bytes, it is padded for encoding into the VAP
1901 message, in which case the attribute length represents the length of
1902 the attribute prior to padding. However, it MUST be less than 255
1903 characters and MUST be at least one character long.
1905 It is RECOMMENDED that it be constructed as:
1907 ///
1909 Where version includes major, minor and build.
1911 10.3.6. Client-Handle
1913 This attribute has a 32 bit value, representing an unsigned integer
1914 to be used as the client handle.
1916 10.3.7. Protocol-Version
1918 This attribute is 32 bits, consisting of two 16-bit unsigned
1919 integers, representing the major and minor version numbers of the
1920 protocol:
1922 0 1 2 3
1923 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
1924 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1925 | Major Version | Minor Version |
1926 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1928 Figure 13: Protocol-Version Syntax
1930 10.3.8. Client-Label
1932 This attribute is a UTF-8 string, which MUST be between 1 and 255
1933 characters. It is not used by this specification.
1935 10.3.9. Keepalive
1937 This attribute is a 32 bit unsigned integer, representing the number
1938 of milliseconds that the server will retain client state after the
1939 last message from the client has been received.
1941 10.3.10. ServiceIdentity
1943 The format of the ServiceIdentity attribute is:
1945 0 1 2 3
1946 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
1947 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1948 | Service ID | Subservice ID |
1949 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1950 | VServiceID (most significant) |
1951 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1952 | VServiceID (2nd most significant) |
1953 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1954 | Instance (3rd significant) |
1955 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1956 | Instance (least significant) |
1957 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
1959 Figure 14: ServiceIdentity Attribute
1961 The value of serviceID must always be 101. A Subservice value of 4
1962 indicates VService publications. A subservice value of 3 indicates
1963 number publications.
1965 10.3.11. ServiceVersion
1967 The ServiceVersion field is a 32 bit unsigned integer. It contains
1968 the version number for the service advertised in the Publish request.
1969 It always increments by at least one for each change in the service.
1971 10.3.12. ServiceContent
1973 The ServiceContent is the actual content of the service definition.
1974 It is an arbitrary number of bytes. If the number of bytes of
1975 content are not a multiple of four, the content is padded with
1976 arbitrary data so that it is a multiple of four. The value of the
1977 length field of the attribute is the length prior to padding.
1979 The ServiceContent MUST be less than 32k, despite the fact that the
1980 length field of the attribute itself would allow content up to 64k.
1982 10.3.13. SubscriptionID
1984 The SubscriptionID is present in successful responses to Subscribe
1985 and in Unsubscribe messages. It contains an identifier for the
1986 subscription. It is a unique handle, unique within all subscriptions
1987 between the client and this server. It is an unsigned 32 bit
1988 integer. It is also present in Notify and Withdraw requests.
1990 10.3.14. CallDirection
1992 This attribute is a 32 bit unsigned integer. A value of 0 indicates
1993 a received call. A value of 1 indicates a sent call. Other values
1994 are reserved and not valid in this version of the protocol.
1996 10.3.15. StartTime
1998 The start and is a 64 bit NTP time value. The start time is measured
1999 in the following way:
2001 1. For calls sent to the PSTN (i.e., originated by this call agent),
2002 the start time is measured from the instant of the receipt of the
2003 call acceptance message indicating that the called party answered
2004 the call. For SIP, this would correspond to receipt of the 200
2005 OK to the original SIP INVITE.
2006 2. For calls received from the PSTN, (i.e., received by this call
2007 agent), the start time is measured from the instant of
2008 transmission of the call acceptance message towards the PSTN,
2009 indicating that the called party answered the call. For SIP,
2010 this would correspond to transmission of the 200 OK to the
2011 original SIP INVITE.
2013 10.3.16. StopTime Attribute
2015 The stop time is a 64 bit NTP value and is measured in the following
2016 way:
2018 1. For the call agent which terminates the call, it corresponds to
2019 the transmission of the call termination message towards the
2020 PSTN. For SIP, this corresponds to the transmission of a SIP BYE
2021 request.
2022 2. For the call agent which receives the termination, it corresponds
2023 to the receipt of the call termination message from the PSTN.
2024 For SIP this corresponds to the receipt of a SIP BYE request.
2026 10.3.17. CallingNum Attribute
2028 The calling party number MUST be expressed in fully qualified E.164
2029 format, and the attribute is a string with variable length.
2031 The calling party number is complicated. This is because this value
2032 is often munged and modified by the PSTN as it traverses the network.
2033 Fortunately, ViPR does not depend on it being delivered or being
2034 correct, but when it is delivered it improves security. Its presence
2035 is also needed for validating numbers which connect to multiple
2036 users, such that multiple calls to that number are often in progress
2037 at the same time. For example, 800 numbers.
2039 For the originating call agent, the value is the E.164 number of
2040 calling party number delivered to the PSTN. For the terminating call
2041 agent, the value is E.164 normalized value of the caller ID received
2042 from the PSTN. This will require that national numbers delivered
2043 over a PRI are normalized to include their country code.
2045 10.3.18. CalledNum Attribute
2047 The called party number MUST be expressed in fully qualified E.164
2048 format, and it is represented in the attribute as a string with
2049 variable length. The following rules apply for computation of the
2050 called party number:
2052 For the call agent which initiates the call, the called party number
2053 is the E.164 number, including the leading plus, of the target of the
2054 call. Of course, this may not (and is probably not) the same as the
2055 digit sequence dialed by the calling party. The originating call
2056 agent MUST normalize this number to E.164 format based on its local
2057 dialing rules.
2059 For the call agent which receives the call, the called party number
2060 is the E.164 number, including the leading plus, of the target of the
2061 call. Of course, this may not (and is probably not), the same as the
2062 called party number as delivered by the PSTN. It is likely that
2063 country codes, for example, are omitted from the message delivered by
2064 the PSTN. It is the responsibility of the terminating call agent to
2065 reconstruct the E.164 number of the called party.
2067 10.3.19. Quota Attribute
2069 This attribute consists of two 32 bit values. The first is the quota
2070 limit, which is the total number of numbers that can be published by
2071 this and other call agents attached to this ViPR server into this
2072 DHT. The second is the current total number of numbers being
2073 published by this and other call agents attached to this ViPR server
2074 into this DHT. If the current value is less than the quota value,
2075 everything is fine. Once it exceeds it, the DHT is likely to begin
2076 dropping entries and the admin needs to reduce the number of numbers
2077 being published.
2079 10.3.20. DHTLifetime Attribute
2081 This attribute is a 32 bit unsigned integer. It indicates the number
2082 of seconds that data written into the DHT will remain in the DHT
2083 prior to being expunged.
2085 11. Security Considerations
2087 11.1. Outsider Attacks
2089 VAP prevents against traditional outsider attacks by means of TLS
2090 along with password-based digest authentication. That mechanism MUST
2091 be implemented by clients and servers and SHOULD be used.
2093 11.2. Insider Attacks
2095 Of much more concern are attacks whereby the client is authenticated,
2096 but it misuses the VAP connection to attack the overall system.
2098 The principal attack to be considered is where an attacker injects
2099 false numbers by sending Publish requests for the number service
2100 containing numbers that the client doesn't own. This attack is the
2101 fundamental security problem that ViPR overall addresses with the
2102 validation mechanism, and so that attack is handled outside of VAP.
2104 Another potential attack is a flooding attack where a client sends a
2105 large amount of numbers into the DHT. This attack is prevented by
2106 the distributed quota mechanism within the ViPR RELOAD usage, and
2107 thus prevented outside of VAP. Similarly, an attacker might try to
2108 DOS the ViPR network by sending a large volume of reads or writes
2109 into the DHT. This is prevented by means of the rate control
2110 mechanisms enforced by the ViPR server.
2112 12. IANA Considerations
2114 There are no IANA considerations associated with this specification.
2116 13. References
2118 13.1. Normative References
2120 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
2121 Requirement Levels", BCP 14, RFC 2119, March 1997.
2123 [RFC3261] Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,
2124 A., Peterson, J., Sparks, R., Handley, M., and E.
2125 Schooler, "SIP: Session Initiation Protocol", RFC 3261,
2126 June 2002.
2128 [RFC5389] Rosenberg, J., Mahy, R., Matthews, P., and D. Wing,
2129 "Session Traversal Utilities for NAT (STUN)", RFC 5389,
2130 October 2008.
2132 [RFC0791] Postel, J., "Internet Protocol", STD 5, RFC 791,
2133 September 1981.
2135 [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
2136 Leach, P., Luotonen, A., and L. Stewart, "HTTP
2137 Authentication: Basic and Digest Access Authentication",
2138 RFC 2617, June 1999.
2140 [RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
2141 Hashing for Message Authentication", RFC 2104,
2142 February 1997.
2144 [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
2145 Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
2146 Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
2148 [VIPR-PVP]
2149 Rosenberg, J., Jennings, C., and M. Petit-Huguenin, "The
2150 Public Switched Telephone Network (PSTN) Validation
2151 Protocol (PVP)", draft-rosenberg-dispatch-vipr-pvp-03
2152 (work in progress), October 2010.
2154 13.2. Informative References
2156 [VIPR-OVERVIEW]
2157 Rosenberg, J., Jennings, C., and M. Petit-Huguenin,
2158 "Verification Involving PSTN Reachability: Requirements
2159 and Architecture Overview",
2160 draft-rosenberg-dispatch-vipr-overview-04 (work in
2161 progress), October 2010.
2163 Appendix A. Release notes
2165 This section must be removed before publication as an RFC.
2167 A.1. Modifications between rosenberg-03 and rosenberg-02
2168 o Nits.
2169 o Shorter I-Ds references.
2170 o Added terminology section.
2171 o Changed figures to fit in the page width.
2172 o Change reference from RFC 2401 to RFC 2104
2173 o Removed cut & paste error from STUN.
2174 o Fixed some invalid lists.
2175 o Section 9.1: Removed mutual authentication to be consistent with
2176 5.1.
2177 o Fixed the text for the creation of the resource name in 9.4.2, to
2178 be consistent with -reload-usage.
2179 o Fixed example to really contain hexadecimal.
2181 Authors' Addresses
2183 Cullen Jennings
2184 Cisco
2185 170 West Tasman Drive
2186 MS: SJC-21/2
2187 San Jose, CA 95134
2188 USA
2190 Phone: +1 408 421-9990
2191 Email: fluffy@iii.ca
2193 Jonathan Rosenberg
2194 jdrosen.net
2195 Monmouth, NJ
2196 US
2198 Email: jdrosen@jdrosen.net
2199 URI: http://www.jdrosen.net
2201 Marc Petit-Huguenin
2202 Stonyfish
2204 Email: marc@stonyfish.com