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 draft-levine-ogp-clientcap-00 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 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. Abstract 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", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 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 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 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 resources. 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 sequencesequence number resourcepath of resource methodPOST payload{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 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 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. a77e875e0f82d975@adhost.test.org/ccaps/e132c4ea-55c8-4be3-a77e- host_end_cap fully.qualified.domain.com 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 org.ogpx.friendship.client_listener eventq://4a0e0e09-d3e1-4ab8-bc3f- 875e0f82d975@adhost.test.org/ccaps/e132c4ea-55c8-4be3-a77e- 3ec91ef63b7a/fslistner 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: request_type friendship request user social name Hippo The Avatarian user uuid 4509971b-b2f3-43a9-bc71-1736c971a8f7 message 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 . . methodPOST sequence id98726 resource /ccaps/e132c4ea-55c8-4be3-a77e-3ec91ef63b7a/fslistner payload request_type friendship request user social name Hippo The Avatarian user uuid 4509971b-b2f3-43a9-bc71-1736c971a8f7 message 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; .. sequence number98726 http_response response code 404 payload 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 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 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. .. sequence number 98726 http_response response code 200 payload 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 sequence number 98726 http_response response code 200 payload request_type friendship accept user social name Happy Songbird user uuid 4509971b-ffa3-43a9-1748-1736c978fa3e message 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, . [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 USA Phone: +1 914-784-7427 Email: dwl@us.ibm.com Levine Expires January 14, 2010 [Page 14]