Client Capabilities for VWRAP
draft-levine-vwrap-clientcap-01

Abstract

client side capabilities for VWRAP.

Status of this Memo

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

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet-Drafts.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as “work in progress.”

The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt.

The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html.

This Internet-Draft will expire on September 9, 2010.

Copyright Notice

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

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

Table of Contents

1.  Requirements Language
2.  overview
3.  Motivation
4.  Requirements
5.  Options
6.  Rest/Caps style model for client resources
7.  One approach
8.  A simple example (friendship)
9.  An eventq URI
10.  Putting it all together
11.  From login to a client cap delivered message
12.  Login/Auth initial cap grants
13.  Setting up an event queue
14.  Wiring up the client side resource of a service
15.  Flowing a message to the handler
16.  Flowing a response
17.  Passing back content
18.  IANA Considerations
19.  Security Considerations
20.  References
    20.1.  Normative References
    20.2.  Informative References
Appendix A.  Additional Stuff
§  Authors' Addresses

1.  Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].

2.  overview

This note defines the use of "Client" side capabilities within the VWRAP specifications. Client Capabilities are Capabilities, as defined by the VWRAP specifications, on the client or virtual worlds viewer.

Client side capabilities will often represent resources hosted on devices and systems behind firewalls, and will thus be accessed via event queues are similar mechanisms. This note defines patterns for using client side capabilities, and an URI scheme for addressing such capabilities. A fairly complete worked example is provided. The exact LLSD, the exact URI formats, and the example service are provided to illustrate the service pattern, and are extremely provisional. The sequence diagrams used to illustrate the flows, as well as the structural diagrams represent one possible approach to implementing the service pattern. Nothing beyond the interfaces would be normative. This note is an informational draft. It is very preliminary and is intended to drive discussion.

Questions of note:

1. How much run time / latency cost is associated with this design? As we move things from UDP to client side caps, what are the performance implications for the client?
2. This design is intended to permit the substitution of r-http, websockets, or xmpp or similar transports in the architecture. How close do we come to that ideal?
3. Will this model fit well with the security and trust policy model being contemplated for VWRAP?
4. Do we really want to specify that requests to the client should be valid on 'any' event queue pipe?? For instance, if I am an untrusted region, maybe I do not want to service a request for friendship. Maybe i don't trust the region enough to take friendship requests, maybe i only want to accept them from my nice safe trusted agentd.
5. Is everything in the eventq uri needed? The viewer wouldn't be servicing requests for other agents
6. Why is host_end_cap specified the way it is? Why is it not just a URI like it is today?
7. Are we missing any key requirements here?

3.  Motivation

The VWRAP specifications derive much of their initial structure from the design patterns embodied in Linden Lab(TM)'s Second Life(Tm) virtual world service. This service has been characterized by a fairly straightforward deployment pattern, where services are clustered and facaded behind large, unitary interfaces.

In a facaded model it is easy to manage message routing. From the client's perspective, all traffic terminates in the facade. There is an event queue or a two way pipe, and the client accepts asynchronous traffic from any services within the facade from that message source. The facade pattern hides any internal routing within the service deployment. There may be internal routing occurring, but the client is kept unaware of these issues.

The VWRAP specifications describe a set of services. When those services are decomposed into multiple deployment patterns, the question of how a given service can delivery asynchronous information to another service or client becomes cogent.

The "caps granting" pattern makes it straight forward to return a cap to a separate service. A client may contact the seed cap granter at a URI and be handed a URI to a service hosted on a separate server and indeed a service which is not even hosted by the cap granter. Services returned by a single caps grant may span trust and administrative domains. When these services need to deliver asynchronous messages the routing problem becomes clear.

The second motivation for this work is managing pairwise addition and evolution of protocols. The current design assumes that the "client" is a unitary, process with a deep understanding of the expected services available on the servers. As the VWRAP specification grow, and we build and explore various ways of delivering services, we will want to allow new services to be described, and we will almost certainly find the current client approach limiting. Having an explicit way of saying "For this service, please route notification to this endpoint" allows people to easily build a range of possible client side structures including ones which are different than current clients.

These two sets of motivations drive a desire to explicitly model the service deployment and client deployment model in a way that allows a dynamic association between the services.

4.  Requirements

This note addresses the following requirements for service/client modeling in VWRAP:

1. Support deploying services across arbitrary domain and hosting models In particular, permit services to be deployed across multiple hosts within a domain, clustering pipes, and securely sharing event queues and event delivery.
2. Abstract away a specific single bidirectional pipe from the VWRAP specs Support event queues, r-http if it becomes a common pattern, websockets, if they become common, and full duplex schemes, such as xmpp, if they become viable
3. Provide a model for architecturally describing resources on the client. This, in effect, is "addressing" client side resources, providing references to them.
4. Permit service side deployers to pass around references to these client side resources within the service cloud safely and transparently
5. • Prevent services from spoofing messages to resources others than those they have been granted access to
   • Provide a endpoint independent path to the client (via any eventq available, or any URI representing the client resource)
   • Preventing guessing of endpoint resource addresses
