[Docs] [txt|pdf|xml|html] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02

vipr                                                         C. Jennings
Internet-Draft                                                     Cisco
Intended status:  Standards Track                           J. Rosenberg
Expires:  September 6, 2012                                  jdrosen.net
                                                       M. Petit-Huguenin
                                                               Stonyfish
                                                           March 5, 2012


Verification Involving PSTN Reachability: The ViPR Access Protocol (VAP)
                       draft-jennings-vipr-vap-02

Abstract

   Verification Involving PSTN Reachability (ViPR) is a technique for
   inter-domain SIP federation.  ViPR hybridizes the PSTN, P2P networks,
   and SIP, and in doing so, addresses the phone number routing and VoIP
   spam problems that have been a barrier to federation.  The ViPR
   architecture uses a server, the ViPR server, which performs P2P and
   validation services on behalf of call agents, which acts as clients
   to the server.  Such an architecture requires a client/server
   protocol between call agents and the ViPR server.  That protocol,
   defined here, is called the ViPR Access Protocol (VAP).

Legal

   This documents and the information contained therein are provided on
   an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE
   REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE
   IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL
   WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
   WARRANTY THAT THE USE OF THE INFORMATION THEREIN WILL NOT INFRINGE
   ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
   FOR A PARTICULAR PURPOSE.

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at http://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference



Jennings, et al.        Expires September 6, 2012               [Page 1]


Internet-Draft            ViPR Access Protocol                March 2012


   material or to cite them other than as "work in progress."

   This Internet-Draft will expire on September 6, 2012.

Copyright Notice

   Copyright (c) 2012 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

































Jennings, et al.        Expires September 6, 2012               [Page 2]


Internet-Draft            ViPR Access Protocol                March 2012


Table of Contents

   1.  Introduction to ViPR . . . . . . . . . . . . . . . . . . . . .  5
   2.  Overview of VAP  . . . . . . . . . . . . . . . . . . . . . . .  5
   3.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  7
   4.  VAP Message Structure  . . . . . . . . . . . . . . . . . . . .  8
   5.  VAP Transactions . . . . . . . . . . . . . . . . . . . . . . . 10
     5.1.  Transport and Connection Management  . . . . . . . . . . . 11
     5.2.  Requestor Procedures . . . . . . . . . . . . . . . . . . . 11
       5.2.1.   Generating Requests . . . . . . . . . . . . . . . . . 12
       5.2.2.   Receiving Responses . . . . . . . . . . . . . . . . . 12
     5.3.  Responder Behaviors  . . . . . . . . . . . . . . . . . . . 13
       5.3.1.   Receiving Requests  . . . . . . . . . . . . . . . . . 13
       5.3.2.   Sending Responses . . . . . . . . . . . . . . . . . . 14
   6.  State Model  . . . . . . . . . . . . . . . . . . . . . . . . . 14
   7.  Protocol Versioning  . . . . . . . . . . . . . . . . . . . . . 17
   8.  ViPR Client Procedures . . . . . . . . . . . . . . . . . . . . 18
     8.1.  Discovery  . . . . . . . . . . . . . . . . . . . . . . . . 18
     8.2.  Registration . . . . . . . . . . . . . . . . . . . . . . . 18
     8.3.  Unregistering  . . . . . . . . . . . . . . . . . . . . . . 20
     8.4.  Publishing Services  . . . . . . . . . . . . . . . . . . . 20
       8.4.1.   VService  . . . . . . . . . . . . . . . . . . . . . . 21
       8.4.2.   ViPR Number Service . . . . . . . . . . . . . . . . . 23
     8.5.  Updating the VService  . . . . . . . . . . . . . . . . . . 24
     8.6.  Uploading VCRs . . . . . . . . . . . . . . . . . . . . . . 25
     8.7.  Subscribing to Number Service  . . . . . . . . . . . . . . 25
     8.8.  Unsubscribing to Services  . . . . . . . . . . . . . . . . 26
     8.9.  Receiving Notify . . . . . . . . . . . . . . . . . . . . . 27
     8.10. Receiving PublishRevoke  . . . . . . . . . . . . . . . . . 27
   9.  ViPR Server Procedures . . . . . . . . . . . . . . . . . . . . 27
     9.1.  Connection Establishment . . . . . . . . . . . . . . . . . 28
     9.2.  Registration . . . . . . . . . . . . . . . . . . . . . . . 28
     9.3.  Unregistration . . . . . . . . . . . . . . . . . . . . . . 29
     9.4.  Publication  . . . . . . . . . . . . . . . . . . . . . . . 29
       9.4.1.   VService  . . . . . . . . . . . . . . . . . . . . . . 29
       9.4.2.   ViPR Number Service . . . . . . . . . . . . . . . . . 31
     9.5.  Unpublish  . . . . . . . . . . . . . . . . . . . . . . . . 33
     9.6.  Subscribe  . . . . . . . . . . . . . . . . . . . . . . . . 33
     9.7.  Unsubscribe  . . . . . . . . . . . . . . . . . . . . . . . 34
     9.8.  UploadVCR  . . . . . . . . . . . . . . . . . . . . . . . . 34
       9.8.1.   Originating . . . . . . . . . . . . . . . . . . . . . 35
       9.8.2.   Terminating . . . . . . . . . . . . . . . . . . . . . 36
     9.9.  Sending Notify . . . . . . . . . . . . . . . . . . . . . . 36
     9.10. Sending PublishRevoke  . . . . . . . . . . . . . . . . . . 37
   10. Syntax Details . . . . . . . . . . . . . . . . . . . . . . . . 37
     10.1. XML Schema for VService  . . . . . . . . . . . . . . . . . 37
     10.2. XML Schema for ValInfo . . . . . . . . . . . . . . . . . . 39
     10.3. VAP Attributes . . . . . . . . . . . . . . . . . . . . . . 39



Jennings, et al.        Expires September 6, 2012               [Page 3]


Internet-Draft            ViPR Access Protocol                March 2012


       10.3.1.  USERNAME  . . . . . . . . . . . . . . . . . . . . . . 40
       10.3.2.  REALM . . . . . . . . . . . . . . . . . . . . . . . . 40
       10.3.3.  MESSAGE-INTEGRITY . . . . . . . . . . . . . . . . . . 41
       10.3.4.  ERROR-CODE  . . . . . . . . . . . . . . . . . . . . . 41
       10.3.5.  Client-Name . . . . . . . . . . . . . . . . . . . . . 43
       10.3.6.  Client-Handle . . . . . . . . . . . . . . . . . . . . 43
       10.3.7.  Protocol-Version  . . . . . . . . . . . . . . . . . . 43
       10.3.8.  Client-Label  . . . . . . . . . . . . . . . . . . . . 43
       10.3.9.  Keepalive . . . . . . . . . . . . . . . . . . . . . . 44
       10.3.10. ServiceIdentity . . . . . . . . . . . . . . . . . . . 44
       10.3.11. ServiceVersion  . . . . . . . . . . . . . . . . . . . 44
       10.3.12. ServiceContent  . . . . . . . . . . . . . . . . . . . 44
       10.3.13. SubscriptionID  . . . . . . . . . . . . . . . . . . . 45
       10.3.14. CallDirection . . . . . . . . . . . . . . . . . . . . 45
       10.3.15. StartTime . . . . . . . . . . . . . . . . . . . . . . 45
       10.3.16. StopTime Attribute  . . . . . . . . . . . . . . . . . 45
       10.3.17. CallingNum Attribute  . . . . . . . . . . . . . . . . 45
       10.3.18. CalledNum Attribute . . . . . . . . . . . . . . . . . 46
       10.3.19. Quota Attribute . . . . . . . . . . . . . . . . . . . 46
       10.3.20. DHTLifetime Attribute . . . . . . . . . . . . . . . . 47
   11. Security Considerations  . . . . . . . . . . . . . . . . . . . 47
     11.1. Outsider Attacks . . . . . . . . . . . . . . . . . . . . . 47
     11.2. Insider Attacks  . . . . . . . . . . . . . . . . . . . . . 47
   12. IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 47
   13. References . . . . . . . . . . . . . . . . . . . . . . . . . . 47
     13.1. Normative References . . . . . . . . . . . . . . . . . . . 47
     13.2. Informative References . . . . . . . . . . . . . . . . . . 48
   Appendix A.  Release notes . . . . . . . . . . . . . . . . . . . . 48
     A.1.  Modifications between rosenberg-03 and rosenberg-02  . . . 48
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 49





















Jennings, et al.        Expires September 6, 2012               [Page 4]


Internet-Draft            ViPR Access Protocol                March 2012


1.  Introduction to ViPR

   [VIPR-OVERVIEW] introduces a new technology, called Verification
   Involving PSTN Reachability (ViPR), which enables VoIP federation
   between domains, over the Internet.  ViPR is a hybrid technology that
   combines together the PSTN, P2P networks, and SIP.  In doing so, it
   addresses the phone number routing problem and anti-spam problems
   that have been the most significant barriers to widespread deployment
   of SIP inter-domain federation.

   It is assumed that readers of this document have read and understood
   [VIPR-OVERVIEW].

   One of the key protocols used in ViPR is the ViPR Access Protocol
   (VAP).  VAP connects call agents, such as phones, SBCs and IP PBXs,
   to a ViPR server.  This document defines the VAP protocol in detail.


2.  Overview of VAP

   A high level view on the ViPR architecture is shown in Figure 1.
   This architecture is discussed in more detail in [VIPR-OVERVIEW].





























Jennings, et al.        Expires September 6, 2012               [Page 5]


Internet-Draft            ViPR Access Protocol                March 2012


                       +-+            +-+
                       | |            | |   +------+
                       | |      +-----| |---|Enroll|
                       | |      |     | |   +------+
                       |I|      |     |I|
                       |n|   +-----+  |n|
                VAP    |t|   | ViPR|  |t|
            +----------|r|---|Srvr |--|e|-----------------
            |          |a|   |     |  |r|   P2P-Validation
            |          |n|   +-----+  |n|
            |          |e|            |e|
            |          |t|            |t|
         +-----+  SIP  | |   +-----+  | |
         | CA  |-------|F|---|     |--|F| ---------------
         +-----+       |i|   |     |  |i|  SIP/TLS
            .          |r|   |  .  |  |r|
     SIP/   .          |e|   |     |  |e|
     MGCP/  .          |w|   | BE  |  |w|
     TDM    .          |a|   |     |  |a|
            .          |l|   |     |  |l|
         +-----+       |l|   |     |  |l|
         | UA  |-------| |---|     |--| |-----------------
         +-----+       | |   +-----+  | |   SRTP
                       | |            | |
                       +-+            +-+
    |                                      |
    +--------------------+-----------------+
                         |
            Single administrative domain

                          Figure 1: Architecture

   A key component of this architecture is the ViPR server.  The ViPR
   server is responsible for connecting to the P2P network, publishing
   phone numbers into that network, performing validation, and learning
   new routes.  The ViPR server performs those functions on behalf of
   one or more call agents.  This requires a protocol to run between the
   call agents and the ViPR server.  This protocol is called VAP - the
   ViPR Access Protocol.

   VAP is a client-server protocol that runs between the call agent and
   the ViPR server.  VAP is a simple, binary based, request/response
   protocol.  It utilizes the same syntactic structure and transaction
   state machinery as STUN [RFC5389], but otherwise is totally distinct
   from it.  VAP clients initiate TCP/TLS connections towards the ViPR
   server.  The ViPR server never opens connections towards the call
   agent.  This allows the ViPR servers to run on the public side of
   NATs and firewalls.



Jennings, et al.        Expires September 6, 2012               [Page 6]


