idnits 2.17.1 draft-levine-ogp-clientcap-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.ii or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == The document doesn't use any RFC 2119 keywords, yet seems to have RFC 2119 boilerplate text. -- The document date (July 13, 2009) is 5401 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 OGPX pre BOF D. Levine, Ed. 3 Internet-Draft IBM Thomas J. Watson Research 4 Intended status: Informational Center 5 Expires: January 14, 2010 July 13, 2009 7 Client Capabilities for OGPX 8 draft-levine-ogp-clientcap-00 10 Status of this Memo 12 This Internet-Draft is submitted to IETF in full conformance with the 13 provisions of BCP 78 and BCP 79. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at 26 http://www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on January 14, 2010. 33 Copyright Notice 35 Copyright (c) 2009 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents in effect on the date of 40 publication of this document (http://trustee.ietf.org/license-info). 41 Please review these documents carefully, as they describe your rights 42 and restrictions with respect to this document. 44 Abstract 46 client side capabilities for OGPX. 48 Table of Contents 50 1. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 51 2. overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 4. Rest/Caps style model for client resources . . . . . . . . . . 4 54 5. Overall approach . . . . . . . . . . . . . . . . . . . . . . . 5 55 6. A simple example (friendship) . . . . . . . . . . . . . . . . 5 56 7. An eventq URI . . . . . . . . . . . . . . . . . . . . . . . . 6 57 8. Putting it all together . . . . . . . . . . . . . . . . . . . 7 58 9. From login to a client cap delivered message . . . . . . . . . 7 59 10. Login/Auth initial cap grants . . . . . . . . . . . . . . . . 7 60 11. Setting up an event queue . . . . . . . . . . . . . . . . . . 8 61 12. Wiring up the client side resource of a service . . . . . . . 8 62 13. Flowing a message to the handler . . . . . . . . . . . . . . . 9 63 14. Flowing a response . . . . . . . . . . . . . . . . . . . . . . 10 64 15. Passing back content . . . . . . . . . . . . . . . . . . . . . 11 65 16. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 66 17. Security Considerations . . . . . . . . . . . . . . . . . . . 12 67 18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 68 18.1. Normative References . . . . . . . . . . . . . . . . . . 13 69 18.2. Informative References . . . . . . . . . . . . . . . . . 13 70 Appendix A. Additional Stuff . . . . . . . . . . . . . . . . . . 13 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13 73 1. Requirements Language 75 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 76 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 77 document are to be interpreted as described in RFC 2119 [RFC2119]. 79 2. overview 81 This note defines the use of "Client" side capabilities within the 82 OGPX specifications. Client Capabilities are Capabilities, as 83 defined by the OGPX specifications, on the client or virtual worlds 84 viewer. Often, these capabilities will represent resources hosted on 85 devices and systems behind firewalls, and will thus be accessed via 86 event queues are similar mechanisms. This note defines patterns for 87 using client side capabilities, and an URI scheme for adressing such 88 capabilities. A fairly complete worked example is provided. The 89 exact LLSD, the exact URI formats, and the example service are 90 provided to illustrate the service pattern, and are extremely 91 provisional. The sequence diagrams used to illustrate the flows, as 92 well as the structural diagrams represent one possible approach to 93 implementing the service pattern. Nothing beyond the interfaces 94 would be normative. This note is a DRAFT it is very preliminary and 95 is intended to drive discussion. Following further discussion, I 96 expect to post it as a formal input to the OGXP discussion. 98 Questions of note: 100 1. How much run time / latency cost is associated with this design 102 2. This design is intended to permit the substitution of rhttp, or 103 xmpp or similar transports in the architecture. How close do we 104 come to that ideal. 106 3. Is this secure enough to not hit an instant EKR wall at the IETF 108 4. Are we missing any key requirements here? 110 3. Requirements 112 This note addresses the following requirements for service/client 113 modeling in OGPX: 115 1. Support deploying services across arbitrary domain and hosting 116 models In particular, permit services to be deployed across 117 multiple hosts within a domain, clustering pipes, and securely 118 sharing event queues and event delivery. 120 2. Abstract away a specific single bidirectional pipe from the OGPX 121 specs Support event queues, r-http if it becomes a common 122 pattern, websockets, if they become common, and full duplex 123 schemes, such as xmpp, if they become viable 125 3. Provide a model for architecturally describing resources on the 126 client. This, in effect, is "addressing" client side resources, 127 providing references to them. 129 4. Permit service side deployers to pass around references to these 130 client side resources within the service cloud safely and 131 transparently 133 5. 135 * Prevent services from spoofing messages to resources others 136 than those they have been granted access to 138 * Provide a endpoint independent path to the client (via any 139 eventq available, or any URI representing the client resource) 141 * Preventing guessing of endpoint resource addresses 143 6. Closely model the current event queue implementations 145 Support deploying services on multiple domains and hosting models 146 Virtual worlds have a wide range of deployment patterns, and require 147 a broad range of services, with different computational profiles. We 148 want to enable people to delegate services to arbitrary servers. 149 This should enable clouds to host services, and permit deployers to 150 chose deployment models which meet their needs. Abstracting away 151 specific pipes This is the single largest driver. We want to divorce 152 the OGPX specifications from the current Linden Lab event queue 153 implementation, the UDP pipes, and any single approach to delivering 154 bits to the client. OGPX aspires to support virtual worlds over a 155 period of multiple years. We assume that the pipes to clients will 156 evolve over time. Creating a web services, URI addressed approach to 157 managing connections to regions, is a powerful way to de-couple 158 transport choices from protocol handlers. 160 4. Rest/Caps style model for client resources 162 Once we want to model the client's resources separate from the 163 communications pipes used to access those resources, we are faced 164 with the problem of naming, and addressing those resources. The 165 current client, mostly assumes that it can parse from message type to 166 determine where the message should be routed. The overall 167 justifications for using REST approaches are as cogent for the 168 client, as any other portion of OGP. The REST model affords a 169 consistent approach to modeling resources 171 5. Overall approach 173 We approach the overall design as describing access to resources 174 hosted by clients. As many clients are inaccessible for full http 175 access from the services which wish to contact them, we describe the 176 overall approach, in a way which permits eventqueues to be used in 177 the current implementation, and approaches such as reverse-HTTP 178 (Sometimes refered to as rhttp, r-http or ptth) in the future with no 179 changes to the basic approach. (and ideally none to the code, beyond 180 supporting r-http listeners.) Named client side resources The major 181 addition to the current model is that of addressable client side 182 resources. This effectively extends the REST/ Capabilities model to 183 interactions involving sending data to the client. Instead of 184 sending them to the client as a single endpoint, we can route the 185 data to specific endpoints managed by the client. By using the basic 186 REST model for manipulating these resources, we get a simple, well 187 defined set of interactions between services and client side 188 resources. 190 6. A simple example (friendship) 192 So, instead of embedding friendship inside a IM message, or even in a 193 separate message, and requiring the client to parse the header and 194 then route the message, we instead define a resource on the client, 195 which is associated with friendship messages. This resource is then 196 passed to the service(s) which need to manipulate the resource. The 197 common case will be that services will post messages to the client, 198 but we define the model generally so that services can invoke normal 199 REST semantic operations on the resources. 201 Exposing client side resources with an event queue 203 Since the client cannot directly expose its resources, the client 204 relies on event queues to fetch requests destined for these resources 205 from services. This is mediated via a COMET style event queue. The 206 client polls the service, and when there are requests destined for 207 it, it collects those requests and routes them to the handlers which 208 process them. 210 The requests contain the resource they are routed to, and the method 211 to be invoked on the resource, as well as the payload of the request. 213 214 sequencesequence number 215 resourcepath of resource 216 methodPOST 217 payload{LLSD of payload} 218 220 Each request can be routed by the event queue to the desired handler. 221 Note the separate event queues sharing one map of resource to 222 handlers, and delivering events to shared handlers. Now, in order to 223 complete this story, we need to describe how the services know what 224 resources on the client they should post to, and how these resources 225 are addressed. 227 7. An eventq URI 229 To support addressing client side resource reached vit event queues, 230 we introduce an "eventq:" URI. 231 eventq://client_id@fqdn_of_eventq_host/{path to resource} or 232 eventqs://client_id@fqdn_of_eventq_host/{path to resource} For 233 details on URI format, http://en.wikipedia.org/wiki/URI_scheme and 234 more formally: http://tools.ietf.org/html/rfc3986 We are describing a 235 scheme "eventq" with hierarchical part broken into the traditional 236 "authority" and "path" Our authority is addressed as "client_id@ 237 fqdn_of eventq_host" What this says is "for the unique client 238 (client_id) you can route via an event queue hosted by the host 239 listed as "fqdn_of_eventq_host" which will be a hostname. To address 240 the specic resource, on that client, you must provide the path. The 241 client_id, is a short term unique string representing the client, 242 during this session with the services cloud. This is provided to 243 permit several important options. First, it permits us to pass a 244 capability with an eventq: URI to a service which already has a 245 connection to the client, and allows the transport level software to 246 understand it already has a connection to the client. It also allows 247 correct behavior in the face of an attempt to re-establish a 248 connection to the eventq host, and finally, it allows services to 249 chose *any* event queue it knows about which connects to the client 250 for delivering it's requests to the client. This allows a number of 251 potential deployment patterns which permit scaling of the 252 computational fabric with no changes to the client, or necessarily 253 the services. The eventqs scheme, is identical to the eventq scheme, 254 with the added requirement that the underyling event queue be 255 implemented using https or an equally secure transport, so that 256 messages cannot be intercepted, and there is a high degree of 257 confidence that the host holding the service end of the eventq is the 258 desired host. 260 8. Putting it all together 262 To actually use this plumbing, we need to associate the client side 263 resource with the service which wishes to use it. We incorporate 264 this into the setup flow needed to use the resource. The client/ 265 viewer requests a capability from a seed cap in the services network. 266 (from initial login, or transitively from other caps) The service 267 returns with a URI of the service side resource. The client then 268 creates a client side resource (or resources) for the service to use, 269 and passes them up to the service, which then begins to issue 270 requests against these resources. 272 1. Client/Viewer logs into a service and acquires one or more 273 seedcaps 275 2. The client requests a set of capabilities from the seedcaps. 277 3. One or more of these capability requests includes an event queue 279 4. The client establishes the event queues, posting its "client_id" 280 to the event queue host. 282 5. Zero or more of the capabilities requested use client side 283 resources. For these capabilties, the client creates and 284 registers a client side resource, in the form of a client 285 capability, composes a URI for the resources, and informs the 286 service of the URIs of the client side resources. 288 6. The service side service begins posting requests on the 289 associated event queues 291 7. The client routes the requests to the registered handlers. 293 8. We flow a response from the handler back to the invoker 295 9. From login to a client cap delivered message 297 A small worked example. The actual service involved, and the 298 deployment details of the service are purely notional. Do not focus 299 on the specific service messages, but the routing and setup flows 300 which enable the messages to flow. 302 10. Login/Auth initial cap grants 304 This is pretty much OGP business as usual. The client connects to 305 the authentication service, and gets a seedcap, on an Agent Domain 306 Service (n, one of many) 308 +----------------+ +-------------------+ +----------------------+ 309 | OGPX viewer | | OGPX Auth Service | | Agent Domain Service | 310 +----------------+ +-------------------+ +----------------------+ 311 | | | 312 | Login() | | 313 |--------------------- --->| | 314 | | | 315 | login_response(seed_cap) | | 316 |<-------------------------| | 317 | | | 318 | Request_caps(Caps list) | | 319 |----------------------------------------------->| 320 | | | 321 | | | 322 |<-----------------------------------------------| 323 caps_granted(array of caps, URIs, of caps) 325 11. Setting up an event queue 327 Pretty straight forward. We create a handler on the client, which 328 calls the cap the client got from the login step. The AD has created 329 an event queue, which we call. There is one additional tidbit that 330 flows at this point, which is that we get the Host end of our caps. 331 This fetches from the host side of the agent domain event queue, 332 which we will use in our URIs. 334 a77e875e0f82d975@adhost.test.org/ccaps/e132c4ea-55c8-4be3-a77e- 335 host_end_cap 336 fully.qualified.domain.com 337 339 12. Wiring up the client side resource of a service 341 The next step is the major addition to the sequence. We take the cap 342 for a service we requested earlier, and then create the client side 343 handler, associate it with a client side resource, and pass that 344 resource to the service side cap 345 346 org.ogpx.friendship.client_listener 347 eventq://4a0e0e09-d3e1-4ab8-bc3f- 348 875e0f82d975@adhost.test.org/ccaps/e132c4ea-55c8-4be3-a77e- 349 3ec91ef63b7a/fslistner 350 352 13. Flowing a message to the handler 354 Finally, with all the bits in place, we can send an event, and expect 355 it to get picked up at the far end by the handler. Our hypothetical 356 message is: 358 359 request_type 360 friendship request 361 user social name 362 Hippo The Avatarian 363 user uuid 364 4509971b-b2f3-43a9-bc71-1736c971a8f7 365 message 366 Please be my friend, we met at the hippo wallow last week 367 368 370 So, the Friendship services takes that payload, and the URI of the 371 client's resource. It is out of scope, how it posts the request to 372 the service end of the event queue. (being a deployer issue, not part 373 of the public spec) It passes the URI, and the payload, and it gets 374 to the input hopper of the event queue, along with the method being 375 invoked. (in this case "POST") The event queue then packages up the 376 message as part of the array of messages it has bound to the client: 378 379 . 380 . 381 382 methodPOST 383 sequence id98726 384 resource 385 /ccaps/e132c4ea-55c8-4be3-a77e-3ec91ef63b7a/fslistner 386 payload 387 388 request_type 389 friendship request 390 user social name 391 Hippo The Avatarian 392 user uuid 393 4509971b-b2f3-43a9-bc71-1736c971a8f7 394 message 395 Please be my friend, we met at the hippo wallow last week 396 397 398 399 401 14. Flowing a response 403 No such resource: If there is no handler at the resource listed in 404 the request the event queue handler flows back a 404 responds per 405 traditional http; 407 408 .. 409 410 sequence number98726 412 http_response 413 414 response code 415 404 416 payload 417 418 No resource associated with this key 419 420 421 422 423 Successful responses When the friendship handler has accepted the 424 request, it can post a response. This can, of course, include simply 425 accepting the request, and then posting an "accept friendship" 426 message to the main cap, or accepting it directly, depending on the 427 design of the friendship service. We will do both, for illustrative 428 purposes 430 Simple ok 432 For the simple, accepted response, the handler will post back to the 433 event queue an OK. (This is an internal flow, not part of the OGPX 434 architecture) and the event queue will then pass on the response to 435 the invoker. Structurally, this is very similar to the request. The 436 get() call will pass up responses for handling by the service side 437 event queue. 439 440 .. 441 442 sequence number 443 98726 445 http_response 446 447 response code 448 200 449 payload 450 451 452 454 15. Passing back content 456 The final case, is actually passing back content on a reply. This 457 merely adds the payload 458 459 460 sequence number 461 98726 463 http_response 464 465 response code 466 200 467 payload 468 469 request_type 470 friendship accept 471 user social name 472 Happy Songbird 473 user uuid 474 4509971b-ffa3-43a9-1748-1736c978fa3e 475 message 476 Thank you. I'd love to be friends. 477 478 479 480 481 483 The overall pattern and other URIs.. The overall pattern is intended 484 to provide a framework for handling not just eventq: sceme URIs, but 485 any URI which will successfully flow the data between the two 486 services. For this to work, the basic pattern, of setting a client 487 side cap needs to keep in mind that the "eventq/eventqs" scheme is 488 not the only URI which might be passed in the future. 490 16. IANA Considerations 492 This memo includes no request to IANA. 494 If this specification progresses, a request to IANA to register the 495 eventq scheme might be contemplated 497 17. Security Considerations 499 Event queues expose client side resources to messages from servers. 500 The URI for eventq provides routing to these resources. This exposes 501 these resources to a number of possible attacks. The use of 502 capabilities, and the limitation that in order to access a client 503 side capability, one has to have access to the host side of an event 504 queue, eliminates most of the possible attacks. The current 505 capabilities specification uses a 128 bit UUID, generated for each 506 session, for each capability, to make the resource portion of the 507 capability essentially un-guessable. This requires care in passing 508 around capabilities, as if they are passed in plaintext, they would 509 be subject to sniffing, and if passed in open sessions, such as http, 510 they would be vulnerable to man in the middle attacks. Control of 511 the services side endpoint of event queues provides a separate means 512 of limiting the security issues. Nothing described here defines how 513 the host end of an event queue is exposed to services. Depending on 514 the host implementation, the resource could be accessible broadly, or 515 only to programs running in the address space of the event queue. If 516 the resource is made available broadly, the capability design limits 517 the exposure of the resource to messages aimed at the actually 518 resource, but opens up the event queue itself as a vehicle for denial 519 of service attacks. 521 18. References 523 18.1. Normative References 525 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 526 Requirement Levels", BCP 14, RFC 2119, March 1997. 528 [min_ref] authSurName, authInitials., "Minimal Reference", 2006. 530 18.2. Informative References 532 [cable] Intel, "Cable Beach Design Wiki", 2009, . 535 [caps] Linden Lab, "Open Grid Protocol: Foundation", 2009, 536 . 538 [intro] Linden Lab, "Open Grid Protocol: Foundation", 2009, 539 . 541 Appendix A. Additional Stuff 543 This becomes an Appendix. 545 Author's Address 547 David W. levine (editor) 548 IBM Thomas J. Watson Research Center 549 19 Skyline Drive 550 Hawthorne, New York 10532 551 USA 553 Phone: +1 914-784-7427 554 Email: dwl@us.ibm.com