OGPX pre BOF                                              D. Levine, Ed.
Internet-Draft                             IBM Thomas J. Watson Research
Intended status: Informational                                    Center
Expires: January 14, 2010                                  July 13, 2009

                      Client Capabilities for OGPX

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-

   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

   The list of Internet-Draft Shadow Directories can be accessed at

   This Internet-Draft will expire on January 14, 2010.

Copyright Notice

   Copyright (c) 2009 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 in effect on the date of
   publication of this document (http://trustee.ietf.org/license-info).
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.


   client side capabilities for OGPX.

Levine                  Expires January 14, 2010                [Page 1]

Internet-Draft              OGPX Client Caps                   July 2009

Table of Contents

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

Levine                  Expires January 14, 2010                [Page 2]

Internet-Draft              OGPX Client Caps                   July 2009

1.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   document are to be interpreted as described in RFC 2119 [RFC2119].

2.  overview

   This note defines the use of "Client" side capabilities within the
   OGPX specifications.  Client Capabilities are Capabilities, as
   defined by the OGPX specifications, on the client or virtual worlds
   viewer.  Often, these capabilities will 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 adressing 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 a DRAFT it is very preliminary and
   is intended to drive discussion.  Following further discussion, I
   expect to post it as a formal input to the OGXP discussion.

   Questions of note:

   1.  How much run time / latency cost is associated with this design

   2.  This design is intended to permit the substitution of rhttp, or
       xmpp or similar transports in the architecture.  How close do we
       come to that ideal.

   3.  Is this secure enough to not hit an instant EKR wall at the IETF

   4.  Are we missing any key requirements here?

3.  Requirements

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

   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.

Levine                  Expires January 14, 2010                [Page 3]

Internet-Draft              OGPX Client Caps                   July 2009

   2.  Abstract away a specific single bidirectional pipe from the OGPX
       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


       *  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
   chose deployment models which meet their needs.  Abstracting away
   specific pipes This is the single largest driver.  We want to divorce
   the OGPX specifications from the current Linden Lab event queue
   implementation, the UDP pipes, and any single approach to delivering
   bits to the client.  OGPX 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.

4.  Rest/Caps style model for client resources

   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

Levine                  Expires January 14, 2010                [Page 4]

Internet-Draft              OGPX Client Caps                   July 2009

   justifications for using REST approaches are as cogent for the
   client, as any other portion of OGP.  The REST model affords a
   consistent approach to modeling resources

5.  Overall 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 eventqueues to be used in
   the current implementation, and approaches such as reverse-HTTP
   (Sometimes refered 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

6.  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.

Levine                  Expires January 14, 2010                [Page 5]

Internet-Draft              OGPX Client Caps                   July 2009

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

   Each request can be routed by the 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.

7.  An eventq URI

   To support addressing client side resource reached vit 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 specic 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 underyling 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.

Levine                  Expires January 14, 2010                [Page 6]

Internet-Draft              OGPX Client Caps                   July 2009

8.  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

   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

9.  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.

10.  Login/Auth initial cap grants

   This is pretty much OGP business as usual.  The client connects to
   the authentication service, and gets a seedcap, on an Agent Domain

Levine                  Expires January 14, 2010                [Page 7]

Internet-Draft              OGPX Client Caps                   July 2009

   Service (n, one of many)

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

11.  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.  The AD has created
   an event queue, which we call.  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.


12.  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

Levine                  Expires January 14, 2010                [Page 8]

Internet-Draft              OGPX Client Caps                   July 2009


13.  Flowing a message to the handler

   Finally, with all the bits in place, we can send an event, and expect
   it to get picked up at the far end by the handler.  Our hypothetical
   message is:

   <string>friendship request</string>
   <key>user social name</key>
   <string> Hippo The Avatarian</string>
   <key>user uuid</key>
   <string>Please be my friend, we met at the hippo wallow last week

   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:

Levine                  Expires January 14, 2010                [Page 9]

Internet-Draft              OGPX Client Caps                   July 2009

  <key>sequence id</key><integer>98726</integer>
  <string>friendship request</string>
  <key>user social name</key>
  <string> Hippo The Avatarian</string>
  <key>user uuid</key>
  <string>Please be my friend, we met at the hippo wallow last week

14.  Flowing a response

   No such resource: If there is no handler at the resource listed in
   the request the event queue handler flows back a 404 responds per
   traditional http;

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

   <key>response code</key>
   No resource associated with this key

Levine                  Expires January 14, 2010               [Page 10]

Internet-Draft              OGPX Client Caps                   July 2009

   Successful responses When the 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

   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 OGPX
   architecture) and the event queue will then pass on the response to
   the invoker.  Structurally, this is very similar to the request.  The
   get() call will pass up responses for handling by the service side
   event queue.

   <key>sequence number</key>

   <key>response code</key>

15.  Passing back content

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

Levine                  Expires January 14, 2010               [Page 11]

Internet-Draft              OGPX Client Caps                   July 2009

   <key>sequence number</key>

   <key>response code</key>
     <string>friendship accept</string>
     <key>user social name</key>
     <string>Happy Songbird</string>
     <key>user uuid</key>
     <string>Thank you. I'd love to be friends.

   The overall pattern and other URIs..  The overall pattern is intended
   to provide a framework for handling not just eventq: sceme 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.

16.  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

17.  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

Levine                  Expires January 14, 2010               [Page 12]

Internet-Draft              OGPX Client Caps                   July 2009

   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 plaintext, 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.

18.  References

18.1.  Normative References

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

   [min_ref]  authSurName, authInitials., "Minimal Reference", 2006.

18.2.  Informative References

   [cable]    Intel, "Cable Beach Design Wiki", 2009, <http://

   [caps]     Linden Lab, "Open Grid Protocol: Foundation", 2009,

   [intro]    Linden Lab, "Open Grid Protocol: Foundation", 2009,

Appendix A.  Additional Stuff

   This becomes an Appendix.

Levine                  Expires January 14, 2010               [Page 13]

Internet-Draft              OGPX Client Caps                   July 2009

Author's Address

   David W. levine (editor)
   IBM Thomas J. Watson Research Center
   19 Skyline Drive
   Hawthorne, New York  10532

   Phone: +1 914-784-7427
   Email: dwl@us.ibm.com

Levine                  Expires January 14, 2010               [Page 14]