Current login protocols

From Second Life Wiki
Jump to navigation Jump to search

Introduction

This page documents the log-in protocol for Second life as it exists currently. It will eventually be replaced by the login portion of the Second Life Grid Open Grid Protocol (SLGOGP).

The purpose of this document and others like it is to give a detailed description of the Second Life protocols so that programmers can refer to it when implementing their own Second Life viewer without referring to or using the source code of either the Linden Lab viewer, or the libsecond life viewer. It also allows internal developers at Linden Lab to check their understanding of the current log-in protocol as they develop the new version described in the SLGOGP.

Working examples of this protocol are found on the links in the Example Protocol Code page

Conventions

On this page the following conventions are used:

"in quotes is a literal string"
[ represents a list of choices | separated by a vertical bar ]
< represents a value which can be substituted by an appropriate string described inside >
'represents a string that must be quoted, but how will be implementation specific' for example in LSL "" denotes a string and " will be used in place of the single quote (').
+ means to concatenate the two parts, though how will be implementation specific, for example + can be used to concatenate strings.

Log-in

The current Second Life log-in requires the viewer to send an http/1.1 XML-RPC message with specific input parameters to a Second Life log-in URL and parse the response for further processing. The URL is specified by using "-loginuri" in the command line parameters, as described in the command line parameters page on the Second Life wiki.

Authentication Flow

This is a simplified version of the authentication flow, showing the major steps in the process.

Note: Step 6 through Step 8 are not strictly part of login and are documented in the Establishing_Avatar_Presence page.


Step 1
Viewer -----------> Login Server {XML-RPC)
Step 2
Login Server ------> Database
Step 3
Login Server------> SIM in the Grid
Step 4
Login server ------> Viewer (XML-RPC response)
Step 5
Viewer -------> Simulator UseCirucuitCode (UDP expects ack)
Step 6
Viewer -------> Simulator CompleteAgentMovement (UDP expects ack)
Step 7
Viewer -------> Simulator AgentUpdate (UDP expects ack)

XML-RPC call

Note: This section details Step 1 and Step 5 of the #Authentication Flow.

Input parameters

Required parameters

The following explains the standard key value pairs, with an explanation of "options" at the end:

"first": <first>
first name of the avatar.
"last": <last>
last name of the avatar.
"passwd": '$1$' + <passwd_md5>
the avatar password encrypted using MD5 encryption.
"start": ["first" | "last" | <specific location> ]
attempt to log in to this sim, though if it is full or not available, or the agent is not allowed, another sim will be selected by the grid from its list of choices. "First" means home location. If home is filled then the grid will try last. If last is filled and home is set, the grid will try home. In either case the last choice will be from a list of telehubs. For a log in to a specific location the format is "uri:<existing region name>&<x>&<y>&<z>".
"channel": <channel name>
the name of the client. Used to differentiate official viewers from third party clients.
"version": <version string>
version number of the client.
"platform": ["Lin" | "Mac" | "Win"]
the platform of the client.
"mac": <MAC Address>
the MAC address associated with the client's computer.
"options": [optional_login]
optional array of character strings. (See Optional Parameters below)
"id0": "00000000-0000-0000-0000-000000000000"
hardware hash (based on the serial number of the first hard drive in Windows) used for uniquely identifying computers.
"agree_to_tos": ["true" | "false" | ""]
whether or not the user has agreed to the Terms of Service.
"read_critical": ["true" | "false" | ""]
whether or not the user has read important messages such as Terms of Service updates.
"viewer_digest": "00000000-0000-0000-0000-000000000000"
MD5 hash of the viewer executable, only relevant when the channel is set to an official Second Life viewer.
Optional Parameters

Zero or more of the following character strings may appear in any order in the options array:

[ "inventory-root" | "inventory-skeleton" | "inventory-lib-root" |
"inventory-lib-owner" | "inventory-skel-lib" | "gestures" | "event_categories" |
"event_notifications" | "classified_categories" | "buddy_list" | "ui-config" |
"login-flags" | "global-textures" ]

See Optional Response for descriptions of information returned from these options

Response

The valid (non-error) value returned by the login call is in standard xmlrpc name, value format. The most important of these is the "Login Seed-Capability" discussed below (not to be confused with the new "seed capability" for the new login procedure):

Note: all return values are in "name: value" format as used in Python 2.5 dictionaries unless otherwise noted.
Note: A complete dump of return values was moved to another page for clarity.

Required Response

