Internet Engineering Task Force M. Lentczner
Internet-Draft Linden Research, Inc.
Intended status: Informational March 3, 2009
Expires: September 4, 2009
Open Grid Protocol: Foundation
draft-lentczner-ogp-base-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 September 4, 2009.
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
The Open Grid Protocol documents define the protocols by which a
vast, Internet wide virtual world can operate. This protocol enables
different regions of the virtual world to be operated independently,
Lentczner Expires September 4, 2009 [Page 1]
Internet-Draft Open Grid Protocol: Foundation March 2009
yet interoperate to form a cohesive experience.
This document specifies the foundation upon which various suites of
virtual world functionality are built. It describes the basic
structure of OGP interaction and common methodology and terminology
for protocols.
Table of Contents
1. Structure . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.1. Requirements Language . . . . . . . . . . . . . . . . 3
1.2. Domains . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.3. Basic Flow . . . . . . . . . . . . . . . . . . . . . . . . 4
1.4. Structure of the Protocol . . . . . . . . . . . . . . . . 4
1.5. Document Structure . . . . . . . . . . . . . . . . . . . . 5
2. Base Protocols . . . . . . . . . . . . . . . . . . . . . . . . 5
2.1. Resources, HTTP & REST . . . . . . . . . . . . . . . . . . 5
2.2. LLSD & LLIDL . . . . . . . . . . . . . . . . . . . . . . . 6
2.2.1. Serialization . . . . . . . . . . . . . . . . . . . . 6
2.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . . 6
2.3.1. Obtaining . . . . . . . . . . . . . . . . . . . . . . 7
2.3.2. Invocation . . . . . . . . . . . . . . . . . . . . . . 7
2.3.3. Lifetime & Revocation . . . . . . . . . . . . . . . . 7
2.3.4. Names . . . . . . . . . . . . . . . . . . . . . . . . 8
2.3.5. Seed Capability (Resource Class) . . . . . . . . . . . 8
2.3.6. Security . . . . . . . . . . . . . . . . . . . . . . . 9
2.4. Event Queues . . . . . . . . . . . . . . . . . . . . . . . 9
2.4.1. Basic Flow . . . . . . . . . . . . . . . . . . . . . . 9
2.4.2. Restrictions . . . . . . . . . . . . . . . . . . . . . 9
2.4.3. Event Queue Get (Resource Class) . . . . . . . . . . . 10
2.4.4. Requests . . . . . . . . . . . . . . . . . . . . . . . 10
2.4.5. Responses . . . . . . . . . . . . . . . . . . . . . . 10
2.4.6. Long Poll . . . . . . . . . . . . . . . . . . . . . . 10
2.4.7. Closing the Queue . . . . . . . . . . . . . . . . . . 11
3. Security Considerations . . . . . . . . . . . . . . . . . . . 11
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12
5. Normative References . . . . . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 13
Lentczner Expires September 4, 2009 [Page 2]
Internet-Draft Open Grid Protocol: Foundation March 2009
1. Structure
1.1. Introduction
The Open Grid Protocol (OGP) is about a three way interaction between
viewer, agent and region in order to facilitate a shared experience
between people. While the description here is grounded in a common
view of what a virtual world is, the terms are deliberately described
so as to be usable in a wider variety of situations. The OGP
structure is design to support the abstract the notion of persistent
user identity interacting over time in a variety of shared
experiences in different persistent locations, especially where the
users and locations are operated by different administrative domains.
1.1.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].
1.2. Domains
The viewer is the element that senses and acts on the state of the
virtual world. The viewer does so from the vantage point of an
agent. An agent is persistent identity and persona that interacts in
a virtual world. The agent persists and can be interacted with even
when the user controlling it (though a viewer) is off-line. Regions
are persistent locations in the virtual world. Multiple agents may
be present in a region at the same time, and when they are they have
a shared experience.
Groups of regions and agents are managed by domains. A region domain
is responsible for a collection of regions. An agent domain manages
agent accounts.
This protocol makes few assumptions about how a domain manages its
collection of elements. In particular, it does not assume that a
region will be entirely managed on a single host, nor that an agent
will or won't be managed by a single process.
It is useful to think of the "stance" that each element takes in the
three-way protocol:
The viewer is the direct proxy for a human that wants to control an
agent. This control can be direct as in the case of an interactive
3D viewer, or indirect as in the case of a web site that the user
directs to display their agent's status.
Lentczner Expires September 4, 2009 [Page 3]
Internet-Draft Open Grid Protocol: Foundation March 2009
The agent domain is responsible for the agent itself. The persistent
state of the agent is held within the agent domain, and requests to
interact with the agent, even by the viewer, are mediated by the
agent domain.
The region domain runs the live simulations of regions in the virtual
world. The region domain manages the persistent state of these
regions.
1.3. Basic Flow
The basic flow of the protocol is:
1. The viewer authenticates to an agent domain for the authorized
control of a particular agent.
2. The viewer directs the agent domain to to place the agent in a
region.
3. The agent domain contacts the region domain for the region, and
negotiates placement of the agent.
4. The region grants access to the agent domain, which in turn
passes some of that granted access on to the viewer.
At this stage, each entity will have access to many resources in the
other entities. For example:
o The viewer has access to region resources that let it move the
avatar.
o The region has access to viewer resources that update the state of
objects in the region.
o The viewer and agent have access to resources in each other to
facilitate text messaging.
1.4. Structure of the Protocol
The protocol is fundamentally composed of individual resources that
can be invoked by one entity in the system upon another. Each
resource is a member of a resource class that describes the syntax
and semantics of invoking the resource.
The resource classes are composed into suites that form logical
groupings, though suites do not otherwise play a part in the
protocol. Other protocol suites based on this document, when
complete, will describe the several hundred resource classes that
Lentczner Expires September 4, 2009 [Page 4]
Internet-Draft Open Grid Protocol: Foundation March 2009
make up the virtual world.
In order to facilitate migration from the existing systems, as well
as support future extension, some resources could return information
that allow entities to continue to communicate using other protocols
and structures. These protocols and structures are not part of OGP.
It is the intention that when this work is complete, virtual world
interaction will be entirely OGP based, and that OGP itself will have
enough extensibility for future development.
Agent and region domains have a few resources that are available at
well known URLs. All other resources in the agent and region domains
are accessed via capabilities obtained from the those few initial
resources.
Since viewers are typically behind firewalls that do not allow
connection, resources in the viewer are accessed by event queues held
in the agent and region for the viewer. The viewer uses the "long
poll" technique to efficiently proxy these inward resource
invocations.
1.5. Document Structure
OGP is a large suite of interrelated protocol suites. Each major
protocol suite is described in its own document. For examples, see
the OGP Authentication and OGP Teleport documents. This document
describes the base facilities and concepts upon which the other
protocols are based. To be compliant with OGP, an implementation
MUST conform to this document, and may implement any of the other
protocol sets that are deemed relevant.
2. Base Protocols
2.1. Resources, HTTP & REST
All interaction between entities is through a client invoking a
resource. Resources are invoked either directly via HTTP [RFC2616],
or through an event queue.
For each resource class, this protocol defines how the client obtains
the URL, the HTTP verb (or verbs) to be used, the request and
response bodies (if any), and significant status codes. Resource
classes are designed with REST style semantics.
In general, HTTP & REST are used as follows: The URL will be either
well-known in advance or returned in a response from another
resource. The latter is called a capability. Except for security
Lentczner Expires September 4, 2009 [Page 5]
Internet-Draft Open Grid Protocol: Foundation March 2009
reasons, URLs are always treated as opaque. Clients should not
modify them. Parameters are never added to them via the query
section. Resource handlers must be prepared to ignore query
sections.
Resources follow general REST semantics and so respond to one of
these HTTP verb sets:
GET for cacheable resources
GET, PUT for cacheable resources that can be modified
GET, PUT, DELETE for cacheable resources that can be modified and
deleted
POST for non-cacheable resources
Unless otherwise stated, if a resource accepts PUT, it accepts
multiple PUT invocations.
The request and response bodies are transmitted as serialized LLSD
data. If a resource has no response defined, then it can return
either an undefined value, an empty map, or have a zero length
response body.
HTTP status codes should only be used to indicate the status of the
HTTP interaction itself. In general, if the resource is reachable,
and the request understood, a 2xx code should be returned.
HTTP headers, both for the request and the response are never part of
a resource class definition. Headers are handled as per the HTTP
standard.
2.2. LLSD & LLIDL
All data in this system is defined by LLSD and protocols specified in
LLIDL. LLSD is an abstract way of talking about structured data. It
is defined in LLSD & LLIDL [draft-hamrick-llsd-00].
2.2.1. Serialization
When used as part of OGP, the XML and JSON serializations of LLSD
MUST be supported.
2.3. Capabilities
This protocol makes extensive use of capabilities. A capability is
an opaque HTTP (or HTTPS) URL used for accessing a particular
Lentczner Expires September 4, 2009 [Page 6]
Internet-Draft Open Grid Protocol: Foundation March 2009
resource. The provider of the resource has three logical parts:
the_grantor_, the_capability host_, and the_service_.
The grantor uses the capability host to construct a capability that
maps to the service that provides the resource, then returns that
capability to the client. At some point in the future, the client
invokes the capability which makes a connection to the capability
host. The capability host then proxies to the service to provide the
resource.
The parts that make up the provider may be separate entities or may
be the same.
The client can't invoke the resource without the capability.
Typically the capability is a URL with a cryptographically secure
path component. Within the capability host, this URL is mapped to
the actual internal resource URL.
The client is free to hand the capability to other entities who
become clients of the capability as well. Other than for the
security considerations below, the client must not rely on any
assumed structure of the capability URL.
2.3.1. Obtaining
For each resource a client wants to invoke, the capability must be
obtained. In a few cases, the capability will have been expressly
returned in the result of some other resource. Usually, the system
uses a seed capability (see below) to request the capability for a
given resource by name.
2.3.2. Invocation
To invoke a capability, the holder performs an HTTP transaction with
the capability as the URL. The resource class the capability
represents will dictate which verb (or verbs) can be used, and what
the request and response bodies (if any) should be.
2.3.3. Lifetime & Revocation
Capabilities can be either unlimited or one-shot. Unlimited
capabilities can be used multiple times, whereas one-shot can be used
only once and are automatically revoked on invocation.
Invoking a one-shot with the HTTP verbs HEAD or OPTIONS does not
revoke it.
Any capability can be revoked at will by the provider of the
Lentczner Expires September 4, 2009 [Page 7]
Internet-Draft Open Grid Protocol: Foundation March 2009
resource. Clients must be prepared to handle revoked capabilities.
A revoked capability, when invoked must return a 4xx HTTP status
code. The capability host may return a 404, even if the capability
had been previously active.
2.3.4. Names
The resource a capability performs is identified by name. When
requesting a capability, or when returning a capability, the opaque
URL is identified with this name. The names of such resources are
intended to be globally unique.
Names are URIs. When a name appears without a scheme component, then
it is a relative URL, considered relative to the base:
http://xmlns.secondlife.com/capability/name/
While names do exhibit path-link structure, they are to be considered
opaque identifiers. For example, while the following three
capability names are indeed from the same protocol suite, nothing
should be inferred about a capability that starts with their common
prefix:
inventory/root
inventory/folder_contents
inventory/move_folder
While not required, this protocol prefers names that are all lower
case ASCII letters, separated by underscores and forward slashes.
2.3.5. Seed Capability (Resource Class)
In many cases, a sub-system will return a_seed capability_from which
other capabilities can be requested.
%% seed
-> { capabilities: [ string, ... ] }
<- { capabilities: { $: uri } }
The request contains an array of all resource names for which
capabilities are desired. The response contains a map with an entry
for each capability granted. Note: a grantor may grant all, some or
none of the requested capabilities. The grantor may also grant
additional capabilities that were requested, or none at all. If the
grantor grants none, the response map must be empty and the HTTP
status code should still be 200.
Lentczner Expires September 4, 2009 [Page 8]
Internet-Draft Open Grid Protocol: Foundation March 2009
2.3.6. Security
If an end-point receives a capability from an untrusted source, it is
permissible for security reasons to check the following aspects of
the URL before use:
o The scheme should be http: or https:.
o The authority (in particular, the resolved host name) should not
resolve to ports on the local machine that aren't publicly
accessible.
2.4. Event Queues
An event queue enables an entity to invoke resources in the viewer,
which cannot be directly contaced via HTTP. This is usually the case
because the viewer is behind a firewall that doesn't allow incoming
TCP (and hence HTTP) connections from the region or agent domains.
In such a situation, the client establishes a queue of invocation
requests for resources in the viewer. At the same time, the viewer
uses an*event_queue/get*capability to effectively tunnel the requests
from the client to itself.
2.4.1. Basic Flow
When the viewer invokes*event_queue/get*, the entity replies with the
list of messages that have been queued up. The viewer takes the
response, breaks it apart into a series of requests that it processes
on itself, as resource invocations that the entity wanted to perform.
The next invocation of *event_queue/get* includes the responses to
any requests that have completed processing. While it takes two
resource invocations of* event_queue/get* to tunnel a set of
invocations in the other directions, subsequent transactions are
chained, since the acknowledgement of a previous requests is
performed in the same invocation that gets the next set.
2.4.2. Restrictions
Resources accessed this way have the following restrictions:
o Resources are identified by their resource class name. With
capabilities, there can be several resources in an entity that all
conform to the same resource class. With event queues only one
resource can exist for each resource class within the viewer.
This is not usually a severe restriction.
Lentczner Expires September 4, 2009 [Page 9]
Internet-Draft Open Grid Protocol: Foundation March 2009
o The only verb allowed is POST.
2.4.3. Event Queue Get (Resource Class)
This resource is a capability both in the agent and in the region,
for implementing a tunneled series of resource invocations from the
entity back to the client:
%% event_queue/get
-> { responses: [ &response, ... ], done: bool }
<- { requests: [ &request, ... ] }
&request = { id: int, name: string, body: undef }
&response = { id: int, status: int, body: undef }
2.4.4. Requests
Each request contains a name and a body. The name is the resource
name to be invoked. The request can then be seen as equivalent to
fetching the capability for this named resource from a seed
capability, and then invoking that capability. Since the viewer
cannot have URLs that point into it, these two steps must be combined
into one operation here.
The id field represents a number that is used later to correlate
responses with the requests. The number must be considered opaque
from the point of view of the viewer. It is up to the entity to
choose an allocation regieme that works for itself.
2.4.5. Responses
Each response includes the id number from the request it is the
response to. This enables the entity to correate responses with
requests. The status value is the same as the HTTP status code for
the request. However, the status of 0 (which corresponds to the
value that would be seen if the status field were missing in the
LLSD), shall be construed as a status of 200. The body is the
response body.
Note that requestors need to be prepared to handle the same set of
eventualities as any REST request: A response to a request might
never come, or might be delayed significantly.
2.4.6. Long Poll
Both viewers and entities must be prepared to handle use the "long
poll" technique to keep the flow of requests timely. Viewers must be
prepared to handle that invoking *event_queue/get* may take a
relatively long time to return, as the entity may choose to delay
Lentczner Expires September 4, 2009 [Page 10]
Internet-Draft Open Grid Protocol: Foundation March 2009
responding if there are no requests pending, or if it believes it
would be better to wait for more requests to queue. Entities must be
prepared to handle viewers that request as soon as they are ready for
events with no delay. Both sides must be prepared to handle time
outs and retries.
2.4.7. Closing the Queue
When the viewer is ready to terminate the queue, meaning that it
wishes to be done accepting requests, it may signal such by including
the done flag in the next invocation of* event_queue/get*. This
value is purely advisory, but enables entities to cleanly flush
remaining events, and release resources. Specifically, setting done
to true in the invocation body indicates to the entity that if no
requests are returned, the viewer intends to no longer invoke this
queue.
3. Security Considerations
The OGP protocols described by this document describe mechanism by
which other application specific protocols are layered on top.
Issues such as authentication and authorization are described in
other OGP documents, and only pertain to systems that choose to use
them. However, as this document's protocols form a base of others,
and these are intended to be deployed across the Internet, there are
some basic security considerations at this level.
All resources in OGP are invoked via HTTP or HTTPS URLs. Where a
resource requires any of end-to-end data integrity, protection from
man-in-the middle attacks, or authentication of resource provider,
that resource should be accessed via HTTPS, with the client checking
the validity of the server certificate. If the URL indicates https:,
then the security available with HTTPS connections applies to the
resource request.
Some resources in OGP are accessed via cryptographically strong URLs.
That is, a entity decides to authorize a client to access a resource,
and does so by handing back a non-guessable URL to the service to the
client. When such a URL is returned, it must be over a HTTPS
channel, lest the URL be sniffed as it traverses the network. Care
must be taken by the entity providing the capability to ensure that
the URL is unguessable and unforgeable. Usually, using a 128 bit
random key in the URL path is sufficient, assuming the randomness has
sufficient cryptographic properties.
Clients must take care to consider such URLs precious - just as they
would session cookies in a web browser environment. These URLs are
Lentczner Expires September 4, 2009 [Page 11]
Internet-Draft Open Grid Protocol: Foundation March 2009
authorized to invoke some action, and if leaked, give out that
ability. Since they are generally limited in scope, it is possible
to delegate these URLs to other sub-systems the client may entrust to
perform its work, and it is safer to do so than techniques like
sharing session cookies or account passwords.
As discussed in Section 2.3.6, clients must take caution that
capabilities returned by services don't point to localhost. The
primary reason for this is that it is common for hosts to have more
ports and services open to localhost than to external entities. A
malicous external entity returning a URL pointed at localhost, if it
can guess the likely services available, can cause the client to
invoke those services on its behalf, even thought it can't directly
view the results. Clients should check the resolved IP address for
the host in the URL, since it is trivial to have remotely controlled
DNS names that resolve to 127.0.0.1. Note: This threat is no
different that already exists in web browsing in general.
There are two denial of service attack vectors. As with any web
service, entities must be prepared to handle all manner of ill formed
requests, requests that take too much time, and requests that come at
a high rate. Standard web service techniques can be used to mitigate
these risks. In the case of the Event Queue, clients must be
prepared to handle unreasonable, or malformed requests from the
contacted entity. If a client finds itself overwhelmed by requests
from an Event Queue, simply dropping the connection and not replying
is completely acceptable mitigation. The long poll technique also
allows either side to release the connection at any time that
resources are being too heavily consumed.
4. IANA Considerations
This document has no actions for IANA.
5. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[draft-hamrick-llsd-00]
Brashears, A., Hamrick, M., and M. Lentczner, "Linden Lab
Structured Data", 2009.
Lentczner Expires September 4, 2009 [Page 12]
Internet-Draft Open Grid Protocol: Foundation March 2009
Author's Address
Mark Lentczner
Linden Research, Inc.
945 Battery St.
San Francisco, CA 94111
US
Phone: +1 415 243 9000
Email: zero@lindenlab.com
Lentczner Expires September 4, 2009 [Page 13]