SLGOGP Teleport Strawman

This strawman represents a possible open teleport protocol. The sequencing is described first, which also introduces the major players: Client, Agent Domain, Simulator/Region Domain A, Simulator/Region Domain B. For perspective, the current Second Life Grid teleport flow is also included. Following that are the draft specifications for the two main pieces, called rezAvatar and derezAvatar on the agent domain. The simulator side portions of this protocol have been tentatively dubbed "teleport_avatar" and "give_up_av_to_pipe".

Teleport Flow

Here is the basic flow for current SL teleports:

Fine tuning the proposed protocol and cap names after discussion with AWG groupies resulted in a unified approach for Login, Teleport, and Logout, diagrammed below:

Login

Teleport

Logout

Authentication

• In order to get the agent host seed capability, credentials must first be posted to http://login.aditi.lindenlab.com/cgi-bin/auth.cgi

Request: viewer -> auth.cgi

Required Parameters

{
    'firstname':  <string>,
    'lastname':   <string>,
    'password':   <string>
}

or

{
    'firstname':    <string>,
    'lastname':     <string>,
    'md5-password': <string>
}

Optional Parameters

{
    'agree_to_tos' : <bool>,
    'read_critical': <bool>
}

Response

Successful

 status:  302 

 {
    'authenticated': true
    'location'     : <agent host seed capability url> 
 }

• Note: the 302 status code will be changed to 200 status in the future

Unsuccessful

 status:  4xx - login was unsuccessful
 status:  5xx - server error

 { 
    'authenticated' : false
    'reason'        : <one word identifier>
    'message'       : <error description>
 }

• Non-transport/server errors will be changed to 200 status in the future

Terms of Service

 { 
    'authenticated' : false
    'reason'        : 'tos'
    'message'       : <terms of service text>
 }

• Once user agrees to terms of service call authenticate again with { 'agreed_to_tos' : true }

Critical Message

 { 
    'authenticated' : false
    'reason'        : 'critical'
    'message'       : <critical message text>
 }

• Once user has read the message call authenticate again with { 'read_critical' : true }

Miscellaneous Reason

• data - bad input or server side data fetch failed
• key - bad password
• god, restricted, ban, suspend, disabled - denied based on account details

Agent Information