last_name
last name of avatar--identical to name given in input parameters
{ 'last_name':<last_name>}


sim_ip
ip address of starting sim
{ 'sim_ip':<ip_num> }
start_location: last
seconds_since_epoch: 1195447316
message: -=- http://blog.secondlife.com -=- Visit the Official Linden Blog for the latest world status updates!
first_name: first_name
circuit_code: 245160577
sim_port: 13005
secure_session_id: fdb501ca-22f1-4470-b515-2650f54b8117
look_at: [r-0.85717299999999996274,r0.51502899999999995906,r0]
agent_id: d5f403c7-7981-425d-a0b5-c65a3d0a4693
inventory_host: inv12-mysql
region_y: 244992
region_x: 247808
seed_capability: https://sim2054.agni.lindenlab.com:12043/cap/d373fdc9-d275-e484-3ad2-4a9b231f4e34
agent_access: M
session_id: 65a7213a-723a-4fcf-baca-7b247c4b43c5
login: true

Optional Response

inventory-root
UUID of the agent’s root inventory folder.
{ 'inventory-root': [{'folder_id': <uuid>}] }
inventory-skeleton
Initial list of folders in agent’s inventory. Returned as an array of five-entry dictionaries. Each dictionary element describes a folder with its name, version, type, its UUID, and the UUID of the containing folder.
{'inventory-skeleton': [{'parent_id': <uuid>, 'version': <int>, 'name': <name>, 'type_default': <int>, 'folder_id': <uuid>}, .... ]}
inventory-lib-root
folder_id of library root inventory folder.
{ 'inventory-lib-root': [{'folder_id': <uuid>}] }
inventory-lib-owner
agent_id of owner for inventory lib. Used to establish common inventory library for all avatars in Second Life

Note: Not the same as the agent_id in the required response section

{ 'inventory-lib-owner': [{'agent_id': <uuid>}] }
inventory-skel-lib
Initial list of folders in agent’s inventory. Returned as an array of five element dictionaires. Each dictionary describes a folder with its name, its UUID, the UUID of the containing folder, its type, its version.
{'inventory-skeleton': [{'parent_id': <uuid>, 'version': <int>, 'name': <name>, 'type_default': <int>, 'folder_id': <uuid>},... ]}
gestures
List of active gestures. An array of two element dictionaries with the inventory item uuid and the asset uuid.
{ 'gestures': [{'item_id': <uuid>, 'asset_id': <uuid>},...] }
event_categories
List of different event categories, mapping category id (an integer) to a category name. Returned as an array of two element dictionaries. Each dictionary describes a category’s id and it’s name.
{ 'event_categories': [{'category_id': <int>, 'category_name': <name>},...] }
event_notifications
List of events for which the agent has pending notifications. An array of eight-element dictionaries containing: event_id, event_name, event_desc, event_date, grid_x, grid_y, x_region, y_region.
{'events': [{"event_id":<uuid>, "event_name"<name>,"event_desc":<string>, "event_date":<date>, "grid_x":<float>, "grid_y":<float>, "x_region":<float>, "y_region":<float>}, ...]}
classified_categories"
List of classifieds categories, mapping category id (an integer) to a category. Returned as an array of two element dictionaries with a category’s id and it’s name.
{ 'event_categories': [{'category_id': <int>, 'category_name': <name>},...] }
buddy-list
List of friends with granted and given rights masks. Returned as an array of three-element dictionaries with riend’s agent id, granted rights mask, given rights mask.
{ 'buddy-list':[{'buddy_id': <uuid>', 'buddy_rights_given': <int>, 'buddy_rights_has': <int>}, ....] }
ui-config
list of UI enabled/disabled states, currently: allow_first_life ('Y' or 'N') for teens.
{ 'ui-config': {'allow_first_life': if allow first life} }
login-flags
Several flags about the state of the agent.
{ 'login-flags': {'stipend_since_login': <'Y'|'N'>, 'ever_logged_in': <'Y'|'N'>, 'gendered': <'Y'|'N'>, 'daylight_savings': <'Y'|'N'>} }
global-textures
The asset ids of several global textures.
{ 'global-textures': {'sun_texture_id': <uuid>, 'moon_texture_id': <uuid>, 'cloud_texture_id': <uuid>} }

Login Seed-Capability

The current Login Seed-Capability is a Capability associated with the login sim. It should not be confused with the Seed-Capability proposed for the new protocols.

See Current Sim Capabilities for more info.

External Links

[1] -- libsl login page, includes sample code.