Internet-Draft            ViPR Access Protocol                March 2012


   Once the connections are established, the call agent sends a Register
   message to the ViPR server.  This register message primarily provides
   authentication and connects the client to the ViPR server.  VAP
   provides several messages for different purposes:
   o  Publish:  The Publish message informs the ViPR server of service
      information.  There are two types of Publishes supported in ViPR.
      The first is the ViPR Service (VService).  This informs the ViPR
      server of the SIP URIs on the call agent and black and white lists
      used by the ViPR server to block validations.  The ViPR server
      stores that information locally and uses it during the validation
      process, as described above.  The second Publish is the ViPR
      Number Service.  The ViPR server, upon receiving this message,
      performs a Store operation into the DHT.
   o  UploadVCR:  This message comes in two flavors - an originating and
      terminating message.  An originating UploadVCR comes from a call
      agent upon completion of a non-ViPR call to the PSTN.  A
      terminating UploadVCR comes from an agent upon completion of a
      call received FROM the PSTN.  The ViPR server behavior for both
      messages is very different.  For originating UploadVCR, the ViPR
      server will store these, and at a random time later, query the DHT
      for the called number and attempt validation against the ViPR
      servers that are found.  For a terminating UploadVCR, the ViPR
      server will store these, awaiting receipt of a validation against
      them.
   o  Subscribe:  Call agents can subscribe for information from the
      ViPR server.  There is one service that call agent can subscribe
      for:  Number Service.  When a new number is validated, the ViPR
      server will send a Notify to the call agent, containing the
      validated number, the ticket, and a set of SIP trunk URIs.
   o  Notify:  The ViPR server sends this message to the call agent when
      it has an event to report for a particular subscription.

   The VAP protocol provides authentication by including an integrity
   object in each message.  This integrity message is the hash of the
   contents of the message and a shared secret between the ViPR server
   and the client.  VAP can also be run over TLS, which enhances
   security further.


3.  Terminology

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].







Jennings, et al.        Expires September 6, 2012               [Page 7]


Internet-Draft            ViPR Access Protocol                March 2012


4.  VAP Message Structure

   VAP messages follow the syntax and structure of Session Traversal
   Utilities for NAT (STUN) [RFC5389].  It also shares the same
   transaction model as STUN.  However, aside from its common syntax and
   transaction model, STUN and VAP are unrelated.

   VAP messages are encoded in binary using network-oriented format
   (most significant byte or octet first, also commonly known as big-
   endian).  The transmission order is described in detail in Appendix B
   of RFC791 [RFC0791].  Unless otherwise noted, numeric constants are
   in decimal (base 10).

   All VAP messages MUST start with a 20-byte header followed by zero or
   more Attributes.  The VAP header contains a VAP message type, message
   length, magic cookie and transaction ID.

       0                   1                   2                   3
       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
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |0 0|     VAP Message Type      |         Message Length        |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |                         Magic Cookie                          |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      |                                                               |
      |                     Transaction ID (96 bits)                  |
      |                                                               |
      +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                  Figure 2: Format of VAP Message Header

   The most significant two bits of every VAP message MUST be zeroes.

   The message type defines the message class (request, success
   response, failure response) and the message method (the primary
   function) of the VAP message.  Although there are four message
   classes, there is only one type of transaction in VAP:  request/
   response transactions (which consist of a request message and a
   response message).  Response classes are split into error and success
   responses to aid in quickly processing the VAP message.











Jennings, et al.        Expires September 6, 2012               [Page 8]


Internet-Draft            ViPR Access Protocol                March 2012


   The message type field is decomposed further into the following
   structure:

                        0                 1
                        2  3  4 5 6 7 8 9 0 1 2 3 4 5

                       +--+--+-+-+-+-+-+-+-+-+-+-+-+-+
                       |M |M |M|M|M|C|M|M|M|C|M|M|M|M|
                       |11|10|9|8|7|1|6|5|4|0|3|2|1|0|
                       +--+--+-+-+-+-+-+-+-+-+-+-+-+-+

                Figure 3: Format of VAP Message Type Field

   Here the bits in the message type field are shown as most-significant
   (M11) through least-significant (M0).  M11 through M0 represent a 12-
   bit encoding of the method.  C1 and C0 represent a 2 bit encoding of
   the class.  A class of 0b00 is a Request, a class of 0b10 is a
   success response, and a class of 0b11 is an error response.  The
   method and class are orthogonal, so that for each method, a request,
   success response, error response and indication are defined for that
   method.

   The magic cookie field MUST contain the fixed value 0x41666679 in
   network byte order (note that this is a different value than STUN).

   The transaction ID is a 96 bit identifier, used to uniquely identify
   VAP transactions.  For request/response transactions, the transaction
   ID is chosen by the VAP client for the request and echoed by the
   server in the response.  The transaction ID MUST be uniformly and
   randomly chosen from the interval 0 .. 2**96-1, and SHOULD be
   cryptographically random.  The client MUST choose a new transaction
   ID for new transactions.  Success and error responses MUST carry the
   same transaction ID as their corresponding request.

   The message length MUST contain the size, in bytes, of the message
   not including the 20 byte VAP header.  Since all VAP attributes are
   padded to a multiple of four bytes, the last two bits of this field
   are always zero.

   Following the VAP fixed portion of the header are zero or more
   attributes.  Each attribute is TLV (type-length-value) encoded.  The
   details of the attributes themselves is given in Section 10.3.

   The methods defined in VAP, and their corresponding method values,
   are:






Jennings, et al.        Expires September 6, 2012               [Page 9]


Internet-Draft            ViPR Access Protocol                March 2012


                          Method            Value
                          ------           ------
                          Register          0x001
                          Unregister        0x002
                          Publish           0x004
                          Unpublish         0x005
                          PublishRevoke     0x006
                          Subscribe         0x007
                          Unsubscribe       0x008
                          Notify            0x00a
                          UploadVCR         0x00b

                           Figure 4: VAP Methods

   After the VAP header are zero or more attributes.  Each attribute is
   TLV encoded, with a 16 bit type, 16 bit length, and variable value.
   Each attribute MUST end on a 32 bit boundary:

      0                   1                   2                   3
      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |         Type                  |            Length             |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                             Value                 ....        |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                         Figure 5: VAP Attributes

   The Length refers to the length of the actual useful content of the
   Value portion of the attribute, measured in bytes.  Since VAP aligns
   attributes on 32 bit boundaries, attributes whose content is not a
   multiple of 4 bytes are padded with 1, 2 or 3 bytes of padding so
   that they are a multiple of 4 bytes.  Such padding is only needed
   with attributes that take freeform strings, such as USERNAME.  For
   attributes that contain more structured data, the attributes are
   constructed to align on 32 bit boundaries.  The value in the Length
   field refers to the length of the Value part of the attribute prior
   to padding - i.e., the useful content.  Consequently, when parsing
   messages, implementations will need to round up the Length field to
   the nearest multiple of four in order to find the start of the next
   attribute.


5.  VAP Transactions

   This section describes the general behavior of VAP transactions,
   regardless of the method.




Jennings, et al.        Expires September 6, 2012              [Page 10]


Internet-Draft            ViPR Access Protocol                March 2012


5.1.  Transport and Connection Management

   VAP runs only over TCP.  UDP is not supported.  As a consequence,
   transactions are simple.  For each transaction, the client sends a
   single request, and the server sends a response.

   VAP can also be run over TLS.  The server MUST implement TLS, and the
   client SHOULD utilize it.  The TLS_RSA_WITH_AES_128_CBC_SHA
   ciphersuite MUST be implemented.  The client MUST verify that the
   server certificate matches a configured value associated with the
   ViPR server that is to be used.  The server MUST accept any
   certificate from the client.  Client authentication is performed
   using a simple digest technique.

   Reliability of VAP over TCP and TLS-over-TCP is handled by TCP
   itself, and there are no retransmissions at the VAP protocol level.
   However, for a request/response transaction, if the client has not
   received a response by Ti seconds after it sent the SYN to establish
   the connection, it considers the transaction to have timed out.  Ti
   SHOULD be configurable and SHOULD have a default of 39.5s.

   In addition, if the client is unable to establish the TCP connection,
   or the TCP connection is reset or fails before a response is
   received, any request/response transaction in progress is considered
   to have failed.

   The client MAY send multiple transactions over a single TCP (or TLS-
   over-TCP) connection, and it MAY send another request before
   receiving a response to the previous.  The client SHOULD keep the
   connection open until it
   o  has no further VAP requests to send over that connection, and;
   o  has no outstanding subscriptions

   At the server end, the server SHOULD keep the connection open, and
   let the client close it, unless the server has determined that the
   connection has timed out (for example, due to the client
   disconnecting from the network).  The server SHOULD NOT close a
   connection if a request was received over that connection for which a
   response was not sent.  A server MUST NOT ever open a connection back
   towards the client in order to send a response.  Servers SHOULD
   follow best practices regarding connection management in cases of
   overload.

5.2.  Requestor Procedures

   Though VAP is a client/server protocol, the ViPR server can
   asynchronously send requests towards the client call agent.  As such,
   this section defines transaction rules in terms of the requestor (the



Jennings, et al.        Expires September 6, 2012              [Page 11]


Internet-Draft            ViPR Access Protocol                March 2012


   entity sending the request) and the responder (the entity receiving
   the request).

5.2.1.  Generating Requests

   The requestor MUST construct a request message based on the syntax in
   Section 4.  The message class MUST be a request.  The method depends
   on the method of the request.

   The requestor MUST add a MESSAGE-INTEGRITY, REALM and USERNAME
   attribute to the request message.  The USERNAME contains a string
   which is the provisioned username identifying the client to the VAP
   server.  The REALM attribute MUST have the value of "ViPR".  The
   MESSAGE-INTEGRITY is computed as described in Section 10.3.3.  That
   computation relies on a 16-byte key.  The 16-byte key for MESSAGE-
   INTEGRITY HMAC is formed by taking the MD5 hash of the result of
   concatenating the following five fields:  (1) The username, with any
   quotes and trailing nulls removed, (2) A single colon, (3) The realm,
   with any quotes and trailing nulls removed, (4) A single colon, and
   (5) The password, with any trailing nulls removed.  Note that the
   password itself never appears in the message.

   This format for the key was chosen so as to enable a common
   authentication database for SIP, which uses digest authentication as
   defined in RFC 2617 [RFC2617].

   The request will contain other attributes depending on the method.

5.2.2.  Receiving Responses

   All responses MUST first be authenticated by the requestor.
   Authentication is performed by first comparing the Transaction ID of
   the response to an outstanding request.  If there is no match, the
   requestor MUST discard the response.  Then the requestor SHOULD check
   the response for a MESSAGE-INTEGRITY attribute.  If not present, it
   MUST discard the response, except for error responses with response
   codes 431 and 436.  If MESSAGE-INTEGRITY is present, the requestor
   computes the HMAC over the response.  The key that is used MUST be
   same as used to compute the MESSAGE-INTEGRITY attribute in the
   request.

   If the computed HMAC matches the one from the response, processing
   continues.  If the response was discarded, in cases where the failure
   is due to an implementation error, this will cause timeout of the
   transaction.

   If the response is an Error Response, the requestor checks the
   response code from the ERROR-CODE attribute of the response.  For a



Jennings, et al.        Expires September 6, 2012              [Page 12]


Internet-Draft            ViPR Access Protocol                March 2012


   400 (Bad Request) response code, the requestor SHOULD generate an
   alarm (a notification here refers to some kind of indication, sent to
   the administrator of the system, indicating an error condition.
   Notification mechanisms include SNMP alarms, logs, syslog, and so on,
   and are a matter of local implementation) containing the reason
   phrase.

   For a 431 (Integrity Check Failure) response code, this is typically
   caused by a mis-provisioning of the password.  The requestor SHOULD
   generate an alarm and SHOULD NOT retry.

   If the requestor receives a 436 (Unknown Username) response, it means
   that the username it provided in the request is unknown.  This is
   typically due to a provisioning error, a consequence of a mismatched
   username.  The requestor SHOULD generate an alarm.

   The requestor MUST ignore any attributes from the response whose
   attribute type were not understood by the requestor.