6. Closely model the current event queue implementations

Support deploying services on multiple domains and hosting models Virtual worlds have a wide range of deployment patterns, and require a broad range of services, with different computational profiles. We want to enable people to delegate services to arbitrary servers. This should enable clouds to host services, and permit deployers to choose deployment models which meet their needs. Abstracting away specific pipes This is the single largest driver. We want to divorce the VWRAP specifications from the current Linden Lab event queue implementation, the UDP pipes, and any single approach to delivering bits to the client. VWRAP aspires to support virtual worlds over a period of multiple years. We assume that the pipes to clients will evolve over time. Creating a web services, URI addressed approach to managing connections to regions, is a powerful way to de-couple transport choices from protocol handlers.

5.  Options

There are basically two broad strokes of options and then severl variations. In all of the options for solving this set of requirements, we need to allow the client and a set of servcies determine how to wire each other together in the face of possible transports. In particular, we need to signal to the client if it needs to take specific actions to permit servcies to signal it, and services, the actions they may need to take as well.

Currently, services simply chose to use either UDP or the eventq managed by the region to access the client. The client is forced to assume a message might come over either pipe. This exposes the client to complexity, and open up potential security exposures, if an attack is delivered over an unexpected channel. The notion of listening on all possible channesl also becomes problematic as additional possible channels become available, such as websockets, or xmpp.

