One document matched: draft-rosenberg-dispatch-vipr-vap-00.xml
<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc iprnotified="yes" ?>
<?rfc strict="no" ?>
<?rfc compact="yes" ?>
<?rfc sortrefs="no" ?>
<?rfc colonspace="yes" ?>
<?rfc rfcedstyle="no" ?>
<?rfc tocdepth="4"?>
<rfc category="std" docName="draft-rosenberg-dispatch-vipr-vap-00"
ipr="trust200902">
<front>
<title abbrev="VIPR Access Protocol"> Verification Involving PSTN Reachability:
The ViPR Access Protocol (VAP)</title>
<author initials="J.R." surname="Rosenberg"
fullname="Jonathan Rosenberg">
<organization>jdrosen.net</organization>
<address>
<postal>
<street/>
<city>Monmouth</city> <region>NJ</region>
<country>US</country>
</postal>
<email>jdrosen@jdrosen.net</email>
<uri>http://www.jdrosen.net</uri>
</address>
</author>
<author fullname="Cullen Jennings" initials="C." surname="Jennings">
<organization>Cisco</organization>
<address>
<postal>
<street>170 West Tasman Drive</street>
<street>MS: SJC-21/2</street>
<city>San Jose</city>
<region>CA</region>
<code>95134</code>
<country>USA</country>
</postal>
<phone>+1 408 421-9990</phone>
<email>fluffy@cisco.com</email>
</address>
</author>
<date day="9" month="November" year="2009" />
<area>RAI</area>
<workgroup>dispatch</workgroup>
<abstract>
<t> 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).</t>
</abstract>
<note title="Legal">
<t>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.</t>
</note>
</front>
<middle>
<section title="Introduction to ViPR">
<t> <xref target="I-D.rosenberg-dispatch-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.
</t>
<t>
It is assumed that readers of this document have read and understood
<xref target="I-D.rosenberg-dispatch-vipr-overview"/>.
</t>
<t>
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.
</t>
</section>
<section title="Overview of VAP">
<t>
A high level view on the ViPR architecture is shown in
<xref target="fig-arch"/>. This architecture is discussed in more
detail in <xref target="I-D.rosenberg-dispatch-vipr-overview"/>.
</t>
<figure anchor="fig-arch" title="Architecture ">
<artwork><![CDATA[
+-+ +-+
| | | | +------+
| | +-----| |---|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
]]></artwork>
</figure>
<t>
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.
</t>
<t>
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 <xref target="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.
</t>
<t>
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:
<list style="symbols">
<t>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.</t>
<t>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.</t>
<t>Subscribe: Call agents can subscribe for information from the VipR
server. There is one service that UCM 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.</t>
<t>Notify: The ViPR server sends this message to the call agent when it has
an event to report for a particular subscription.</t>
</list></t>
<t>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.</t>
</section>
<section anchor="message_structure" title="VAP Message Structure">
<t>
VAP messages follow the syntax and structure of Session Traversal
Utilities for NAT (STUN) <xref target="RFC5389"/>. It also shares the
same transaction model as STUN. However, aside from its common syntax
and transaction model, STUN and VAP are unrelated.
</t>
<t>
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 <xref target="RFC0791">RFC791</xref>. Unless otherwise noted,
numeric constants are in decimal (base 10).</t>
<figure anchor="stun_message_header"
title="Format of VAP Message Header">
<preamble>All VAP messages MUST start with a 20-byte
header followed by zero or more Attributes. The VAP header contains a VAP
message type, magic cookie, transaction ID, and message
length.</preamble>
<artwork align="center"><![CDATA[
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) |
| |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork>
</figure>
<t>The most significant two bits of every VAP message MUST be zeroes.</t>
<t>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.</t>
<figure anchor="stun_message_type"
title="Format of VAP Message Type Field">
<preamble>The message type field is decomposed further into the
following structure:</preamble>
<artwork align="center"><![CDATA[
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|
+--+--+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork></figure>
<t>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. This
specification defines a single method, Binding. The method
and class are orthogonal, so that for each method, a
request, success response, error response and indication
are defined for that method. </t>
<t>The magic cookie field MUST contain the fixed value
0x41666679 in network byte order (note that this is a
different value than STUN). </t>
<t>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. </t>
<t>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. </t>
<t>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 encoding, and
of the attributes themselves is given in
<xref target="attribute_details"/>.</t>
<t>
The methods defined in VAP, and their corresponding method values,
are:
</t>
<figure anchor="vap_methods" title="VAP Methods">
<artwork align="center"><![CDATA[
Method Value
------ ------
Register 0x001
Unregister 0x002
Publish 0x004
Unpublish 0x005
PublishRevoke 0x006
Subscribe 0x007
Unsubscribe 0x008
Notify 0x00a
UploadVCR 0x00b
]]></artwork></figure>
<t>
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:
</t>
<figure anchor="fig-vap-atts" title="VAP Attributes">
<artwork align="center"><![CDATA[
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 .... |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork></figure>
<t>
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.
</t>
</section>
<section title="VAP Transactions">
<t>
This section describes the general behavior of VAP transactions,
regardless of the method.
</t>
<section title="Transport and Connection Management">
<t>
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.
</t>
<t>
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.
</t>
<t>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. </t>
<t>
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.
</t>
<t>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<list style="symbols">
<t>has no further VAP requests to send over that
connection, and;</t>
<t>has no outstanding subcriptions</t>
</list></t>
<t>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. </t>
</section>
<section anchor="sec-requestor" title="Requestor Procedures">
<t>
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
entity sending the request) and the responder (the entity receiving
the request).
</t>
<section title="Generating Requests">
<t>
The requestor MUST construct a request message based on the syntax in
<xref target="message_structure"/>. The message class MUST be a
request. The method depends on the method of the request.
</t>
<t>
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 <xref target="sec-mi"/>. 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.
</t>
<t>
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 <xref target="RFC2617"/>.
</t>
<t>
The request will contain other attributes depending on the method.
</t>
</section>
<section title="Receiving Responses">
<t>
All responses MUST first be authenticated by the requestor.
Authentication is performed by first comparing the Transaction ID of
the response to an oustanding 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.
</t>
<t>
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.
</t>
<t>
If the response is an Error Response, the requestor checks the
response code from the ERROR-CODE attribute of the response. For a 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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>The requestor MUST ignore any attributes from the response whose
attribute type were not understood by the requestor.
</t>
</section>
<!-- Client -->
</section>
<section anchor="sec-responders" title="Responder Behaviors">
<section title="Receiving Requests">
<t>
A responder will receive requests on an existing TCP connection,
either one initiated by the client, or the one accepted by the ViPR
server.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
The responder MUST ignore any attributes from the request whose
attribute type were not understood by the responder.
</t>
</section>
<section title="Sending Responses">
<t>
To construct the response the responder follows the message structure
described in <xref target="message_structure"/>. 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.
</t>
<t>
The attributes that get added to the response depend on the type of
response.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
</section>
<!-- end transactions -->
</section>
<section anchor="sec-state" title="State Model">
<t>
The state model for VAP is shown in Figure
<xref target="fig-vap-state"/>. This state is built up as a
consequence of the primary messages which build state on the ViPR
server: Register, Publish, UploadVCR and Subscribe.</t>
<figure anchor="fig-vap-state"
title="VAP State Model">
<artwork align="center"><![CDATA[
+-------+
|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 |
+--------+ +--------+
]]></artwork></figure>
<t> It is important to understand that the ViPR client publishes two
unique sets of information to the ViPR server: </t>
<t>
1. The set of numbers that
are reachable by the client through a particular ViPR service,</t>
<t> 2. The set of ViPR services</t>
<t> 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 the routes associated with
that Vservice, as each client will have its own route to reach the same
VService.</t>
<t> 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. </t>
<t> 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 ClientHandle, allowing the ViPR server to
immediately determine the client associated with the messaging.</t>
<t> 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.</t>
<t> 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.</t>
<t> 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 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.</t>
<t> 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.</t>
<t> 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.</t>
<t> 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.
</t>
</section>
<section anchor="sec-version" title="Protocol Versioning">
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
The protocol version number is included in client register messages,
and negotiation as part of that exchange.
</t>
<t>
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.
</t>
</section>
<section title="ViPR Client Procedures">
<section title="Discovery">
<t>
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.
</t>
</section>
<section title="Registration">
<t>
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.
</t>
<t>
The Client constructs a Register request based on the basic Client
procedures in <xref target="sec-requestor"/>. 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.
</t>
<t>
If the Client is registering for the first time towards this ViPR
server, the registration MUST omit the Client-Handle
attribute.
</t>
<t>
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.
</t>
<t>
The client MUST include the ClientLabel attribute in the
request. However, it is not used and its contents are arbitrary.
</t>
<t>
Once constructed, the Client sends the Register request to the ViPR
server. The response is processed using the general techniques in
<xref target="sec-requestor"/>. Assuming a success response is
ultimately received, it indicates that the Client has successfully
registered. This response 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.
</t>
<t>
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 <xref target="sec-version"/>, 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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
During an initial Register (one that omits Client-Handle), the client
MUST NOT generate any subsequent requests until that Register
transaction completes.
</t>
<t>
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,
as well. </t>
</section>
<section title="Unregistering">
<t>
A Client that wishes to terminate its connectiongracefully does
so using the Unregister request. This request is first constructed as
described in <xref target="sec-requestor"/>. Once constructed, the
Client MUST add the Client-Handle attribute to the request, and send
it to the ViPR server.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="Publishing Services">
<t>
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.
</t>
<t>
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.
</t>
<t>
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
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.
</t>
<t>
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.
</t>
<t>
Finally, the Publish Request MUST contain a ServiceData
attribute. This attribute contains the actual service data. Its actual
structure and syntax are a function of the service and sub-service.
</t>
<t>
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.
</t>
<t>
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 ClientHandle), flushing all subscriptions.
</t>
<t>
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.
</t>
<t>
If the response was a success, the publication has been accepted.
</t>
<section title="VService">
<t>
The VSevice 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.
</t>
<t>
The additional information placed into the VService publication will
not vary amongst different instances. That information is:
</t>
<list style="symbols">
<t>
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".
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
A count of the number of phone numbers being published for this
VService. This is used for quota management on the ViPR server.
</t>
</list>
<t>
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.
</t>
<t>
<xref target="sec-xml-vservice"/> defines the XML schema for the
object included in the Publish request.
</t>
<t>The SIP URI is constructed as follows:</t>
<list style="numbers">
<t> The scheme MUST be sip</t>
<t>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.</t>
<t> The domain part MUST be the domain associated with this
call agent, and MUST match certificates that the domain can
obtain.</t>
<t> There MUST be a port and it MUST be the port on which incoming
SIP invites can be received.</t>
<t> There MUST be an maddr URI parameter, and it MUST contain the IP
address or hostname of the instance of the call agent server.
</t>
<t> The transport URI parameter MUST be present and MUST be tcp.</t>
</list>
<t>
There will be one or more URI per each instance of the call
agent. The IP address in the URI MUST be a publically 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. </t>
<t> The use of the IP address in the maddr parameter allows the system
to operate without DNS support.</t>
<t> An example document for a Vservice on the public DHT
is: </t>
<figure anchor="fig-example-vpub"
title="Example ServiceContent">
<artwork align="center"><![CDATA[
<?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>
]]></artwork></figure>
<t>
The ViPR client SHOULD publish each ViPR trunk service to both its
primary and backup ViPR server, for purposes of HA.
</t>
</section>
<section title="ViPR Number Service">
<t>
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; it is merely left to expire.
</t>
<t>
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.
</t>
</section>
<!-- end client Publication -->
</section>
<section title="Updating the VService">
<t>
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.
</t>
<t>
To update a VService, the client modifies its service description, and
creates a new Publish request. This request is first formed as
described in <xref target="message_structure"/>. 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.
</t>
<t>
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).
</t>
<t>
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.
</t>
<t>
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 ClientHandle).
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="Uploading VCRs">
<t>
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.
</t>
<t>
In addition, it MUST contain a CallingNum, CalledNum, StartTime and
StopTime attribute. The CallDirection attribute is set as described in
<xref target="sec-calld" />.
</t>
<t>
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.
</t>
<t>
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 ClientHandle) and a new VService
publication.
</t>
<t>
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.
</t>
</section>
<section title="Subscribing to number Services">
<t>
In order to learn about validated numbers, a ViPR client MUST
subscribe for the ViPR number service. The client should subscribe to
just its primary ViPR server.
</t>
<t>
To create a subscription, the Client creates a Subscribe request. The
request is formed as described in
<xref target="message_structure"/>. It MUST NOT be sent if the Client
has not previously generated a successful Register request on this
connection.
</t>
<t>
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.
</t>
</section>
<section title="Unsubscribing to Services">
<t>
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.
</t>
<t>
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.
</t>
<t>
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 ClientHandle).
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="Receiving Notify">
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="Receiveing PublishRevoke">
<t>
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.
</t>
</section>
</section>
<section title="ViPR Server Procedures">
<section title="Connection Establishment">
<t>
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. If so configured for TLS, the ViPR
server must be prepared to receive TLS with mutual TLS authentication.
</t>
</section>
<section title="Registration ">
<t>
The purpose of registrations is to create VAP client objects, which
represent a VAP connection and contain the state described in
<xref target="sec-state"/>, 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.
</t>
<t>
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 <xref target="sec-responders"/>. 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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
If the registration succeeds, the server sends a success
response. This response MUST include the ClientHandle attribute
containing the handle created by the server. The response MUST
include a Keepalive 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.
</t>
</section>
<section title="Unregistration">
<t>
The client can gracefully disconnect by using an Unregister request.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
Note that unregistration does not ever remove VCRs.
</t>
</section>
<section title="Publication">
<t>
Behavior depends on whether the publication is for the
Vservice or the ViPR number service.
</t>
<t>
The ViPR server extracts the ServiceIdentity attribute. If the value
is not one of the following:</t>
<t><list style="numbers">
<t>ServiceID is 101 and SubserviceID is 3.</t>
<t>ServiceID is 101 and SubserviceID is 4</t>
</list></t>
<t>
the ViPR server sends a 400 response.
</t>
<section title="Vservice">
<t>
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 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. </t>
<t>
The ViPR server extracts the contents of the ServiceContent
attribute. This will be an XML object structured as defined in
<xref target="sec-xml-vservice"/>. It also extracts the VServiceID and
Instance values from the ServiceIdentity attribute.
</t>
<t>
First, the ViPR server checks if it has any Vservice objects with
the VServiceID from the publish.
</t>
<list style="symbols">
<t> 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:</t>
<t><list style="symbols">
<t>If it is, the route elements for that instance are replaced
with the route values from the publish.</t>
<t>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.
</t>
</list></t>
<t>
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 routevalues from the publish are
associated with that instance.
</t>
</list>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="ViPR number Service">
<t>
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.</t>
<t>
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 prefix seed.
</t>
<t> Next, the ViPR server generates two additional strings. The first
is formed by taking the prefix seed, and appending the string
"COPY1". The second is formed by taking the prefix seed
and appending the string "COPY2". </t>
<t>
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 resourceID
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.
</t>
<t>
Conceptually:
</t>
<figure><artwork align="left"><![CDATA[
Store(resourceID, object)
]]></artwork></figure>
<t>Where resourceID is the 128
bit resourceID computed above. The stored object is a dictionary entry
which has a key and a value:</t>
<figure><artwork align="left"><![CDATA[
Object = {key,value}
]]></artwork></figure>
<t>
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
0x8h60f5gab753037g64ab6c53947fd532 receives a Publish with a Vservice
of 0x7ggb6a7036478351, the resulting key is:</t>
<figure><artwork align="left"><![CDATA[
8h60f5gab753037g64ab6c53947fd532+7ggb6a7036478351
]]></artwork></figure>
<t>
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 every 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 Vservice ID) do not
clobber or step on numbers published by another call agent (using a
different Vservice ID). The responsible node does not verify or check
the VserviceID.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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 (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
disambiguation the first Publish for a service and an updated
Publish. It performs identical processing for each.
</t>
<t>
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.
</t>
</section>
<!-- end publication -->
</section>
<section title="UnPublish">
<t>
The ViPR client can only Unpublish for the Vservice.
</t>
<t>
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.
</t>
</section>
<section title="Subscribe">
<t>
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.
</t>
<t>
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.
</t>
<t>
If the ServiceIdentity is valid, the server MUST create a new
subscription object. It MUST allocate a subscription ID for this
subscription. This ID MUST be unique across all subscription IDs
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
assign them sequentially and store the associations.</t>
<t>
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. </t>
<t>
The server then generatres a success response to the Subscribe
request. It MUST include the SubscriptionID attribute in the response,
identifying this subscription.
</t>
</section>
<section title="UnSubscribe">
<t>
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.
</t>
<t>
Next, the server extracts the SubscriptionID attribute from the
request. If it contains a subscription ID 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.
</t>
<t>
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.
</t>
</section>
<section title="UploadVCR">
<t>
The ViPR server first processes the request like any other VAP
request, specifically it will perform the message integrity check and
follow associated procedures.
</t>
<t>
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.
</t>
<t>
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
terminating UploadVCR.
</t>
<section title="Originating">
<t>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.
</t>
<t>
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.
</t>
<t>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.
</t>
<t>
If there is a result, the ViPR server will now have all of the
dictionary entries associated with the resourceID. 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.
</t>
<t>
The ViPR server SHOULD perform validation, using the validation
protocol <xref target="I-D.rosenberg-dispatch-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.
</t>
<t>
If a Notify is to be sent as a consequence of a validation success,
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 E164 number of the called number which validated.
</t>
</section>
<section title="Terminating">
<t>
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.
</t>
</section>
</section>
<section title="Sending Notify">
<t>
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.
</t>
<t>
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.
</t>
<t>
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 documented, which is
the scrubbed document from the ValExchange response. An example
document is:
</t>
<figure anchor="fig-notify-xml"
title="Example Notify XML">
<artwork align="center"><![CDATA[
<?xml version="1.0" encoding="utf-8"?>
<valinfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="valinfo.xsd">
<number>+17327662496</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>
]]></artwork></figure>
</section>
<section title="Sending PublishRevoke">
<t>
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 PublishRevoken
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.</t>
</section>
<!-- end server -->
</section>
<section title="Syntax Details">
<section anchor="sec-xml-vservice" title="XML Schema for Vservice">
<t> This document is included in publications for the ViPR service. Note
its target namespace. </t>
<figure anchor="fig-vservice-xmlschema" title="VService XML Schema">
<artwork align="center"><![CDATA[
<?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">
<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>
</xs:schema>
]]></artwork></figure>
</section>
<section title="XML Schema for ValInfo">
<t>
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.
</t>
<figure anchor="fig-valinfo-xmlschema" title="Valinfo XML Schema">
<artwork align="center"><![CDATA[
<?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>
]]></artwork></figure>
</section>
<section anchor="attribute_details" title="VAP Attributes">
<t>
This section enumerates the attributes used by VAP. The attribute
names and corresponding types are:
</t>
<figure anchor="fig-vapatts" title="VAP Attributes">
<artwork align="center"><![CDATA[
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
ServiceData 0x100c
SubscriptionID 0x100e
CallDirection 0x2001
StartTime 0x2002
StopTime 0x2003
CallingNum 0x2004
CalledNum 0x2005
peerID 0x2008
Quota 0x200a
DHTLifetime 0x200b
]]></artwork></figure>
<section title="USERNAME">
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="REALM">
<t>
The REALM attribute is present in requests and responses. It contains
text which meets the grammar for "realm" as described in RFC 3261
<xref target="RFC3261"/>, and
will thus contain a quoted string (including the quotes).
</t>
<t>
The value of this attribute MUST always be "ViPR".
</t>
</section>
<section anchor="sec-mi" title="MESSAGE-INTEGRITY">
<t>
The MESSAGE-INTEGRITY attribute contains an HMAC-SHA1
<xref target="RFC2401"/> 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, ncluding 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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="ERROR-CODE">
<t>
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 <xref target="RFC3261"/> and
<xref target="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.
</t>
<t>
To facilitate processing, the class of the error code (the hundreds
digit) is encoded separately from the rest of the code.
</t>
<figure anchor="fig-error-syntax" title="ERROR-CODE Syntax">
<artwork align="center"><![CDATA[
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) ..
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork></figure>
<t>
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.
</t>
<t>
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.
</t>
<t>
The following response codes, along with their recommended reason
phrases (in brackets) are defined at this time:
</t>
<list style="hanging">
<t hangText="400 (Bad Request):">The request was malformed. The
requestor should not retry the request without modification from the
previous attempt.</t>
<t hangText="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 .
</t>
<t hangText="436 (Unknown Username):"> The username was not
known. This was likely due to a misconfiguration.
</t>
<t hangText="471 (Bad Client Handle):"> The client handle provided in
the Register request is not known.
</t>
<t hangText="472 (Version Number Too Low):"> The client published a
service whose version was lower than the currently held one by the
server.
</t>
<t hangText="474 (Unregistered):"> The client tried an operation, such
as publish or subscribe, but it has not yet registered.
</t>
<t hangText="476 (Unknown Subscription):"> The referenced subscription
does not exist.
</t>
<t hangText="477 (Already Registered):"> The client tried an initial
Register request, but it is already registered.
</t>
<t hangText="478 (Unsupported Protocol Version):"> The server does not
support the protocol version requested by the Client.
</t>
<t hangText="481 (Publication Failed):"> The
publication was attempted but could not be performed due to an error
reaching the DHT. The client should try again.
</t>
</list>
</section>
<section title="Client-Name">
<t>
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.
</t>
<t>
It is RECOMMENDED that it be constructed as:
</t>
<figure>
<artwork align="center"><![CDATA[
<vendor>/<product>/<version>/<hostname or IP>
]]></artwork></figure>
<t>
Where version includes major, minor and build.
</t>
</section>
<section title="Client-Handle">
<t>
This attribute has a 32 bit value, representing an unsigned integer to
be used as the client handle.
</t>
</section>
<section title="Protocol-Version">
<t>
This attribute is 32 bits, consisting of two 16-bit unsigned integers,
representing the major and minor version numbers of the protocol:
</t>
<figure anchor="fig-version-att" title="Protocol-Version Syntax">
<artwork align="center"><![CDATA[
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 |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork></figure>
</section>
<section title="Client-Label">
<t>
This attribute is a UTF-8 string, which MUST be between 1 and 255
characters. It is not used by this specification.
</t>
</section>
<section title="Keepalive">
<t>
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.
</t>
</section>
<section title="ServiceIdentity">
<t>
The format of the ServiceIdentity attribute is:
</t>
<figure anchor="fig-serviceidentity" title="ServiceIdentity Attribute">
<artwork align="center"><![CDATA[
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) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
]]></artwork></figure>
<t>The value of serviceID must always be 101. A Subservice value of 4
indicates VService publications. A subservice value of 3 indicates
number publications.
</t>
</section>
<section title="ServiceVersion">
<t>
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
</t>
</section>
<section title="ServiceContent">
<t>
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.
</t>
<t>
The ServiceContent MUST be less than 32k, despite the fact that the
length field of the attribute itself would allow content up to 64k.
</t>
</section>
<section title="SubscriptionID">
<t>
The SubscriptionID is present in successful responses to Subscribe and
in Unsubscribe messages. It contains an indentifier 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.
</t>
</section>
<section anchor="sec-calld" title="CallDirection">
<t>
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.
</t>
</section>
<section title="StartTime">
<t>
The start and stop times are both 64 bit NTP time values. The start
time is measured in the following way:
</t>
<t><list style="numbers">
<t>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. </t>
<t>
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.
</t>
</list></t>
</section>
<section title="StopTime Attribute">
<t>
The stop time is a 64 bit NTP value and is measured in the following
way:
</t>
<list style="numbers">
<t>
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.
</t>
<t>
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.
</t>
</list>
</section>
<section title="CallingNum Attribute">
<t>
The calling and called party numbers MUST be expressed in fully
qualified E.164 format, and the attribute is a string with variable
length.
</t>
<t>
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.</t>
<t>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.
</t>
</section>
<section title="CalledNum Attribute">
<t>
The calling and called party numbers 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:</t>
<t> 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.
</t>
<t>
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.
</t>
</section>
<section title="Quota Attribute">
<t>
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.
</t>
</section>
<section title="DHTLifetime Attribute">
<t>
This attribute has identical syntax to the Keepalive attribute. It
indicates the number of seconds that data written into the DHT
will remain in the DHT prior to being expunged.
</t>
</section>
<!-- end attributes -->
</section>
<!-- syntax -->
</section>
<section title="Security Considerations">
<section title="Outsider Attacks">
<t>
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.
</t>
</section>
<section title="Insider Attacks">
<t>
Of much more concern are attacks whereby the client is authenticated,
but it misuses the VAP connection to attack the overall system.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="IANA Considerations">
<t>
There are no IANA considerations associated with this specification.
</t>
</section>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.2119"?>
<?rfc include="reference.RFC.3261"?>
<?rfc include="reference.RFC.5389"?>
<?rfc include="reference.RFC.0791"?>
<?rfc include="reference.RFC.2617"?>
<?rfc include="reference.RFC.2401"?>
<?rfc include="reference.RFC.2616"?>
<reference anchor="I-D.rosenberg-dispatch-vipr-pvp">
<front>
<title abbrev="VIPR PSTN Validation Protocol">The Public Switched
Telephone Network (PSTN) Validation Protocol (PVP)</title>
<author fullname="Jonathan Rosenberg" initials="J.R."
surname="Rosenberg">
<organization>Cisco</organization>
<address>
<postal>
<street></street>
<city>Edison</city>
<region>NJ</region>
<country>US</country>
</postal>
<email>jdrosen@jdrosen.net</email>
<uri>http://www.jdrosen.net</uri>
</address>
</author>
<author fullname="Cullen Jennings" initials="C." surname="Jennings">
<organization>Cisco</organization>
<address>
<postal>
<street>170 West Tasman Drive</street>
<street>MS: SJC-21/2</street>
<city>San Jose</city>
<region>CA</region>
<code>95134</code>
<country>USA</country>
</postal>
<phone>+1 408 421-9990</phone>
<email>fluffy@cisco.com</email>
</address>
</author>
<date day="2" month="November" year="2009" />
<area>RAI</area>
<workgroup>dispatch</workgroup>
</front>
</reference>
</references>
<references title="Informative References">
<?rfc include="reference.I-D.ietf-p2psip-concepts"?>
<reference anchor="I-D.rosenberg-dispatch-vipr-overview">
<front>
<title abbrev="VIPR Overview">Verification Involving PSTN
Reachability: Requirements and Architecture Overview</title>
<author fullname="Jonathan Rosenberg" initials="J.R."
surname="Rosenberg">
<organization>Cisco</organization>
<address>
<postal>
<street></street>
<city>Edison</city>
<region>NJ</region>
<country>US</country>
</postal>
<email>jdrosen@jdrosen.net</email>
<uri>http://www.jdrosen.net</uri>
</address>
</author>
<author fullname="Cullen Jennings" initials="C." surname="Jennings">
<organization>Cisco</organization>
<address>
<postal>
<street>170 West Tasman Drive</street>
<street>MS: SJC-21/2</street>
<city>San Jose</city>
<region>CA</region>
<code>95134</code>
<country>USA</country>
</postal>
<phone>+1 408 421-9990</phone>
<email>fluffy@cisco.com</email>
</address>
</author>
<date day="2" month="November" year="2009" />
<area>RAI</area>
<workgroup>dispatch</workgroup>
</front>
</reference>
</references>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-24 01:19:09 |