5.3.  Responder Behaviors

5.3.1.  Receiving Requests

   A responder will receive requests on an existing TCP connection,
   either one initiated by the client, or the one accepted by the ViPR
   server.

   If a responder cannot process a request because the request does not
   meet the syntactic requirements necessary for the processing
   described below, the responder SHOULD reject the request with an
   error response and include an ERROR-CODE attribute with a response
   code of 400 (Bad Request).  If the request is so malformed that a
   response cannot be generated, the request is just dropped.  Error
   codes for specific failures are not provided, since these failures
   would not be seen in a functionally correct system.  The protocol
   only provides error codes for errors that can arise due to
   misconfiguration or network error.  Note, however, that a responder
   SHOULD NOT verify that a requestor has generated the request in full
   compliance to this specification; it should only validate what it
   needs to perform the processing described for handling the request.

   First, the responder authenticates the request.  The request will
   contain a USERNAME, REALM, and MESSAGE-INTEGRITY attribute.  If the
   USERNAME is unknown, the responder generates an error response with
   an ERROR-CODE attribute with a response code of 436 (Unknown
   Username).  The response MUST include the REALM, but MUST omit the
   MESSAGE-INTEGRITY attribute.




Jennings, et al.        Expires September 6, 2012              [Page 13]


Internet-Draft            ViPR Access Protocol                March 2012


   The responder computes the HMAC over the request.  If the computed
   HMAC differs from the one from the MESSAGE-INTEGRITY attribute in the
   request, the responder MUST generate an error response with an ERROR-
   CODE attribute with a response code of 431 (Integrity Check Failure).
   This response MUST include a REALM but MUST omit the MESSAGE-
   INTEGRITY attribute.

   The responder MUST ignore any attributes from the request whose
   attribute type were not understood by the responder.

5.3.2.  Sending Responses

   To construct the response the responder follows the message structure
   described in Section 4.  The message type MUST indicate either a
   success response or error response class and MUST indicate the same
   method as the request.  The responder MUST copy the transaction ID
   from the request to the response.

   The attributes that get added to the response depend on the type of
   response.

   When sending an error response, the server MUST add an ERROR-CODE
   attribute containing the error code.  The reason phrase is not fixed,
   but SHOULD be something suitable for the error code.

   All responses except for an error response with ERROR-CODE of 431 and
   436 will contain a MESSAGE-INTEGRITY attribute.  All responses will
   contain a REALM attribute.  The computation of the message integrity
   is based on the same username value present in the request (along
   with its corresponding password); however the response SHOULD NOT
   contain the USERNAME attribute.

   All responses MUST be sent on the same TCP connection on which the
   request was received.  If this connection has closed, the responder
   MUST NOT open a new connection in order to try to send the response.
   The transaction is considered failed in this case.


6.  State Model

   The state model for VAP is shown in Figure Figure 6.  This state is
   built up as a consequence of the primary messages which build state
   on the ViPR server:  Register, Publish, UploadVCR and Subscribe.








Jennings, et al.        Expires September 6, 2012              [Page 14]


Internet-Draft            ViPR Access Protocol                March 2012


       +-------+
       |Handle |
       +-------+
          ^1                                            1 +----+
          |1                                    +-------->|DHT |
       +-------+       n+--------+ n            |         +----+
       |Client |<-------|Instance|<------+      |
       +-------+        +--------+       |      |       1 +----------+
          |                 |            |      | +------>|BlackWhite|
          |                 |            |      | |       +----------+
          Vn                |         +-------------+
       +------------+       |         |             |   1 +---------+
       |Subscription|       V         | VService    |---->|NumCount |
       +------------+    +-----+      +-------------+     +---------+
                         |route|           |1    |
                         +-----+           |     |      1 +--------+
                                           |     +------->|domain  |
                                           |1             +--------+
                                     +----------+
                                     |VServiceID|
                                     +----------+
                                      |1      |1
                                      |       |
                                      Vn      Vn
                               +--------+    +--------+
                               |OrigVCR |    |TermVCR |
                               +--------+    +--------+


                         Figure 6: VAP State Model

   It is important to understand that the ViPR client publishes two
   unique sets of information to the ViPR server:

   1.  The set of numbers that are reachable by the client through a
   particular ViPR service,

   2.  The set of ViPR services

   Both of these are uploaded from the client to the ViPR server using a
   VAP Publish operation.  The ViPR clients have the concept of a "ViPR
   Service" (not to be confused with ViPR server).  A ViPR service is a
   unique instance of ViPR processing in a call agent - and is
   associated with a specific DHT, specific routes, specific domain,
   specific set of numbers to use, and specific set of policies
   governing operation.  When a client publishes a number, it is always
   associated with a specific ViPR service, or VService.  Multiple
   clients can publish the same VServices, and they will differ only in



Jennings, et al.        Expires September 6, 2012              [Page 15]


Internet-Draft            ViPR Access Protocol                March 2012


   the routes associated with that VService, as each client will have
   its own route to reach the same VService.

   The ViPR server actively tracks the association of clients,
   VServices, routes, DHTs, BlackWhite lists, and VServiceIDs.  Number
   publications and VService publications are differentiated from each
   other by different serviceID values in attributes in the Publish
   request.  To be thoroughly confusing, this serviceID is not the same
   as a VServiceID.  ServiceID refers to whether something is a VService
   publication or number publication, and is an enumerated value,
   whereas a VServiceID is an instance ID for a particular VService.
   The ViPR server only actually stores the VService publications; when
   receiving a Publish for a number service, the corresponding data is
   written directly to the DHT and then forgotten by the ViPR server.
   The ViPR server doesn't take any responsibility for removing the
   state or for keeping it fresh.  All of this is the responsibility of
   the ViPR client.  Consequently, VAP itself is not responsible for
   maintaining this information.

   Firstly, when a client connects, it will Register to the ViPR server.
   That creates an instance of the client object, which is assigned a
   unique handle that identifies it.  The client object is one of the
   key pieces of state (ViPR service being the other).  All subsequent
   messaging from the client includes that Client-Handle, allowing the
   ViPR server to immediately determine the client associated with the
   messaging.

   The client can issue subscriptions for services over its connection
   to the ViPR server.  The ViPR server remembers the set of
   subscriptions from that client.

   The VService publication builds the next large block of state.  When
   a VService publication is received from a client, the ViPR server
   creates the VService object if it didn't have one yet for that
   VServiceID.  Each distinct instance of a VService publication gets
   linked to it, and each distinct instance is, in turn, associated with
   one or more routes.  Each route has a SIP URI, but the internal
   structure of the route is opaque to the ViPR server.  It parses no
   deeper than the route element itself; the contents are not parsed,
   examined or checked by the ViPR server.  This allows for future
   extensibility on how call routing is done.  The VService itself has a
   numberCount, domain, BlackWhite list and DHT, all of which are
   learned from the VService publication.  The VServiceID is 1-1
   associated with each VService.

   Finally, each UploadVCR, whether it is originating or terminating,
   contains a VServiceID as well.  This binds it to a particular
   VService.  It is important to note that, the linkage from VCRs to



Jennings, et al.        Expires September 6, 2012              [Page 16]


Internet-Draft            ViPR Access Protocol                March 2012


   VServices is indirect, through the VServiceID.  This allows a
   temporary outage to break all client connections, which will delete
   the VService objects, but keep the VCRs and the VServiceIDs.  When
   the clients reconnect, the VServices are rebuilt, along with their
   IDs, and once again can be linked to the VCRs.

   When the VAP connection terminates, the client object and
   subscription state from the corresponding client is destroyed.  Any
   instances of a VService from that client are destroyed.  If there are
   no longer any instances of the VService left, the VService itself is
   destroyed.  The VCRs are not affected by the termination of a
   connection from a client.

   When the client TCP connection breaks or keepalives cease to be sent,
   the ViPR server will remove the registration, subscription and
   VServiceID to SIP trunk/DHT mappings.  Similarly, on the client side,
   if the TCP connection breaks, the client must create a new TCP
   connection, register without a handle, subscribe and performs its
   VService publications.

   The VAP state above is, in addition, utterly and completely
   orthogonal to the state of the DHT itself.  That state is driven
   through number service publications, which cause storage operations
   into the DHT.


7.  Protocol Versioning

   Each version of VAP has a major and minor version number.  This
   specification describes major version 1, minor version 0.  It is
   anticipated that the protocol may require updating in the future.

   If an update can be done such that an older client will work with a
   newer server, and an older server with a newer client, this MUST be
   done using an increase in the minor version number within the major
   version.  This would typically include bug fixes and minor
   extensions.  If a protocol change is such that it cannot be
   understood by previous servers and clients, this MUST be done using
   an increase in the major version number of the protocol.

   This specification further requires that, in addition to the most
   recent version of the protocol they understand, a client MUST
   understand the previous major version number.  For example, a client
   supporting version 2.1 would also need to support version 1.0.

   The protocol version number is included in client register messages,
   and negotiation as part of that exchange.




Jennings, et al.        Expires September 6, 2012              [Page 17]


Internet-Draft            ViPR Access Protocol                March 2012


   This allows for a graceful upgrade procedure.  When a new version of
   the protocol is to be rolled out, the clients are upgraded first,
   each in turn.  When they are upgraded, they'll come back, but during
   registration, notices that the servers only support a previous major
   version.  The clients thus switch to the previous version of the
   protocol.  Once all of the clients are updated, the servers can be
   updated.  When the clients connect to them, they will utilize the
   newest version of the protocol.


8.  ViPR Client Procedures

8.1.  Discovery

   VAP provides no discovery mechanism.  The client must be provisioned
   with the domain names and/or IP addresses and ports of its ViPR
   servers.  Typically, a client will be provisioned with two servers -
   a primary and a backup.

8.2.  Registration

   Once a TCP connection is established, the client MUST perform a
   registration.  This applies to all TCP connections held by the client
   for purposes of high availability.

   The client constructs a Register request based on the basic client
   procedures in Section 5.2.  In addition, the client MUST include the
   Client-Name attribute.  This field is used strictly for debugging
   purposes and indicates the name of the client to the server.

   If the client is registering for the first time towards this ViPR
   server, the registration MUST omit the Client-Handle attribute.

   If the client is registering for the first time towards this ViPR
   server (and thus there was not Client-Handle attribute), the client
   MUST include a Protocol-Version attribute in the request.  This
   includes the major and minor version number of the most recent
   version of the protocol supported by the client.  For purposes of
   extensibility, in addition to their current version of the client
   protocol, a client MUST support the previous major version as well.

   The client MUST include the Client-Label attribute in the request.
   However, it is not used and its contents are arbitrary.

   Once constructed, the client sends the Register request to the ViPR
   server.  The response is processed using the general techniques in
   Section 5.2.  Assuming a success response is ultimately received, it
   indicates that the client has successfully registered.  This response



Jennings, et al.        Expires September 6, 2012              [Page 18]