The broad stroke options are to either have an asynchronous pipe for each service of cluster of facaded services, or to permit one or more aynchronous pipe to proxy for other services. Note that aynchronous pipe might be an event queue, a websocket connection, or other appropriate transport. In any of these cases, the question will devolve onto either sharing some connectoin(s) or having a single connectoin per service/Service facade. (A faceded servie collection is effectively sharing an event path, it merely hides it in the details of its implementation. Servcies aggregated by a single provider can easily facade in this fashion, although potentially at he cost of creating bottlenecks. Aggregatign services provided by multiple provdiers exposes trust and API boundaries.

6.  Rest/Caps style model for client resources

This represents one pattern which could address the requirements. One open question is whether simply permitting each service to create an event queue as needed is sufficient.

Once we want to model the client's resources separate from the communications pipes used to access those resources, we are faced with the problem of naming, and addressing those resources. The current client, mostly assumes that it can parse from message type to determine where the message should be routed. The overall justifications for using REST approaches are as cogent for the client, as any other portion of VWRAP. The REST model affords a consistent approach to modeling resources

7.  One approach

We approach the overall design as describing access to resources hosted by clients. As many clients are inaccessible for full HTTP access from the services which wish to contact them, we describe the overall approach, in a way which permits event queues to be used in the current implementation, and approaches such as reverse-HTTP (Sometimes referred to as rhttp, r-http or ptth) in the future with no changes to the basic approach. (and ideally none to the code, beyond supporting r-http listeners.) Named client side resources The major addition to the current model is that of addressable client side resources. This effectively extends the REST/ Capabilities model to interactions involving sending data to the client. Instead of sending them to the client as a single endpoint, we can route the data to specific endpoints managed by the client. By using the basic REST model for manipulating these resources, we get a simple, well defined set of interactions between services and client side resources.

8.  A simple example (friendship)

So, instead of embedding friendship inside a IM message, or even in a separate message, and requiring the client to parse the header and then route the message, we instead define a resource on the client, which is associated with friendship messages. This resource is then passed to the service(s) which need to manipulate the resource. The common case will be that services will post messages to the client, but we define the model generally so that services can invoke normal REST semantic operations on the resources.

Exposing client side resources with an event queue

Since the client cannot directly expose its resources, the client relies on event queues to fetch requests destined for these resources from services. This is mediated via a COMET style event queue. The client polls the service, and when there are requests destined for it, it collects those requests and routes them to the handlers which process them.

The requests contain the resource they are routed to, and the method to be invoked on the resource, as well as the payload of the request.

<map>
<key>sequence</key><int>sequence number</int>
<key>resource</key><string>path of resource</string>
<key>method</key><string>POST</string>
<key>payload</key>{LLSD of payload}
</map>

Each request can be routed by the client side event queue to the desired handler. Note the separate event queues sharing one map of resource to handlers, and delivering events to shared handlers. Now, in order to complete this story, we need to describe how the services know what resources on the client they should post to, and how these resources are addressed.

9.  An eventq URI

To support addressing client side resource reached event queues, we introduce an "eventq:" URI. eventq://client_id@fqdn_of_eventq_host/{path to resource} or eventqs://client_id@fqdn_of_eventq_host/{path to resource} For details on URI format, http://en.wikipedia.org/wiki/URI_scheme and more formally: http://tools.ietf.org/html/rfc3986 We are describing a scheme "eventq" with hierarchical part broken into the traditional "authority" and "path" Our authority is addressed as "client_id@fqdn_of eventq_host" What this says is "for the unique client (client_id) you can route via an event queue hosted by the host listed as "fqdn_of_eventq_host" which will be a hostname. To address the specif resource, on that client, you must provide the path. The client_id, is a short term unique string representing the client, during this session with the services cloud. This is provided to permit several important options. First, it permits us to pass a capability with an eventq: URI to a service which already has a connection to the client, and allows the transport level software to understand it already has a connection to the client. It also allows correct behavior in the face of an attempt to re-establish a connection to the eventq host, and finally, it allows services to chose *any* event queue it knows about which connects to the client for delivering it's requests to the client. This allows a number of potential deployment patterns which permit scaling of the computational fabric with no changes to the client, or necessarily the services. The eventqs scheme, is identical to the eventq scheme, with the added requirement that the underlying event queue be implemented using https or an equally secure transport, so that messages cannot be intercepted, and there is a high degree of confidence that the host holding the service end of the eventq is the desired host.

10.  Putting it all together

To actually use this plumbing, we need to associate the client side resource with the service which wishes to use it. We incorporate this into the setup flow needed to use the resource. The client/viewer requests a capability from a seed cap in the services network. (from initial login, or transitively from other caps) The service returns with a URI of the service side resource. The client then creates a client side resource (or resources) for the service to use, and passes them up to the service, which then begins to issue requests against these resources.

1. Client/Viewer logs into a service and acquires one or more seedcaps
2. The client requests a set of capabilities from the seedcaps.
3. One or more of these capability requests includes an event queue
4. The client establishes the event queues, posting its "client_id" to the event queue host.
5. Zero or more of the capabilities requested use client side resources. For these capabilties, the client creates and registers a client side resource, in the form of a client capability, composes a URI for the resources, and informs the service of the URIs of the client side resources.
6. The service side service begins posting requests on the associated event queues
7. The client routes the requests to the registered handlers.
8. We flow a response from the handler back to the invoker

11.  From login to a client cap delivered message

A small worked example. The actual service involved, and the deployment details of the service are purely notional. Do not focus on the specific service messages, but the routing and setup flows which enable the messages to flow.

12.  Login/Auth initial cap grants

This is pretty much VWRAP business as usual. The client connects to the authentication service, and gets a seedcap, on an Agent Domain Service (n, one of many)

+----------------+       +-------------------+  +------------------+
| VWRAP viewer    |       | VWRAP Auth Service |  | Agent  Service |
+----------------+       +-------------------+  +------------------+
        |                          |                     |
        | Login()                  |                     |
        |--------------------- --->|                     |
        |                          |                     |
        | login_response(seed_cap) |                     |
        |<-------------------------|                     |
        |                          |                     |
        | Request_caps(Caps list)  |                     |
        |----------------------------------------------->|
        |                          |                     |
        |                          |                     |
        |<-----------------------------------------------|
                caps_granted(array of caps, URIs, of caps)

13.  Setting up an event queue

Pretty straight forward. We create a handler on the client, which calls the cap the client got from the login step. There is one additional tidbit that flows at this point, which is that we get the Host end of our caps. This fetches from the host side of the agent domain event queue, which we will use in our URIs. XXX dummy needs explanation here.

<map>a77e875e0f82d975@adhost.test.org/ccaps/e132c4ea-55c8-4be3-a77e-
<key>host_end_cap</key>
<string>fully.qualified.domain.com</string>
</map>

14.  Wiring up the client side resource of a service

The next step is the major addition to the sequence. We take the cap for a service we requested earlier, and then create the client side handler, associate it with a client side resource, and pass that resource to the service side cap.[NOTE: this seems confusing, i think in part because I'm not sure who "we" is. So it is hard to tell who is telling whom. I think u know what you mean, but it's not coming across in the text. Also, Is there a step where the client 'advertises' what services it can provide on a specific event queue? And Does the server side 'ask' for a list of client side caps like the viewer asks for caps from the AD and region? ]

<map>
<key>org.VWRAP.friendship.client_listener</key>
<string>eventq://4a0e0e09-d3e1-4ab8-bc3f-
875e0f82d975@adhost.test.org/ccaps/e132c4ea-55c8-4be3-a77e-
3ec91ef63b7a/fslistner</string>
</map>

15.  Flowing a message to the handler

Finally, with all the bits in place, the invoker can send an event, and expect it to get picked up at the far end by the handler. XXX is this the AD handler, the friendship services handler, or do you mean the client eq handler?? This thing just aches for an actual diagram. XXX Our hypothetical message is:

<map>
<key>request_type</key>
<string>friendship request</string>
<key>user social name</key>
<string> Hippo The Avatarian</string>
<key>user uuid</key>
<string>4509971b-b2f3-43a9-bc71-1736c971a8f7</string>
<key>message</key>
<string>Please be my friend, we met at the hippo wallow last week
</string>
</map>

So, the Friendship services takes that payload, and the URI of the client's resource. It is out of scope, how it posts the request to the service end of the event queue. (being a deployer issue, not part of the public spec) It passes the URI, and the payload, and it gets to the input hopper of the event queue, along with the method being invoked. (in this case "POST") The event queue then packages up the message as part of the array of messages it has bound to the client: XXX not quite sure why you need to state it is out of scope. plz explainie.

<array>
.
.
<map>
<key>method</key><string>POST</string>
<key>sequence id</key><integer>98726</integer>
<key>resource</key>
<string>/ccaps/e132c4ea-55c8-4be3-a77e-3ec91ef63b7a/fslistner</string>
<key>payload</key>
<map>
<key>request_type</key>
<string>friendship request</string>
<key>user social name</key>
<string> Hippo The Avatarian</string>
<key>user uuid</key>
<string>4509971b-b2f3-43a9-bc71-1736c971a8f7</string>
<key>message</key>
<string>Please be my friend, we met at the hippo wallow last week
</string>
</map>
</map>
</array>

16.  Flowing a response

No such resource: If there is no client side handler at the resource listed in the request the event queue handler flows back a 404 responds per traditional http; XXX if we arent requiring http, do we need our own set of error codes defined?

<array>
..
<map>
<key>sequence number</key><integer>98726</integer>

<key>http_response</key>
<map>
<key>response code</key>
<integer>404</integer>
<key>payload</key>
<string>
No resource associated with this key
</string>
</map>
</map>
</array>

Successful responses When the client's friendship handler has accepted the request, it can post a response. This can, of course, include simply accepting the request, and then posting an "accept friendship" message to the main cap, or accepting it directly, depending on the design of the friendship service. We will do both, for illustrative purposes

Simple OK

For the simple, accepted response, the handler will post back to the event queue an OK. (This is an internal flow, not part of the VWRAP architecture) and the event queue will then pass on the response to the invoker. It Structurally, this is very similar to the request. The get() call will pass up responses for handling by the service side event queue.

<array>
..
<map>
<key>sequence number</key>
<integer>98726</integer>

<key>http_response</key>
<map>
<key>response code</key>
<integer>200</integer>
<key>payload</key>
</map>
</map>
</array>

17.  Passing back content

The final case, is actually passing back content on a reply. This merely adds the payload.

<array>
<map>
<key>sequence number</key>
<integer>98726</integer>

<key>http_response</key>
<map>
<key>response code</key>
<integer>200</integer>
<key>payload</key>
  <map>
  <key>request_type</key>
  <string>friendship accept</string>
  <key>user social name</key>
  <string>Happy Songbird</string>
  <key>user uuid</key>
  <string>4509971b-ffa3-43a9-1748-1736c978fa3e</string>
  <key>message</key>
  <string>Thank you. I'd love to be friends.
  </string>
  </map>
</map>
</map>
</array>

The overall pattern and other URIs.. The overall pattern is intended to provide a framework for handling not just eventq: scheme URIs, but any URI which will successfully flow the data between the two services. For this to work, the basic pattern, of setting a client side cap needs to keep in mind that the "eventq/eventqs" scheme is not the only URI which might be passed in the future.

18.  IANA Considerations

This memo includes no request to IANA.

If this specification progresses, a request to IANA to register the eventq scheme might be contemplated

19.  Security Considerations

Event queues expose client side resources to messages from servers. The URI for eventq provides routing to these resources. This exposes these resources to a number of possible attacks. The use of capabilities, and the limitation that in order to access a client side capability, one has to have access to the host side of an event queue, eliminates most of the possible attacks. The current capabilities specification uses a 128 bit UUID, generated for each session, for each capability, to make the resource portion of the capability essentially un-guessable. This requires care in passing around capabilities, as if they are passed in plain text, they would be subject to sniffing, and if passed in open sessions, such as HTTP, they would be vulnerable to man in the middle attacks. Control of the services side endpoint of event queues provides a separate means of limiting the security issues. Nothing described here defines how the host end of an event queue is exposed to services. Depending on the host implementation, the resource could be accessible broadly, or only to programs running in the address space of the event queue. If the resource is made available broadly, the capability design limits the exposure of the resource to messages aimed at the actually resource, but opens up the event queue itself as a vehicle for denial of service attacks.

20.  References

20.1. Normative References

20.2. Informative References

Appendix A.  Additional Stuff

This becomes an Appendix.

Authors' Addresses