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