Internet-Draft            ViPR Access Protocol                March 2012


   will contain a Client-Handle attribute.  The client MUST retain this
   handle and store it for the lifetime of the clients connection to the
   server.  The response will also contain the Keepalive attribute,
   which tells the client how often it needs to keepalive its
   registration to the server.

   If the response to the initial Register request (one without a
   Client-Handle) is an error response with an ERROR-CODE attribute with
   a response code of 478, it means that the server does not support the
   major protocol version signaled by the client.  The client MUST
   extract the Protocol-Version attribute from the error response.  This
   attribute indicates the major and minor versions supported by the
   server.  Based on the principles in Section 7, the client will be
   able to support a version of the protocol that has a major protocol
   version matching the one in the Protocol-Version attribute of the
   error response.  The client MUST switch to this version of the
   protocol, and then MUST generate a new Register request (without a
   Client-Handle), indicating a Protocol-Version equal to the new, lower
   version of the protocol.

   If the response to the initial Register request (one without a
   Client-Handle) is an error response with an ERROR-CODE attribute with
   a response code of 477, it means that the server believes that the
   client has already registered on this connection.  There has been a
   state synchronization error.  The client SHOULD generate an alarm,
   and then tear down the TCP connection.  It MUST open a new TCP
   connection, and then generate a fresh Register request (without a
   Client-Handle) over that connection.

   If the Register message was for an existing connection (and thus a
   keepalive), and thus included the Client-Handle attribute in the
   request, but the response was a Register Error response with an
   ERROR-RESPONSE with a response code of 471, the client MUST consider
   this a failure of the connection.  It SHOULD attempt a new connection
   and a new Register, but without a Client-Handle.

   During an initial Register (one that omits Client-Handle), the client
   MUST NOT generate any subsequent requests until that Register
   transaction completes.

   If the TCP connection fails, the client needs to reconnect and create
   a new registration without the handle, and furthermore, resubscribe
   and republish as needed.  In other words, on the client side, the
   lifetime of the handle is equal to the lifetime of the TCP
   connection.  The server also holds onto the handle as long as the
   connection is active.  However, it will also watch for refreshes of
   registrations, and if it doesn't see one fast enough, remove the
   client registration, the handle, and state received from that client,



Jennings, et al.        Expires September 6, 2012              [Page 19]


Internet-Draft            ViPR Access Protocol                March 2012


   as well.

8.3.  Unregistering

   A Client that wishes to terminate its connection gracefully does so
   using the Unregister request.  This request is first constructed as
   described in Section 5.2.  Once constructed, the client MUST add the
   Client-Handle attribute to the request, and send it to the ViPR
   server.

   If the response was an error response and was of type 400, it means
   that the client did not construct the request properly.  The client
   MUST NOT retry unless it changes the content or set of attributes in
   the request to match the requirements defined here.

   If the response was an error response with an ERROR-RESPONSE
   attribute with a response code of 471, the client MUST consider this
   a failure of the connection.  It indicates a synchronization error
   between client and server.  The client SHOULD generate an alarm.

   If the response was an error response and was of type 474, it means
   that the client sent an Unregister request on a TCP connection but
   had not yet registered.  If the client had registered, there has been
   some kind of synchronization error.  The client SHOULD generate an
   alarm.

   In all cases, success or error responses, the client MUST consider
   all subscriptions to this server terminated, and consider all
   published VServices to this server as unpublished.  The client MUST
   terminate the TCP connection after the response has been received.

8.4.  Publishing Services

   Publish requests inform the ViPR server of information from the
   client.  There are two types, VService publications and number
   publications.  These differ in the value of the ServiceIdentity
   attribute.

   All publications contain a ServiceContent attribute which contains an
   XML element that defines the service.  The schema for the
   ServiceContent element depends on whether the publication is a
   VService or number publication.

   The Publish request MUST contain a ServiceVersion attribute.  This
   attribute is a version number that increments by at least one every
   time a particular service (identified by a unique VService, instance,
   service ID and sub-service ID value) changes in any way.  If the
   service data different from the previous published value, the



Jennings, et al.        Expires September 6, 2012              [Page 20]


Internet-Draft            ViPR Access Protocol                March 2012


   ServiceVersion attribute MUST increase.  If the service data is the
   same as the previous published value, the ServiceVersion SHOULD stay
   the same, but MAY increase.  Consequently, increasing version numbers
   are not a guarantee that there was a change; only that lack of
   increasing version number is a guarantee that there was no change.

   If a client loses track of the previous version number of the service
   (due, for example, to a restart), it MUST choose a new instance ID
   and then it can reset the ServiceVersion.

   Finally, the Publish Request MUST contain a ServiceContent attribute.
   This attribute contains the actual service data.  Its actual
   structure and syntax are a function of the service and sub-service.

   If the response was an error response and was of type 472, it means
   that the client didn't increment the sequence number.  More likely,
   it indicates that the client has inadvertently forgotten the version
   number of the service and gotten out of sync with the server.  The
   client SHOULD choose a new instance ID for this service, withdraw the
   old one, and publish the new one.

   If the response was an error response and was of type 474, it means
   that the client sent a Publish request on a TCP connection but had
   not yet registered.  If the client hadn't registered, it MUST now do
   so.  If it had registered, there has been some kind of
   synchronization error.  The client SHOULD generate an alarm.  Then,
   it MUST generate a new register (without the Client-Handle), flushing
   all subscriptions.

   If the response was an error response and was of type 400, it means
   that the client did not construct the request properly.  The client
   MUST NOT retry unless it changes the content or set of attributes in
   the request to match the requirements defined here.

   If the response was a success, the publication has been accepted.

8.4.1.  VService

   The VService indicates the critical information for the VService
   identified by the VService ID.  Typically, a call agent will run on
   many servers, each of which is listening for SIP traffic on a
   specific IP address and port.  Each such IP address and port forms a
   particular instance of the VService, and represents an alternative
   SIP destination for receiving incoming calls.  The instance ID is a
   unique identifier, within the scope of the VServiceID, which
   identifies that call agent server.

   The additional information placed into the VService publication will



Jennings, et al.        Expires September 6, 2012              [Page 21]


Internet-Draft            ViPR Access Protocol                March 2012


   not vary amongst different instances.  That information is:

   o  The DHT that the client wishes its numbers to be published into
      for this VService.  This must always be the name of the public
      ViPR DHT, which is "Quetzalcoatl".
   o  The domain name associated with this VService, e.g., example.com.
      This domain name is used by the ViPR server at the end of the
      validation process.
   o  The set of routes which can be used to reach a SIP server on the
      call agent instance.  Each route contains a SIP URI, in addition
      to extensions to allow for future advanced routing.  This
      parameter of the VService data is instance specific.
   o  a black/white list of domains.  These are used by the ViPR server
      during the validation protocol.  The white list contains the set
      of domains that this domain wishes to only federate with.  The
      black list contains the list of domains that this domain does not
      wish to federate with.
   o  A count of the number of phone numbers being published for this
      VService.  This is used for quota management on the ViPR server.

   Note that the VService does not contain phone numbers.  VService
   information is not stored into the DHT by the ViPR server.  It is
   stored locally on the ViPR server and used to support the validation
   protocol.

   Section 10.1 defines the XML schema for the object included in the
   Publish request.

   The SIP URI is constructed as follows:

   1.  The scheme MUST be sip.
   2.  The user part MUST be an identifier which is unique to this agent
       and is identical for all instances of that call agent.  For
       example, if a call agent consists of two servers for purposes
       availability, and either can be used, the user part will be
       identical in the SIP URI published by each server.
   3.  The domain part MUST be the domain associated with this call
       agent, and MUST match certificates that the domain can obtain.
   4.  There MUST be a port and it MUST be the port on which incoming
       SIP invites can be received.
   5.  There MUST be an maddr URI parameter, and it MUST contain the IP
       address or hostname of the instance of the call agent server.
   6.  The transport URI parameter MUST be present and MUST be TCP.

   There will be one or more URI per each instance of the call agent.
   The IP address in the URI MUST be a publicly reachable one.  If the
   call agent is to be reached through a border element, the IP address
   and port on the border element MUST be used here.



Jennings, et al.        Expires September 6, 2012              [Page 22]


Internet-Draft            ViPR Access Protocol                March 2012


   The use of the IP address in the maddr parameter allows the system to
   operate without DNS support.

   An example document for a VService on the public DHT is:


    <?xml version="1.0" encoding="UTF-8"?>
    <service-description
    xmlns="http://www.cisco.com/namespaces/saf-uc" id="has7gg"
    xmlns:vt="http://www.cisco.com/namespaces/viprtrunk"
    schemaVersion="1.0">
    <tns:vservice xmlns:tns="http://www.cisco.com/namespaces/viprtrunk">
     <tns:DHTname>Quetzalcoatl</tns:DHTname>
     <tns:DIDCount>3670</tns:DIDCount>
     <tns:domain>example.com</tns:domain>
     <tns:whitelist>
       <tns:domain>example.com</tns:domain>
       <tns:domain>foo.edu</tns:domain>
     </tns:whitelist>
     <tns:route>
       <tns:SIPURI>
    sip:17ahhs7zpaksux6z5==@example.com:2371;maddr=1.2.3.4;transport=tcp
       </tns:SIPURI>
     </tns:route>
     </tns:vservice>
    </service-description>


                     Figure 7: Example ServiceContent

   The ViPR client SHOULD publish each ViPR trunk service to both its
   primary and backup ViPR server, for purposes of HA.

8.4.2.  ViPR Number Service

   The ViPR number service is used to publish the numbers that are
   associated with the VService.  It is published as a separate service
   due to the differing state requirements associated with the numbers.
   For the VService, the ViPR server stores the information and does not
   actually publish it into the DHT.  For ViPR number service, the ViPR
   server immediately writes the data into the DHT and doesn't actually
   store it locally.  The ViPR server does not refresh the data in the
   DHT on its own, nor does it withdraw the data from the DHT when the
   client disconnects.  The ViPR client is responsible for refreshing
   the data in the DHT by periodically refreshing each of its numbers in
   each DHT.  The numbers in the DHT have a configurable expiration.
   Consequently, the ViPR client has to refresh the data prior to the
   expiration.  There is no way in VAP to remove a number from the DHT;



Jennings, et al.        Expires September 6, 2012              [Page 23]


Internet-Draft            ViPR Access Protocol                March 2012


   it is merely left to expire.

   The ViPR client SHOULD publish each service to both its primary and
   backup ViPR server, for purposes of HA.  Next, the client constructs
   a ViPR number service advertisement.  Unlike VService advertisements,
   which utilize an XML object in the ServiceContent attribute, number
   services utilize only VAP attributes.  The Publish message will
   contain a ServiceIdentity attribute and a CalledNum attribute.  The
   VServiceID of the ServiceIdentity attribute indicates the VService
   for this number, and is used by the ViPR server to determine which
   DHT to publish into.  The CalledNum attribute contains the number to
   be published into the DHT.  The ServiceVersion attribute is not
   present.

8.5.  Updating the VService

   A client can change the VService information at any time.  Typically,
   changes in the black or white list will require an updated VService
   publication, as will changes in the set of servers listening for
   incoming SIP traffic.

   To update a VService, the client modifies its service description,
   and creates a new Publish request.  This request is first formed as
   described in Section 4.  This request MUST contain the
   ServiceIdentity attribute, identifying the service to be modified.
   The request MUST also contain the ServiceContent attributes,
   containing the relevant information for the service.

   The request MUST contain a ServiceVersion attribute.  That version
   number MUST be at least one higher than the version number in the
   previous publication for the same service (as identified by service
   ID, subservice ID and instance).

   If the response was an error response and was of type 472, it means
   that the client didn't increment the sequence number.  More likely,
   it indicates that the client has inadvertently forgotten the version
   number of the service and gotten out of sync with the server.  The
   client SHOULD choose a new instance ID for this service, unregister,
   reconnect, re-register, and republish.

   If the response was an error response and was of type 474, it means
   that the client sent a Publish request on a TCP connection but had
   not yet registered.  If the client hadn't registered, it MUST now do
   so.  If it had registered, there has been some kind of
   synchronization error.  The client SHOULD generate an alarm.  Then,
   it MUST generate a new register (without the Client-Handle).

   If the response was an error response and was of type 400, it means



Jennings, et al.        Expires September 6, 2012              [Page 24]