Agent Information
Name	agent/info
URL	capability from agent domain
Verb	GET
Response	{ agent_id: <uuid>, circuit_code: <int>, session_id: <uuid>, secure_session_id: <uuid>, presence: { status : online|offline, region_url: <url> }
	a map of agent information for this session

rez_avatar/place

• Once the viewer acquires the cap for place_avatar, it requests it from the agent domain
• The viewer can also invoke place_avatar for teleport

Request: viewer -> agentd

{
    'region_url': <r_url>
    'position':  [x, y, z]
}

Response

{
  'seed_capability': uri string
  'look_at' : [f32, f32, f32]
  'sim_ip': ip string
  'sim_port': int
  'region_x': int
  'region_y': int
  'region_id' : uuid
  'sim_access' : <PG/Mature>
  'connect': bool
  'position': [f32, f32, f32]
// The above are the same as response to rez_avatar
// The following are only returned on login, not over teleport
   'session_id':<uuid>
   'secure_session_id':<uuid>
   'circuit_code':<int>
// Extra stuff
   'connect': <bool>
}

rez_avatar/request

Request: agentd -> simulator

{
   'agent_id' : <uuid>,
   'first_name': <string>,
   'last_name': <string>,
   'age_verified' : <boolean>,
   'agent_access' : <boolean>,
   'allow_redirect: <boolean>,
   'god_level':  <int>,
   'identified':  <bool>,
   'transacted': <bool>,
   'limited_to_estate': <int>
    'sim_access' : <PG/Mature>,
   'granters': []
}

Example: (hard coded)

{
  'agent_id' : <uuid>,
  'first_name': <string>,
  'last_name': <string>,
  'age_verified' : false, 
  'agent_access' : false,
  'allow_redirect: 1,
  'god_level':  0,
  'identified':  false,
  'transacted': false,
  'limited_to_estate': 1
  'sim_access' : 'PG'
}

Response to request_rez_avatar

{
   'connect':True
   'rez_avatar/rez':<cap>
   'sim_ip': ip string
   'sim_port': int
   'region_x': int
   'region_y': int
   'region_id' : uuid
   'sim_access' : <PG/Mature>
   'seed_capability': uri string

Optional params for Second Life regions only:

   'src_can_see_mainland':<bool>,
   'src_estate_id':<int>
}

Failed request.

{
   'connect':False
   'redirect':False
   'resethome':False
   'message': string
}

Failed request. Need to reset home location.

{
   'connect':False
   'redirect':False
   'resethome':True
   'message': string
}

Failed request. Need to redirect to new location

{
   'connect':False
   'redirect':True
   'resethome':False
   'message': "You have been redirected to a telehub."
}

rez_avatar/rez

Request: agentd -> simulator OR simulator a -> simulator b via derez_avatar

• For login, the agent domain then invokes rez_avatar on the simulator at the given region_url
• For teleport, the agent domain invokes derez_avatar on simulator a, which invokes rez_avatar on simulator b

{
   'circuit_code': <int>,
   'god_overide':   <bool>,
   'position': [x, y, z],
   'secure_session_id':  <uuid>,
   'session_id':  <uuid>,
   'inventory_host':  <uri string>, // not really here!
   'voice_password': <string> // what to do?

   // The following are only sent from simulator a -> simulator b via derez_avatar
   // Note: No assets are actually being sent through when going from SL -> non-SL regions
   'attachment_data': [ {'attachment_point':<int>, 'item_id':<uuid>, 'asset_id':<uuid> | 'asset_data':<binary>}...]
   'baked_texture_data': [ {'texture_id':<uuid>, 'asset_host_name':<host?????>}...]
   'texture_data': [ <uuid>...]
   'animations':[{'state':<uuid>, 'source':<uuid>, 'sequence':<int>}...]
}

Response: simulator -> agentd

• The simulator then returns the actual region (in case it might be different from requested) and the seed cap.

{
   'look_at' : [f32, f32, f32]
   'position': [f32, f32, f32]
// Extra stuff
   'connect': <bool>
}

rez_avatar/derez

Request: agentd -> simulator a

{
    'rez_avatar/rez': <url>
    'position':  [x, y, z]
}

Response: simulator a -> agentd

Response: simulator -> agentd

{
   'look_at' : [f32, f32, f32]
   'position': [f32, f32, f32]
// Extra stuff
   'connect': <bool>
}

Maintenance

OGP Maintenance refers to an extension of the existing OGP Login protocol to support per-user maintenance tasks when an agent "logs in." Per-user, login-time maintenance is considered "better" in some cases than universal maintenance because:

1. it reduces the requirement for system-wide downtime
2. assuming that all agents do not "log in" simultaneously, it distributes the load of maintenance across time
3. and, it consumes system resources only for those agents who actually "log in."

It is not, however, without disadvantages:

1. performing per-user maintenance can lead to more complex systems
2. agents who do not "log in" frequently will experience delays as pending maintenance is performed.

Dramatis Personae

• the user  : the human or automated service on whose behalf interaction with the grid is initiated
• an account : an administrative convenience maintained by the agent domain on behalf of the user "containing" one or more agents
• the agent  : a specific actor on the grid, identified uniquely by a name, a UUID and a credential
• the client : the software component participating in the protocol with the agent domain and optionally (hopefully) a region
• the agent domain : a collection of systems that respond to OGP and report and manipulate agent related information
• the credential  : a syndrome of a shared secret presented by the client to the agent domain on behalf of the user
• a maintenance token : an opaque data structure representing maintenance being done by the agent domain on the user's behalf

Requirements

• Maintenance must occur subsequent to authentication
• The client must be alerted that maintenance is occurring
• The agent domain must not require a client to re-authenticate themselves in order to check on the status of ongoing maintenance, once the client has been informed that maintenance is occurring (subject to reasonable limitation on the validity period of the credential)
• The agent domain must use the initial authentication (that started the maintenance process) to continue the login process (subject to reasonable limitation on the validity period of the credential)
• (reasonable limitation on the validity period of a credential)
  • In situations where a credential has a validity period (X.509, OpenID, etc.) the agent domain must not depend on an authenticator after it's validity period is expired.
  • An agent domain may choose a "reasonable" validity period for credentials that do not have an explicit validity period (shared secret, SRP, etc.)
• The agent domain should give the client an estimate on how long maintenance should last
• If a user "logs in" using two distinct clients with the same agent, the agent domain should provide the same maintenance token to both clients
• The agent domain must expose an interface allowing the client to use the maintenance token to retrieve status information regarding ongoing maintenance

A Few Comments

• If the agent domain has a good estimate for how long maintenance will take, it may choose to delay responding to maintenance caps for some period of time.
  • This has the benefit of discouraging clients from repeatedly querying for status updates.
• If the agent domain does not have a good estimate for how long maintenance will take, it may choose to insert a smaller delay in responding to maintenance caps.
  • This will allow the client to retrieve progressively more accurate estimates of maintenance lengths.

How it maps to the existing implementation

• the "maintenance token" is a "maintenance cap"
• when auth.py determines that a transform must be applied, it:
  • checks to see if maintenance is under way. If it is not, it:
    • queries ??? for a new maintenance cap
    • updates the user_transformation table to include the current maintenance cap that is executing
    • tells ??? to start performing transforms
  • then returns the current maintenance cap

Open Questions

• it's possible for an agent to have several transformations to be applied (denoted as several rows in the user_transformation table), so:
  • do we use the same maintenance cap for each transformation, or do we create a new cap for each transform?

Maintenance / Transform ideas

Current Maintenance Flow:

   * next_url -> transform.cgi
   * viewer POST credentials again to transform.cgi (not okay for protocol)

OGP Maintenance

   * next_url is a cap
   * Need expiry/lifetime of cap -> connect to user.transform_until
   * If transform_until: give back same cap for next_url

credential is { password | openid url }

Viewer Auth.py (name,credential) ==>

                  * do authentication
                  * is a transform currently being performed?
                    * return transform cap
                  * is there a transform?
                  * get cap for transform
                  (name,transform type) ==>
                 <== (cap)OGP Maintenance