Internet-Draft            ViPR Access Protocol                March 2012


   that the client did not construct the request properly.  The client
   MUST NOT retry unless it changes the content or set of attributes in
   the request to match the requirements defined here.

   If a client is no longer capable of receiving SIP requests at the URI
   it previously published, it should remove its VService by sending an
   Unpublish request.

8.6.  Uploading VCRs

   When the call agent initiates or receives a call that goes towards
   the PSTN, whether it be through a PSTN gateway or through a SIP trunk
   to a service provider, the call agent MUST send an UploadVCR request
   to its primary server ViPR server.  It SHOULD send its terminating
   UploadVCRs to its secondary ViPR server, and SHOULD NOT send its
   originating UploadVCRs to its secondary.  The UploadVCR request is
   first constructed like any other VAP request.  This means it will
   contain the USERNAME, REALM, and MESSAGE-INTEGRITY attributes.

   In addition, it MUST contain a CallingNum, CalledNum, StartTime and
   StopTime attribute.  The CallDirection attribute is set as described
   in Section 10.3.14.

   The UploadVCR request MUST contain a ServiceIdentity attribute.  The
   serviceID is 100, the subservice ID is 3 (ViPR number service) and
   the VService ID must identify the VService for which this UploadVCR
   is associated.  The instance is arbitrary and are ignored by the ViPR
   server.

   If the response was an error response and was of type 474, it means
   that the client sent a UploadVCR request on a TCP connection but had
   not yet registered and had not yet sent a VService publication with a
   VServiceID matching that of the UploadVCR.  If the client hadn't
   registered and published a matching VService, it MUST now do so.  If
   it had, there has been some kind of synchronization error.  The
   client SHOULD generate an alarm.  Then, it MUST disconnect, generate
   a new register (without the Client-Handle) and a new VService
   publication.

   If the response was an error response and was of type 400, it means
   that the client did not construct the request properly.  The client
   MUST NOT retry unless it changes the content or set of attributes in
   the request to match the requirements defined here.

8.7.  Subscribing to Number Service

   In order to learn about validated numbers, a ViPR client MUST
   subscribe for the ViPR Number Service.  The client should subscribe



Jennings, et al.        Expires September 6, 2012              [Page 25]


Internet-Draft            ViPR Access Protocol                March 2012


   to just its primary ViPR server.

   To create a subscription, the client creates a Subscribe request.
   The request is formed as described in Section 4.  It MUST NOT be sent
   if the client has not previously generated a successful Register
   request on this connection.

   Each initial Subscribe request MUST omit the SubscriptionID
   attribute; that attribute is only used when withdrawing a
   subscription.  The client MUST include a ServiceIdentity attribute in
   the request.  The service ID MUST be 101, the subserviceID MUST be 3,
   the VServiceID MUST be the VServiceID for the VService from which
   learned numbers are desired, and the instance value MUST be all ones.
   This will cause the client to receive notifications upon validated
   numbers learned as a consequence of an UploadVCR for that VService.

8.8.  Unsubscribing to Services

   A client MAY terminate a subscription at any time.  To do that, it
   sends an Unsubscribe request.  This request MUST contain the
   SubscriptionID attribute identifying the subscription to be
   terminated.  Note that this unsubscription will affect only the
   subscription identified by the subscription ID.  Other subscriptions
   will continue to be in effect.

   The client MAY generate additional Unsubscribe requests while the
   transactions for previous Subscribe, Publish or Unpublish requests
   are in progress.  By definition a client can only Unsubscribe a
   subscription for which it had already received a successful response
   to a Subscribe request that created the subscription.

   If the response was an error response and was of type 474, it means
   that the client sent a Subscribe request on a TCP connection but had
   not yet registered.  If the client hadn't registered, it MUST now do
   so.  If it had registered, there has been some kind of
   synchronization error.  The client SHOULD generate an alarm.  Then,
   it MUST generate a new register (without the Client-Handle).

   If the response was an error response and was of type 476, it means
   that the client sent an Unsubscribe request for a subscription which
   does not exist.  The client SHOULD generate an alarm, since a
   synchronization error has occurred.  It should however proceed as if
   the withdrawal was successful.

   If the response was an error response and was of type 400, it means
   that the client did not construct the request properly.  The client
   MUST NOT retry unless it changes the content or set of attributes in
   the request to match the requirements defined here.



Jennings, et al.        Expires September 6, 2012              [Page 26]


Internet-Draft            ViPR Access Protocol                March 2012


8.9.  Receiving Notify

   The ViPR server will generate a Notify request when a new number and
   route are learned.  It will send this Notify request to all clients
   which have subscribed to the corresponding VService.

   Once the client has received a successful response to its Subscribe
   request, the client MUST be prepared to receive Notify requests on
   the TCP connection to its ViPR server.  When the client receives a
   Notify request, it searches for the SubscriptionID attribute in the
   request.  This informs the client of the subscription that this
   notification is associated with.  If this subscriptionID is known to
   the client, it proceeds.  Otherwise, it MUST generate a Notify error
   response with a 476 response code in an ERROR-RESPONSE attribute.
   When this occurs, there has been a synchronization error between the
   client and server in the set of valid subscriptions.  This event
   SHOULD be alarmed, and the contents of the Notify not used.

   The Notify request will contain a ServiceIdentity attribute and a
   ServiceContent attribute, in addition to the standard authentication
   attributes and the SubscriptionID attribute.  The ViPR client must
   verify that the ServiceIdentity has service 100, subservice 3.  It
   looks at the instance value, and checks that the topmost 64 bits of
   the instance contain a VServiceID that matches one for which the ViPR
   client is currently interested in learning about.  The ViPR client
   then extracts the contents of the ServiceContent attribute.  This
   will be an XML object, formatted as described below.

   The client SHOULD store the phone number, SIP URI and Ticket.  When
   receiving a future call to that phone number, it SHOULD send a SIP
   INVITE request to the SIP URI and include the ticket in an X-Cisco-
   ViPR-Ticket header field.

8.10.  Receiving PublishRevoke

   The PublishRevoke method is defined only for the VService, not for
   the Number Service.  The ViPR server will send a PublishRevoke for a
   VService if the corresponding DHT is no longer available.  The
   request will contain the ServiceIdentity attribute, which indicates
   the specific VService and instance that are being withdrawn.  If
   these correspond to a known VService, the client should consider that
   service deactivated, and periodically try to republish it.


9.  ViPR Server Procedures






Jennings, et al.        Expires September 6, 2012              [Page 27]


Internet-Draft            ViPR Access Protocol                March 2012


9.1.  Connection Establishment

   The ViPR server MUST be prepared to receive incoming TCP or TLS
   connections on a configure port.  Whether or not TCP or TLS is used,
   is a configured property of that port.

9.2.  Registration

   The purpose of registrations is to create VAP client objects, which
   represent a VAP connection and contain the state described in
   Section 6, and then link those with a TCP connection.  Each VAP
   connection can be considered a client object, linked to one and only
   one TCP connection at a time.

   The first request that the server will receive over the TCP
   connection will be a Register request.  This request is first
   processed as described in Section 5.3.  Assuming those procedures
   succeed, the server checks for the Client-Handle attribute in the
   Register request.  If present, the server checks if it currently has
   a client state object with that handle.  If the client object was
   already bound to another TCP connection, that other TCP connection
   MUST be closed by the server, and then the new TCP connection MUST be
   bound to the client object.

   If the Register request had a Client-Handle attribute, but there were
   no client objects with that handle, the server MUST generate an error
   response and MUST include an ERROR-CODE attribute with a response
   code of 471.  This is due to a state synchronization error between
   the client and server.  The server SHOULD generate an alarm.

   If the Register did not have a Client-Handle attribute, it is a
   request to create a client object.  The server examines the Protocol-
   Version attribute from the request.  If the major version indicated
   in the attribute is higher than the version supported by the server,
   the server MUST reject the Register request with an error response
   and include an ERROR-CODE attribute with a response code of 478.
   That error response MUST include a Protocol-Version attribute that
   contains the major and minor protocol versions supported by the
   server.

   Next, the server MUST create a new client object, and allocate a new
   Client-Handle for it.  The Client-Handle MUST be unique amongst all
   other Client-Handles known to this server, across all clients that
   are connected to it.

   If the registration succeeds, the server sends a success response.
   This response MUST include the Client-Handle attribute containing the
   handle created by the server.  The response MUST include a Keepalive



Jennings, et al.        Expires September 6, 2012              [Page 28]


Internet-Draft            ViPR Access Protocol                March 2012


   attribute, indicating the time in milliseconds that the server will
   need to see traffic from the client in order to continue to maintain
   the client object.

9.3.  Unregistration

   The client can gracefully disconnect by using an Unregister request.

   If the server receives an Unregister request on a TCP connection, it
   first looks for the client object bound to that connection.  If there
   is no client object bound to it, it means that the client has sent an
   Unregister request prior to registering, or there has been some kind
   of synchronization error.  The server MUST respond with an error
   response, and MUST include an ERROR-CODE attribute with a response
   code of 474.

   Otherwise, if the client object is known to the server, it MUST
   generate a success response.  Once it does, the server MUST destroy
   the client, its associated subscriptions, and published VService
   instances.  It then sets a timer equal to thirty seconds.  If the
   client has not closed the TCP connection bound to this client object,
   the server MUST close the TCP connection.

   If, as a consequence of the deletion of those VService instances,
   there are no longer any instances left for a VService, that VService
   and its associated data (BlackWhite, DHT, numberCount) are removed.

   Note that unregistration does not ever remove VCRs.

9.4.  Publication

   Behavior depends on whether the publication is for the VService or
   the ViPR number service.

   The ViPR server extracts the ServiceIdentity attribute.  If the value
   is not one of the following:

   1.  ServiceID is 101 and SubserviceID is 3.
   2.  ServiceID is 101 and SubserviceID is 4

   the ViPR server sends a 400 response.

9.4.1.  VService

   If the Publish request is for service 100, sub-service 4, it
   indicates that this was for the VService.  The ViPR server first
   looks for the client object bound to that connection.  If there is no
   client object bound to it, it means that the client has sent a



Jennings, et al.        Expires September 6, 2012              [Page 29]


Internet-Draft            ViPR Access Protocol                March 2012


   Publish request prior to registering, or there has been some kind of
   synchronization error.  The server MUST respond with an error
   response, and MUST include an ERROR-CODE attribute with a response
   code of 474.

   The ViPR server extracts the contents of the ServiceContent
   attribute.  This will be an XML object structured as defined in
   Section 10.1.  It also extracts the VServiceID and Instance values
   from the ServiceIdentity attribute.

   First, the ViPR server checks if it has any VService objects with the
   VServiceID from the publish.

   o  If it does, it replaces the BlackWhite, numberCount, domain, and
      DHTName parameters of that VService with the ones from the
      publish.  Next, it checks to see if the instance is currently an
      instance associated with that VService:
   o
      *  If it is, the route elements for that instance are replaced
         with the route values from the publish.
      *  If it is not, a new instance object is created, associated with
         the client and the VService, and is linked with the route
         values from the publish.
   o  If it does not, it creates a new VService object, and associates
      it with the values of the BlackWhite, numberCount, domain, and
      DHTName parameters of the VService.  Next, it creates a new
      instance, associates it with the VService, The route values from
      the publish are associated with that instance.

   ViPR server sends a Publish success response.  The ViPR server looks
   for all other ViPR services in the same DHT as the one from this
   Publish, it sums up their numberCounts, and includes that value in
   the "current" field of the Quota attribute in the Publish response.
   Since there is a limit on the count of the numbers that can be
   published into the DHT, this mechanism allows the ViPR server to
   inform the clients about the total usage across all clients of this
   ViPR server.  Note further, that since the ViPR server itself does
   not have local memory of the numbers it stored into the DHT, the ViPR
   server cannot determine how many numbers have been placed into the
   DHT for a particular VService.  That information is known only to the
   client.  That is why the client informs the ViPR server of how many
   numbers it has published as part of the VService publication.

   The ViPR server places its configured per-DHT limit for that DHT into
   the "limit" field in the Quota attribute in the Publish response.
   This tells the clients the maximum count of phone numbers which can
   be published.




Jennings, et al.        Expires September 6, 2012              [Page 30]


Internet-Draft            ViPR Access Protocol                March 2012


   The ViPR server includes a DHTLifetime attribute in the response.
   This attribute indicates the amount of time that data will remain in
   the DHT prior to be expunged.  This is a configured property of the
   DHT.

9.4.2.  ViPR Number Service

   If the server receives a Publish request for service 100, sub-service
   3, it indicates that this was for the ViPR Number Service.  The ViPR
   server first looks for the client object bound to that connection.
   If there is no client object bound to it, it means that the client
   has sent a Publish request prior to registering, or there has been
   some kind of synchronization error.  The ViPR server MUST respond
   with an error response, and MUST include an ERROR-CODE attribute with
   a response code of 474.  The ViPR server extracts the VServiceID from
   the ServiceIdentity attribute.  It checks that, for that VServiceID,
   there is a VService object currently being stored.  If not, the ViPR
   server MUST respond with an error response, and MUST include an
   ERROR-CODE attribute with a response code of 474.

   Next, the ViPR server extracts the number from the CalledNum
   attribute.  The ViPR server extracts the DHT from the VService object
   associated with the VServiceID from the Publish.  For the number, the
   ViPR server takes the number and treats it as an ASCII string, called
   the suffix seed.

   Next, the ViPR server generates two additional strings.  The first is
   formed by taking the suffix seed, and prepending the string "COPY1".
   The second is formed by taking the suffix seed and prepending the
   string "COPY2".

   Each of the three values is passed through the SHA-1 hash function,
   producing 160 bits.  The least significant 128 bits of this are
   taken.  Those 128 bits, for each of the three values, form the
   Resource-ID against which a STORE is to be performed.  Three separate
   stores are performed in order to provide security in the DHT.  Each
   store operation writes an object into the DHT whose value is a
   dictionary (or map) entry.

   Conceptually:

   Store(Resource-ID, object)

   Where Resource-ID is the 128 bit Resource-ID computed above.  The
   stored object is a dictionary entry which has a key and a value:

   Object = {key,value}




Jennings, et al.        Expires September 6, 2012              [Page 31]


Internet-Draft            ViPR Access Protocol                March 2012


   Here, the key is formed by taking the peerID of the storing node in
   hex format, without the "0x", appending a "+", followed by the
   VServiceID in hex format, without the "0x".  For example, if a peer
   with peerID 0x8e60f5fab753037f64ab6c53947fd532 receives a Publish
   with a VServiceID of 0x7eeb6a7036478351, the resulting key is:

   8e60f5fab753037f64ab6c53947fd532+7eeb6a7036478351

   Both parts of this key are important.  Using the peerID of the node
   performing the store basically segments the keyspace of the
   dictionary so that no two peers ever store using the same key.
   Indeed, the responsible node will verify the signature over the
   stored data and check the peerID against the value of the key, to
   make sure that a conflict does not take place.  The usage of the
   VService allows for a single ViPR server to service multiple call
   agents, and to ensure that numbers published by one call agent (using
   one VServiceID) do not clobber or step on numbers published by
   another call agent (using a different VServiceID).  The responsible
   node does not verify or check the VServiceID.

   In this version of the protocol, only one of the three stored objects
   is read.  Three are stored to allow an enhancement in the future,
   which will read all three and use a simple voting algorithm to handle
   inconsistencies in the results.  In this way, if a malicious node
   returns no result or fakes the result, as long as the remaining two
   results are retrieved, the validation process can continue.  This
   means that the compromise of a single node has, with only extremely
   low probability (order Log(N)/N where N is the number of nodes in the
   ring) of being able to disrupt validation against a number.

   The value of the dictionary entry is a sequence of TLV attributes,
   with the same format used by VAP.  In this case, it is a single
   attribute, the peerID attribute.  This attribute is populated with
   the peerID of the ViPR server in the DHT into which the STORE is
   being performed.  The reason for using the TLV construct is to
   provide extensibility in the contents of the DHT.  In the future, if
   needed, new ViPR nodes can add additional data, each with a specific
   attribute type.  Older nodes will ignore any unknown attributes and
   go right for the peerID attribute, while newer ones can process the
   new and old attributes.

   The Store operations are paced into the DHT at a fixed rate.  The
   ViPR server maintains a queue.  This queue is filled with store
   requests.  The ViPR server services that queue at a fixed,
   provisioned rate, the Store Rate Limit.  When serviced, the next
   Store operation in the queue is serviced.  Because transactions from
   clients are pipelined, there can only be as many Store operations in
   the queue as there are simultaneously connected clients, times three



Jennings, et al.        Expires September 6, 2012              [Page 32]


Internet-Draft            ViPR Access Protocol                March 2012


   (three Stores per Publish, one Publish at a timer per client).  The
   Publish is then responded to with a success response.  Note that, a
   success response is not sent until all three Store operations have
   been performed.  If there is a failure due to inability to store into
   the DHT, the server returns a 481 error response.  Note that a ViPR
   server cannot disambiguate the first Publish for a service and an
   updated Publish.  It performs identical processing for each.

   Note further that, the DHT itself will replicate each of the three
   stored values, producing a total of nine copies of each number into
   the DHT.

9.5.  Unpublish

   The ViPR client can only Unpublish for the VService.

   The ViPR server extracts the VServiceID and instance from the
   ServiceIdentity in the Unpublish.  It checks to see if there is an
   instance with that ID associated with the VService with that
   VServiceID.  If there is, it removes the instance object and its
   associated SIPURI.  If, as a consequence, there are no longer any
   instances associated with the VService, it deletes the VService
   object and its associated attributes.

9.6.  Subscribe

   If the server receives a Subscribe request on a connection, it first
   looks for the client object bound to that connection.  If there is no
   client object bound to it, it means that the client has sent a
   Subscribe request prior to registering, or there has been some kind
   of synchronization error.  The server MUST respond with an error
   response, and MUST include an ERROR-CODE attribute with a response
   code of 474.

   The ViPR server checks that the ServiceIdentity from the request.  If
   verifies that the ServiceID is 101 and the SubServiceID is 3.  Any
   other combination causes the server to return a 400 response.  The
   subscription is to the VServiceID identified in the ServiceIdentity
   attribute.

   If the ServiceIdentity is valid, the server MUST create a new
   subscription object.  It MUST allocate a SubscriptionID for this
   subscription.  This ID MUST be unique across all SubscriptionIDs
   associated with this client.  The subscription MUST be linked with
   the client object.  It is not permitted for there to be multiple
   subscriptions from a client with identical VServices since each
   subscription is for a unique service/subservice/VServiceID/instance,
   the ViPR server can hash these to get a 32 bit SubscriptionID, or



Jennings, et al.        Expires September 6, 2012              [Page 33]


Internet-Draft            ViPR Access Protocol                March 2012


   assign them sequentially and store the associations.

   The ViPR server then checks the VServiceID from the ServiceIdentity
   attribute.  The ViPR server adds a subscription object to the client
   object, and associates it with a SubscriptionID and the VServiceID
   which is being watched.

   The server then generates a success response to the Subscribe
   request.  It MUST include the SubscriptionID attribute in the
   response, identifying this subscription.

9.7.  Unsubscribe

   If the server receives an Unsubscribe request on a connection, it
   first looks for the client object bound to that connection.  If there
   is no client object bound to it, it means that the client has sent an
   Unsubscribe request prior to registering, or there has been some kind
   of synchronization error.  The server MUST respond with an error
   response, and MUST include an ERROR-CODE attribute with a response
   code of 474.

   Next, the server extracts the SubscriptionID attribute from the
   request.  If it contains a SubscriptionID not known to the server,
   there has been a synchronization error.  The server MUST reject the
   Unsubscribe request with an error response and MUST include an ERROR-
   CODE attribute with a value of 476.

   Assuming the SubscriptionID is known, the server MUST remove the
   subscription object from the client object, and destroy it.  The
   server will therefore no longer send notifications associated with
   this subscription.  The server MUST respond to the Unsubscribe
   request with a success response.

9.8.  UploadVCR

   The ViPR server first processes the request like any other VAP
   request, specifically it will perform the message integrity check and
   follow associated procedures.

   If the UploadVCR was received on a TCP connection but the client had
   not yet registered over that connection, it is an error and the ViPR
   server returns a 474.  If the client had registered, but the
   VServiceID from the ServiceIdentity doesn't match a known VService,
   the UploadVCR is rejected with a 474.

   Otherwise, the ViPR server extracts the CallDirection, StartTime,
   StopTime, CallingNum and CalledNum attributes, and stores them.
   Further processing depends on whether it was an originating or



Jennings, et al.        Expires September 6, 2012              [Page 34]


Internet-Draft            ViPR Access Protocol                March 2012


   terminating UploadVCR.

9.8.1.  Originating

   Once stored, the ViPR server starts timer Tv.  Tv is selected as a
   random number, in seconds, starting from 30 and ending at the maximum
   validation time, which is a configured parameter of the ViPR Server
   for the DHT associated with the VService.  The validation request -
   which includes the VCR - is stored until that timer fires.  The
   validation request includes the details from the UploadVCR (calling,
   called numbers, start and stop time), along with the VService
   associated with the UploadVCR.

   When the timer fires, the ViPR server examines the called party
   number.  This number will be a plus followed by N digits.  Using this
   number, it forms a lookup key K. K is equal to the least significant
   128 bits of the SHA1 hash of the called party number in string form,
   including the + sign.  Next, the ViPR server extracts VService
   associated with the VCR.  It checks to see if this VService is
   currently being published.  If so, it performs a lookup into the DHT
   using key K. Each DHT node has a queue on read transactions.  These
   lookups are queued because the node has, per-DHT, a limit on the rate
   at which it will perform read requests.

   Once the lookup request comes to the top of the queue and it can be
   serviced, the resulting fetch will be a result, a no-match, or a
   timeout.  If there is a no-match or timeout, ViPR server processing
   is complete.

   If there is a result, the ViPR server will now have all of the
   dictionary entries associated with the Resource-ID.  Each dictionary
   entry is a key and a value.  The key is the concatenation of a peerID
   and VServiceID, and the value is a set of TLV attributes.  The ViPR
   server parses each dictionary entry as a sequence of TLV attributes,
   and extracts the first TLV value whose type is peerID (type 0x2008).
   From this, the ViPR server obtains a set of {peerID, VServiceID}s.

   The ViPR server SHOULD perform validation, using the validation
   protocol [VIPR-PVP].  A ViPR server MAY use any algorithm of its
   choosing to determine whether a number should be validated once, many
   times, or not at all.  When the ViPR server is satisfied that a
   number has been sufficiently validated, it SHOULD send a Notify.
   Furthermore, during validation, the ViPR server SHOULD compare the
   domain of the learned number with the blacklist for the VService
   associated with the matching VCR.  If the domain is on the blacklist
   or not on the whitelist, a Notify SHOULD NOT be sent.

   If a Notify is to be sent as a consequence of a validation success,



Jennings, et al.        Expires September 6, 2012              [Page 35]


Internet-Draft            ViPR Access Protocol                March 2012


   the ViPR server looks to see if there is currently a subscription
   from a client whose VServiceID matches the one from the VCR that
   triggered the validation that is causing the notification.  For each
   matching one, it sends a Notify message.  The ServiceContent in the
   Notify contains a ValInfo XML containing the SIPURI and ticket
   learned from the validation.  It also contains the full E.164 number
   of the called number which validated.

9.8.2.  Terminating

   When the ViPR server receives a terminating UploadVCR, it stores the
   information, awaiting the receipt of a validation query.  This
   information MUST be stored for a minimum whose value is a configured
   property of the DHT.

9.9.  Sending Notify

   The ViPR server MUST NOT send a Notify until it had already sent a
   response to the Subscribe message that created the subscription, for
   which the Notify is being sent.

   When a Notify is to be sent, it must contain the SubscriptionID
   attribute associated with the subscription on which the notification
   is being sent.  This will differ for each client that is subscribed.

   The Notify MUST contain the ServiceIdentity attribute, containing
   service 100, subservice 3, a VServiceID for the VService on which the
   number was learned, and an instance ID whose instance is all ones.
   The content of the ServiceContent attribute is an XML document, which
   is the scrubbed document from the ValExchange response.  An example
   document is:




















Jennings, et al.        Expires September 6, 2012              [Page 36]


Internet-Draft            ViPR Access Protocol                March 2012


       <?xml version="1.0" encoding="utf-8"?>
       <valinfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="valinfo.xsd">
        <number>+17325552496</number>
        <ticket>7hasd88a7sd6a6d7989xkk8g7a6sdq78ekaz</ticket>
        <route>
          <SIPURI>
            sip:17ahhs$7zpaksux6z5==@example.com:2371;maddr=1.2.3.4
          </SIPURI>
        </route>
        <route>
          <SIPURI>
            sip:17ahhs$7zpaksux6z5==@example.com:2371;maddr=1.2.3.5
          </SIPURI>
        </route>
       </valinfo>

                       Figure 8: Example Notify XML

9.10.  Sending PublishRevoke

   The ViPR server is only permitted to PublishRevoke the VService; it
   cannot withdraw Number Service publications.  It should PublishRevoke
   published VServices when the corresponding DHT is no longer
   available.  If this should happen, the ViPR server sends a
   PublishRevoke for each VService that was published which utilized the
   DHT which is no longer available.  That PublishRevoke MUST include a
   ServiceIdentity attribute indicating the VServiceID and instanceID of
   the PublishRevoke service.  Furthermore, it SHOULD include a
   ServiceContent attribute with the corresponding service description;
   this is used strictly for diagnostic purposes and is not needed by
   the client.  Once sent, the ViPR server removes that instance of that
   VServiceID from its internal state.


10.  Syntax Details

10.1.  XML Schema for VService

   This document is included in publications for the ViPR service.  Note
   its target namespace.

     <?xml version="1.0" encoding="utf-8"?>

     <xs:schema xmlns="http://www.cisco.com/namespaces/saf-uc"
      attributeFormDefault="unqualified" elementFormDefault="qualified"
      targetNamespace="http://www.cisco.com/namespaces/saf-uc"
      xmlns:xs="http://www.w3.org/2001/XMLSchema">



Jennings, et al.        Expires September 6, 2012              [Page 37]


Internet-Draft            ViPR Access Protocol                March 2012


      <xs:element name="service-description">
        <xs:complexType>
          <xs:choice>
     <xs:element name="vservice">
       <xs:complexType>
         <xs:sequence>
           <xs:element name="DHTname" type="xs:string" />
           <xs:element name="DIDCount" type="xs:integer" />
           <xs:element minOccurs="1" maxOccurs="1" name="domain"
             type="xs:string" />
           <xs:choice minOccurs="0" maxOccurs="1">
             <xs:element
               xmlns:q1="http://www.cisco.com/namespaces/viprtrunk"
               name="blacklist" type="q1:whiteOrBlackList" />
             <xs:element
               xmlns:q2="http://www.cisco.com/namespaces/viprtrunk"
               name="whitelist" type="q2:whiteOrBlackList" />
           </xs:choice>
           <xs:sequence minOccurs="1" maxOccurs="unbounded">
             <xs:element
               xmlns:q1="http://www.cisco.com/namespaces/viprtrunk"
               name="route" type="q1:routeType" />
           </xs:sequence>
           <xs:any minOccurs="0" maxOccurs="unbounded"
             namespace="##other"
             processContents="lax" />
         </xs:sequence>
       </xs:complexType>
     </xs:element>
          </xs:choice>
          <xs:attribute name="schemaVersion" type="xs:string"
            use="required" />
          <xs:attribute name="id" type="xs:string" use="required" />
        </xs:complexType>
      </xs:element>
     <xs:complexType name="whiteOrBlackList">
        <xs:sequence minOccurs="1" maxOccurs="unbounded">
          <xs:element name="domain" type="xs:string" />
        </xs:sequence>
      </xs:complexType>
      <xs:complexType name="routeType">
        <xs:sequence>
          <xs:element minOccurs="1" maxOccurs="unbounded" name="SIPURI"
            type="xs:string" />
          <xs:any minOccurs="0" maxOccurs="unbounded"
            namespace="##other" />
        </xs:sequence>
      </xs:complexType>



Jennings, et al.        Expires September 6, 2012              [Page 38]


Internet-Draft            ViPR Access Protocol                March 2012


     </xs:schema>

                       Figure 9: VService XML Schema

10.2.  XML Schema for ValInfo

   This document is passed from the terminating ViPR server to the
   originating, containing the ticket, routes and number which was
   validated.  The originating ViPR server verifies this and passes it
   to the client in VService notifications.

    <?xml version="1.0" encoding="utf-8" ?>
    <xs:schema elementFormDefault="qualified"
       xmlns:xs="http://www.w3.org/2001/XMLSchema">
     <xs:element name="valinfo">
       <xs:complexType>
         <xs:sequence minOccurs="0" maxOccurs="unbounded">
           <xs:element minOccurs="1" maxOccurs="1" name="number"
             type="xs:string" />
           <xs:element minOccurs="1" maxOccurs="1" name="ticket"
             type="xs:string" />
           <xs:element minOccurs="1" maxOccurs="unbounded" name="route"
             type="routeType" />
           <xs:any minOccurs="0" />
         </xs:sequence>
       </xs:complexType>
     </xs:element>
     <xs:complexType name="routeType">
       <xs:sequence>
         <xs:element minOccurs="1" maxOccurs="unbounded" name="SIPURI"
           type="xs:string" />
         <xs:any minOccurs="0" maxOccurs="unbounded"
           namespace="##other" />
       </xs:sequence>
     </xs:complexType>
    </xs:schema>

                       Figure 10: ValInfo XML Schema

10.3.  VAP Attributes

   This section enumerates the attributes used by VAP.  The attribute
   names and corresponding types are:








Jennings, et al.        Expires September 6, 2012              [Page 39]


Internet-Draft            ViPR Access Protocol                March 2012


                   Attribute Name                  Type
                   --------------                  ----
                   USERNAME                        0x0006
                   MESSAGE-INTEGRITY               0x0008
                   REALM                           0x0014
                   ERROR-CODE                      0x0009
                   Client-Name                     0x1001
                   Client-Handle                   0x1002
                   Protocol-Version                0x1003
                   Client-Label                    0x1005
                   Keepalive                       0x1006
                   ServiceIdentity                 0x1007
                   ServiceVersion                  0x100b
                   ServiceContent                  0x100c
                   SubscriptionID                  0x100e
                   CallDirection                   0x2001
                   StartTime                       0x2002
                   StopTime                        0x2003
                   CallingNum                      0x2004
                   CalledNum                       0x2005
                   peerID                          0x2008
                   Quota                           0x200a
                   DHTLifetime                     0x200b


                         Figure 11: VAP Attributes

10.3.1.  USERNAME

   The USERNAME attribute is used for authentication.  It identifies the
   shared secret used in the message integrity check.  Consequently, the
   USERNAME MUST be included in any request that contains the MESSAGE-
   INTEGRITY attribute.

   The value of USERNAME is a variable length opaque value of UTF-8
   characters.  Note that, as described above, if the USERNAME is not a
   multiple of four bytes it is padded for encoding into the VAP
   message, in which case the attribute length represents the length of
   the USERNAME prior to padding.

10.3.2.  REALM

   The REALM attribute is present in requests and responses.  It
   contains text which meets the grammar for "realm" as described in RFC
   3261 [RFC3261], and will thus contain a quoted string (including the
   quotes).

   The value of this attribute MUST always be "ViPR".



Jennings, et al.        Expires September 6, 2012              [Page 40]


Internet-Draft            ViPR Access Protocol                March 2012


10.3.3.  MESSAGE-INTEGRITY

   The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1 [RFC2104] of
   the message.  The MESSAGE-INTEGRITY attribute can be present in any
   message type.  Since it uses the SHA1 hash, the HMAC will be 20
   bytes.  The text used as input to HMAC is the message, including the
   header, up to and including the attribute preceding the MESSAGE-
   INTEGRITY attribute.  That text is then padded with zeroes so as to
   be a multiple of 64 bytes.  The MESSAGE-INTEGRITY attribute MUST be
   the last attribute in the message.

   The 16-byte key for MESSAGE-INTEGRITY HMAC is formed by taking the
   MD5 hash of the result of concatenating the following five fields:
   (1) The username, with any quotes and trailing nulls removed, (2) A
   single colon, (3) The realm, with any quotes and trailing nulls
   removed, (4) A single colon, and (5) The password, with any trailing
   nulls removed.  Note that the password itself never appears in the
   message.

   Since the hash is computed over the entire message, it includes the
   length field from the message header.  This length indicates the
   length of the entire message, including the MESSAGE-INTEGRITY
   attribute itself.  Consequently, the MESSAGE-INTEGRITY attribute MUST
   be inserted into the message as the last attribute (with dummy
   content) prior to the computation of the integrity check.  Once the
   computation is performed, the value of the attribute can be filled
   in.  This ensures the length has the correct value when the hash is
   performed.

10.3.4.  ERROR-CODE

   The ERROR-CODE attribute is present in error responses.  It is a
   numeric value in the range of 100 to 699 plus a textual reason phrase
   encoded in UTF-8, and is consistent in its code assignments and
   semantics with [RFC3261] and [RFC2616].  The reason phrase is meant
   for user consumption (typically freeform fields in alarms and logs),
   and can be anything appropriate for the response code.  Recommended
   reason phrases for the defined response codes are presented below.

   To facilitate processing, the class of the error code (the hundreds
   digit) is encoded separately from the rest of the code.










Jennings, et al.        Expires September 6, 2012              [Page 41]


Internet-Draft            ViPR Access Protocol                March 2012


      0                   1                   2                   3
      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |                   0                     |Class|     Number    |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |      Reason Phrase (variable)                                ..
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                       Figure 12: ERROR-CODE Syntax

   The class represents the hundreds digit of the response code.  The
   value MUST be between 1 and 6.  The number represents the response
   code modulo 100, and its value MUST be between 0 and 99.

   If the reason phrase has a length that is not a multiple of four
   bytes, it is padded for encoding into the message, in which case the
   attribute length represents the length of the entire ERROR-CODE
   attribute (including the reason phrase) prior to padding.

   The following response codes, along with their recommended reason
   phrases (in brackets) are defined at this time:

   400 (Bad Request):  The request was malformed.  The requestor should
      not retry the request without modification from the previous
      attempt.
   431 (Integrity Check Failure):  The request contained a MESSAGE-
      INTEGRITY attribute, but the HMAC failed verification.  This could
      be a sign of a potential attack, or misconfiguration of the
      password .
   436 (Unknown Username):  The username was not known.  This was likely
      due to a misconfiguration.
   471 (Bad Client Handle):  The client handle provided in the Register
      request is not known.
   472 (Version Number Too Low):  The client published a service whose
      version was lower than the currently held one by the server.
   474 (Unregistered):  The client tried an operation, such as publish
      or subscribe, but it has not yet registered.
   476 (Unknown Subscription):  The referenced subscription does not
      exist.
   477 (Already Registered):  The client tried an initial Register
      request, but it is already registered.
   478 (Unsupported Protocol Version):  The server does not support the
      protocol version requested by the client.
   481 (Publication Failed):  The publication was attempted but could
      not be performed due to an error reaching the DHT.  The client
      should try again.





Jennings, et al.        Expires September 6, 2012              [Page 42]


Internet-Draft            ViPR Access Protocol                March 2012


10.3.5.  Client-Name

   The Client-Name attribute is included the Register request.  It
   contains a textual description, in UTF-8, of the software being used
   by the client, including manufacturer and version number.  The
   attribute has no impact on operation of the protocol, and serves only
   as a tool for diagnostic and debugging purposes.  The value of
   Client-Name is variable length.  If the value of Client-Name is not a
   multiple of four bytes, it is padded for encoding into the VAP
   message, in which case the attribute length represents the length of
   the attribute prior to padding.  However, it MUST be less than 255
   characters and MUST be at least one character long.

   It is RECOMMENDED that it be constructed as:


               <vendor>/<product>/<version>/<hostname or IP>


   Where version includes major, minor and build.

10.3.6.  Client-Handle

   This attribute has a 32 bit value, representing an unsigned integer
   to be used as the client handle.

10.3.7.  Protocol-Version

   This attribute is 32 bits, consisting of two 16-bit unsigned
   integers, representing the major and minor version numbers of the
   protocol:

      0                   1                   2                   3
      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |   Major Version               | Minor Version                 |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                    Figure 13: Protocol-Version Syntax

10.3.8.  Client-Label

   This attribute is a UTF-8 string, which MUST be between 1 and 255
   characters.  It is not used by this specification.







Jennings, et al.        Expires September 6, 2012              [Page 43]


Internet-Draft            ViPR Access Protocol                March 2012


10.3.9.  Keepalive

   This attribute is a 32 bit unsigned integer, representing the number
   of milliseconds that the server will retain client state after the
   last message from the client has been received.

10.3.10.  ServiceIdentity

   The format of the ServiceIdentity attribute is:

      0                   1                   2                   3
      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
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |      Service ID                 | Subservice ID               |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |      VServiceID (most significant)                            |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |      VServiceID (2nd most significant)                        |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |     Instance (3rd significant)                                |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
     |      Instance (least significant)                             |
     +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

                   Figure 14: ServiceIdentity Attribute

   The value of serviceID must always be 101.  A Subservice value of 4
   indicates VService publications.  A subservice value of 3 indicates
   number publications.

10.3.11.  ServiceVersion

   The ServiceVersion field is a 32 bit unsigned integer.  It contains
   the version number for the service advertised in the Publish request.
   It always increments by at least one for each change in the service.

10.3.12.  ServiceContent

   The ServiceContent is the actual content of the service definition.
   It is an arbitrary number of bytes.  If the number of bytes of
   content are not a multiple of four, the content is padded with
   arbitrary data so that it is a multiple of four.  The value of the
   length field of the attribute is the length prior to padding.

   The ServiceContent MUST be less than 32k, despite the fact that the
   length field of the attribute itself would allow content up to 64k.





Jennings, et al.        Expires September 6, 2012              [Page 44]


Internet-Draft            ViPR Access Protocol                March 2012


10.3.13.  SubscriptionID

   The SubscriptionID is present in successful responses to Subscribe
   and in Unsubscribe messages.  It contains an identifier for the
   subscription.  It is a unique handle, unique within all subscriptions
   between the client and this server.  It is an unsigned 32 bit
   integer.  It is also present in Notify and Withdraw requests.

10.3.14.  CallDirection

   This attribute is a 32 bit unsigned integer.  A value of 0 indicates
   a received call.  A value of 1 indicates a sent call.  Other values
   are reserved and not valid in this version of the protocol.

10.3.15.  StartTime

   The start and is a 64 bit NTP time value.  The start time is measured
   in the following way:

   1.  For calls sent to the PSTN (i.e., originated by this call agent),
       the start time is measured from the instant of the receipt of the
       call acceptance message indicating that the called party answered
       the call.  For SIP, this would correspond to receipt of the 200
       OK to the original SIP INVITE.
   2.  For calls received from the PSTN, (i.e., received by this call
       agent), the start time is measured from the instant of
       transmission of the call acceptance message towards the PSTN,
       indicating that the called party answered the call.  For SIP,
       this would correspond to transmission of the 200 OK to the
       original SIP INVITE.

10.3.16.  StopTime Attribute

   The stop time is a 64 bit NTP value and is measured in the following
   way:

   1.  For the call agent which terminates the call, it corresponds to
       the transmission of the call termination message towards the
       PSTN.  For SIP, this corresponds to the transmission of a SIP BYE
       request.
   2.  For the call agent which receives the termination, it corresponds
       to the receipt of the call termination message from the PSTN.
       For SIP this corresponds to the receipt of a SIP BYE request.

10.3.17.  CallingNum Attribute

   The calling party number MUST be expressed in fully qualified E.164
   format, and the attribute is a string with variable length.



Jennings, et al.        Expires September 6, 2012              [Page 45]


Internet-Draft            ViPR Access Protocol                March 2012


   The calling party number is complicated.  This is because this value
   is often munged and modified by the PSTN as it traverses the network.
   Fortunately, ViPR does not depend on it being delivered or being
   correct, but when it is delivered it improves security.  Its presence
   is also needed for validating numbers which connect to multiple
   users, such that multiple calls to that number are often in progress
   at the same time.  For example, 800 numbers.

   For the originating call agent, the value is the E.164 number of
   calling party number delivered to the PSTN.  For the terminating call
   agent, the value is E.164 normalized value of the caller ID received
   from the PSTN.  This will require that national numbers delivered
   over a PRI are normalized to include their country code.

10.3.18.  CalledNum Attribute

   The called party number MUST be expressed in fully qualified E.164
   format, and it is represented in the attribute as a string with
   variable length.  The following rules apply for computation of the
   called party number:

   For the call agent which initiates the call, the called party number
   is the E.164 number, including the leading plus, of the target of the
   call.  Of course, this may not (and is probably not) the same as the
   digit sequence dialed by the calling party.  The originating call
   agent MUST normalize this number to E.164 format based on its local
   dialing rules.

   For the call agent which receives the call, the called party number
   is the E.164 number, including the leading plus, of the target of the
   call.  Of course, this may not (and is probably not), the same as the
   called party number as delivered by the PSTN.  It is likely that
   country codes, for example, are omitted from the message delivered by
   the PSTN.  It is the responsibility of the terminating call agent to
   reconstruct the E.164 number of the called party.

10.3.19.  Quota Attribute

   This attribute consists of two 32 bit values.  The first is the quota
   limit, which is the total number of numbers that can be published by
   this and other call agents attached to this ViPR server into this
   DHT.  The second is the current total number of numbers being
   published by this and other call agents attached to this ViPR server
   into this DHT.  If the current value is less than the quota value,
   everything is fine.  Once it exceeds it, the DHT is likely to begin
   dropping entries and the admin needs to reduce the number of numbers
   being published.




Jennings, et al.        Expires September 6, 2012              [Page 46]


Internet-Draft            ViPR Access Protocol                March 2012


10.3.20.  DHTLifetime Attribute

   This attribute is a 32 bit unsigned integer.  It indicates the number
   of seconds that data written into the DHT will remain in the DHT
   prior to being expunged.


11.  Security Considerations

11.1.  Outsider Attacks

   VAP prevents against traditional outsider attacks by means of TLS
   along with password-based digest authentication.  That mechanism MUST
   be implemented by clients and servers and SHOULD be used.

11.2.  Insider Attacks

   Of much more concern are attacks whereby the client is authenticated,
   but it misuses the VAP connection to attack the overall system.

   The principal attack to be considered is where an attacker injects
   false numbers by sending Publish requests for the number service
   containing numbers that the client doesn't own.  This attack is the
   fundamental security problem that ViPR overall addresses with the
   validation mechanism, and so that attack is handled outside of VAP.

   Another potential attack is a flooding attack where a client sends a
   large amount of numbers into the DHT.  This attack is prevented by
   the distributed quota mechanism within the ViPR RELOAD usage, and
   thus prevented outside of VAP.  Similarly, an attacker might try to
   DOS the ViPR network by sending a large volume of reads or writes
   into the DHT.  This is prevented by means of the rate control
   mechanisms enforced by the ViPR server.


12.  IANA Considerations

   There are no IANA considerations associated with this specification.


13.  References

13.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC3261]  Rosenberg, J., Schulzrinne, H., Camarillo, G., Johnston,



Jennings, et al.        Expires September 6, 2012              [Page 47]


Internet-Draft            ViPR Access Protocol                March 2012


              A., Peterson, J., Sparks, R., Handley, M., and E.
              Schooler, "SIP: Session Initiation Protocol", RFC 3261,
              June 2002.

   [RFC5389]  Rosenberg, J., Mahy, R., Matthews, P., and D. Wing,
              "Session Traversal Utilities for NAT (STUN)", RFC 5389,
              October 2008.

   [RFC0791]  Postel, J., "Internet Protocol", STD 5, RFC 791,
              September 1981.

   [RFC2617]  Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S.,
              Leach, P., Luotonen, A., and L. Stewart, "HTTP
              Authentication: Basic and Digest Access Authentication",
              RFC 2617, June 1999.

   [RFC2104]  Krawczyk, H., Bellare, M., and R. Canetti, "HMAC: Keyed-
              Hashing for Message Authentication", RFC 2104,
              February 1997.

   [RFC2616]  Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
              Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
              Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.

   [VIPR-PVP]
              Rosenberg, J., Jennings, C., and M. Petit-Huguenin, "The
              Public Switched Telephone Network (PSTN) Validation
              Protocol (PVP)", draft-rosenberg-dispatch-vipr-pvp-03
              (work in progress), October 2010.

13.2.  Informative References

   [VIPR-OVERVIEW]
              Rosenberg, J., Jennings, C., and M. Petit-Huguenin,
              "Verification Involving PSTN Reachability: Requirements
              and Architecture Overview",
              draft-rosenberg-dispatch-vipr-overview-04 (work in
              progress), October 2010.


Appendix A.  Release notes

   This section must be removed before publication as an RFC.

A.1.  Modifications between rosenberg-03 and rosenberg-02






Jennings, et al.        Expires September 6, 2012              [Page 48]


Internet-Draft            ViPR Access Protocol                March 2012


   o  Nits.
   o  Shorter I-Ds references.
   o  Added terminology section.
   o  Changed figures to fit in the page width.
   o  Change reference from RFC 2401 to RFC 2104
   o  Removed cut & paste error from STUN.
   o  Fixed some invalid lists.
   o  Section 9.1:  Removed mutual authentication to be consistent with
      5.1.
   o  Fixed the text for the creation of the resource name in 9.4.2, to
      be consistent with -reload-usage.
   o  Fixed example to really contain hexadecimal.


Authors' Addresses

   Cullen Jennings
   Cisco
   170 West Tasman Drive
   MS: SJC-21/2
   San Jose, CA  95134
   USA

   Phone:  +1 408 421-9990
   Email:  fluffy@iii.ca


   Jonathan Rosenberg
   jdrosen.net
   Monmouth, NJ
   US

   Email:  jdrosen@jdrosen.net
   URI:    http://www.jdrosen.net


   Marc Petit-Huguenin
   Stonyfish

   Email:  marc@stonyfish.com











Jennings, et al.        Expires September 6, 2012              [Page 49]


Html markup produced by rfcmarkup 1.129d, available from https://tools.ietf.org/tools/rfcmarkup/